Class SQLStore

Object
DataStore
SQLStore
All Implemented Interfaces:
Auto­Closeable, Aggregate, Resource, Localized
Direct Known Subclasses:
Simple­Feature­Store
public abstract class SQLStore extends DataStore implements Aggregate
An abstract data store for reading or writing resources from/to a spatial database. SQLStore requires a Data­Source to be specified (indirectly) at construction time. While not mandatory, a pooled data source is recommended because SQLStore may open and close connections many times.

This class provides basic support for ISO 19125-2, also known as OGC Simple feature access - Part 2: SQL option: selected tables, views and queries can be viewed as Feature­Set resources. This selection is specified by implementing the read­Resource­Definitions(Data­Access) method. The mapping from table structures to feature types is described in the package Javadoc.

Since:
1.0

  • Field Details

    • source

      protected final DataSource source
      The data source to use for obtaining connections to the database. This is the storage given (indirectly, through the Storage­Connector argument) at construction time.
      Since:
      1.5
      See Also:

    • contentLocale

      protected final Locale contentLocale
      The locale to use for international texts to write in a database table. This is not necessarily the same locale as Data­Store​.get­Locale(), because the latter is for warning and error messages to shown in user applications.

      Example: if a new CRS needs to be added in the "SPATIAL_REF_SYS" table and if that table contains a "description" column (as in the Geopackage format), then the text to write in that column will be localized with this locale.

      If the value is null, then a default locale is used.

      Since:
      1.5
      See Also:

  • Constructor Details

    • SQLStore

      protected SQLStore(DataStoreProvider provider, StorageConnector connector) throws DataStoreException
      Creates a new SQLStore for the given data source. The given connector shall contain a Data­Source instance. Tables or views to include in the store will be specified by the read­Resource­Definitions(Data­Access) method, which will be invoked when first needed.
      Parameters:
      provider - the factory that created this Data­Store instance, or null if unspecified.
      connector - information about the storage (JDBC data source, etc).
      Throws:
      Data­Store­Exception - if an error occurred while creating the data store for the given storage.
      Since:
      1.5

  • Method Details

    • initialize

      protected void initialize(Connection connection) throws DataStoreException, SQLException
      Invoked the first time that SQLStore opens a connection on the database, or after refresh. The default implementation does nothing. Subclasses can override this method if they need to create tables in an empty database, or for fetching more information.

      If refresh() has been invoked, then this initialization method will be invoked again the next time that a connection is needed. This method is invoked before read­Resource­Definitions(Data­Access).

      Parameters:
      connection - a connection to the database.
      Throws:
      Data­Store­Exception - if an error occurred during the initialization.
      SQLException - if an error occurred during the execution of an SQL query.
      Since:
      1.5

    • getDataSource

      public DataSource getDataSource()
      Returns the data source to use for obtaining connections to the database.
      Returns:
      the data source to use for obtaining connections to the database.
      Since:
      1.5

    • getOpenParameters

      public Optional<ParameterValueGroup> getOpenParameters()
      Returns parameters that can be used for opening this SQL data store. The parameters are described by SQLStore­Provider​.get­Open­Parameters() and contains at least a parameter named "location" with a Data­Source value.
      Specified by:
      get­Open­Parameters in class Data­Store
      Returns:
      parameters used for opening this data store.
      See Also:

    • getIdentifier

      public Optional<GenericName> getIdentifier() throws DataStoreException
      Returns an identifier for the root resource of this SQL store, or an empty value if none. The default implementation returns the database name if this property can be found in the Data­Source implementation.
      Specified by:
      get­Identifier in interface Resource
      Overrides:
      get­Identifier in class Data­Store
      Returns:
      an identifier for the root resource of this SQL store.
      Throws:
      Data­Store­Exception - if an error occurred while fetching the identifier.
      See Also:

    • getDatabaseSoftwareVersions

      public Map<String,Version> getDatabaseSoftwareVersions() throws DataStoreException
      Returns the version of the database software, together with versions of extensions if any. For example, in the case of a database on PostgreSQL, this map may contain two entries: the first one with the "PostgreSQL" key, optionally followed by an entry with the "PostGIS" key.
      Returns:
      version of the database software as the first entry, followed by versions of extensions if any.
      Throws:
      Data­Store­Exception - if an error occurred while fetching the metadata.
      Since:
      1.5

    • getMetadata

      public Metadata getMetadata() throws DataStoreException
      Returns information about the dataset as a whole. The returned metadata object can contain information such as the list of feature types.
      Specified by:
      get­Metadata in interface Resource
      Specified by:
      get­Metadata in class Data­Store
      Returns:
      information about the dataset.
      Throws:
      Data­Store­Exception - if an error occurred while fetching the metadata.
      See Also:

    • components

      public Collection<? extends Resource> components() throws DataStoreException
      Returns the resources (feature set or coverages) in this SQL store. The collection of resources should be constructed only when first needed and cached for future invocations of this method. The cache can be cleared by refresh(). This method should not load immediately the whole data of the Resource elements, as Resource sub-interfaces provide the API for deferred loading.

      Default implementation

      By default, the collection contains one Feature­Set per table, view or query matching a Resource­Definition returned by read­Resource­Definitions(Data­Access).
      Specified by:
      components in interface Aggregate
      Returns:
      children resources that are components of this SQL store.
      Throws:
      Data­Store­Exception - if an error occurred while fetching the components.

    • findResource

      public Resource findResource(String identifier) throws DataStoreException
      Searches for a resource identified by the given identifier. This method shall recognize at least the identifiers of the resources returned by components(), but may also (optionally) recognize the identifiers of auxiliary resources such as component dependencies (e.g., tables referenced by foreigner keys).

      Default implementation

      By default, this method searches for a table, view or query with a name matching the given identifier. The scope of the search includes the tables, views or queries matching a Resource­Definition, together with other tables referenced by foreigner keys (the dependencies). The given identifier may be qualified with the schema name, or may be only the table name if there is no ambiguity.
      Overrides:
      find­Resource in class Data­Store
      Parameters:
      identifier - identifier of the resource to fetch. Must be non-null.
      Returns:
      resource associated to the given identifier (never null).
      Throws:
      Illegal­Name­Exception - if no resource is found for the given identifier, or if more than one resource is found.
      Data­Store­Exception - if another kind of error occurred while searching resources.
      See Also:

    • readResourceDefinitions

      protected abstract ResourceDefinition[] readResourceDefinitions(DataAccess dao) throws DataStoreException
      A callback for providing the resource definitions of a database, typically from a content table. SQLStore will invoke this method when first needed after construction or after calls to refresh(). Implementations can use the SQL connection and methods provided by the dao argument. This method does not need to cache the result.
      Example: in a database conform to the Geopackage standard, the resource definitions are provided by the "gpkg_contents" table. Therefore, the
      invalid reference 
      org​.apache​.sis​.storage​.geopackage​.Gpkg­Store
      subclass will read the content of that table every times this method is invoked.
      Parameters:
      dao - low-level access (such as SQL connection) to the database.
      Returns:
      tables or views to include in the store. Only the main tables need to be specified. Dependencies (inferred from the foreigner keys) will be followed automatically.
      Throws:
      Data­Store­Exception - if an error occurred while fetching the resource definitions.
      Since:
      1.5
      See Also:

    • newDataAccess

      public DataAccess newDataAccess(boolean write)
      Creates a new low-level data access object. Each Data­Access instance can provide a single SQL Connection to the database (sometime protected by a read or write lock), together with methods for fetching or adding CRS definitions from/into the SPATIAL_REF_SYS table.

      The returned object shall be used in a try ... finally block. This is needed not only for closing the connection, but also for releasing read or write lock. Example:

      try (DataAccess dao = newDataAccess(false)) {
    try (Statement stmt = dao.getConnection().createStatement()) {
        // Perform some SQL queries here.
    }
}
      Parameters:
      write - whether write operations may be performed.
      Returns:
      an object provider low-level access (e.g. through SQL queries) to the data.
      Since:
      1.5

    • addListener

      public <T extends StoreEvent> void addListener(Class<T> eventType, StoreListener<? super T> listener)
      Registers a listener to notify when the specified kind of event occurs in this data store. The current implementation of this data store can emit only Warning­Events; any listener specified for another kind of events will be ignored.
      Specified by:
      add­Listener in interface Resource
      Overrides:
      add­Listener in class Data­Store
      Type Parameters:
      T - compile-time value of the event­Type argument.
      Parameters:
      event­Type - type of Store­Event to listen (cannot be null).
      listener - listener to notify about events.

    • vacuum

      public void vacuum() throws DataStoreException
      Executes the "VACUUM" statement on the database. This is a non-standard feature that exists on some databases such as PostgreSQL and SQLite. This method executes the statement only if the SQL keywords declared in the database metadata contains "VACUUM", ignoring case.

      This is a potentially costly operation which should be rarely executed. A typical use case if to compress a newly created Geopackage file (which are SQLite database).

      Throws:
      Data­Store­Exception - if an error occurred while executing the vacuum.
      Since:
      1.5

    • refresh

      public void refresh()
      Clears the cache so that next operations will reload all needed information from the database. This method can be invoked when the database content has been modified by a process other than the methods in this class.
      Since:
      1.5

    • close

      public void close() throws DataStoreException
      Closes this SQL store and releases any underlying resources.
      Specified by:
      close in interface Auto­Closeable
      Specified by:
      close in class Data­Store
      Throws:
      Data­Store­Exception - if an error occurred while closing the SQL store.
      See Also: