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
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
TheStorageConnector
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 sameGridGeometry
.
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
-
Nested Class Summary
Nested classes/interfaces inherited from class org.apache.sis.internal.storage.image.WorldFileStore
WorldFileStore.Components
Nested classes/interfaces inherited from class org.apache.sis.internal.storage.PRJDataStore
PRJDataStore.AuxiliaryContent, PRJDataStore.Provider
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate int
Number of images in this store, or any negative value if unknown.private final long
Position of the input/output stream beginning.private ImageWriter
The image writer, created when first needed and cleared when the store is closed.Fields inherited from class org.apache.sis.internal.storage.image.WorldFileStore
CELL_ANCHOR, identifiers, MAIN_IMAGE, suffix
Fields inherited from class org.apache.sis.internal.storage.PRJDataStore
crs, encoding, PRJ
Fields inherited from class org.apache.sis.internal.storage.URIDataStore
location
-
Constructor Summary
ConstructorsConstructorDescriptionWritableStore
(FormatFinder format) Creates a new store from the given file, URL or stream. -
Method Summary
Modifier and TypeMethodDescriptionAdds a newResource
in thisAggregate
.void
close()
Closes this data store and releases any underlying resources.private void
Sets the locale to use for warning messages, if supported.(package private) WorldFileResource
createImageResource
(int index) Creates aGridCoverageResource
for the specified image.String[]
getImageFormat
(boolean asMimeType) Returns the Image I/O format names or MIME types of the image read or written by this data store.private <T extends ImageReaderWriterSpi>
TgetProviderByClass
(Class<T> type, String[] classNames, ImageReaderWriterSpi originating) Returns the first service provider that we can get from the given list of class names.(package private) final int
Returns whether this data store contains more than one image.private static String
Returns a label for the given resource in error messages.(package private) ImageReader
prepareReader
(ImageReader current) Prepares an image reader compatible with the writer and sets its input.void
Removes aResource
from thisAggregate
.(package private) String
setGridGeometry
(int index, GridGeometry gg) Sets the store-wide grid geometry.private <T> void
setStream
(T codec, Object stream, BiConsumer<T, Object> setter) Sets the input or output stream on the given image reader or writer.(package private) final ImageWriter
writer()
Returns the writer if it has not been closed.Methods inherited from class org.apache.sis.internal.storage.image.WorldFileStore
components, components, getComponentFiles, getCurrentReader, getGridGeometry, getMetadata, isComponentHidden, reader, resources
Methods inherited from class org.apache.sis.internal.storage.PRJDataStore
deleteAuxiliaryFile, getOpenParameters, listComponentFiles, readAuxiliaryFile, readPRJ, writeAuxiliaryFile, writePRJ
Methods inherited from class org.apache.sis.internal.storage.URIDataStore
addTitleOrIdentifier, getIdentifier, getOriginator, getSpecifiedPath, location, parameters
Methods inherited from class org.apache.sis.storage.DataStore
addListener, findResource, getDisplayName, getLocale, getNativeMetadata, getProvider, removeListener, setLocale, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.apache.sis.storage.Resource
addListener, removeListener
-
Field Details
-
streamBeginning
private final long streamBeginningPosition of the input/output stream beginning. This is usually 0. -
writer
The image writer, created when first needed and cleared when the store is closed. Only one ofWorldFileStore.reader
andwriter
should have its input or output set at a given time.- See Also:
-
numImages
private int numImagesNumber of images in this store, or any negative value if unknown. This information is redundant withImageReader.getNumImages(boolean)
but is stored here becauseWorldFileStore.reader
may be null andImageWriter
does not have agetNumImages(…)
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
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 classWorldFileStore
- Parameters:
asMimeType
-true
for MIME types, orfalse
for format names.- Returns:
- the requested names, or an empty array if none or unknown.
-
isMultiImages
Returns whether this data store contains more than one image. This is used for deciding ifWritableStore
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
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 anIncompatibleResourceException
is thrown.This method may use the
ImageReader
for checking the number of images, so it is better to invoke this method beforewriter()
.- Overrides:
setGridGeometry
in classWorldFileStore
- 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
Creates aGridCoverageResource
for the specified image. This method is invoked byWorldFileStore.Components
when first needed and the result is cached by the caller.- Overrides:
createImageResource
in classWorldFileStore
- 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
Adds a newResource
in thisAggregate
. The givenResource
will be copied, and the effectively added resource returned.- Parameters:
resource
- the resource to copy in thisAggregate
.- Returns:
- the effectively added resource.
- Throws:
DataStoreException
- if the given resource cannot be stored in thisAggregate
.
-
remove
Removes aResource
from thisAggregate
. The given resource should be one of the instances returned byWorldFileStore.components()
.- Overrides:
remove
in classWorldFileStore
- Parameters:
resource
- child resource to remove from thisAggregate
.- Throws:
DataStoreException
- if the given resource could not be removed.
-
label
Returns a label for the given resource in error messages.- Throws:
DataStoreException
-
prepareReader
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 classWorldFileStore
- Parameters:
current
- the current image reader, ornull
if none.- Returns:
- the image reader to use, or
null
if none. - Throws:
IOException
- if an error occurred while preparing the reader.
-
writer
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
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 thecodec
argument.- Parameters:
codec
- theImageReader
orImageWriter
on which to set the stream.stream
- the input or output to set on the specifiedcodec
.setter
- for calling thesetInput(Object)
orsetOutput(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 oftype
argument.- Parameters:
type
- type of the provider to get.classNames
- class names of provider implementations, ornull
if none.originating
- the originating provider, used for fetching the class loader.- Returns:
- first provider found, or
null
if none.
-
close
Closes this data store and releases any underlying resources.- Specified by:
close
in interfaceAutoCloseable
- Overrides:
close
in classWorldFileStore
- Throws:
DataStoreException
- if an error occurred while closing this data store.- See Also:
-