Package org.apache.sis.internal.metadata.sql

Class Initializer

java.lang.Object

org.apache.sis.internal.metadata.sql.Initializer

Direct Known Subclasses:

DatabaseListener

public abstract class Initializer
extends Object

Manages the unique DataSource instance to the $SIS_DATA/Databases/SpatialMetadata database. This includes initialization of a new database if none existed. The schemas will be created by subclasses of this Initializer class, which must be registered in the following file: Initializer implementations should define the following methods:

• createSchema(Connection) — invoked when a new database is created.
• dataSourceChanged() — invoked when the data source changed.

All other methods are related to getting the DataSource instance, through JNDI or otherwise.

Since:

0.7

Version:

1.2

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static final class	Initializer.Listener	A JNDI listener for being informed of changes in the DataSource associated to "jdbc/SpatialMetadata".

Field Summary

Fields

Modifier and Type	Field	Description
private static boolean	connected	true if connected(DatabaseMetaData) has been invoked at least once.
static final String	DATABASE	Name of the database to open in the $SIS_DATA/Databases directory or the directory given by the derby.system.home property.
static final String	JNDI	Name of the JNDI resource to lookup in the "java:comp/env" context.
private static DataSource	source	The unique, SIS-wide, data source to the $SIS_DATA/Databases/SpatialMetadata database.
private static Supplier<DataSource>	supplier	Data source specified by the user, to be used if no data source is specified by JNDI.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Initializer()	For subclasses only.

Method Summary

Modifier and Type	Method	Description
static LogRecord	connected(DatabaseMetaData metadata)	Prepares a log record saying that a connection to the spatial metadata database has been created.
protected abstract void	createSchema(Connection connection)	Invoked for populating an initially empty database.
protected abstract void	dataSourceChanged()	Invoked when the JNDI data source associated to "jdbc/SpatialMetadata" changed.
private static DataSource	embedded()	If the non-free:sis-embedded-data module is present on the classpath, returns the data source for embedded Derby database.
static DataSource	getDataSource()	Returns the data source for the SIS-wide "SpatialMetadata" database.
static boolean	hasJNDI()	Returns true if SIS will try to fetch the DataSource from JNDI.
static boolean	setDefault(Supplier<DataSource> ds)	Specifies the data source to use if there is no JNDI environment or if no data source is binded to jdbc/SpatialMetadata.
private static void	shutdown()	Invoked when the JVM is shutting down, or when the Servlet or OSGi bundle is uninstalled.
static Object	unspecified(Locale locale, boolean asLog)	Returns a message for unspecified data source.

Methods inherited from class java.lang.Object

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

Field Details

DATABASE

public static final String DATABASE

Name of the database to open in the $SIS_DATA/Databases directory or the directory given by the derby.system.home property.

Note: this field is public for the needs of non-free:sis-embedded-data module.

See Also:

• Constant Field Values

JNDI

public static final String JNDI

Name of the JNDI resource to lookup in the "java:comp/env" context.

See Also:

• Constant Field Values

supplier

private static Supplier<DataSource> supplier

Data source specified by the user, to be used if no data source is specified by JNDI.

See Also:

• setDefault(Supplier)

source

private static DataSource source

The unique, SIS-wide, data source to the $SIS_DATA/Databases/SpatialMetadata database. Created when first needed, and cleared on shutdown.

See Also:

• getDataSource()

connected

private static boolean connected

true if connected(DatabaseMetaData) has been invoked at least once. This is reset to false if the source is changed. We use this information for logging purpose.

Constructor Details

Initializer

protected Initializer()

For subclasses only.

Method Details

createSchema

protected abstract void createSchema(Connection connection)
                              throws SQLException

Invoked for populating an initially empty database.

Parameters:

connection - connection to the empty database.

Throws:

SQLException - if an error occurred while populating the database.

dataSourceChanged

protected abstract void dataSourceChanged()

Invoked when the JNDI data source associated to "jdbc/SpatialMetadata" changed.

setDefault

@Configuration
public static boolean setDefault(Supplier<DataSource> ds)

