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: All other methods are related to getting the DataSource instance, through JNDI or otherwise.
Since:
0.7
Version:
1.2
Author:
Martin Desruisseaux (Geomatys)

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    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.

  • 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.
    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.
    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:

    • JNDI

      public static final String JNDI
      Name of the JNDI resource to lookup in the "java:comp/env" context.
      See Also:

  • 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:

    • 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:

    • 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.

    • 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.