Db (Tentackle Persistence 2.0.7 API)

java.lang.Object
- org.tentackle.persist.Db

All Implemented Interfaces:

Cloneable, Comparable<Session>, Session
```
public class Db
extends Object
implements Session, Cloneable
```
A logical database connection. Db connections are an abstraction for a connection between a client and a server, whereas "server" is not necessarily a database server, because Db connections can be either local or remote.
A local Db talks to a database backend via a ConnectionManager which is responsible for the physical JDBC-connection. However, there is no 1:1 relationship between a Db and a physical connection. This is up to the connection manager. Local Db connections are used in client applications running in 2-tier mode or in application servers.
Remote Db connections are connected to a Tentackle application server via RMI. Client applications running in 3-tier mode (more precise n-tier, with n ≥ 3) use remote connections.
With the abstraction of a logical Db connection, Tentackle applications are able to run both in 2- or n-tier mode without a single modification to the source code. It's just a small change in a config file.
The configuration is achieved by a property file, which is located by the SessionInfo passed to the Db.
Local connections can be either a DataSource bound via JNDI or a direct JDBC connection. JNDI is used in application servers, for example running a JRuby on Rails application from within Glassfish (see tentackle-web).
JDBC connections are for standalone 2-tier applications or Tentackle application servers.
For local connections via JDBC the file contains at least the following properties:
```
 driver=jdbc-driver
 url=jdbc-url

 Example:
 driver=org.postgresql.Driver
 url=jdbc:postgresql://gonzo.krake.local/erp
 
```
Local connections via JNDI need only the url. The url starts with "jndi:" and is followed by the JNDI-name. The optional database backend type is only necessary if it cannot be determined from the connection's metadata.
```
 url=jndi:name[:database-type]

 Example:
 url=jndi:jdbc/erpPool
 
```
For remote connections only one line is required at minimum:
```
 url=rmi://hostname[:port]/service

 Example:
 url=rmi://gonzo.krake.local:28004/ErpServer
 
```
The port is optional and defaults to 1099 (the default RMI registry).
Optionally, the following properties can be defined:
For local connections via JDBC:
- A predefined user and password
```
  user=fixed-user
  password=fixed-password
  
```
- By default the credentials used to connect to the backend are the same as the ones in the session info. However, if a technical user must be used, the configuration for the backend may be defined in another property file.
```
  backendinfo=property-file
  
```
For local connections via JDBC or JNDI:
- Each object persistable to the database (database object for short) gets a unique object ID which is generated by an IdSource. The default source is ObjectId.
```
  idsource=id-source-descriptor
  
```
  See IdSourceConfigurator for details.
For remote connections, the properties (session info) will be sent to the server. This can be used to set some application specific options or to tune the connection.
Author:

harald

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`CIPHER_SUITES` The property key for the SSL cipher suites.
`static String`	`PROPERTY_IDSOURCE` property key for IdSource.
`static String`	`PROTOCOLS` The property key for the SSL protocols.
`static String`	`SOCKET_FACTORY` The property key for the socket factory.

Constructor Summary

Constructors
Constructor and Description

Db(ConnectionManager conMgr, SessionInfo sessionInfo)
Creates an instance of a logical db connection.

