org.sormula
Class Database

java.lang.Object
  extended by org.sormula.Database
All Implemented Interfaces:
TypeTranslatorMap
Direct Known Subclasses:
OperationDatabase

public class Database
extends java.lang.Object
implements TypeTranslatorMap

Source of Table objects for reading/writing from/to database. For single threaded use only. Construct new instances for each transaction and/or thread.

Example - Construct database from JDBC connection:

 Connection connection = ... // jdbc connection
 Database database = new Database(connection);
 Table<MyRow> table = database.getTable(MyRow.class);
 table.selectAll();
 

Example - Construct database from JNDI:

 Database database = new Database("java:comp/env/mydatasource");
 Table<MyRow> table = database.getTable(MyRow.class);
 table.selectAll();
 

Since:
1.0
Author:
Jeff Miller

Constructor Summary
Database(java.sql.Connection connection)
          Constructs for no schema.
Database(java.sql.Connection connection, java.lang.String schema)
          Constructs for schema.
Database(javax.sql.DataSource dataSource)
          Constructs for no schema.
Database(javax.sql.DataSource dataSource, java.lang.String schema)
          Constructs for schema.
Database(java.lang.String dataSourceName)
          Constructs for JNDI name and no schema.
Database(java.lang.String dataSourceName, java.lang.String schema)
          Constructs for JNDI name and schema.
 
Method Summary
 void addNameTranslatorClass(java.lang.Class<? extends NameTranslator> nameTranslatorClass)
          Adds a default name translator class.
 void addTable(Table<?> table)
          Adds a table object to cache to be used for row objects of type Object.getClass().
 void close()
          Dereferences all objects used.
 OperationTime createOperationTime(java.lang.String timingId, java.lang.String description)
          Creates an OperationTime instance with this database total time, getTotalOperationTime() as the parent time.
 java.sql.Connection getConnection()
          Gets connection to use for sql operations.
 javax.sql.DataSource getDataSource()
          Gets data source supplied in constructors, Database(DataSource) and Database(DataSource, String).
 java.lang.String getDataSourceName()
          Gets the JNDI name to use to look up DataSource.
 java.lang.Class<? extends NameTranslator> getNameTranslatorClass()
          Deprecated. 
 java.util.List<java.lang.Class<? extends NameTranslator>> getNameTranslatorClasses()
          Gets the default name translator classes for tables when none is specified for the table.
 OperationTime getOperationTime(java.lang.String timingId)
          Gets the operation time for a specific timing id.
 java.util.Map<java.lang.String,OperationTime> getOperationTimeMap()
          Gets operation times for all operations have been executed.
 java.lang.String getSchema()
          Gets the schema name supplied in constructor.
<R> Table<R>
getTable(java.lang.Class<R> rowClass)
          Gets table object for reading/writing row objects of type R from/to table.
<R> Table<R>
getTable(java.lang.Class<R> rowClass, boolean create)
          Gets table object for reading/writing row objects of type R from/to table.
 OperationTime getTotalOperationTime()
           
 Transaction getTransaction()
          Gets transaction for connection.
 TypeTranslator<?> getTypeTranslator(java.lang.Class<?> typeClass)
          Gets the translator to use to convert a value to a prepared statement and to convert a value from a result set.
 TypeTranslator<?> getTypeTranslator(java.lang.String typeClassName)
          Same as getTypeTranslator(Class) but uses class name.
protected  void init(java.sql.Connection connection, java.lang.String schema)
          Invoked by constructor to initialize.
protected  Transaction initTransaction(java.sql.Connection connection)
          Contructs a transaction to use.
protected  void initTypeTranslatorMap()
          Invoked by constructor to initialize default type translators and type translators annotated on Database class.
 boolean isReadOnly()
          Gets read-only indicator.
 boolean isTimings()
          Gets status of timings.
 void logTimings()
          Logs all times from operation time map, getOperationTimeMap() to log.
 void putTypeTranslator(java.lang.Class<?> typeClass, TypeTranslator<?> typeTranslator)
          Defines the translator to use to convert a value to a prepared statement or to convert a value from a result set.
 void putTypeTranslator(java.lang.String typeClassName, TypeTranslator<?> typeTranslator)
          Same as putTypeTranslator(Class, TypeTranslator) but uses class name.
 void removeNameTranslatorClass(java.lang.Class<? extends NameTranslator> nameTranslatorClass)
          Removes a name translator class.
 void setNameTranslatorClass(java.lang.Class<? extends NameTranslator> nameTranslatorClass)
          Deprecated. 
 void setReadOnly(boolean readOnly)
          Sets read-only indicator.
 void setTimings(boolean timings)
          Sets timings enabled for all database operations.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Database

