org.geotoolkit.coverage.sql
Class CoverageDatabase

Object
  CoverageDatabase

All Implemented Interfaces:

Localized

@ThreadSafe
public class CoverageDatabase
extends Object
implements Localized

A connection to a collection of coverages declared in a SQL database. The connection to the database is specified by a DataSource.

Every query methods in this class are executed in a background thread. In order to get the result immediately, the FutureQuery.result() convenience method can be used as in the example below:

CoverageDatabase database = ...; // Specify your database here.
Layer myLayer = database.getLayer("Temperature").result();
// Use the layer here...

However it is better to invoke FutureQuery.result() as late as possible, in order to have more work executed concurrently.

Since:

3.10

Version:

3.20

Author:

Martin Desruisseaux (Geomatys)

Module:

coverage/geotk-coverage-sql (download)

View source code for this class

Field Summary

static ParameterDescriptorGroup

PARAMETERS A description of the parameters expected by the CoverageDatabase constructors.

Constructor Summary

CoverageDatabase(DataSource datasource, ParameterValueGroup parameters)
Creates a new instance using the given data source and configuration parameters.

CoverageDatabase(DataSource datasource, Properties properties)
Creates a new instance using the given data source and configuration properties.

CoverageDatabase(ParameterValueGroup parameters)
Creates a new instance using the given parameters.

CoverageDatabase(Properties properties)
Creates a new instance using the given properties.

Method Summary

FutureQuery<Boolean>	addLayer(String name) Adds a new layer of the given name, if it does not already exist.
void	addListener(CoverageDatabaseListener listener) Adds the given object to the list of objects to notify about changes in database content.
LayerCoverageReader	createGridCoverageReader(String layer) Configures and returns a GridCoverageReader for the given layer.
LayerCoverageWriter	createGridCoverageWriter(String layer) Configures and returns a LayerCoverageWriter for the given layer.
void	dispose() Disposes the resources used by this database.
void	flush() Flushes the cache.
FutureQuery<SortedSet<Number>>	getAvailableElevations(String layer) Returns the set of altitudes where a coverage is available.
FutureQuery<SortedSet<Date>>	getAvailableTimes(String layer) Returns the set of dates when a coverage is available.
CoordinateReferenceSystem	getCoordinateReferenceSystem() Returns the Coordinate Reference System used by the database for indexing the coverages envelopes.
CRSAuthorityFactory	getCRSAuthorityFactory() Returns the CRS authority factory used by this database.
static CoverageDatabase	getDefaultInstance() Returns the default instance, or null if none.
FutureQuery<Layer>	getLayer(String name) Returns the layer of the given name.
FutureQuery<Set<String>>	getLayers() Returns the name of every layers is the database.
CoverageDatabaseListener[]	getListeners() Returns all listeners to notify about changes in database constent, or an empty array if none.
Locale	getLocale() Returns the locale used for formatting logging and error messages.
FutureQuery<List<MeasurementRange<?>>>	getSampleValueRanges(String layer) Returns the ranges of valid geophysics values for each band of the given layer.
FutureQuery<DateRange>	getTimeRange(String layer) Returns a time range encompassing all coverages in this layer.
FutureQuery<GridCoverage2D>	readSlice(String layer, CoverageEnvelope envelope, IIOListeners listeners) Reads the data of a two-dimensional slice and returns them as a coverage.
FutureQuery<Boolean>	removeLayer(String name) Removes the layer of the given name, if it exist.
void	removeListener(CoverageDatabaseListener listener) Removes the given object from the list of objects to notify about changes in database content.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PARAMETERS

public static final ParameterDescriptorGroup PARAMETERS

A description of the parameters expected by the CoverageDatabase constructors. See the package javadoc for an overview of those parameters.

Since:

3.18

Constructor Detail

CoverageDatabase

public CoverageDatabase(Properties properties)

Creates a new instance using the given properties. The properties shall contains at least an entry for the "URL" key. The value of this entry shall be a JDBC URL in the form of "jdbc:postgresql://host/database".