Constructors
Constructor and Description
`Db(ConnectionManager conMgr, SessionInfo sessionInfo)` Creates an instance of a logical db connection.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`assertNotRemote()` asserts that this is not a remote connection
`void`	`assertNoTxRunning()` Asserts that no transaction is running.
`void`	`assertOpen()` Asserts that the database is open.
`void`	`assertOwnerThread()` Asserts db is not used by another thread than the ownerthread.
`void`	`assertRemote()` asserts that this is a remote connection
`void`	`assertTxRunning()` Asserts that a transaction with the given voucher is running.
`long`	`begin()`
`long`	`begin(String txName)` Starts a transaction. Does nothing if a transaction is already running!
`boolean`	`checkForDeadLink(SQLException ex)` Checks for a dead communications link. If the link is down, for example the database server closed it, the connection is marked dead.
`void`	`clearCloned()` Clears the cloned state.
`void`	`clearPassword()` Clears all passwords (stored in char[]-arrays) so that they are no more visible in memory.
`Db`	`clone()` Clones a logical connection.
`void`	`close()`
`boolean`	`commit(long txVoucher)` Commits a transaction if the corresponding begin() has started it.
`boolean`	`commitImmediately()` Commits the current transaction, if pending.
`int`	`compareTo(Session session)` Compares two db instances.
`Connection`	`connect()` Creates a physical low level connection to the local db server via JDBC using this Db (authentication by userinfo or fixed user/password).
`PreparedStatementWrapper`	`createPreparedStatement(String sql)` Creates a one-shot prepared statement. Uses `ResultSet.TYPE_FORWARD_ONLY` and `ResultSet.CONCUR_READ_ONLY`.
`PreparedStatementWrapper`	`createPreparedStatement(String sql, int resultSetType, int resultSetConcurrency)` Creates a one-shot prepared statement.
`org.tentackle.persist.rmi.RemoteDelegate`	`createRemoteDelegate(String className)` Creates the remote delegate.
`StatementWrapper`	`createStatement()` Creates a non-prepared statement.
`StatementWrapper`	`createStatement(int resultSetType)` Creates a non-prepared statement.
`StatementWrapper`	`createStatement(int resultSetType, int resultSetConcurrency)` Creates a non-prepared statement.
`boolean`	`equals(Object obj)`
`protected void`	`finalize()` finalizer if connection is broken
`void`	`forceDetached()` Detach the db. Used in execption handling to cleanup all pending statements and result sets.
`static Collection<Db>`	`getAllOpenDb()` Gets a list of all currently open Db sessions.
`Backend`	`getBackend()` Gets the database backend.
`BackendInfo`	`getBackendInfo()` Gets the backend info.
`Db`	`getClonedFromDb()` Gets the original db if this db is cloned.
`Collection<CommitTxRunnable>`	`getCommitTxRunnables()` Gets the currently registered commit runnables.
`IdSource`	`getDefaultIdSource()` Gets the default `IdSource`.
`SessionTaskDispatcher`	`getDispatcher()` Gets the dispatcher for this session. The dispatcher can be used to submit asynchroneous tasks in a serial manner.
`int`	`getFetchSize()` Gets the default fetchsize
`String`	`getIdSourceConfiguration()` Gets the ID-Source configuration.
`int`	`getImmediateCommitTxLevel()` Gets the pending txLevel after an immediate commit.
`int`	`getImmediateRollbackTxLevel()` Gets the pending txLevel after an immediate rollback.
`int`	`getInstanceNumber()` Gets the unique instance number of this Db.
`long`	`getKeepAliveInterval()`
`long`	`getLogModificationTxId()` Returns the current transaction id from the last BEGIN modification log.
`int`	`getMaxRows()` gets the maximum number of rows in resultsets.
`String`	`getName()` Gets the db name. Consists of the instance number, the connection id and the connection group id.
`Thread`	`getOwnerThread()` Gets the owner thread.
`Collection<PersistenceVisitor>`	`getPersistenceVisitors()` Gets the currently registered persistence visitors.
`SessionPool`	`getPool()` Gets the pool manager.
`int`	`getPoolId()` Gets the poolid.
`PreparedStatementWrapper`	`getPreparedStatement(StatementKey stmtKey, boolean alwaysPrepare, int resultSetType, int resultSetConcurrency, Supplier<String> sqlSupplier)` Gets the prepared statement.
`PreparedStatementWrapper`	`getPreparedStatement(StatementKey stmtKey, boolean alwaysPrepare, Supplier<String> sqlSupplier)` Gets the prepared statement. Uses `ResultSet.TYPE_FORWARD_ONLY` and `ResultSet.CONCUR_READ_ONLY`.
`RemoteDbConnection`	`getRemoteConnection()` Gets the remote connection object.
`RemoteDbSession`	`getRemoteDbSession()` Gets the remote session object.
`org.tentackle.persist.rmi.RemoteDelegate`	`getRemoteDelegate(int delegateId)` Gets the remote delegate by its id.
`String`	`getRemoteName()` Gets the name of the remote server application.
`RemoteSession`	`getRemoteSession()`
`Collection<RollbackTxRunnable>`	`getRollbackTxRunnables()` Gets the currently registered rollback runnables.
`int`	`getSessionGroupId()`
`int`	`getSessionId()` Gets the connection id.
`SessionInfo`	`getSessionInfo()` Gets the current user info.
`ConnectionManager`	`getSessionManager()` Gets the connection manager for this Db.
`int`	`getTxLevel()` Gets the transaction nesting level.
`String`	`getTxName()` Gets the optional transaction name.
`long`	`getTxNumber()` Transactions get a unique transaction number by counting the transactions per Db instance.
`AbstractDbObject<?>`	`getTxObject()` Gets the optional transaction object.
`int`	`getUpdateCount()` Gets the number of objects modified since the last begin().
`String`	`getUrl()`
`int`	`groupWith(int sessionId)`
`int`	`hashCode()`
`void`	`invalidateTxLevel()` Marks the txLevel invalid.
`boolean`	`isAlive()` Checks whether the db connection is still in use.
`boolean`	`isClientTx()` Checks whether current transaction was initiated by a remote client.
`boolean`	`isCloned()` Gets the cloned state.
`boolean`	`isCountModificationAllowed()` Checks whether objects are allowed to count modifications.
`boolean`	`isCrashed()` Gets the crash flag. May be invoked from any thread.
`boolean`	`isLogModificationAllowed()` Gets the state of logModificationAllowed.
`boolean`	`isLogModificationDeferred()` Gets the state for logModificationDeferred.
`boolean`	`isLogModificationTxEnabled()` Gets the value of logModificationTx.
`boolean`	`isOpen()` Gets the connection state.
`boolean`	`isPersistenceOperationAllowed(AbstractDbObject<?> object, char modType)` Checks whether a persistence operation is allowed. This is determined by consulting the `PersistenceVisitor`s.
`boolean`	`isPooled()` Checks whether this Db is pooled.
`boolean`	`isReadOnly()` Returns whether Db is readonly.
`boolean`	`isRemote()` Gets the type of the logical connection.
`boolean`	`isTxLevelValid()` Returns whether the txLevel is valid.
`boolean`	`isTxRunning()` Gets the current transaction state. Technically, a transaction is running if the autocommit is turned off.
`void`	`logBeginTx()` Creates a begin modification log if necessary.
`void`	`logCommitTx()` Creates a commit modification log if necessary.
`void`	`logException(Logger logger, Logger.Level level, String msg, Throwable e)` Logs an exception.
`void`	`open()` Open a database connection. If the login failes due to wrong passwords or denied access by the application server, the method `handleConnectException(java.lang.Exception)` is invoked.
`List<ModificationLog>`	`popModificationLogsOfTransaction()` Returns the `ModificationLog`s of the current transaction.
`static int`	`prepareRemoteDelegate(Class<?> clazz)` Prepares a `RemoteDelegate`.
`void`	`pushModificationLogOfTransaction(ModificationLog log)` Pushes a `ModificationLog` to the list of modlogs of the current transaction.
`boolean`	`registerCloseHandler(SessionCloseHandler closeHandler)` Registers a close handler.
`DbTransactionHandle`	`registerCommitTxRunnable(CommitTxRunnable commitRunnable)` Registers a `CommitTxRunnable` to be invoked just before committing a transaction.
`static boolean`	`registerGlobalCloseHandler(SessionCloseHandler closeHandler)` Registers a global close handler.
`DbTransactionHandle`	`registerPersistenceVisitor(PersistenceVisitor visitor)` Registers a `PersistenceVisitor` to be invoked just before performing a persistence operation. Notice that the visitor must be registered within the transaction, i.e.
`DbTransactionHandle`	`registerRollbackTxRunnable(RollbackTxRunnable rollbackRunnable)` Registers a `RollbackTxRunnable` to be invoked just before rolling back a transaction.
`boolean`	`rollback(long txVoucher)`
`boolean`	`rollback(long txVoucher, boolean withLog)` Rolls back a transaction if the corresponding begin() has started it.
`boolean`	`rollbackImmediately()` Rolls back the current transaction, if pending.
`boolean`	`rollbackSilently(long txVoucher)`
`void`	`setAlive(boolean alive)` Sets the db connection's alive state.
`void`	`setCountModificationAllowed(boolean countModificationAllowed)` Defines whether objects are allowed to count modifications.
`void`	`setCrashed(boolean crashed)` Sets the crash flag. The db may be marked as crashed to reduce logging of succeeding errors.
`void`	`setDefaultIdSource(IdSource idSource)` Set the default `IdSource`. This is the source that is used to generate unique object IDs if classes did not configure their own source.
`void`	`setFetchSize(int fetchSize)` Sets the default fetchsize for all "wrapped" statements (PreparedStatementWrapper and StatementWrapper)
`void`	`setIdConfiguration(String idConfig)` Sets the ID-Source configuration.
`void`	`setKeepAliveInterval(long keepAliveInterval)`
`void`	`setLogModificationAllowed(boolean logModificationAllowed)` Sets the modification allowed state.
`void`	`setLogModificationDeferred(boolean logModificationDeferred)` Sets the modification logging deferred state for the current transaction. In deferred mode the `ModificationLog`s are not written to the database.
`void`	`setLogModificationTxEnabled(boolean logModificationTxEnabled)` Turn transaction-logging on or off.
`void`	`setLogModificationTxId(long logModificationTxId)` Sets the transaction id.
`void`	`setMaxRows(int maxRows)` sets the maximum number of rows in resultsets.
`void`	`setOwnerThread(Thread ownerThread)` Sets the exclusive owner thread.
`void`	`setPool(SessionPool sessionPool)` Sets the pool manager.
`void`	`setPoolId(int poolId)` Sets the pool id.
`void`	`setReadOnly(boolean readOnly)` Sets the db to readonly.
`void`	`setSessionGroupId(int number)` Sets the group number for this db. This is an optional number describing groups of db-connections, which is particulary useful in rmi-servers: if one connection fails, all others should be closed as well.
`void`	`setSessionInfo(SessionInfo sessionInfo)` Sets the userInfo.
`void`	`setTxObject(AbstractDbObject<?> txObject)` Sets the optional transaction object. By default, whenever a transaction is initiated by a persistence operation of a `AbstractDbObject`, that object becomes the "parent" of the transaction. The `txObject` is mainly used for logging and enhanced auditing (partial history) during transactions. The `txObject` is cleared at the end of the transaction.
`String`	`toString()`
`<T> T`	`transaction(TransactionEnvelope<T> txe)`
`<T> T`	`transaction(TransactionEnvelope<T> txe, String txName)`
`boolean`	`unregisterCloseHandler(SessionCloseHandler closeHandler)` Unregisters a close handler.
`CommitTxRunnable`	`unregisterCommitTxRunnable(DbTransactionHandle handle)` Unregisters a `CommitTxRunnable`.
`static boolean`	`unregisterGlobalCloseHandler(SessionCloseHandler closeHandler)` Unregisters a global close handler.
`PersistenceVisitor`	`unregisterPersistenceVisitor(DbTransactionHandle handle)` Unegisters a `PersistenceVisitor`.
`RollbackTxRunnable`	`unregisterRollbackTxRunnable(DbTransactionHandle handle)` Unregisters a `RollbackTxRunnable`.

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.tentackle.pdo.Session
applyTo, applyTo, assertCurrentSessionValid, clearCurrent, getCurrentSession, getSession, isCurrent, makeCurrent, setCurrentSession