public Database(java.lang.String dataSourceName)
         throws SormulaException
Constructs for JNDI name and no schema. All sql table names will not include a schema prefix.

DataSource will be obtained from JNDI look up of dataSourceName. Typically web containers require data source to be configured with a name like "someds" but the full path to the data source contains an implied context of "java:comp/env". So the constructor parameter, dataSourceName, would be "java:comp/env/someds".

Connection will be obtained with DataSource.getConnection() and connection will be closed when close() is invoked.

Use this constructor when a DataSource is required, for example when DurableLazySelector is used.

Parameters:
dataSourceName - JNDI full path to data source definition; example "java:comp/env/someds"
Throws:
SormulaException - if error
Since:
1.9 and 2.3

Database

public Database(java.lang.String dataSourceName,
                java.lang.String schema)
         throws SormulaException
Constructs for JNDI name and schema. All sql table names will be prefixed with schema name in form of "schema.table".

DataSource will be obtained from JNDI look up of dataSourceName. Typically web containers require data source to be configured with a name like "someds" but the full path to the data source contains an implied context of "java:comp/env". So the constructor parameter, dataSourceName, would be "java:comp/env/someds".

Connection will be obtained with DataSource.getConnection() and connection will be closed when close() is invoked.

Use this constructor when a DataSource is required, for example when DurableLazySelector is used.

Parameters:
dataSourceName - JNDI full path to data source definition; example "java:comp/env/someds"
schema - name of schema to be prefixed to table name in all table names in sql statements; Connection.getCatalog() is typically the schema name but catalog methods are inconsistently supported by jdbc drivers
Throws:
SormulaException - if error
Since:
1.9 and 2.3

Database

public Database(javax.sql.DataSource dataSource)
         throws SormulaException
Constructs for no schema. All sql table names will not include a schema prefix.

Connection will be obtained with DataSource.getConnection() and connection will be closed when close() is invoked.

Use this constructor when a DataSource is required, for example when DurableLazySelector is used.

Parameters:
dataSource - obtain JDBC connection from this data source
Throws:
SormulaException - if error
Since:
1.8 and 2.2

Database

public Database(javax.sql.DataSource dataSource,
                java.lang.String schema)
         throws SormulaException
Constructs for schema. All sql table names will be prefixed with schema name in form of "schema.table".

Connection will be obtained with DataSource.getConnection() and connection will be closed when close() is invoked.

Use this constructor when a DataSource is required, for example when DurableLazySelector is used.

Parameters:
dataSource - obtain JDBC connection from this data source
schema - name of schema to be prefixed to table name in all table names in sql statements; Connection.getCatalog() is typically the schema name but catalog methods are inconsistently supported by jdbc drivers
Throws:
SormulaException - if error
Since:
1.8 and 2.2

Database

public Database(java.sql.Connection connection)
Constructs for no schema. All sql table names will not include a schema prefix.

Parameters:
connection - JDBC connection

Database

public Database(java.sql.Connection connection,
                java.lang.String schema)
Constructs for schema. All sql table names will be prefixed with schema name in form of "schema.table".

Parameters:
connection - JDBC connection
schema - name of schema to be prefixed to table name in all table names in sql statements; Connection.getCatalog() is typically the schema name but catalog methods are inconsistently supported by jdbc drivers
Method Detail

getDataSourceName

public java.lang.String getDataSourceName()
Gets the JNDI name to use to look up DataSource. This name was supplied in constructors: Database(String) and Database(String, String).

Returns:
data source JNDI name or null if none
Since:
1.9 and 2.3

getDataSource

public javax.sql.DataSource getDataSource()
Gets data source supplied in constructors, Database(DataSource) and Database(DataSource, String).

Returns:
data source or null if none was supplied during construction

init

protected void init(java.sql.Connection connection,
                    java.lang.String schema)
             throws SormulaException
Invoked by constructor to initialize.

Parameters:
connection - JDBC connection
schema - name of schema to be prefixed to table name in all table names in sql statements; Connection.getCatalog() is typically the schema name but catalog methods are inconsistently
Throws:
SormulaException - if error

initTypeTranslatorMap

protected void initTypeTranslatorMap()
                              throws SormulaException