Specifies the data source to use if there is no JNDI environment or if no data source is binded to jdbc/SpatialMetadata. Data source specified by JNDI has precedence over this supplier in order to let users control their data source. This method does nothing if the data source has already been initialized.

Initializer will not register any shutdown process for user supplied data source. We presume that database life cycle is managed by the caller.

Parameters:

ds - supplier of data source to set, or null for removing previous supplier. This supplier may return null, in which case it will be ignored.

Returns:

whether the given data source supplier has been successfully set.

Since:

1.0

See Also:

• Configuration.setDatabase(Supplier)

getDataSource

public static DataSource getDataSource()
                                throws Exception

Returns the data source for the SIS-wide "SpatialMetadata" database. This method returns the first of the following steps that succeed:

1. If a JNDI context exists, use the data source registered under the "jdbc/SpatialMetadata" name.
2. Otherwise if a default data source has been supplied, use that data source.
3. Otherwise if the SIS_DATA environment variable is defined, use the data source for "jdbc:derby:$SIS_DATA/Databases/SpatialMetadata". That database will be created if it does not exist. Note that this is the only case where Apache SIS may create the database since it is located in the directory managed by Apache SIS.
4. Otherwise if the non-free:sis-embedded-data module is present on the classpath, use the embedded database.
5. Otherwise if the "derby.system.home" property is defined, use the data source for "jdbc:derby:SpatialMetadata". This database will not be created if it does not exist.
6. Otherwise (no JNDI, no environment variable, no Derby property set), null.

The Derby database may be replaced by a HSQLDB database in above steps.

Returns:

the data source for the $SIS_DATA/Databases/SpatialMetadata or equivalent database, or null if none.

Throws:

NamingException - if an error occurred while fetching the data source from a JNDI context.

MalformedURLException - if an error occurred while converting the derby.jar file to URL.

ClassNotFoundException - if derby.jar has not been found on the JDK installation directory.

InstantiationException - if an error occurred while creating org.apache.derby.jdbc.EmbeddedDataSource.

NoSuchMethodException - if a JDBC bean property has not been found on the data source.

IllegalAccessException - if a JDBC bean property of the data source is not public.

InvocationTargetException - if an error occurred while setting a data source bean property.

Exception - for any other kind of errors. This include RuntimeException not documented above like IllegalArgumentException, ClassCastException, SecurityException, etc.

See Also:

• Configuration.getDatabase()

hasJNDI

public static boolean hasJNDI()

Returns true if SIS will try to fetch the DataSource from JNDI.

Returns:

true if a JNDI environment seems to be present.

embedded

private static DataSource embedded()

If the non-free:sis-embedded-data module is present on the classpath, returns the data source for embedded Derby database. Otherwise returns null.

Since:

0.8

See Also:

• SIS-337

connected

public static LogRecord connected(DatabaseMetaData metadata)
                           throws SQLException

Prepares a log record saying that a connection to the spatial metadata database has been created. This method can be invoked after DataSource.getConnection(). When invoked for the first time, the record level is set to Level.CONFIG. On next calls, the level become Level.FINE.

Parameters:

metadata - the value of DataSource.getConnection().getMetaData() or equivalent.

Returns:

the record to log. Caller should set the source class name and source method name.

Throws:

SQLException - if an error occurred while fetching the database URL.

Since:

0.8

unspecified

public static Object unspecified(Locale locale,
 boolean asLog)

Returns a message for unspecified data source. The message will depend on whether a JNDI context exists or not. This message can be used for constructing an exception when getDataSource() returned null.

Parameters:

locale - the locale for the message to produce, or null for the default one.

asLog - true for returning the message as a LogRecord, false for a String.

Returns:

message for unspecified data source.

shutdown

private static void shutdown()
                      throws ReflectiveOperationException,
SQLException

Invoked when the JVM is shutting down, or when the Servlet or OSGi bundle is uninstalled. This method shutdowns the Derby database.

Throws:

ReflectiveOperationException - if an error occurred while setting the shutdown property on the Derby data source.

SQLException - if call to Wrapper.unwrap(Class) failed. This exception should never happen since source should always be an instance of LocalDataSource when this method is invoked, and SQLException thrown by the database are not propagated here.