- Field Detail
  - PROPERTY_IDSOURCE
```
public static final String PROPERTY_IDSOURCE
```
    property key for IdSource.
    
    See Also:
    
    Constant Field Values
  - SOCKET_FACTORY
```
public static final String SOCKET_FACTORY
```
    The property key for the socket factory.
    
    See Also:
    
    Constant Field Values
  - CIPHER_SUITES
```
public static final String CIPHER_SUITES
```
    The property key for the SSL cipher suites.
    
    See Also:
    
    Constant Field Values
  - PROTOCOLS
```
public static final String PROTOCOLS
```
    The property key for the SSL protocols.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Db
```
public Db(ConnectionManager conMgr,
          SessionInfo sessionInfo)
```
    Creates an instance of a logical db connection.
    
    Parameters:
    
    conMgr - the connection manager to use for this db, unused for local connections
    
    sessionInfo - user information
- Method Detail
  - registerGlobalCloseHandler
```
public static boolean registerGlobalCloseHandler(SessionCloseHandler closeHandler)
```
    Registers a global close handler.
    
    Parameters:
    
    closeHandler - the handler
    
    Returns:
    
    true if added, false if already registered
  - unregisterGlobalCloseHandler
```
public static boolean unregisterGlobalCloseHandler(SessionCloseHandler closeHandler)
```
    Unregisters a global close handler.
    
    Parameters:
    
    closeHandler - the handler
    
    Returns:
    
    true if removed, false if not registered
  - getAllOpenDb
```
public static Collection<Db> getAllOpenDb()
```
    Gets a list of all currently open Db sessions.
    
    Returns:
    
    the list of open Db sessions
  - getInstanceNumber
```
public final int getInstanceNumber()
```
    Gets the unique instance number of this Db.
    
    Specified by:
    
    getInstanceNumber in interface Session
    
    Returns:
    
    the instance number
  - getName
```
public String getName()
```
    Gets the db name.
    Consists of the instance number, the connection id and the connection group id.
    
    Specified by:
    
    getName in interface Session
    
    Returns:
    
    the db name
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - compareTo
```
public int compareTo(Session session)
```
    Compares two db instances. Implemented for trees, caches, etc... because they need a Comparable. We simply use the unique instanceNumber.
    
    Specified by:
    
    compareTo in interface Comparable<Session>
    
    Parameters:
    
    session - the session to compare this db with
    
    Returns:
    
    a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
  - getSessionManager
