Class WorldFileStore
- All Implemented Interfaces:
AutoCloseable
,ResourceOnFileSystem
,StoreResource
,Resource
,Localized
- Direct Known Subclasses:
MultiImageStore
,SingleImageStore
,WritableStore
- A text file containing the coefficients of the affine transform mapping pixel coordinates to geodesic coordinates.
The reader expects one coefficient per line, in the same order than the order expected by the
AffineTransform(double[])
constructor, which is scaleX, shearY, shearX, scaleY, translateX, translateY. The reader looks for a file having the following suffixes, in preference order:- The first letter of the image file extension, followed by the last letter of
the image file extension, followed by
'w'
. Example:"tfw"
for"tiff"
images, and"jgw"
for"jpeg"
images. - The extension of the image file with a
'w'
appended. - The
"wld"
extension.
- The first letter of the image file extension, followed by the last letter of
the image file extension, followed by
- A text file containing the Coordinate Reference System (CRS) definition
in Well Known Text (WKT) syntax.
The reader looks for a file having the
".prj"
extension.
Type of input objects
TheStorageConnector
input should be an instance of the following types:
Path
, File
, URL
or URI
.
Other types such as ImageInputStream
are also accepted but in those cases the auxiliary files cannot be read.
For any input of unknown type, this data store first checks if an ImageReader
accepts the input type directly.
If none is found, this data store tries to create an input stream
from the input object.
The storage input object may also be an ImageReader
instance ready for use
(i.e. with its input set to a non-null value).
In that case, this data store will use the given image reader as-is.
The image reader will be disposed
and its input 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 Aggregate
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 ClassesModifier and TypeClassDescription(package private) final class
A list of images where eachWorldFileResource
instance is initialized when first needed.Nested classes/interfaces inherited from class org.apache.sis.internal.storage.PRJDataStore
PRJDataStore.AuxiliaryContent, PRJDataStore.Provider
-
Field Summary
FieldsModifier and TypeFieldDescription(package private) static final org.opengis.referencing.datum.PixelInCell
The "cell center" versus "cell corner" interpretation of translation coefficients.private WorldFileStore.Components
All images in this resource, created when first needed.private static final String
The default World File suffix when it cannot be determined fromURIDataStore.location
.private GridGeometry
The conversion from pixel center to CRS, ornull
if none or not yet computed.private int
Width and height of the main image.Identifiers used by a resource.private static final String[]
Image I/O format names (ignoring case) for which we have an entry in theSpatialMetadata
database.(package private) static final int
Index of the main image.private org.opengis.metadata.Metadata
The metadata object, ornull
if not yet created.private ImageReader
The image reader, set by the constructor and cleared when the store is closed.(package private) final String
The filename extension (may be an empty string), ornull
if unknown.private String
The filename extension for the auxiliary "world file".private Closeable
The object to close whenWorldFileStore
is closed.private int
Width and height of the main image.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
ConstructorsConstructorDescriptionWorldFileStore
(FormatFinder format, boolean readOnly) Creates a new store from the given file, URL or stream.WorldFileStore
(WorldFileStoreProvider provider, StorageConnector connector) Creates a new store from the given file, URL or stream. -
Method Summary
Modifier and TypeMethodDescriptionvoid
close()
Closes this data store and releases any underlying resources.Collection<? extends GridCoverageResource>
Returns all images in this store.(package private) final WorldFileStore.Components
components
(boolean create, int numImages) Returns all images in this store, ornull
if none andcreate
is false.private void
Sets the locale to use for warning messages, if supported.(package private) WorldFileResource
createImageResource
(int index) Creates aGridCoverageResource
for the specified image.private Errors
errors()
Returns the localized resources for producing error messages.Path[]
Returns paths to the main file together with auxiliary files.(package private) final ImageReader
Returns the reader without doing any validation.(package private) final GridGeometry
getGridGeometry
(int index) Gets the grid geometry for image at the given index.String[]
getImageFormat
(boolean asMimeType) Returns the Image I/O format names or MIME types of the image read by this data store.org.opengis.metadata.Metadata
Returns information about the data store as a whole.private String
Returns the preferred suffix for the auxiliary world file.(package private) boolean
Whether the component of this data store is used only as a delegate.(package private) ImageReader
prepareReader
(ImageReader current) Prepares an image reader compatible with the writer and sets its input.(package private) final ImageReader
reader()
Returns the reader if it has not been closed.private AffineTransform2D
Reads the "World file" by searching for an auxiliary file with a suffix inferred from the suffix of the main file.private AffineTransform2D
readWorldFile
(String wld) Reads the "World file" by parsing an auxiliary file with the given suffix.(package private) void
Invoked byWorldFileStore.Components
when the caller want to remove a resource.(package private) final Resources
Returns the localized resources for producing warnings or error messages.(package private) String
setGridGeometry
(int index, GridGeometry gg) Sets the store-wide grid geometry when a new coverage is written.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
-
KNOWN_FORMATS
Image I/O format names (ignoring case) for which we have an entry in theSpatialMetadata
database. -
MAIN_IMAGE
static final int MAIN_IMAGEIndex of the main image. This is relevant only with formats capable to store an arbitrary number of images. Current implementation assumes that the main image is always the first one, but it may become configurable in a future version if useful.- See Also:
-
DEFAULT_SUFFIX
The default World File suffix when it cannot be determined fromURIDataStore.location
. This is a GDAL convention.- See Also:
-
CELL_ANCHOR
static final org.opengis.referencing.datum.PixelInCell CELL_ANCHORThe "cell center" versus "cell corner" interpretation of translation coefficients. The ESRI specification said that the coefficients map to pixel center. -
suffix
The filename extension (may be an empty string), ornull
if unknown. It does not include the leading dot. -
suffixWLD
The filename extension for the auxiliary "world file". For the TIFF format, this is typically"tfw"
. This is computed as a side-effect ofreadWorldFile()
. -
reader
The image reader, set by the constructor and cleared when the store is closed. May also be null if the store is initially write-only, in which case a reader may be created the first time than an image is read.- See Also:
-
toClose
The object to close whenWorldFileStore
is closed. It may be a different object than reader input or writer output, because someImageInputStream.close()
implementations in the standard Javajavax.imageio.stream
package do not close the underlying stream.The type is
Closeable
instead ofAutoCloseable
because the former is idempotent: invokingCloseable.close()
many times has no effect. By contrastAutoCloseable
does not offer this guarantee. Because it is hard to know whatImageInputStream.close()
will do, we need idempotenttoClose
for safety. Note thatImageInputStream.close()
violates the idempotent contract ofCloseable.close()
, so an additional check will be necessary in ourclose()
implementation. -
width
private int widthWidth and height of the main image. ThegridGeometry
is assumed valid only for images having this size.- See Also:
-
height
private int heightWidth and height of the main image. ThegridGeometry
is assumed valid only for images having this size.- See Also:
-
gridGeometry
The conversion from pixel center to CRS, ornull
if none or not yet computed. The grid extent has the size given bywidth
andheight
.- See Also:
-
components
All images in this resource, created when first needed. Elements in this list will also be created when first needed.- See Also:
-
metadata
private org.opengis.metadata.Metadata metadataThe metadata object, ornull
if not yet created.- See Also:
-
identifiers
Identifiers used by a resource. Identifiers must be unique in the data store, so after an identifier has been used it cannot be reused anymore even if the resource having that identifier has been removed. Values associated to identifiers tell whether the resource still exist.- See Also:
-
-
Constructor Details
-
WorldFileStore
public WorldFileStore(WorldFileStoreProvider provider, StorageConnector connector) throws DataStoreException, IOException Creates a new store from the given file, URL or stream.- Parameters:
provider
- the factory that created thisDataStore
instance, ornull
if unspecified.connector
- information about the storage (URL, stream, etc).- Throws:
DataStoreException
- if an error occurred while opening the stream.IOException
- if an error occurred while creating the image reader instance.
-
WorldFileStore
WorldFileStore(FormatFinder format, boolean readOnly) 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.readOnly
-true
if the store should be open in read-only mode, ignoringformat
. This is a workaround for RFE #4093999 in Sun's bug database, for allowing us to invokeFormatFinder#cleanup()
when invoked from the public constructor.- Throws:
DataStoreException
- if an error occurred while opening the stream.IOException
- if an error occurred while creating the image reader instance.
-
-
Method Details
-
configureReader
private void configureReader()Sets the locale to use for warning messages, if supported. If the reader does not support the locale, the reader's default locale will be used. -
getWorldFileSuffix
Returns the preferred suffix for the auxiliary world file. For TIFF images, this is"tfw"
. This method tries to use the same case (lower-case or upper-case) than the suffix of the main file. -
readWorldFile
Reads the "World file" by searching for an auxiliary file with a suffix inferred from the suffix of the main file. This method tries suffixes with the following conventions, in preference order.- First letter of main file suffix, followed by last letter, followed by
'w'
. - Full suffix of the main file followed by
'w'
. - "wld".
- Returns:
- the "World file" content as an affine transform, or
null
if none was found. - Throws:
IOException
- if an I/O error occurred.DataStoreException
- if the auxiliary file content cannot be parsed.
- First letter of main file suffix, followed by last letter, followed by
-
readWorldFile
Reads the "World file" by parsing an auxiliary file with the given suffix.- Parameters:
wld
- suffix of the auxiliary file.- Returns:
- the "World file" content as an affine transform, or
null
if none was found. - Throws:
IOException
- if an I/O error occurred.DataStoreException
- if the file content cannot be parsed.
-
resources
Returns the localized resources for producing warnings or error messages. -
errors
Returns the localized resources for producing error messages. -
getImageFormat
Returns the Image I/O format names or MIME types of the image read 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"
).- Parameters:
asMimeType
-true
for MIME types, orfalse
for format names.- Returns:
- the requested names, or an empty array if none or unknown.
-
getComponentFiles
Returns paths to the main file together with auxiliary files.- Specified by:
getComponentFiles
in interfaceResourceOnFileSystem
- Overrides:
getComponentFiles
in classPRJDataStore
- Returns:
- paths to the main file and auxiliary files, or an empty array if unknown.
- Throws:
DataStoreException
- if the URI cannot be converted to aPath
.
-
getGridGeometry
Gets the grid geometry for image at the given index. This method should be invoked only once per image, and the result cached.- Parameters:
index
- index of the image for which to read the grid geometry.- Returns:
- grid geometry of the image at the given index.
- Throws:
IndexOutOfBoundsException
- if the image index is out of bounds.IOException
- if an I/O error occurred.DataStoreException
- if the*.prj
or*.tfw
auxiliary file content cannot be parsed.
-
setGridGeometry
Sets the store-wide grid geometry when a new coverage is written. TheWritableStore
implementation is responsible for making sure that the new grid geometry is compatible with preexisting grid geometry.- Parameters:
index
- index of the image for which to set the grid geometry.gg
- the new grid geometry.- Returns:
- suffix of the "world file", or
null
if the image cannot be written. - Throws:
IOException
DataStoreException
-
getMetadata
Returns information about the data store as a whole.- Specified by:
getMetadata
in interfaceResource
- Specified by:
getMetadata
in classDataStore
- Returns:
- information about resources in the data store. Should not be
null
. - Throws:
DataStoreException
- if an error occurred while reading the metadata.- See Also:
-
components
Returns all images in this store. Note that fetching the size of the list is a potentially costly operation.- Returns:
- list of images in this store.
- Throws:
DataStoreException
-
components
Returns all images in this store, ornull
if none andcreate
is false.- Parameters:
create
- whether to create the component list if it was not already created.numImages
- number of images, or any negative value if unknown.
-
remove
Invoked byWorldFileStore.Components
when the caller want to remove a resource. The actual implementation is provided byWritableStore
.- Throws:
DataStoreException
-
createImageResource
Creates aGridCoverageResource
for the specified image. This method is invoked byWorldFileStore.Components
when first needed and the result is cached by the caller.- 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
-
isComponentHidden
boolean isComponentHidden()Whether the component of this data store is used only as a delegate. This isfalse
when the components will be given to the user, ortrue
if the singleton component will be used only for internal purposes. -
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. Its actual implementation is provided byWritableResource
.- 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.
-
getCurrentReader
Returns the reader without doing any validation. The reader may benull
either because the store is closed or because the store is initially opened in write-only mode. The reader may have anull
input. -
reader
Returns the reader if it has not been closed.- Throws:
DataStoreClosedException
- if this data store is closed.IOException
- if an error occurred while preparing the reader.DataStoreException
-
close
Closes this data store and releases any underlying resources.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in classDataStore
- Throws:
DataStoreException
- if an error occurred while closing this data store.- See Also:
-