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
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final class 
    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
    true if connected(DatabaseMetaData) has been invoked at least once.
    static final String
    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
    Name of the JNDI resource to lookup in the "java:comp/env" context.
    private static DataSource
    The unique, SIS-wide, data source to the $SIS_DATA/Databases/SpatialMetadata database.
    private static Supplier<DataSource>
    Data source specified by the user, to be used if no data source is specified by JNDI.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    For subclasses only.
  • Method Summary

    Modifier and Type
    Method
    Description
    static LogRecord
    Prepares a log record saying that a connection to the spatial metadata database has been created.
    protected abstract void
    Invoked for populating an initially empty database.
    protected abstract void
    Invoked when the JNDI data source associated to "jdbc/SpatialMetadata" changed.
    private static DataSource
    If the non-free:sis-embedded-data module is present on the classpath, returns the data source for embedded Derby database.
    static DataSource
    Returns the data source for the SIS-wide "SpatialMetadata" database.
    static boolean
    Returns true if SIS will try to fetch the DataSource from JNDI.
    static boolean
    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
    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:
    • JNDI

      public static final String JNDI
      Name of the JNDI resource to lookup in the "java:comp/env" context.
      See Also:
    • 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:
    • 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:
    • 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:
    • 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.
    • 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:
    • 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.