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

Class LocalDataSource

java.lang.Object
org.apache.sis.internal.metadata.sql.LocalDataSource
All Implemented Interfaces:
Comparable<LocalDataSource>, Wrapper, CommonDataSource, DataSource
public final class LocalDataSource extends Object implements DataSource, Comparable<LocalDataSource>
A data source for a database stored locally in the $SIS_DATA directory. This class wraps the database-provided DataSource with the addition of a shutdown method. It provides our starting point for initiating the system-wide connection.
Since:
1.1
Version:
1.2

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) final boolean
    create
    Whether the database needs to be created.
    private String
    dbFile
    Path to the database to open on the local file system.
    private static final String
    DERBY_HOME_KEY
    The property name for the home of Derby databases.
    private final Dialect
    dialect
    The database product to use.
    private DataSource
    source
    The database-provided data source.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    LocalDataSource(Dialect dialect, String dbFile, boolean create)
    Prepares a new data source for the given database file.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    compareTo(LocalDataSource other)
    Compares this data source with the given one for preference order.
    (package private) static LocalDataSource[]
    create(String database, Dialect... dialects)
    Prepares potential data source for the spatial metadata database.
    (package private) final void
    createDatabase()
    Creates the database if needed.
    (package private) static LocalDataSource
    findDriver(LocalDataSource[] sources)
    Returns the first data source from the given array that can be initialized.
    Connection
    getConnection()
    Attempts to establish a connection.
    Connection
    getConnection(String username, String password)
    Attempts to establish a connection.
    int
    getLoginTimeout()
    Returns the maximum time in seconds that this data source will wait while attempting to connect to a database.
    PrintWriter
    getLogWriter()
    Returns the output stream to which all logging and tracing messages for this data source will be printed.
    Logger
    getParentLogger()
    Return the parent of all loggers used by this data source.
    private void
    initialize()
    Creates the data source using the context class loader.
    static boolean
    isSuccessfulShutdown(SQLException e)
    Returns true if the given exception is the one that we expect in successful shutdown of a Derby database.
    boolean
    isWrapperFor(Class<?> type)
    Returns whether unwrap(Class) can be invoked for the given type.
    void
    setLoginTimeout(int seconds)
    Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.
    void
    setLogWriter(PrintWriter out)
    Sets the output stream to which all logging and tracing messages for this data source will be printed.
    (package private) final void
    shutdown()
    Shutdowns the database used by this data source.
    String
    toString()
    Returns a string representation for debugging purpose.
    <T> T
    unwrap(Class<T> type)
    Returns an object of the given type to allow access to non-standard methods.
    (package private) static DataSource
    wrap(DataSource ds)
    Wraps an existing data source for adding a shutdown method to it.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • DERBY_HOME_KEY

      private static final String DERBY_HOME_KEY
      The property name for the home of Derby databases.
      See Also:

    • dialect

      private final Dialect dialect
      The database product to use. Currently supported values are Dialect.DERBY and Dialect.HSQL.

    • dbFile

      private String dbFile
      Path to the database to open on the local file system. This is the argument to give to the DataSource.setDatabaseName(String) method. This value is set to null after source creation because not needed anymore.

    • source

      private DataSource source
      The database-provided data source.

    • create

      final boolean create
      Whether the database needs to be created.

  • Constructor Details

    • LocalDataSource

      private LocalDataSource(Dialect dialect, String dbFile, boolean create)
      Prepares a new data source for the given database file. This construction is incomplete; after return either initialize() shall be invoked or this LocalDataSource is discarded.
      Parameters:
      dialect - Dialect.DERBY or Dialect.HSQL.
      dbFile - path to the database to open on the local file system.
      create - whether the database needs to be created.

  • Method Details

    • create

      static LocalDataSource[] create(String database, Dialect... dialects)
      Prepares potential data source for the spatial metadata database. This constructor prepares the path to local file(s), but actual DataSource construction must be done by a call to initialize() after construction.
      Parameters:
      database - database name (usually "SpatialMetadata").
      dialects - Dialect.DERBY and/or Dialect.HSQL.
      Returns:
      the local data sources (not yet initialized), or null if none. If non-null, then the array is guaranteed to contain at least one element.

    • wrap

      static DataSource wrap(DataSource ds)
      Wraps an existing data source for adding a shutdown method to it. This method is used for source of data embedded in a separated JAR file.
      Parameters:
      ds - the data source, usually given by Initializer.embedded().
      Returns:
      the data source wrapped with a shutdown method, or ds.

    • initialize

      private void initialize() throws ReflectiveOperationException
      Creates the data source using the context class loader. It is caller's responsibility to shutdown the database after usage.
      Throws:
      ClassNotFoundException - if the database driver is not on the classpath.
      ReflectiveOperationException - if an error occurred while setting the properties on the data source.

    • findDriver

      static LocalDataSource findDriver(LocalDataSource[] sources) throws Exception
      Returns the first data source from the given array that can be initialized. The database may be located in the $SIS_DATA/Databases/SpatialMetadata directory, or in the SpatialMetadata sub-directory of the path given by the derby.system.home property.

      This method does not create the database if it does not exist, because this method does not know if we are inside the $SIS_DATA directory.

      It is caller's responsibility to shutdown the database after usage.

      Parameters:
      sources - the data sources to try.
      Returns:
      the first data source for which a driver is available.
      Throws:
      ClassNotFoundException - if no database driver is not on the classpath.
      Exception - if the operation failed for another reason.

    • createDatabase

      final void createDatabase() throws Exception
      Creates the database if needed. For Derby we need to explicitly allow creation. For HSQLDB the creation is enabled by default.
      Throws:
      Exception

    • shutdown

      final void shutdown() throws ReflectiveOperationException
      Shutdowns the database used by this data source.
      Throws:
      ReflectiveOperationException - if an error occurred while setting the shutdown property on the Derby data source.

    • isSuccessfulShutdown

      public static boolean isSuccessfulShutdown(SQLException e)
      Returns true if the given exception is the one that we expect in successful shutdown of a Derby database. While this method is primarily used for Derby shutdown, the error code tested may be applicable to other systems.
      Note: this method is public for the needs of non-free:sis-embedded-data module.
      Parameters:
      e - the exception thrown by Derby.
      Returns:
      true if the exception indicates a successful shutdown.

    • compareTo

      public int compareTo(LocalDataSource other)
      Compares this data source with the given one for preference order. The preferred data sources are the ones for a database that already exists.
      Specified by:
      compareTo in interface Comparable<LocalDataSource>
      Parameters:
      other - the other data source to compare with this one.
      Returns:
      -1 if this data source is preferred to other, +1 if other is preferred to this, or 0 if no preference.

    • isWrapperFor

      public boolean isWrapperFor(Class<?> type) throws SQLException
      Returns whether unwrap(Class) can be invoked for the given type.
      Specified by:
      isWrapperFor in interface Wrapper
      Parameters:
      type - the interface or implementation type of desired wrapped object.
      Returns:
      whether unwrap(Class) can be invoked for the given type.
      Throws:
      SQLException - if an error occurs while checking wrappers.

    • unwrap

      public <T> T unwrap(Class<T> type) throws SQLException
      Returns an object of the given type to allow access to non-standard methods. The type can be either LocalDataSource or any type supported by the wrapped data source.
      Specified by:
      unwrap in interface Wrapper
      Type Parameters:
      T - compile-time value of type.
      Parameters:
      type - the interface or implementation type of desired wrapped object.
      Returns:
      an object of the given type.
      Throws:
      SQLException - if there is no object of the given type.

    • getConnection

      public Connection getConnection() throws SQLException
      Attempts to establish a connection.
      Specified by:
      getConnection in interface DataSource
      Returns:
      a connection to the locally installed database.
      Throws:
      SQLException - if a database access error occurs.

    • getConnection

      public Connection getConnection(String username, String password) throws SQLException
      Attempts to establish a connection.
      Specified by:
      getConnection in interface DataSource
      Parameters:
      username - the database user.
      password - the user's password.
      Returns:
      a connection to the locally installed database.
      Throws:
      SQLException - if a database access error occurs.

    • getLoginTimeout

      public int getLoginTimeout() throws SQLException
      Returns the maximum time in seconds that this data source will wait while attempting to connect to a database. Initial value is 0, meaning default timeout or no timeout.
      Specified by:
      getLoginTimeout in interface CommonDataSource
      Returns:
      the data source login time limit, or 0 for the default.
      Throws:
      SQLException - if a database access error occurs.

    • setLoginTimeout

      public void setLoginTimeout(int seconds) throws SQLException
      Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.
      Specified by:
      setLoginTimeout in interface CommonDataSource
      Parameters:
      seconds - the data source login time limit, or 0 for the default.
      Throws:
      SQLException - if a database access error occurs.

    • getParentLogger

      public Logger getParentLogger() throws SQLFeatureNotSupportedException
      Return the parent of all loggers used by this data source. Can be used for configuring log messages.
      Specified by:
      getParentLogger in interface CommonDataSource
      Returns:
      the parent of all loggers used by this data source.
      Throws:
      SQLFeatureNotSupportedException - if the data source does not use logging.

    • getLogWriter

      public PrintWriter getLogWriter() throws SQLException
      Returns the output stream to which all logging and tracing messages for this data source will be printed. The default writer is null (logging disabled).
      Specified by:
      getLogWriter in interface CommonDataSource
      Returns:
      the log writer, or null if logging is disabled.
      Throws:
      SQLException - if a database access error occurs.

    • setLogWriter

      public void setLogWriter(PrintWriter out) throws SQLException
      Sets the output stream to which all logging and tracing messages for this data source will be printed. This method needs to be invoked for enabling logging.
      Specified by:
      setLogWriter in interface CommonDataSource
      Parameters:
      out - the log writer, or null if logging is disabled.
      Throws:
      SQLException - if a database access error occurs.

    • toString

      public String toString()
      Returns a string representation for debugging purpose.
      Overrides:
      toString in class Object
      Returns:
      an arbitrary string representation.