See the package javadoc for the list of parameters supported by this constructor.

Parameters:

properties - The configuration properties.

Since:

3.11

CoverageDatabase

public CoverageDatabase(ParameterValueGroup parameters)

Creates a new instance using the given parameters. This constructor provides the same functionality than CoverageDatabase(Properties), but using the ISO 19111 parameters construct instead than the Java properties.

See the package javadoc for the list of parameters supported by this constructor.

Parameters:

parameters - The configuration parameters.

Since:

3.18

CoverageDatabase

public CoverageDatabase(DataSource datasource,
                        Properties properties)

Creates a new instance using the given data source and configuration properties. See the package javadoc for the list of parameters supported by this constructor.

Parameters:

datasource - The data source, or null for creating it from the URL.

properties - The configuration properties, or null if none.

CoverageDatabase

public CoverageDatabase(DataSource datasource,
                        ParameterValueGroup parameters)

Creates a new instance using the given data source and configuration parameters. See the package javadoc for the list of parameters supported by this constructor.

This constructor provides the same functionality than CoverageDatabase(DataSource, Properties), but using the ISO 19111 parameters construct instead than the Java properties.

Parameters:

datasource - The data source, or null for creating it from the URL.

parameters - The configuration parameters, or null if none.

Since:

3.18

Method Detail

getDefaultInstance

public static CoverageDatabase getDefaultInstance()
                                           throws CoverageStoreException

Returns the default instance, or null if none. The default instance can be specified by the geotk-setup module.

Returns:

The default instance, or null if none.

Throws:

CoverageStoreException - If an error occurred while fetching the default instance.

Since:

3.11

getCRSAuthorityFactory

public CRSAuthorityFactory getCRSAuthorityFactory()
                                           throws FactoryException

Returns the CRS authority factory used by this database. This factory is typically backed by the PostGIS "spatial_ref_sys" table - this is usually not the standard EPSG factory used by default in the Geotk library. In particular, axis order are often different.

Returns:

The CRS authority factory used by this database.

Throws:

FactoryException - If the factory can not be created.

Since:

3.12

getCoordinateReferenceSystem

public CoordinateReferenceSystem getCoordinateReferenceSystem()

Returns the Coordinate Reference System used by the database for indexing the coverages envelopes. This is the "native" CRS in which this CoverageDatabase instance will transform the requested envelopes before to execute the queries.

Returns:

The "native" coordinate reference system.

Since:

3.11

getLayers

public FutureQuery<Set<String>> getLayers()

Returns the name of every layers is the database.

Returns:

The layer of the given name.

getLayer

public FutureQuery<Layer> getLayer(String name)

Returns the layer of the given name.

Parameters:

name - The layer name.

Returns:

The layer of the given name.

addLayer

public FutureQuery<Boolean> addLayer(String name)

Adds a new layer of the given name, if it does not already exist. If a layer of the given name already exists, then this method does nothing and returns false.

Parameters:

name - The name of the new layer.

Returns:

true if the layer has been added, of false if a layer of the given name already exists.

Since:

3.11

removeLayer

public FutureQuery<Boolean> removeLayer(String name)

Removes the layer of the given name, if it exist. If no layer of the given name exists, then this method does nothing and returns false.

This action removes all references to raster data declared in that layer, unless the foreigner key constraints in the database have been changed from their default values. Note that the raster files are never deleted by this method.

Parameters:

name - The name of the layer to remove.

Returns:

true if the layer has been removed, of false if no layer of the given name exists.

Since:

3.11

getTimeRange

public FutureQuery<DateRange> getTimeRange(String layer)

Returns a time range encompassing all coverages in this layer. This method is equivalent to the code below, except that more code are executed in the background thread:

return getLayer(layer).result().getTimeRange();

Parameters:

layer - The layer for which the time range is desired.

Returns:

The time range encompassing all coverages.

See Also:

Layer.getTimeRange()

getAvailableTimes