```
public ConnectionManager getSessionManager()
```
    Gets the connection manager for this Db.
    
    Specified by:
    
    getSessionManager in interface Session
    
    Returns:
    
    the connection manager
  - setPool
```
public void setPool(SessionPool sessionPool)
```
    Sets the pool manager. The method is invoked from a SessionPool when the Db is created.
    
    Parameters:
    
    sessionPool - the db pool, null = not pooled
  - getPool
```
public SessionPool getPool()
```
    Gets the pool manager.
    
    Specified by:
    
    getPool in interface Session
    
    Returns:
    
    the db pool, null = not pooled
  - isPooled
```
public boolean isPooled()
```
    Checks whether this Db is pooled.
    
    Specified by:
    
    isPooled in interface Session
    
    Returns:
    
    true if pooled, false if not pooled
  - setPoolId
```
public void setPoolId(int poolId)
```
    Sets the pool id. The method is invoked from a SessionPool when the Db is used in a pool.
    
    Parameters:
    
    poolId - the ID given by the pool (> 0), 0 = not used (free Db), -1 if removed from pool
  - getPoolId
```
public int getPoolId()
```
    Gets the poolid.
    
    Returns:
    
    the pool id
  - isReadOnly
```
public boolean isReadOnly()
```
    Returns whether Db is readonly.
    
    Returns:
    
    true if readonly.
  - setReadOnly
```
public void setReadOnly(boolean readOnly)
```
    Sets the db to readonly.
    If a database is readonly, no updates, deletes or inserts are possible. Any attempt to do so results in a persistence exception.
    
    Parameters:
    
    readOnly - true if readonly
  - getRemoteConnection
```
public RemoteDbConnection getRemoteConnection()
```
    Gets the remote connection object.
    
    Returns:
    
    the connection object, null if local
  - getRemoteDbSession
```
public RemoteDbSession getRemoteDbSession()
```
    Gets the remote session object.
    
    Returns:
    
    the session, null if local
  - connect
```
public Connection connect()
                   throws SQLException
```
    Creates a physical low level connection to the local db server via JDBC using this Db (authentication by userinfo or fixed user/password).
    
    Returns:
    
    the low level JDBC connection
    
    Throws:
    
    SQLException - if connection failed
  - assertOwnerThread
```
public void assertOwnerThread()
```
    Asserts db is not used by another thread than the ownerthread.
  - assertOpen
```
public void assertOpen()
```
    Asserts that the database is open.
  - assertTxRunning
```
public void assertTxRunning()
```
    Asserts that a transaction with the given voucher is running.
  - assertNoTxRunning
```
public void assertNoTxRunning()
```
    Asserts that no transaction is running.
  - assertNotRemote
```
public void assertNotRemote()
```
    asserts that this is not a remote connection
  - assertRemote
```
public void assertRemote()
```
    asserts that this is a remote connection
  - isAlive
```
public boolean isAlive()
```
    Checks whether the db connection is still in use. Whenever a StatementWrapper or PreparedStatementWrapper is used (i.e executeQuery or executeUpdate), the db connection is set to be alive. Some other thread may clear this flag regulary and check whether it has been set in the meantime.
    
    Specified by:
    
    isAlive in interface Session
    
    Returns:
    
    true if connection still in use, false if not used since last setAlive(false).
  - setAlive
```
public void setAlive(boolean alive)
```
    Sets the db connection's alive state.
    
    Specified by:
    
    setAlive in interface Session
    
    Parameters:
    
    alive - is true to signal it's alive, false to clear
  - getKeepAliveInterval
```
public long getKeepAliveInterval()
```
    Specified by:
    
    getKeepAliveInterval in interface Session
  - setKeepAliveInterval
```
public void setKeepAliveInterval(long keepAliveInterval)
```
    Specified by:
    
    setKeepAliveInterval in interface Session
  - setIdConfiguration
```
public void setIdConfiguration(String idConfig)
```
    Sets the ID-Source configuration.
    
    Parameters:
    
    idConfig - the configuration
  - getIdSourceConfiguration
```
public String getIdSourceConfiguration()
```
    Gets the ID-Source configuration.
    
    Returns:
    
    the configuration
  - getDispatcher
```
public SessionTaskDispatcher getDispatcher()
```
    Gets the dispatcher for this session.
    The dispatcher can be used to submit asynchroneous tasks in a serial manner. The returned dispatcher is configured to shutdown if idle for a given timeout.
    
    Specified by:
    
    getDispatcher in interface Session
    
    Returns:
    
    the dispatcher
  - logException
```
public void logException(Logger logger,
                         Logger.Level level,
                         String msg,
                         Throwable e)
```
    Logs an exception.
    
    Parameters:
    
    e - the exception head, null if none
    
    msg - the optional message, null if none
    
    logger - the logger
    
    level - the logging level
  - checkForDeadLink
```
public boolean checkForDeadLink(SQLException ex)
```
    Checks for a dead communications link.
    If the link is down, for example the database server closed it, the connection is marked dead.
    
    Parameters:
    
    ex - the sql exception
    
    Returns:
    
    true if connection is dead
    
    See Also:
    
    ManagedConnection.setDead(boolean)
  - open
```
public void open()
```
    Open a database connection.
    If the login failes due to wrong passwords or denied access by the application server, the method handleConnectException(java.lang.Exception) is invoked.
    
    Specified by:
    
    open in interface Session
  - clearPassword
```
public void clearPassword()
```
    Clears all passwords (stored in char[]-arrays) so that they are no more visible in memory.
  - registerCloseHandler
```
public boolean registerCloseHandler(SessionCloseHandler closeHandler)
```
    Registers a close handler.
    
    Parameters:
    
    closeHandler - the handler
    
    Returns:
    
    true if added, false if already registered
  - unregisterCloseHandler
```
public boolean unregisterCloseHandler(SessionCloseHandler closeHandler)
```
    Unregisters a close handler.
    
    Parameters:
    
    closeHandler - the handler
    
    Returns:
    
    true if removed, false if not registered
  - close
