Class StoreUtilities
DataStore
s, DataStoreProvider
s and Resource
s.
This is not a committed API; any method in this class may change in any future Apache SIS version.
Some methods may also move in public API if we feel confident enough.- Since:
- 1.0
- Version:
- 1.3
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final boolean
Whether to allow computation of statistics when no minimum/maximum values can be determined.Names of encoding where bytes less than 128 can be interpreted as ASCII.static final Logger
Logger for the "org.apache.sis.storage" module. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic boolean
basedOnASCII
(Charset encoding) Returnstrue
if a sequence of bytes in the given encoding can be decoded as if they were ASCII, ignoring values greater than 127.static Boolean
canWrite
(Class<? extends DataStoreProvider> provider) Returns whether the given store has write capability.static void
copy
(FeatureSet source, WritableFeatureSet target) Copies all feature from the given source to the given target.private static String
getAnyIdentifier
(org.opengis.metadata.Metadata metadata, boolean unicode) Returns an identifier for a resource having the given metadata, ornull
if none.static org.opengis.geometry.Envelope
getEnvelope
(org.opengis.metadata.Metadata metadata) Returns the spatiotemporal envelope of the given metadata.static String[]
getFileSuffixes
(Class<? extends DataStoreProvider> provider) Returns the possible suffixes of the files written by the data store created by the given provider.static String
getFormatName
(DataStoreProvider provider) Returns an identifier for the given data store provider, ornull
if none.getInterface
(Class<? extends Resource> implementation) Returns the most specific interface implemented by the given class.static String
Returns a short label for the given resource.static DataStoreProvider
providerByFormatName
(String format) Returns a provider for the given format name.static Filter
Returns a log filter that removes the stack trace of filtered given log.static String
resourceNotFound
(DataStore store, String identifier) Returns an error message for a resource not found.static EnumSet
<StandardOpenOption> toStandardOptions
(OpenOption[] options) Converts the given sequence of options into a simplified set of standard options.
-
Field Details
-
ALLOW_LAST_RESORT_STATISTICS
public static final boolean ALLOW_LAST_RESORT_STATISTICSWhether to allow computation of statistics when no minimum/maximum values can be determined. This is a costly operation because it requires loading all data, so any code enabled by this flag should be executed in last resort only.This flag can be set to
true
for exploring data that we cannot visualize otherwise. But it should generally stay tofalse
, because otherwise browsing resource metadata can become as costly (slow and high memory usage) as visualizing the full raster.In addition of possible performance degradations, setting this flag to
true
can also preventCoverageAggregator
to group coverages that should be together. This is because using statistics may causeSampleDimension
instances to have different sample value ranges for each coverage, which causeCoverageAggregator
to consider that that cannot be aggregated together.- See Also:
-
LOGGER
Logger for the "org.apache.sis.storage" module. This is used when no more specific logger is available, or if the more specific logger is not appropriate (e.g. because the log message come from base class). -
basedOnASCII
Names of encoding where bytes less than 128 can be interpreted as ASCII.- See Also:
-
-
Constructor Details
-
StoreUtilities
private StoreUtilities()Do not allow instantiation of this class.
-
-
Method Details
-
getFormatName
Returns an identifier for the given data store provider, ornull
if none. The data store identifier should be the format name, but this is not guaranteed. It current version, it is not even guaranteed to be unique.This method will need to be revisited since
DataStoreProvider.getShortName()
said that the short name is not to be used as an identifier. In the meantime, we use this method as a way to keep trace of the location in the code where an identifier is desired.- Parameters:
provider
- the provider for which to get an identifier, ornull
.- Returns:
- an identifier for the given data store, or
null
.
-
getAnyIdentifier
Returns an identifier for a resource having the given metadata, ornull
if none. This method checks the information returned byMetadata.getIdentificationInfo()
, with precedence toDataIdentification
over other kinds ofIdentification
. This method does not check for ambiguity (if there is more than one identification info).- Parameters:
metadata
- the metadata from which to get a data identifier, ornull
.unicode
- whether to restrict to valid Unicode identifiers.- Returns:
- a data identifier, or
null
if none. - See Also:
-
getLabel
Returns a short label for the given resource. This method returns the display name if possible, or the identifier otherwise. If neither a display name, identifier or title can be found, then this method returns the kind of resource implemented by the given object.- Parameters:
resource
- the resource for which to get a label.- Returns:
- a human-readable label for the given resource (not to be used as an identifier).
- Throws:
DataStoreException
- if an error occurred while fetching metadata.
-
getEnvelope
public static org.opengis.geometry.Envelope getEnvelope(org.opengis.metadata.Metadata metadata) Returns the spatiotemporal envelope of the given metadata. This method computes the union of allGeographicBoundingBox
in the metadata, assuming the default geographic CRS (usually WGS 84).- Parameters:
metadata
- the metadata from which to compute the envelope, ornull
.- Returns:
- the spatiotemporal extent, or
null
if none.
-
getInterface
Returns the most specific interface implemented by the given class. For indicative purpose only, as this method has arbitrary behavior if more than one leaf is found.- Parameters:
implementation
- the implementation class.- Returns:
- the most specific resource interface.
-
getFileSuffixes
Returns the possible suffixes of the files written by the data store created by the given provider. If the file suffixes are unknown, returns an empty array.- Parameters:
provider
- class of the provider for which to determine if it has write capability, ornull
.- Returns:
- the file suffixes, or an empty array if none or if the suffixes cannot be determined.
- See Also:
-
canWrite
Returns whether the given store has write capability. In case of doubt, this method returnsnull
.- Parameters:
provider
- class of the provider for which to determine if it has write capability, ornull
.- Returns:
- whether the data store has write capability, or
null
if it cannot be determined. - See Also:
-
toStandardOptions
Converts the given sequence of options into a simplified set of standard options. The returned set can contain combinations ofStandardOpenOption.WRITE
,CREATE
,CREATE_NEW
andTRUNCATE_EXISTING
. If the set is empty, then the data store should be read-only. If bothTRUNCATE_EXISTING
andCREATE_NEW
are specified, thenCREATE_NEW
has precedence. More specifically:StandardOpenOption.WRITE
means that theDataStore
should be opened as writable resource.StandardOpenOption.CREATE
means that theDataStore
is allowed to create new files. If this option is present, thenWRITE
is also present. If this option is absent, then writable data stores should not create any new file. This flag can be tested as below (this cover both the read-only case and the writable case where the files must exist):StandardOpenOption.CREATE_NEW
means that theDataStore
should fail to open if the file already exists. This mode is used when creating new writable resources, for making sure that we do not modify existing resources. If this option is present, thenWRITE
andCREATE
are also present.StandardOpenOption.TRUNCATE_EXISTING
means that theDataStore
should overwrite the content of any pre-existing resources. If this option is present, thenWRITE
andCREATE
are also present.- Parameters:
options
- the open options, ornull
.- Returns:
- the open options as a bitmask.
-
basedOnASCII
Returnstrue
if a sequence of bytes in the given encoding can be decoded as if they were ASCII, ignoring values greater than 127. In case of doubt, this method conservatively returnsfalse
.- Parameters:
encoding
- the encoding.- Returns:
- whether bytes less than 128 can be interpreted as ASCII.
-
providerByFormatName
public static DataStoreProvider providerByFormatName(String format) throws UnsupportedStorageException Returns a provider for the given format name.- Parameters:
format
- name of the format for which to get a provider.- Returns:
- first provider found for the given format name.
- Throws:
UnsupportedStorageException
- if no provider is found for the specified format.- See Also:
-
copy
Copies all feature from the given source to the given target. We use this method as central point where such copy occur, in case we want to implement a more efficient algorithm in some future Apache SIS version. For example, we could copy the files usingFiles
if we determine that it is possible.- Parameters:
source
- the source set of features.target
- where to copy the features.- Throws:
DataStoreException
- if an error occurred during the copy operation.- See Also:
-
resourceNotFound
Returns an error message for a resource not found. This is used for exception to be thrown asIllegalNameException
.- Parameters:
store
- the store for which a resource has not been found.identifier
- the requested identifier.- Returns:
- error message for the exception to be thrown.
-
removeStackTraceInLogs
Returns a log filter that removes the stack trace of filtered given log. It can be used as argument in a call toStoreListeners.warning(LogRecord, Filter)
if the caller wants to trim the stack trace in log files or console outputs.This filter should be used only for filtering
LogRecord
created by the caller, because it modifies the record. Users would not expect this side effect on records created by them.- Returns:
- a filter for trimming stack trace.
-