Package org.apache.sis.storage.sql

Class SQLStore

java.lang.Object

org.apache.sis.storage.DataStore

org.apache.sis.storage.sql.SQLStore

All Implemented Interfaces:

AutoCloseable, Aggregate, Resource, Localized

public class SQLStore
extends DataStore
implements Aggregate

A data store capable to read and create features from a spatial database. SQLStore requires a DataSource to be specified (indirectly) at construction time. The DataSource should provide pooled connections, because SQLStore will frequently opens and closes them.

Since:

1.0

Version:

1.3

Field Summary

Fields

Modifier and Type	Field	Description
private final SchemaModifier	customizer	The user-specified method for customizing the schema inferred by table analysis.
private final GeometryLibrary	geomLibrary	The library to use for creating geometric objects, or null for system default.
private org.opengis.metadata.Metadata	metadata	The metadata, created when first requested.
private Database<?>	model	The result of inspecting database schema for deriving FeatureTypes.
private static final String[]	NAME_GETTERS	Names of possible public getter methods for data source title, in preference order.
private final ResourceDefinition[]	queries	Queries to expose as resources, or an empty array if none.
private final DataSource	source	The data source to use for obtaining connections to the database.
private final org.opengis.util.GenericName[]	tableNames	Fully qualified names (including catalog and schema) of the tables to include in this store.

Fields inherited from class org.apache.sis.storage.DataStore

listeners, provider

Constructor Summary

Constructors

Constructor	Description
SQLStore(SQLStoreProvider provider, StorageConnector connector, ResourceDefinition... resources)	Creates a new SQLStore for the given data source and tables, views or queries.

Method Summary

Modifier and Type	Method	Description
<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.
void	close()	Closes this SQL store and releases any underlying resources.
Collection<FeatureSet>	components()	Returns the tables (feature sets) in this SQL store.
FeatureSet	findResource(String identifier)	Searches for a resource identified by the given identifier.
Optional<org.opengis.util.GenericName>	getIdentifier()	SQL data store root resource has no identifier.
org.opengis.metadata.Metadata	getMetadata()	Returns information about the dataset as a whole.
Optional<org.opengis.parameter.ParameterValueGroup>	getOpenParameters()	Returns the parameters used to open this netCDF data store.
private Database<?>	model()	Returns the database model, analyzing the database schema when first needed.
private Database<?>	model(Connection c)	Returns the database model, analyzing the database schema when first needed.

Methods inherited from class org.apache.sis.storage.DataStore

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

removeListener

Field Details

NAME_GETTERS

private static final String[] NAME_GETTERS

Names of possible public getter methods for data source title, in preference order.

source

private final DataSource source

The data source to use for obtaining connections to the database.

geomLibrary

private final GeometryLibrary geomLibrary

The library to use for creating geometric objects, or null for system default.

model

private Database<?> model

The result of inspecting database schema for deriving FeatureTypes. Created when first needed. May be discarded and recreated if the store needs a refresh.

tableNames

private final org.opengis.util.GenericName[] tableNames

Fully qualified names (including catalog and schema) of the tables to include in this store. The names shall be qualified names of 1, 2 or 3 components. The name components can be <catalog>.<schema pattern>.<table pattern> where:

• <catalog>, if present, is the name of a catalog as stored in the database.
• <schema pattern>, if present, is the pattern of a schema. The pattern can use '_' and '%' wildcards characters.
• <table pattern> (mandatory) is the pattern of a table. The pattern can use '_' and '%' wildcards characters.

Only the main tables need to be specified; dependencies will be followed automatically.

queries

private final ResourceDefinition[] queries

Queries to expose as resources, or an empty array if none.

metadata

private org.opengis.metadata.Metadata metadata

The metadata, created when first requested.

customizer

private final SchemaModifier customizer

The user-specified method for customizing the schema inferred by table analysis. This is null if there is none.

Constructor Details

SQLStore

public SQLStore(SQLStoreProvider provider,
 StorageConnector connector,
 ResourceDefinition... resources)
         throws DataStoreException

Creates a new SQLStore for the given data source and tables, views or queries. The given connector shall contain a DataSource instance. Tables or views to include in the store are specified by the resources argument. Only the main tables need to be specified; dependencies will be followed automatically.

Parameters:

provider - the factory that created this DataStore instance, or null if unspecified.

connector - information about the storage (JDBC data source, etc).

resources - tables, views or queries to include in this store.

Throws:

DataStoreException - if an error occurred while creating the data store for the given storage.

Since:

1.1

Method Details

getOpenParameters

public Optional<org.opengis.parameter.ParameterValueGroup> getOpenParameters()

Returns the parameters used to open this netCDF data store. The parameters are described by SQLStoreProvider.getOpenParameters() and contains at least a parameter named "location" with a DataSource value.

Specified by:

getOpenParameters in class DataStore

Returns:

parameters used for opening this data store.

See Also:

• DataStoreProvider.getOpenParameters()

getIdentifier

public Optional<org.opengis.util.GenericName> getIdentifier()
                                                     throws DataStoreException

SQL data store root resource has no identifier.

Specified by:

getIdentifier in interface Resource

Overrides:

getIdentifier in class DataStore

Returns:

empty.

Throws:

DataStoreException - if an error occurred while fetching the identifier.

See Also:

• DataStore.getMetadata()
• DataStore.getDisplayName()

model

private Database<?> model()
                   throws DataStoreException

Returns the database model, analyzing the database schema when first needed.

Throws:

DataStoreException

model

private Database<?> model(Connection c)
                   throws Exception

Returns the database model, analyzing the database schema when first needed. This method performs the same work than model(), but using an existing connection. Callers must own a synchronization lock on this.

Parameters:

c - connection to the database.

Throws:

Exception

getMetadata

public org.opengis.metadata.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:

getMetadata in interface Resource

Specified by:

getMetadata in class DataStore

Returns:

information about the dataset.

Throws:

DataStoreException - if an error occurred while reading the data.

See Also:

• DataStore.getIdentifier()
• DefaultMetadata.deepCopy(Metadata)

components

public Collection<FeatureSet> components()
                                  throws DataStoreException

Returns the tables (feature sets) in this SQL store. The list contains only the tables explicitly named at construction time.

Specified by:

components in interface Aggregate

Returns:

children resources that are components of this SQL store.

Throws:

DataStoreException - if an error occurred while fetching the components.

findResource

public FeatureSet findResource(String identifier)
                        throws DataStoreException

Searches for a resource identified by the given identifier. The given identifier should match one of the table names. It may be one of the tables named at construction time, or one of the dependencies. The given name may be qualified with the schema name, or may be only the table name if there is no ambiguity.

Overrides:

findResource in class DataStore

Parameters:

identifier - identifier of the resource to fetch. Must be non-null.

Returns:

resource associated to the given identifier (never null).

Throws:

IllegalNameException - if no resource is found for the given identifier, or if more than one resource is found.

DataStoreException - if another kind of error occurred while searching resources.

See Also:

• Resource.getIdentifier()
• FeatureNaming

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 WarningEvents; any listener specified for another kind of events will be ignored.

Specified by:

addListener in interface Resource

Overrides:

addListener in class DataStore

Type Parameters:

T - compile-time value of the eventType argument.

Parameters:

eventType - type of StoreEvent to listen (cannot be null).

listener - listener to notify about events.

close

public void close()
           throws DataStoreException

Closes this SQL store and releases any underlying resources.

Specified by:

close in interface AutoCloseable

Specified by:

close in class DataStore

Throws:

DataStoreException - if an error occurred while closing the SQL store.

See Also:

• StoreListeners.close()