```
public void close()
```
    Specified by:
    
    close in interface Session
  - finalize
```
protected void finalize()
                 throws Throwable
```
    finalizer if connection is broken
    
    Overrides:
    
    finalize in class Object
    
    Throws:
    
    Throwable
  - setCrashed
```
public void setCrashed(boolean crashed)
```
    Sets the crash flag.
    The db may be marked as crashed to reduce logging of succeeding errors. May be invoked from any thread.
    
    Parameters:
    
    crashed - the crash flag
  - isCrashed
```
public boolean isCrashed()
```
    Gets the crash flag.
    May be invoked from any thread.
    
    Returns:
    
    true if Db is marked as crashed
  - isOpen
```
public boolean isOpen()
```
    Gets the connection state.
    
    Specified by:
    
    isOpen in interface Session
    
    Returns:
    
    true if db is open, else false
  - getTxNumber
```
public long getTxNumber()
```
    Transactions get a unique transaction number by counting the transactions per Db instance.
    
    Returns:
    
    the current transaction counter, 0 if no transaction in progress
  - getTxName
```
public String getTxName()
```
    Gets the optional transaction name. Useful to distinguish transactions in logModification or alike. The tx-name is cleared after commit or rollback.
    
    Specified by:
    
    getTxName in interface Session
    
    Returns:
    
    the transaction name, null if no transaction in progress
  - getTxLevel
```
public int getTxLevel()
```
    Gets the transaction nesting level.
    
    Returns:
    
    the nesting level, 0 if no transaction in progress
  - invalidateTxLevel
```
public void invalidateTxLevel()
```
    Marks the txLevel invalid.
    Will suppress any checks and warnings.
  - isTxLevelValid
```
public boolean isTxLevelValid()
```
    Returns whether the txLevel is valid.
    
    Returns:
    
    true if valid
  - getImmediateRollbackTxLevel
```
public int getImmediateRollbackTxLevel()
```
    Gets the pending txLevel after an immediate rollback.
    
    Returns:
    
    > 0 if there was an immediate rollback
  - getImmediateCommitTxLevel
```
public int getImmediateCommitTxLevel()
```
    Gets the pending txLevel after an immediate commit.
    
    Returns:
    
    > 0 if there was an immediate commit
  - setTxObject
```
public void setTxObject(AbstractDbObject<?> txObject)
```
    Sets the optional transaction object.
    By default, whenever a transaction is initiated by a persistence operation of a AbstractDbObject, that object becomes the "parent" of the transaction.
    The txObject is mainly used for logging and enhanced auditing (partial history) during transactions.
    The txObject is cleared at the end of the transaction.
    
    Parameters:
    
    txObject - the transaction object, null to clear
  - getTxObject
```
public AbstractDbObject<?> getTxObject()
```
    Gets the optional transaction object.
    
    Returns:
    
    the transaction object, null if none
  - transaction
```
public <T> T transaction(TransactionEnvelope<T> txe,
                         String txName)
```
    Specified by:
    
    transaction in interface Session
  - transaction
```
public <T> T transaction(TransactionEnvelope<T> txe)
```
    Specified by:
    
    transaction in interface Session
  - begin
```
public long begin(String txName)
```
    Starts a transaction.
    Does nothing if a transaction is already running!
    
    Specified by:
    
    begin in interface Session
    
    Parameters:
    
    txName - is the optional transaction name, null if none
    
    Returns:
    
    the transaction voucher (!= 0) if a new transaction was begun, else 0
  - begin
```
public long begin()
```
    Specified by:
    
    begin in interface Session
  - isClientTx
```
public boolean isClientTx()
```
    Checks whether current transaction was initiated by a remote client.
    
    Returns:
    
    true if tx is a remote client transaction
  - logBeginTx
```
public void logBeginTx()
```
    Creates a begin modification log if necessary.
  - logCommitTx
```
public void logCommitTx()
```
    Creates a commit modification log if necessary.
  - getUpdateCount
```
public int getUpdateCount()
```
    Gets the number of objects modified since the last begin(). The method is provided to check whether objects have been modified at all.
    
    Returns:
    
    the number of modified objects, 0 if none modified or no transaction running
  - registerPersistenceVisitor
```
public DbTransactionHandle registerPersistenceVisitor(PersistenceVisitor visitor)
```
    Registers a PersistenceVisitor to be invoked just before performing a persistence operation.
    Notice that the visitor must be registered within the transaction, i.e. after begin(). The visitors are automatically unregistered at the end of a transaction (commit or rollback).
    
    Parameters:
    
    visitor - the visitor to register
    
    Returns:
    
    a handle uniquely referring to the visitor
    
    See Also:
    
    isPersistenceOperationAllowed(org.tentackle.persist.AbstractDbObject, char)
  - unregisterPersistenceVisitor
```
public PersistenceVisitor unregisterPersistenceVisitor(DbTransactionHandle handle)
```
    Unegisters a PersistenceVisitor.
    
    Parameters:
    
    handle - the visitor's handle to unregister
    
    Returns:
    
    the visitor if removed, null if not registered
  - getPersistenceVisitors
```
public Collection<PersistenceVisitor> getPersistenceVisitors()
```
    Gets the currently registered persistence visitors.
    
    Returns:
    
    the visitors, null or empty if none
  - isPersistenceOperationAllowed
```
public boolean isPersistenceOperationAllowed(AbstractDbObject<?> object,
                                             char modType)
```
    Checks whether a persistence operation is allowed.
    This is determined by consulting the PersistenceVisitors.
    
    Parameters:
    
    object - the persistence object
    
    modType - the modification type
    
    Returns:
    
    true if allowed
    
    See Also:
    
    registerPersistenceVisitor(org.tentackle.persist.PersistenceVisitor)
  - registerCommitTxRunnable
```
public DbTransactionHandle registerCommitTxRunnable(CommitTxRunnable commitRunnable)
```
    Registers a CommitTxRunnable to be invoked just before committing a transaction.
    
    Parameters:
    
    commitRunnable - the runnable to register
    
    Returns:
    
    the handle
  - unregisterCommitTxRunnable
