Class StoreUtilities

java.lang.Object
org.apache.sis.util.Static
org.apache.sis.internal.storage.StoreUtilities

public final class StoreUtilities extends Static
Utility methods related to DataStores, DataStoreProviders and Resources. 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 Details

    • ALLOW_LAST_RESORT_STATISTICS

      public static final boolean ALLOW_LAST_RESORT_STATISTICS
      Whether 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 to false, 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 prevent CoverageAggregator to group coverages that should be together. This is because using statistics may cause SampleDimension instances to have different sample value ranges for each coverage, which cause CoverageAggregator to consider that that cannot be aggregated together.

      See Also:
    • LOGGER

      public static final Logger 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

      private static final Set<String> 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

      public static String getFormatName(DataStoreProvider provider)
      Returns an identifier for the given data store provider, or null 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, or null.
      Returns:
      an identifier for the given data store, or null.
    • getAnyIdentifier

      private static String getAnyIdentifier(org.opengis.metadata.Metadata metadata, boolean unicode)
      Returns an identifier for a resource having the given metadata, or null if none. This method checks the information returned by Metadata.getIdentificationInfo(), with precedence to DataIdentification over other kinds of Identification. 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, or null.
      unicode - whether to restrict to valid Unicode identifiers.
      Returns:
      a data identifier, or null if none.
      See Also:
    • getLabel

      public static String getLabel(Resource resource) throws DataStoreException
      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 all GeographicBoundingBox in the metadata, assuming the default geographic CRS (usually WGS 84).
      Parameters:
      metadata - the metadata from which to compute the envelope, or null.
      Returns:
      the spatiotemporal extent, or null if none.
    • getInterface

      public static Class<? extends Resource> getInterface(Class<? extends Resource> implementation)
      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

      public static String[] getFileSuffixes(Class<? extends DataStoreProvider> provider)
      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, or null.
      Returns:
      the file suffixes, or an empty array if none or if the suffixes cannot be determined.
      See Also:
    • canWrite

      public static Boolean canWrite(Class<? extends DataStoreProvider> provider)
      Returns whether the given store has write capability. In case of doubt, this method returns null.
      Parameters:
      provider - class of the provider for which to determine if it has write capability, or null.
      Returns:
      whether the data store has write capability, or null if it cannot be determined.
      See Also:
    • toStandardOptions

      public static EnumSet<StandardOpenOption> toStandardOptions(OpenOption[] options)
      Converts the given sequence of options into a simplified set of standard options. The returned set can contain combinations of StandardOpenOption.WRITE, CREATE, CREATE_NEW and TRUNCATE_EXISTING. If the set is empty, then the data store should be read-only. If both TRUNCATE_EXISTING and CREATE_NEW are specified, then CREATE_NEW has precedence. More specifically:

      StandardOpenOption.WRITE
      means that the DataStore should be opened as writable resource.

      StandardOpenOption.CREATE
      means that the DataStore is allowed to create new files. If this option is present, then WRITE 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 the DataStore 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, then WRITE and CREATE are also present.

      StandardOpenOption.TRUNCATE_EXISTING
      means that the DataStore should overwrite the content of any pre-existing resources. If this option is present, then WRITE and CREATE are also present.

      Parameters:
      options - the open options, or null.
      Returns:
      the open options as a bitmask.
    • basedOnASCII

      public static boolean basedOnASCII(Charset encoding)
      Returns true 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 returns false.
      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

      public static void copy(FeatureSet source, WritableFeatureSet target) throws DataStoreException
      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 using Files 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

      public static String resourceNotFound(DataStore store, String identifier)
      Returns an error message for a resource not found. This is used for exception to be thrown as IllegalNameException.
      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

      public static Filter removeStackTraceInLogs()
      Returns a log filter that removes the stack trace of filtered given log. It can be used as argument in a call to StoreListeners.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.