Invoked by constructor to initialize default type translators and type translators annotated on Database class. Connection.getCatalog() is typically the schema name but catalog methods are inconsistently

Throws:
SormulaException - if error

initTransaction

protected Transaction initTransaction(java.sql.Connection connection)
                               throws SormulaException
Contructs a transaction to use. Default is Transaction. Subclasses can override to use transaction other than the default.

Parameters:
connection - JDBC connection to database
Returns:
transaction for all operations using this database
Throws:
SormulaException - if error

getTransaction

public Transaction getTransaction()
Gets transaction for connection. A Transaction is optional for most situations. Transaction is provided for basic JDBC transaction support if desired. Since Database is single threaded, only one Transaction object exists per instance of Database.

AbstractLazySelector and subclasses start a new transaction if Transaction.isActive() is false. Use a custom subclass of AbstractLazySelector and override begin, commit, and rollback methods to avoid this default behavior.

Returns:
transaction for this database

close

public void close()
Dereferences all objects used. Does not close connection if these constructors were used: Database(Connection) or Database(Connection, String).

Closes connection if this class created the connection. Connection is created by this class when any of the data source constructors are used. This method is required when any of these data source constructors are used: Database(DataSource), Database(DataSource, String), Database(String), Database(String, String).


getConnection

public java.sql.Connection getConnection()
Gets connection to use for sql operations. Used by SqlOperation subclasses to obtain the connection to use for the operation methods.

Returns:
JDBC connection

getSchema

public java.lang.String getSchema()
Gets the schema name supplied in constructor.

Returns:
schema name or empty string for no schema

isReadOnly

public boolean isReadOnly()
Gets read-only indicator.

Returns:
true if modify operations are not permitted
Since:
1.6 and 2.0
See Also:
SqlOperation.isReadOnly()

setReadOnly

public void setReadOnly(boolean readOnly)
Sets read-only indicator. When true, modify operations, ModifyOperation will fail with an exception. By default read-only is false. Set to true as a safe-guard to prevent accidental modification of database.

Parameters:
readOnly - true to prevent modify operations
Since:
1.6 and 2.0
See Also:
SqlOperation.setReadOnly(boolean)

getTable

public <R> Table<R> getTable(java.lang.Class<R> rowClass,
                             boolean create)
                  throws SormulaException
Gets table object for reading/writing row objects of type R from/to table. Table objects are cahced in map by canonical class name. If one exists, it is returned, otherwise a default one is created if create is true.

This method is optional. A table object may also be created with Table constructor.

Type Parameters:
R - row class type
Parameters:
rowClass - annotations on this class determine mapping from row objects to/from database
create - true to create new instance of Table if Database(Connection) does not have one yet; false to return null if no Table instance is found for rowClass
Returns:
table object for reading/writing row objects of type R from/to database; null if table does not exist and create is false
Throws:
SormulaException - if error
Since:
1.7 and 2.1

getTable

public <R> Table<R> getTable(java.lang.Class<R> rowClass)
                  throws SormulaException
Gets table object for reading/writing row objects of type R from/to table. Table objects are cahced in map by canonical class name. If one exists, it is returned, otherwise a default one is created.

This method is optional. A table object may also be created with Table constructor.

Type Parameters:
R - row class type
Parameters:
rowClass - annotations on this class determine mapping from row objects to/from database
Returns:
table object for reading/writing row objects of type R from/to database
Throws:
SormulaException - if error

addTable

public void addTable(Table<?> table)
Adds a table object to cache to be used for row objects of type Object.getClass(). Use this method to save table in cache. This method provides a way to ensure that a custom subclass of Table is returned from getTable(Class) for the table row class.

Parameters:
table - table object to add to cache (table row class cannonical name is key)

getNameTranslatorClass

@Deprecated
public java.lang.Class<? extends NameTranslator> getNameTranslatorClass()
Deprecated. 

Gets the default name translator class for tables when none is specified. Use getNameTranslatorClasses() instead this method.

Returns:
default name translator class; null if none

setNameTranslatorClass

@Deprecated
public void setNameTranslatorClass(java.lang.Class<? extends NameTranslator> nameTranslatorClass)
Deprecated. 

Sets the name translator class to use for a table if no translator is specified by Column.translator(). A new instance is created for each table. Use addNameTranslatorClass(Class) instead of this method.

Parameters:
nameTranslatorClass - default name translator class; null for none

getNameTranslatorClasses

public java.util.List<java.lang.Class<? extends NameTranslator>> getNameTranslatorClasses()
Gets the default name translator classes for tables when none is specified for the table.

Returns:
list of default name translator class; empty list if none
Since:
1.8 and 2.2
See Also:
Table.translateName(String)

addNameTranslatorClass

public void addNameTranslatorClass(java.lang.Class<? extends NameTranslator> nameTranslatorClass)
Adds a default name translator class.

Parameters:
nameTranslatorClass - class to use to translate table/column names
Since:
1.8 and 2.2
See Also:
Table.translateName(String)

removeNameTranslatorClass

public void removeNameTranslatorClass(java.lang.Class<? extends NameTranslator> nameTranslatorClass)
Removes a name translator class.

Parameters:
nameTranslatorClass - class to remove
Since:
1.8 and 2.2
See Also:
Table.translateName(String)

isTimings

public boolean isTimings()
Gets status of timings.

Returns:
true if operations are to record execution times
Since:
1.5

setTimings

public void setTimings(boolean timings)
Sets timings enabled for all database operations. When enabled all operations will record execution times. Use logTimings() to write the timings to the log. Use getOperationTime(String) or getOperationTimeMap() to get timings that have been recorded.

Parameters:
timings - true to enable all operations to record execution timings; false for no operation timings by default (can be overriden by each SqlOperation)
Since:
1.5

getOperationTime

public OperationTime getOperationTime(java.lang.String timingId)
Gets the operation time for a specific timing id.

Parameters:
timingId - timing id to get
Returns:
OperationTime for timing id or null if timing id is not in map
Since:
1.5

createOperationTime

public OperationTime createOperationTime(java.lang.String timingId,
                                         java.lang.String description)
Creates an OperationTime instance with this database total time, getTotalOperationTime() as the parent time. The new instance is add to operation time map, getOperationTimeMap().

Parameters:
timingId - timing id for created instance
description - description for created instance
Returns:
new instance of OperationTime with id and description
Since:
1.5

getTotalOperationTime

public OperationTime getTotalOperationTime()
Returns:
operation times for all operations that have been executed
Since:
1.5

getOperationTimeMap

public java.util.Map<java.lang.String,OperationTime> getOperationTimeMap()
Gets operation times for all operations have been executed. Key to map is timing id.

Returns:
map of timing ids to operation time
Since:
1.5

logTimings

public void logTimings()
Logs all times from operation time map, getOperationTimeMap() to log. Total operation time, getTotalOperationTime() is logged also.

Since:
1.5

putTypeTranslator

public void putTypeTranslator(java.lang.Class<?> typeClass,
                              TypeTranslator<?> typeTranslator)
Defines the translator to use to convert a value to a prepared statement or to convert a value from a result set. This method is needed only for type translators that are not defined with ImplicitType annotation.

By default, all primative types and most subclasses of TypeTranslator in org.sormula.translator.standard package are added during initialization of this class. Use this method to override default translators or to add a new translator.

These tranlators may be overridden for a table by Table.putTypeTranslator(Class, TypeTranslator).

Specified by:
putTypeTranslator in interface TypeTranslatorMap
Parameters:
typeClass - class that translator operates upon
typeTranslator - translator to use for typeClass
Since:
1.6 and 2.0

putTypeTranslator

public void putTypeTranslator(java.lang.String typeClassName,
                              TypeTranslator<?> typeTranslator)
Same as putTypeTranslator(Class, TypeTranslator) but uses class name. Usefull for adding primative types like "int", "boolean", "float", etc.

Specified by:
putTypeTranslator in interface TypeTranslatorMap
Parameters:
typeClassName - class name that translator operates upon
typeTranslator - translator to use for typeClass
Since:
1.6 and 2.0

getTypeTranslator

public TypeTranslator<?> getTypeTranslator(java.lang.Class<?> typeClass)
Gets the translator to use to convert a value to a prepared statement and to convert a value from a result set.

Specified by:
getTypeTranslator in interface TypeTranslatorMap
Parameters:
typeClass - class that translator operates upon
Returns:
translator to use for typeClass
Since:
1.6 and 2.0

getTypeTranslator

public TypeTranslator<?> getTypeTranslator(java.lang.String typeClassName)
Same as getTypeTranslator(Class) but uses class name.

Parameters:
typeClassName - class name that translator operates upon
Returns:
translator to use for typeClass
Since:
1.6 and 2.0