```
public CommitTxRunnable unregisterCommitTxRunnable(DbTransactionHandle handle)
```
    Unregisters a CommitTxRunnable.
    
    Parameters:
    
    handle - the runnable's handle to unregister
    
    Returns:
    
    the runnable, null if not registered
  - getCommitTxRunnables
```
public Collection<CommitTxRunnable> getCommitTxRunnables()
```
    Gets the currently registered commit runnables.
    
    Returns:
    
    the runnables, null or empty if none
  - registerRollbackTxRunnable
```
public DbTransactionHandle registerRollbackTxRunnable(RollbackTxRunnable rollbackRunnable)
```
    Registers a RollbackTxRunnable to be invoked just before rolling back a transaction.
    
    Parameters:
    
    rollbackRunnable - the runnable to register
    
    Returns:
    
    the handle
  - unregisterRollbackTxRunnable
```
public RollbackTxRunnable unregisterRollbackTxRunnable(DbTransactionHandle handle)
```
    Unregisters a RollbackTxRunnable.
    
    Parameters:
    
    handle - the runnable's handle to unregister
    
    Returns:
    
    the runnable, null if not registered
  - getRollbackTxRunnables
```
public Collection<RollbackTxRunnable> getRollbackTxRunnables()
```
    Gets the currently registered rollback runnables.
    
    Returns:
    
    the runnables, null or empty if none
  - commit
```
public boolean commit(long txVoucher)
```
    Commits a transaction if the corresponding begin() has started it. The corresponding begin() is determined by the txVoucher parameter. If it fits to the issued voucher the tx will be committed. If it is 0, nothing will happen. In all other cases an exception will be thrown.
    
    Specified by:
    
    commit in interface Session
    
    Parameters:
    
    txVoucher - the transaction voucher, 0 if do nothing (nested tx)
    
    Returns:
    
    true if committed, false if nested tx
  - commitImmediately
```
public boolean commitImmediately()
```
    Commits the current transaction, if pending.
    Applications should use commit(long). Invocations of this method will be logged as a warning.
    
    Returns:
    
    true if committed
  - rollback
```
public boolean rollback(long txVoucher)
```
    Specified by:
    
    rollback in interface Session
  - rollbackSilently
```
public boolean rollbackSilently(long txVoucher)
```
    Specified by:
    
    rollbackSilently in interface Session
  - rollback
```
public boolean rollback(long txVoucher,
                        boolean withLog)
```
    Rolls back a transaction if the corresponding begin() has started it.
    
    Parameters:
    
    txVoucher - the transaction voucher, 0 if ignore (nested tx)
    
    withLog - true if log via INFO
    
    Returns:
    
    true if tx was really rolled back, false if not.
  - rollbackImmediately
```
public boolean rollbackImmediately()
```
    Rolls back the current transaction, if pending.
    Applications should use rollback(long). Invocations of this method will be logged as a warning.
    
    Specified by:
    
    rollbackImmediately in interface Session
    
    Returns:
    
    true if rolled back
  - forceDetached
```
public void forceDetached()
```
    Detach the db.
    Used in execption handling to cleanup all pending statements and result sets.
  - getSessionId
```
public int getSessionId()
```
    Gets the connection id. This is a unique number assigned to this Db by the ConnectionManager.
    
    Specified by:
    
    getSessionId in interface Session
    
    Returns:
    
    the connection id, 0 = Db is new and not connected so far
  - setSessionGroupId
```
public void setSessionGroupId(int number)
```
    Sets the group number for this db.
    This is an optional number describing groups of db-connections, which is particulary useful in rmi-servers: if one connection fails, all others should be closed as well. Groups are only meaningful for local db-connections, i.e. for remote dbs the group instance refers to that of the rmi-server.
    
    Parameters:
    
    number - is the group number, 0 = no group
  - getSessionGroupId
```
public int getSessionGroupId()
```
    Specified by:
    
    getSessionGroupId in interface Session
  - groupWith
```
public int groupWith(int sessionId)
```
    Specified by:
    
    groupWith in interface Session
  - setOwnerThread
```
public void setOwnerThread(Thread ownerThread)
```
    Sets the exclusive owner thread.
    Allows to detect other threads accidently using this db.
    Caution: don't forget to clear!
    
    Specified by:
    
    setOwnerThread in interface Session
    
    Parameters:
    
    ownerThread - the owner thread, null to clear
  - getOwnerThread
```
public Thread getOwnerThread()
```
    Gets the owner thread.
    
    Specified by:
    
    getOwnerThread in interface Session
    
    Returns:
    
    the exclusive thread, null if none
  - createStatement
```
public StatementWrapper createStatement(int resultSetType,
                                        int resultSetConcurrency)
```
    Creates a non-prepared statement.
    Non-prepared statements attach the db as soon as they are instatiated! The db is detached after executeUpdate or after executeQuery when its result set is closed.
    
    Parameters:
    
    resultSetType - a result set type; one of ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
    
    resultSetConcurrency - a concurrency type; one of ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
    
    Returns:
    
    the statement wrapper
  - createStatement
```
public StatementWrapper createStatement(int resultSetType)
```
    Creates a non-prepared statement.
    
    Parameters:
    
    resultSetType - a result set type; one of ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
    
    Returns:
    
    a new Statement object that will generate ResultSet objects with the given type and concurrency CONCUR_READ_ONLY
  - createStatement
```
public StatementWrapper createStatement()
```
    Creates a non-prepared statement.
    
    Returns:
    
    a new Statement object that will generate ResultSet objects with type TYPE_FORWARD_ONLY and concurrency CONCUR_READ_ONLY
  - getPreparedStatement
