Class MetadataSource

  • All Implemented Interfaces:
    Auto­Closeable
    Direct Known Subclasses:
    Metadata­Writer

    public class MetadataSource
    extends Object
    implements AutoCloseable
    A connection to a metadata database in read-only mode. It can be either the database provided by Apache SIS with pre-defined ISO 19115 metadata, or another database specified at construction time. Metadata instances can be obtained as in the example below:
    MetadataSource metadata = MetadataSource.getProvided();
    Format format = source.lookup(Format.class, "PNG");
    where id is the primary key value for the desired record in the Format table.
    Properties
    The constructor expects three Java arguments (the metadata standard, the data source and the database schema) completed by an arbitrary amount of optional arguments given as a map of properties. The following keys are recognized by Metadata­Source and all other entries are ignored:
    Optional properties at construction time
    Key Value type Description
    "catalog" String The database catalog where the metadata schema is stored.
    "classloader" ClassLoader The class loader to use for creating Proxy instances.
    "maxStatements" Integer Maximal number of Prepared­Statements that can be kept simultaneously open.
    Concurrency
    Metadata­Source is thread-safe but is not concurrent. If concurrency is desired, multiple instances of Metadata­Source can be created for the same Data­Source. The Metadata­Source(Metadata­Source) convenience constructor can be used for this purpose.
    Since:
    0.8

    Defined in the sis-metadata module

    • Field Detail

      • standard

        protected final MetadataStandard standard
        The metadata standard to be used for constructing the database schema.
    • Constructor Detail

      • MetadataSource

        public MetadataSource​(MetadataStandard standard,
                              DataSource dataSource,
                              String schema,
                              Map<String,​?> properties)
        Creates a new metadata source. The metadata standard to implement (typically ISO 19115, but not necessarily) and the database source are mandatory information. All other information are optional and can be null.
        Parameters:
        standard - the metadata standard to implement.
        data­Source - the source for getting a connection to the database.
        schema - the database schema were metadata tables are stored, or null if none.
        properties - additional options, or null if none. See class javadoc for a description.
      • MetadataSource

        public MetadataSource​(MetadataSource source)
        Creates a new metadata source with the same configuration than the given source. The two Metadata­Source instances will share the same Data­Source but will use their own Connection. This constructor is useful when concurrency is desired.

        The new Metadata­Source initially contains all warning listeners declared in the given source. But listeners added or removed in a Metadata­Source after the construction will not impact the other Metadata­Source instance.

        Parameters:
        source - the source from which to copy the configuration.
    • Method Detail

      • getProvided

        public static MetadataSource getProvided()
        Returns the metadata source connected to the "jdbc/Spatial­Metadata" database. In a default Apache SIS installation, this metadata source contains pre-defined records for some commonly used citations and formats among others.

        If connection to the metadata database can not be established, then this method returns a fallback with a few hard-coded values.

        Returns:
        source of pre-defined metadata records from the "jdbc/Spatial­Metadata" database.
      • search

        public String search​(Object metadata)
                      throws MetadataStoreException
        Searches for the given metadata in the database. If such metadata is found, then its identifier (primary key) is returned. Otherwise this method returns null.
        Parameters:
        metadata - the metadata to search for.
        Returns:
        the identifier of the given metadata, or null if none.
        Throws:
        Metadata­Store­Exception - if the metadata object does not implement a metadata interface of the expected package, or if an error occurred while searching in the database.
      • lookup

        public <T> T lookup​(Class<T> type,
                            String identifier)
                     throws MetadataStoreException
        Returns an implementation of the specified metadata interface filled with the data referenced by the specified identifier. Alternatively, this method can also return a Code­List or Enum element.
        Type Parameters:
        T - the parameterized type of the type argument.
        Parameters:
        type - the interface to implement (e.g. Citation), or the Controlled­Vocabulary type (Code­List or some Enum).
        identifier - the identifier of the record for the metadata entity to be created. This is usually the primary key of the record to search for.
        Returns:
        an implementation of the required interface, or the code list element.
        Throws:
        Metadata­Store­Exception - if a SQL query failed.
      • addWarningListener

        @Deprecated
        public void addWarningListener​(WarningListener<? super MetadataSource> listener)
                                throws IllegalArgumentException
        Deprecated.
        Warning­Listener to be replaced by Filter.
        Adds a listener to be notified when a warning occurred while reading from or writing metadata. When a warning occurs, there is a choice:
        • If this metadata source has no warning listener, then the warning is logged at Level​.WARNING.
        • If this metadata source has at least one warning listener, then all listeners are notified and the warning is not logged by this metadata source instance.
        Consider invoking this method in a tryfinally block if the Metadata­Source lifetime is longer than the listener lifetime, as below:
        source.addWarningListener(listener);
        try {
            // Do some work...
        } finally {
            source.removeWarningListener(listener);
        }
        Parameters:
        listener - the listener to add.
        Throws:
        Illegal­Argument­Exception - if the given listener is already registered in this metadata source.