Database (sormula)

java.lang.Object
- org.sormula.Database

All Implemented Interfaces:: java.lang.AutoCloseable, TypeTranslatorMap

Direct Known Subclasses:: OperationDatabase

public class Database
extends java.lang.Object
implements TypeTranslatorMap, java.lang.AutoCloseable

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

Constructors
Constructor and Description
`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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addNameTranslatorClass(java.lang.Class<? extends NameTranslator> nameTranslatorClass)` Adds a default name translator class.
`void`	`addTable(Table<?> table)` Adds a table object to map to be used for row objects of type `Object.getClass()`.
`void`	`close()` Closes connection if this class created the connection from a data source.
`OperationTime`	`createOperationTime(java.lang.String timingId, java.lang.String description)` Creates an `OperationTime` instance with this database total time, `getTotalOperationTime()` as the parent time.
`void`	`flush()` Invokes `Table.flush()` on all known table objects in this database.
`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.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.lang.String schema)` Invoked by constructor to initialize.
`protected Transaction`	`initTransaction(java.sql.Connection connection)` Constructs a transaction to use.
`protected void`	`initTypeTranslatorMap()` Invoked by constructor to initialize default type translators and type translators annotated on `Database` class.
`boolean`	`isAutoGeneratedKeys()` Gets the most recent value of `setAutoGeneratedKeys(boolean)`.
`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`	`setAutoGeneratedKeys(boolean autoGeneratedKeys)` Sets the default way identity columns are processed for newly created `Table` objects.
`void`	`setConnection(java.sql.Connection connection)` Sets new connection to use by this class and all related classes.
`void`	`setReadOnly(boolean readOnly)` Sets read-only indicator.
`void`	`setTimings(boolean timings)` Sets timings enabled for all database operations.
`void`	`setTransaction(Transaction transaction)` Sets a custom implementation of `Transaction` subclass.

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

isAutoGeneratedKeys
```
public boolean isAutoGeneratedKeys()
```
Gets the most recent value of setAutoGeneratedKeys(boolean). The default is true.

Returns:

true if database is to generate keys for identity columns

Since:

4.1

setAutoGeneratedKeys
```
public void setAutoGeneratedKeys(boolean autoGeneratedKeys)
```
Sets the default way identity columns are processed for newly created Table objects. Table objects created will have Table.setAutoGeneratedKeys(boolean) set to isAutoGeneratedKeys(). Setting to false is useful when a column is defined as an identity column but the key will be manually created by the application.
Changing this value will have no affect on Table objects that have already been created.

Parameters:

autoGeneratedKeys - true if Table objects created for this database should assume that database will automatically generate key values for fields defined as identity (Column.identity() is true)

Since:

4.1

See Also:

Column.identity(), Table.isAutoGeneratedKeys(), Statement.getGeneratedKeys()

init
```
protected void init(java.lang.String schema)
             throws SormulaException
```
Invoked by constructor to initialize.

Parameters:

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 jdbc drivers are not consistent

Throws:

SormulaException - if error

Since:

4.1

initTypeTranslatorMap

protected void initTypeTranslatorMap()
                              throws SormulaException

Invoked by constructor to initialize default type translators and type translators annotated on Database class.

Default Translators
Field Type	Translator
boolean / java.lang.Boolean	`BooleanTranslator`
byte / java.lang.Byte	`ByteTranslator`
double / java.lang.Double	`DoubleTranslator`
float / java.lang.Float	`FloatTranslator`
int / java.lang.Integer	`IntegerTranslator`
long / java.lang.Long	`LongTranslator`
short / java.lang.Short	`ShortTranslator`
java.math.BigDecimal	`BigDecimalTranslator`
java.lang.String	`StringTranslator`
java.util.Date	`DateTranslator`
java.sql.Date	`SqlDateTranslator`
java.sql.Time	`SqlTimeTranslator`
java.sql.Timestamp	`SqlTimestampTranslator`
java.util.GregorianCalendar	`GregorianCalendarTranslator`
java.time.LocalDate	`LocalDateTranslator`
java.time.LocalTime	`LocalTimeTranslator`
java.time.Instant	`InstantTranslator`

Throws:: SormulaException - if error

initTransaction
```
protected Transaction initTransaction(java.sql.Connection connection)
                               throws SormulaException
```
Constructs 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 some 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

setTransaction
```
public void setTransaction(Transaction transaction)
```
Sets a custom implementation of Transaction subclass. This method should be invoked prior to creating Table objects that use this Database and prior to using getTable(Class) or getTable(Class, boolean).

Parameters:

transaction - transaction for this database

Since:

3.0

flush
```
public void flush()
           throws SormulaException
```
Invokes Table.flush() on all known table objects in this database.

Throws:

SormulaException - if error

close
```
public void close()
```
Closes connection if this class created the connection from a data source. 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).
If the Database instance was created using a data source, then it may be reused after closing. A new connection will be obtained from the data source if needed.
Does not close connection if these constructors were used: Database(Connection) or Database(Connection, String).

Specified by:

close in interface java.lang.AutoCloseable

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

Returns:

JDBC connection

setConnection
```
public void setConnection(java.sql.Connection connection)
                   throws SormulaException
```
Sets new connection to use by this class and all related classes. This method is useful for situations where Database and related Table, SqlOperation, etc. objects are created and you want to reuse them for a different connection. This method is primarily intended to be used on Database objects that were created with the Connection constructors: Database(Connection) and Database(Connection, String).
Warning: Do not use this method while the transaction for this Database is active.
Warning: If any of the datasource constructors were used to create Database then you must explicitly close the old connection to avoid a connection leak.
Note: If any datasource constructor was used, then setting to null will force new connection to be obtained from datasource but the old connection will not be closed. Old connection must be explicitly closed. Using close() is a simpler way to achieve the same outcome.

Parameters:

connection - new connection to use; null to force new connection from datasource

Throws:

SormulaException - if the transaction (getTransaction()) is active

Since:

4.2

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 a ReadOnlyException. 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 cached 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 cached 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 map to be used for row objects of type Object.getClass(). Use this method to save table in map. 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 map (table row class cannonical name is key)

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 overridden 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 primitive 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 translators 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. Useful for adding primitive 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

Class Database

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Database

Database

Database

Database

Database

Database

Method Detail

getDataSourceName

getDataSource

isAutoGeneratedKeys

setAutoGeneratedKeys

init

initTypeTranslatorMap

initTransaction

getTransaction

setTransaction

flush

close

getConnection

setConnection

getSchema

isReadOnly

setReadOnly

getTable

getTable

addTable

getNameTranslatorClasses

addNameTranslatorClass

removeNameTranslatorClass

isTimings

setTimings

getOperationTime

createOperationTime

getTotalOperationTime

getOperationTimeMap

logTimings

putTypeTranslator

putTypeTranslator

getTypeTranslator

getTypeTranslator