Package org.apache.sis.internal.storage.image

Class WritableStore

java.lang.Object
org.apache.sis.storage.DataStore
org.apache.sis.internal.storage.URIDataStore
org.apache.sis.internal.storage.PRJDataStore
org.apache.sis.internal.storage.image.WorldFileStore
org.apache.sis.internal.storage.image.WritableStore
All Implemented Interfaces:
AutoCloseable, ResourceOnFileSystem, StoreResource, Resource, Localized
Direct Known Subclasses:
MultiImageStore.Writable
class WritableStore extends WorldFileStore
A data store which writes grid coverages using Image I/O writers completed by the World File convention. Georeferencing is defined by two auxiliary files described in the WorldFileStore parent class.

Type of output objects

The StorageConnector output should be an instance of the following types: Path, File, URL or URI. Other types such as ImageOutputStream are also accepted but in those cases the auxiliary files cannot be written. For any output of unknown type, this data store first checks if an ImageWriter accepts the output type directly. If none is found, this data store tries to create an output stream from the output object.

The storage output object may also be an ImageWriter instance ready for use (i.e. with its output set to a non-null value). In that case, this data store will use the given image writer as-is. The image writer will be disposed and its output closed (if AutoCloseable) when this data store is closed.

Handling of multi-image files

Because some image formats can store an arbitrary number of images, this data store is considered as an aggregate with one resource per image. All image should have the same size and all resources will share the same GridGeometry. However, this base class does not implement the WritableAggregate interface directly in order to give a chance to subclasses to implement GridCoverageResource directly when the format is known to support only one image per file.
Since:
1.2
Version:
1.3

  • Field Details

    • streamBeginning

      private final long streamBeginning
      Position of the input/output stream beginning. This is usually 0.

    • writer

      private ImageWriter writer
      The image writer, created when first needed and cleared when the store is closed. Only one of WorldFileStore.reader and writer should have its input or output set at a given time.
      See Also:

    • numImages

      private int numImages
      Number of images in this store, or any negative value if unknown. This information is redundant with ImageReader.getNumImages(boolean) but is stored here because WorldFileStore.reader may be null and ImageWriter does not have a getNumImages(…) method.
      See Also:

  • Constructor Details

    • WritableStore

      WritableStore(FormatFinder format) throws DataStoreException, IOException
      Creates a new store from the given file, URL or stream.
      Parameters:
      format - information about the storage (URL, stream, etc) and the reader/writer to use.
      Throws:
      DataStoreException - if an error occurred while opening the stream.
      IOException - if an error occurred while creating the image reader instance.

  • Method Details

    • configureWriter

      private void configureWriter()
      Sets the locale to use for warning messages, if supported. If the writer does not support the locale, the writer's default locale will be used.

    • getImageFormat

      public String[] getImageFormat(boolean asMimeType)
      Returns the Image I/O format names or MIME types of the image read or written by this data store. More than one names may be returned if the format has aliases or if the MIME type has legacy types (e.g. official "image/png" and legacy "image/x-png").
      Overrides:
      getImageFormat in class WorldFileStore
      Parameters:
      asMimeType - true for MIME types, or false for format names.
      Returns:
      the requested names, or an empty array if none or unknown.

    • isMultiImages

      final int isMultiImages() throws IOException, DataStoreException
      Returns whether this data store contains more than one image. This is used for deciding if WritableStore can overwrite a grid geometry.
      Returns:
      0 if this store is empty, 1 if it contains exactly one image, or a value greater than 1 if it contains more than one image. The returned value is not necessarily the number of images.
      Throws:
      IOException
      DataStoreException
      See Also:

    • setGridGeometry

      String setGridGeometry(int index, GridGeometry gg) throws IOException, DataStoreException
      Sets the store-wide grid geometry. Only one grid geometry can be set for a data store. If a grid geometry already exists and the specified grid geometry is incompatible, then an IncompatibleResourceException is thrown.

      This method may use the ImageReader for checking the number of images, so it is better to invoke this method before writer().

      Overrides:
      setGridGeometry in class WorldFileStore
      Parameters:
      index - index of the image for which to read the grid geometry.
      gg - the new grid geometry.
      Returns:
      suffix of the "world file", or null if this method wrote nothing.
      Throws:
      IncompatibleResourceException - if the "grid to CRS" is not affine, or if a different grid geometry already exists.
      IOException
      DataStoreException
      See Also:

    • createImageResource

      WorldFileResource createImageResource(int index) throws DataStoreException, IOException
      Creates a GridCoverageResource for the specified image. This method is invoked by WorldFileStore.Components when first needed and the result is cached by the caller.
      Overrides:
      createImageResource in class WorldFileStore
      Parameters:
      index - index of the image for which to create a resource.
      Returns:
      resource for the image identified by the given index.
      Throws:
      IndexOutOfBoundsException - if the image index is out of bounds.
      DataStoreException
      IOException

    • add

      public Resource add(Resource resource) throws DataStoreException
      Adds a new Resource in this Aggregate. The given Resource will be copied, and the effectively added resource returned.
      Parameters:
      resource - the resource to copy in this Aggregate.
      Returns:
      the effectively added resource.
      Throws:
      DataStoreException - if the given resource cannot be stored in this Aggregate.

    • remove

      public void remove(Resource resource) throws DataStoreException
      Removes a Resource from this Aggregate. The given resource should be one of the instances returned by WorldFileStore.components().
      Overrides:
      remove in class WorldFileStore
      Parameters:
      resource - child resource to remove from this Aggregate.
      Throws:
      DataStoreException - if the given resource could not be removed.

    • label

      private static String label(Resource resource) throws DataStoreException
      Returns a label for the given resource in error messages.
      Throws:
      DataStoreException

    • prepareReader

      ImageReader prepareReader(ImageReader current) throws IOException
      Prepares an image reader compatible with the writer and sets its input. This method is invoked for switching from write mode to read mode.
      Overrides:
      prepareReader in class WorldFileStore
      Parameters:
      current - the current image reader, or null if none.
      Returns:
      the image reader to use, or null if none.
      Throws:
      IOException - if an error occurred while preparing the reader.

    • writer

      final ImageWriter writer() throws DataStoreException, IOException
      Returns the writer if it has not been closed. If the data store was in read mode, invoking this method switch to write mode.
      Throws:
      DataStoreClosedException - if this data store is closed.
      IOException - if an error occurred while preparing the writer.
      DataStoreException

    • setStream

      private <T> void setStream(T codec, Object stream, BiConsumer<T,Object> setter) throws IOException
      Sets the input or output stream on the given image reader or writer. If the operation fails, the stream is closed.
      Type Parameters:
      T - class of the codec argument.
      Parameters:
      codec - the ImageReader or ImageWriter on which to set the stream.
      stream - the input or output to set on the specified codec.
      setter - for calling the setInput(Object) or setOutput(Object) method.
      Throws:
      IOException

    • getProviderByClass

      private <T extends ImageReaderWriterSpi> T getProviderByClass(Class<T> type, String[] classNames, ImageReaderWriterSpi originating)
      Returns the first service provider that we can get from the given list of class names.
      Type Parameters:
      T - compile-time value of type argument.
      Parameters:
      type - type of the provider to get.
      classNames - class names of provider implementations, or null if none.
      originating - the originating provider, used for fetching the class loader.
      Returns:
      first provider found, or null if none.

    • close

      public void close() throws DataStoreException
      Closes this data store and releases any underlying resources.
      Specified by:
      close in interface AutoCloseable
      Overrides:
      close in class WorldFileStore
      Throws:
      DataStoreException - if an error occurred while closing this data store.
      See Also: