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
FieldsModifier and TypeFieldDescription(package private) final boolean
Whether the database needs to be created.private String
Path to the database to open on the local file system.private static final String
The property name for the home of Derby databases.private final Dialect
The database product to use.private DataSource
The database-provided data source. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
LocalDataSource
(Dialect dialect, String dbFile, boolean create) Prepares a new data source for the given database file. -
Method Summary
Modifier and TypeMethodDescriptionint
compareTo
(LocalDataSource other) Compares this data source with the given one for preference order.(package private) static LocalDataSource[]
Prepares potential data source for the spatial metadata database.(package private) final void
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.Attempts to establish a connection.getConnection
(String username, String password) Attempts to establish a connection.int
Returns the maximum time in seconds that this data source will wait while attempting to connect to a database.Returns the output stream to which all logging and tracing messages for this data source will be printed.Return the parent of all loggers used by this data source.private void
Creates the data source using the context class loader.static boolean
Returnstrue
if the given exception is the one that we expect in successful shutdown of a Derby database.boolean
isWrapperFor
(Class<?> type) Returns whetherunwrap(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.toString()
Returns a string representation for debugging purpose.<T> T
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
Methods inherited from interface javax.sql.CommonDataSource
createShardingKeyBuilder
Methods inherited from interface javax.sql.DataSource
createConnectionBuilder
-
Field Details
-
DERBY_HOME_KEY
The property name for the home of Derby databases.- See Also:
-
dialect
The database product to use. Currently supported values areDialect.DERBY
andDialect.HSQL
. -
dbFile
Path to the database to open on the local file system. This is the argument to give to theDataSource.setDatabaseName(String)
method. This value is set tonull
aftersource
creation because not needed anymore. -
source
The database-provided data source. -
create
final boolean createWhether the database needs to be created.
-
-
Constructor Details
-
LocalDataSource
Prepares a new data source for the given database file. This construction is incomplete; after return eitherinitialize()
shall be invoked or thisLocalDataSource
is discarded.- Parameters:
dialect
-Dialect.DERBY
orDialect.HSQL
.dbFile
- path to the database to open on the local file system.create
- whether the database needs to be created.
-
-
Method Details
-
create
Prepares potential data source for the spatial metadata database. This constructor prepares the path to local file(s), but actualDataSource
construction must be done by a call toinitialize()
after construction.- Parameters:
database
- database name (usually "SpatialMetadata").dialects
-Dialect.DERBY
and/orDialect.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
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 byInitializer.embedded()
.- Returns:
- the data source wrapped with a shutdown method, or
ds
.
-
initialize
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
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 theSpatialMetadata
sub-directory of the path given by thederby.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
Creates the database if needed. For Derby we need to explicitly allow creation. For HSQLDB the creation is enabled by default.- Throws:
Exception
-
shutdown
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
Returnstrue
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 ofnon-free:sis-embedded-data
module.- Parameters:
e
- the exception thrown by Derby.- Returns:
true
if the exception indicates a successful shutdown.
-
compareTo
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 interfaceComparable<LocalDataSource>
- Parameters:
other
- the other data source to compare with this one.- Returns:
- -1 if this data source is preferred to
other
, +1 ifother
is preferred tothis
, or 0 if no preference.
-
isWrapperFor
Returns whetherunwrap(Class)
can be invoked for the given type.- Specified by:
isWrapperFor
in interfaceWrapper
- 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
Returns an object of the given type to allow access to non-standard methods. The type can be eitherLocalDataSource
or any type supported by the wrapped data source.- Specified by:
unwrap
in interfaceWrapper
- Type Parameters:
T
- compile-time value oftype
.- 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
Attempts to establish a connection.- Specified by:
getConnection
in interfaceDataSource
- Returns:
- a connection to the locally installed database.
- Throws:
SQLException
- if a database access error occurs.
-
getConnection
Attempts to establish a connection.- Specified by:
getConnection
in interfaceDataSource
- 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
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 interfaceCommonDataSource
- Specified by:
getLoginTimeout
in interfaceDataSource
- Returns:
- the data source login time limit, or 0 for the default.
- Throws:
SQLException
- if a database access error occurs.
-
setLoginTimeout
Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.- Specified by:
setLoginTimeout
in interfaceCommonDataSource
- Specified by:
setLoginTimeout
in interfaceDataSource
- Parameters:
seconds
- the data source login time limit, or 0 for the default.- Throws:
SQLException
- if a database access error occurs.
-
getParentLogger
Return the parent of all loggers used by this data source. Can be used for configuring log messages.- Specified by:
getParentLogger
in interfaceCommonDataSource
- Returns:
- the parent of all loggers used by this data source.
- Throws:
SQLFeatureNotSupportedException
- if the data source does not use logging.
-
getLogWriter
Returns the output stream to which all logging and tracing messages for this data source will be printed. The default writer isnull
(logging disabled).- Specified by:
getLogWriter
in interfaceCommonDataSource
- Specified by:
getLogWriter
in interfaceDataSource
- Returns:
- the log writer, or null if logging is disabled.
- Throws:
SQLException
- if a database access error occurs.
-
setLogWriter
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 interfaceCommonDataSource
- Specified by:
setLogWriter
in interfaceDataSource
- Parameters:
out
- the log writer, or null if logging is disabled.- Throws:
SQLException
- if a database access error occurs.
-
toString
Returns a string representation for debugging purpose.
-