Interface Source

public interface Source

Locates, provides access to, and infers the format of a source image. This is an abstract interface; at least one of the sub-interfaces must be implemented.

Methods are called in the following order:

  1. setIdentifier(Identifier) and setDelegate(Delegate) (in either order)
  2. stat()
  3. Any other methods
  4. shutdown()

  • Method Details

    • getIdentifier

      Identifier getIdentifier()
      Returns:
      Identifier of the source image to read.

    • setIdentifier

      void setIdentifier(Identifier identifier)
      Parameters:
      identifier - Identifier of the source image to read.

    • stat

      StatResult stat() throws IOException

      Checks the accessibility of the source image and returns some limited metadata.

      Will be called only once.

      Returns:
      Instance with as many of its properties set as possible.
      Throws:
      NoSuchFileException - if an image corresponding to the set identifier does not exist.
      AccessDeniedException - if an image corresponding to the set identifier is not readable.
      IOException - if there is some other issue accessing the image.

    • getFile

      default Path getFile() throws IOException
      N.B.: This default implementation throws an UnsupportedOperationException. It must be overridden if supportsFileAccess() returns true.
      Returns:
      File referencing the source image corresponding to the identifier set with setIdentifier(is.galia.image.Identifier); never null.
      Throws:
      UnsupportedOperationException - if access to files is not supported.
      IOException - if anything goes wrong.

    • getFormatIterator

      Iterator<Format> getFormatIterator()

      Returns an iterator over the results of various techniques of checking the format, in the order of least to most expensive.

      A typical sequence of checks would be:

      1. Filename extension (using Format.inferFormat(String)
      2. Identifier extension (using Format.inferFormat(Identifier))
      3. Magic bytes (using FormatDetector)

      Any of the calls to Iterator.next() may return either an inaccurate value, or Format.UNKNOWN. Clients should proceed using the first non-unknown format they encounter and, if this turns out to be wrong, iterate and try again.

      Returns:
      Iterator over whatever format-inference strategies the instance supports. The instance is cached and the same one is returned every time.

    • newInputStream

      ImageInputStream newInputStream() throws IOException
      Returns:
      Instance from which to read the source image identified by the identifier passed to setIdentifier(is.galia.image.Identifier); never null.
      Throws:
      IOException - if anything goes wrong.

    • setDelegate

      void setDelegate(Delegate delegate)
      Parameters:
      delegate - Delegate for the current request.

    • shutdown

      default void shutdown()

      Shuts down the instance and any of its shared resource handles, threads, etc.

      Only called at the end of the application lifecycle.

      The default implementation does nothing.

    • supportsFileAccess

      default boolean supportsFileAccess()

      N.B. 1: This method's return value affects the behavior of getFile(). See the documentation of that method for more information.

      N.B. 2: The default implementation returns false.

      Returns:
      Whether the source image can be accessed via a Path.