```
public PreparedStatementWrapper getPreparedStatement(StatementKey stmtKey,
                                                     boolean alwaysPrepare,
                                                     int resultSetType,
                                                     int resultSetConcurrency,
                                                     Supplier<String> sqlSupplier)
```
    Gets the prepared statement.
    Getting the prepared statement will attach the db to a connection. The db will be detached after executeUpdate() or executeQuery when its result set is closed.
    
    Parameters:
    
    stmtKey - the statement key
    
    alwaysPrepare - true if always do a physical prepare
    
    resultSetType - one of ResultSet.TYPE_...
    
    resultSetConcurrency - one of ResultSet.CONCUR_...
    
    sqlSupplier - the SQL supplier
    
    Returns:
    
    the prepared statement for this db
  - getPreparedStatement
```
public PreparedStatementWrapper getPreparedStatement(StatementKey stmtKey,
                                                     boolean alwaysPrepare,
                                                     Supplier<String> sqlSupplier)
```
    Gets the prepared statement.
    Uses ResultSet.TYPE_FORWARD_ONLY and ResultSet.CONCUR_READ_ONLY.
    
    Parameters:
    
    stmtKey - the statement key
    
    alwaysPrepare - true if always do a physical prepare
    
    sqlSupplier - the SQL supplier
    
    Returns:
    
    the prepared statement for this db
  - createPreparedStatement
```
public PreparedStatementWrapper createPreparedStatement(String sql,
                                                        int resultSetType,
                                                        int resultSetConcurrency)
```
    Creates a one-shot prepared statement.
    Getting the prepared statement will attach the db to a connection. The db will be detached after executeUpdate() or executeQuery() when its result set is closed.
    
    Parameters:
    
    sql - the SQL code
    
    resultSetType - one of ResultSet.TYPE_...
    
    resultSetConcurrency - one of ResultSet.CONCUR_...
    
    Returns:
    
    the prepared statement for this db
  - createPreparedStatement
```
public PreparedStatementWrapper createPreparedStatement(String sql)
```
    Creates a one-shot prepared statement.
    Uses ResultSet.TYPE_FORWARD_ONLY and ResultSet.CONCUR_READ_ONLY.
    
    Parameters:
    
    sql - the SQL code
    
    Returns:
    
    the prepared statement for this db
  - isTxRunning
```
public boolean isTxRunning()
```
    Gets the current transaction state.
    Technically, a transaction is running if the autocommit is turned off.
    
    Specified by:
    
    isTxRunning in interface Session
    
    Returns:
    
    true if a transaction is running
  - getSessionInfo
```
public SessionInfo getSessionInfo()
```
    Gets the current user info.
    
    Specified by:
    
    getSessionInfo in interface Session
    
    Returns:
    
    the UserInfo
  - setSessionInfo
```
public void setSessionInfo(SessionInfo sessionInfo)
```
    Sets the userInfo. This will *NOT* send the session to the remote server if this is a remote db.
    
    Parameters:
    
    sessionInfo - the session info
  - getBackendInfo
```
public BackendInfo getBackendInfo()
```
    Gets the backend info.
    
    Returns:
    
    the backend info
  - getUrl
```
public String getUrl()
```
    Specified by:
    
    getUrl in interface Session
  - clone
```
public Db clone()
```
    Clones a logical connection.
    Connections may be cloned, which results in a new connection using the cloned userinfo of the original connection. If the old db is already open, the new db will be opened as well. If the old db is closed, the cloned db will be closed.
    
    Specified by:
    
    clone in interface Session
    
    Overrides:
    
    clone in class Object
    
    Returns:
    
    the cloned Db
  - getClonedFromDb
```
public Db getClonedFromDb()
```
    Gets the original db if this db is cloned.
    
    Returns:
    
    the orginal db, null if this db is not cloned.
  - clearCloned
```
public void clearCloned()
```
    Clears the cloned state. Useful if the information is no longer needed.
  - isCloned
```
public boolean isCloned()
```
    Gets the cloned state.
    
    Returns:
    
    true if this db is cloned
  - getFetchSize
```
public int getFetchSize()
```
    Gets the default fetchsize
    
    Returns:
    
    the default fetchSize.
  - setFetchSize
```
public void setFetchSize(int fetchSize)
```
    Sets the default fetchsize for all "wrapped" statements (PreparedStatementWrapper and StatementWrapper)
    
    Parameters:
    
    fetchSize - the new default fetchSize
  - getMaxRows
```
public int getMaxRows()
```
    gets the maximum number of rows in resultsets.
    
    Returns:
    
    the max rows, 0 = no limit
  - setMaxRows
```
public void setMaxRows(int maxRows)
```
    sets the maximum number of rows in resultsets.
    
    Parameters:
    
    maxRows - the max rows, 0 = no limit (default)
  - isRemote
```
public boolean isRemote()
```
    Gets the type of the logical connection.
    
    Specified by:
    
    isRemote in interface Session
    
    Returns:
    
    true if remote, false if local
  - getRemoteSession
```
public RemoteSession getRemoteSession()
```
    Specified by:
    
    getRemoteSession in interface Session
  - prepareRemoteDelegate
```
public static int prepareRemoteDelegate(Class<?> clazz)
```
    Prepares a RemoteDelegate.
    The delegates for the AbstractDbObject-classes "live" in the db, i.e. the remote session. Thus, delegates are unique per class AND db! In order for the AbstractDbObject-derived classes to quickly map to the corresponding delegate, the delegates get a unique handle, i.e. an index to an array of delegates, which in turn is unique among ALL sessions.
    
    Parameters:
    
    clazz - is the AbstractDbObject-class
    
    Returns:
    
    the handle
  - getRemoteDelegate
```
public org.tentackle.persist.rmi.RemoteDelegate getRemoteDelegate(int delegateId)
```
    Gets the remote delegate by its id.
    
    Parameters:
    
    delegateId - is the handle for the delegate
    
    Returns:
    
    the delegate for this session
  - createRemoteDelegate
```
public org.tentackle.persist.rmi.RemoteDelegate createRemoteDelegate(String className)
                                                              throws RemoteException
```
    Creates the remote delegate.
    
    Parameters:
    
    className - the classname
    
    Returns:
    
    the delegate
    
    Throws:
    
    RemoteException - if creating the delegate failed
  - isCountModificationAllowed