public FutureQuery<SortedSet<Date>> getAvailableTimes(String layer)

Returns the set of dates when a coverage is available. This method is equivalent to the code below, except that more code are executed in the background thread:

return getLayer(layer).result().getAvailableTimes();

Parameters:

layer - The layer for which the available times are desired.

Returns:

The set of dates.

See Also:

Layer.getAvailableTimes()

getAvailableElevations

public FutureQuery<SortedSet<Number>> getAvailableElevations(String layer)

Returns the set of altitudes where a coverage is available. This method is equivalent to the code below, except that more code are executed in the background thread:

return getLayer(layer).result().getAvailableElevations();

Parameters:

layer - The layer for which the available elevations are desired.

Returns:

The set of altitudes.

See Also:

Layer.getAvailableElevations()

getSampleValueRanges

public FutureQuery<List<MeasurementRange<?>>> getSampleValueRanges(String layer)

Returns the ranges of valid geophysics values for each band of the given layer. This method is equivalent to the code below, except that more code are executed in the background thread:

return getLayer(layer).result().getSampleValueRanges();

Parameters:

layer - The layer for which the range of measurement values is desired.

Returns:

The range of valid sample values.

See Also:

Layer.getSampleValueRanges()

readSlice

public FutureQuery<GridCoverage2D> readSlice(String layer,
                                             CoverageEnvelope envelope,
                                             IIOListeners listeners)

Reads the data of a two-dimensional slice and returns them as a coverage. Note that the returned two-dimensional slice is not guaranteed to have exactly the requested envelope. Callers may need to check the geometry of the returned envelope and perform an additional resampling if needed.

Parameters:

layer - The layer of the coverage to query.

envelope - The desired envelope and resolution, or null for all data.

listeners - The listeners, or null if none.

Returns:

The coverage.

Since:

3.20

See Also:

LayerCoverageReader.readSlice(int, GridCoverageReadParam)

createGridCoverageReader

public LayerCoverageReader createGridCoverageReader(String layer)
                                             throws CoverageStoreException

Configures and returns a GridCoverageReader for the given layer. This provides an alternative way (as compared to readSlice) for reading two-dimensional slices of coverage. This method is provided for inter-operability with libraries which want to access to the data through the GridCoverageReader API only.

Parameters:

layer - The name of the initial layer to be read by the returned reader, or null.

Returns:

A grid coverage reader using the given layer as input.

Throws:

CoverageStoreException - If an error occurred while querying the database.

createGridCoverageWriter

public LayerCoverageWriter createGridCoverageWriter(String layer)
                                             throws CoverageStoreException

Configures and returns a LayerCoverageWriter for the given layer. This method is provided for inter-operability with libraries which want to add data through the LayerCoverageWriter API only.

Parameters:

layer - The name of the initial layer to be read by the returned writer, or null.

Returns:

A grid coverage writer using the given layer as input.

Throws:

CoverageStoreException - If an error occurred while querying the database.

Since:

3.20

addListener

public void addListener(CoverageDatabaseListener listener)

Adds the given object to the list of objects to notify about changes in database content.

Parameters:

listener - The new listener to add.

Since:

3.12

removeListener

public void removeListener(CoverageDatabaseListener listener)

Removes the given object from the list of objects to notify about changes in database content. This method does nothing if the given object is not a member of the listener list.

Parameters:

listener - The listener to remove.

Since:

3.12

getListeners

public CoverageDatabaseListener[] getListeners()

Returns all listeners to notify about changes in database constent, or an empty array if none.

Returns:

All registered listeners, or an empty array if none.

Since:

3.12

getLocale

public Locale getLocale()

Returns the locale used for formatting logging and error messages.

Specified by:

getLocale in interface Localized

Returns:

The locale, or null for the default locale.

flush

public void flush()

Flushes the cache. This method shall be invoked when the database content has been changed by some other way than through the CoverageDatabase API.

dispose

public void dispose()

Disposes the resources used by this database.