```
public boolean isCountModificationAllowed()
```
    Checks whether objects are allowed to count modifications. The default is true.
    
    Returns:
    
    true if objects are allowed to count modifications
  - setCountModificationAllowed
```
public void setCountModificationAllowed(boolean countModificationAllowed)
```
    Defines whether objects are allowed to count modifications. Useful to turn off modcount for a special (temporary) connection doing certain tasks that should not be counted.
    
    Parameters:
    
    countModificationAllowed - true if allowed, false if turned off
  - setLogModificationAllowed
```
public void setLogModificationAllowed(boolean logModificationAllowed)
```
    Sets the modification allowed state. Useful to turn off modlog for a special (temporary) connection doing certain tasks that should not be logged. The state will be handed over to the remote db-connection as well.
    
    Parameters:
    
    logModificationAllowed - true to allow, false to deny
  - isLogModificationAllowed
```
public boolean isLogModificationAllowed()
```
    Gets the state of logModificationAllowed.
    
    Returns:
    
    true if modification logging is allowed (default).
  - setLogModificationDeferred
```
public void setLogModificationDeferred(boolean logModificationDeferred)
```
    Sets the modification logging deferred state for the current transaction.
    In deferred mode the ModificationLogs are not written to the database. Instead they are kept in memory and can be processed later via popModificationLogsOfTransaction(). The state will be handed over to the remote db-connection as well.
    Note: the deferred state will be reset to false after each begin/commit/rollback.
    Important: if the deferred state is changed within a transaction and there are already modifications made, i.e. modlogs were created, the deferred state will *not* be changed! Furthermore, if the deferred state is changed to false. the modlogs are removed from the database (but kept in memory). As a consequence, the in-memory modlogs will always contain the whole transaction or nothing. Only popModificationLogsOfTransaction() removes the logs collected so far or the end of the transaction.
    
    Parameters:
    
    logModificationDeferred - true to defer logs for the rest of current transaction, false to undefer
  - isLogModificationDeferred
```
public boolean isLogModificationDeferred()
```
    Gets the state for logModificationDeferred.
    
    Returns:
    
    true if modification logging is deferred. Default is not deferred.
  - pushModificationLogOfTransaction
```
public void pushModificationLogOfTransaction(ModificationLog log)
```
    Pushes a ModificationLog to the list of modlogs of the current transaction.
    Notice: only allowed for local databases!
    
    Parameters:
    
    log - the modlog
    
    See Also:
    
    popModificationLogsOfTransaction()
  - popModificationLogsOfTransaction
```
public List<ModificationLog> popModificationLogsOfTransaction()
```
    Returns the ModificationLogs of the current transaction. Upon return the list of logs is cleared.
    Works for local and remote databases.
    
    Returns:
    
    the logs, null = no logs
    
    See Also:
    
    pushModificationLogOfTransaction(org.tentackle.persist.ModificationLog)
  - getDefaultIdSource
```
public IdSource getDefaultIdSource()
```
    Gets the default IdSource.
    
    Returns:
    
    the idSource
  - setDefaultIdSource
```
public void setDefaultIdSource(IdSource idSource)
```
    Set the default IdSource.
    This is the source that is used to generate unique object IDs if classes did not configure their own source.
    
    Parameters:
    
    idSource - New value of property idSource.
  - getLogModificationTxId
```
public long getLogModificationTxId()
```
    Returns the current transaction id from the last BEGIN modification log. The tx-ID is only available if logModificationTx is true.
    
    Returns:
    
    the tx ID, 0 if no transaction is pending.
  - setLogModificationTxId
```
public void setLogModificationTxId(long logModificationTxId)
```
    Sets the transaction id. Normally the tx-ID is derived from the id of the BEGIN-modlog so it's not necessary to invoke this method from an application. (Poolkeeper's replication layer will do so!)
    
    Parameters:
    
    logModificationTxId - the transaction ID
  - isLogModificationTxEnabled
```
public boolean isLogModificationTxEnabled()
```
    Gets the value of logModificationTx.
    
    Returns:
    
    true if transaction begin/end is logged in the modification log, false if not (default)
  - setLogModificationTxEnabled
```
public void setLogModificationTxEnabled(boolean logModificationTxEnabled)
```
    Turn transaction-logging on or off. Default is off.
    With enabled logging the transactions are logged in the ModificationLog as well.
    
    Parameters:
    
    logModificationTxEnabled - true to turn on transaction logging.
  - getBackend
```
public Backend getBackend()
```
    Gets the database backend.
    
    Returns:
    
    the backend
  - getRemoteName
```
public String getRemoteName()
```
    Gets the name of the remote server application.
    
    Returns:
    
    the remote name

Class Db

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface org.tentackle.pdo.Session

Field Detail

PROPERTY_IDSOURCE

SOCKET_FACTORY

CIPHER_SUITES

PROTOCOLS

Constructor Detail

Db

Method Detail

registerGlobalCloseHandler

unregisterGlobalCloseHandler

getAllOpenDb

getInstanceNumber

getName

toString

compareTo

hashCode

equals

getSessionManager

setPool

getPool

isPooled

setPoolId

getPoolId

isReadOnly

setReadOnly

getRemoteConnection

getRemoteDbSession

connect

assertOwnerThread

assertOpen

assertTxRunning

assertNoTxRunning

assertNotRemote

assertRemote

isAlive

setAlive

getKeepAliveInterval

setKeepAliveInterval

setIdConfiguration

getIdSourceConfiguration

getDispatcher

logException

checkForDeadLink

open

clearPassword

registerCloseHandler

unregisterCloseHandler

close

finalize

setCrashed

isCrashed

isOpen

getTxNumber

getTxName

getTxLevel

invalidateTxLevel

isTxLevelValid

getImmediateRollbackTxLevel

getImmediateCommitTxLevel

setTxObject

getTxObject

transaction

transaction

begin

begin

isClientTx

logBeginTx

logCommitTx

getUpdateCount

registerPersistenceVisitor

unregisterPersistenceVisitor

getPersistenceVisitors

isPersistenceOperationAllowed

registerCommitTxRunnable