Session (JSimpleDB Main Classes 3.0.0 API)

java.lang.Object
- org.jsimpledb.Session

```
public class Session
extends Object
```
Utility class for programmatic JSimpleDB database access.
Instances operate in one of three modes; see SessionMode.
Instances are not thread safe.

See Also:

SessionMode

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`Session.Action` Callback interface used by `Session.performSessionAction()` and `Session.performSessionActionWithCurrentTransaction()`.
`static interface`	`Session.HasTransactionOptions` Interface implemented by `Session.TransactionalAction`'s that want to provide custom transaction options.
`static interface`	`Session.RetryableAction` Tagging interface indicating a `Session.TransactionalAction` that should be retried if a `RetryTransactionException` is thrown.
`static interface`	`Session.TransactionalAction` Tagging interface indicating an `Session.Action` that requires there to be an open transaction.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`DEFAULT_INITIAL_RETRY_DELAY` Default value for the initial retry delay (in milliseconds).
`static int`	`DEFAULT_MAX_RETRIES` Default value for the maximum number of retry attempts.
`static int`	`DEFAULT_MAXIMUM_RETRY_DELAY` Default value for the maximum retry delay (in milliseconds).
`protected Logger`	`log`

Constructor Summary

Constructors
Constructor and Description
`Session(Database db)` Constructor for `SessionMode.CORE_API`.
`Session(JSimpleDB jdb)` Constructor for `SessionMode.JSIMPLEDB`.
`Session(KVDatabase kvdb)` Constructor for `SessionMode.KEY_VALUE`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Database`	`getDatabase()` Get the associated `Database`, if any.
`String`	`getDatabaseDescription()` Get a description of the database.
`int`	`getInitialRetryDelay()` Get the initial retry delay when a `Session.RetryableAction` is given to `performSessionAction()`.
`JSimpleDB`	`getJSimpleDB()` Get the associated `JSimpleDB`, if any.
`JTransaction`	`getJTransaction()` Get the open `JTransaction` currently associated with this instance.
`KVDatabase`	`getKVDatabase()` Get the associated `KVDatabase`.
`KVTransaction`	`getKVTransaction()` Get the open `KVTransaction` currently associated with this instance.
`int`	`getMaximumRetryDelay()` Configure the maximum retry delay when a `Session.RetryableAction` is given to `performSessionAction()`.
`int`	`getMaxRetries()` Get the maximum number of allowed retries when a `Session.RetryableAction` is given to `performSessionAction()`.
`SessionMode`	`getMode()` Get this instance's `SessionMode`.
`NameIndex`	`getNameIndex()` Get the `NameIndex` for this instance's `SchemaModel`.
`SchemaModel`	`getSchemaModel()` Get the `SchemaModel` configured for this instance.
`int`	`getSchemaVersion()` Get the schema version associated with this instance.
`Transaction`	`getTransaction()` Get the open `Transaction` currently associated with this instance.
`ValidationMode`	`getValidationMode()` Get the `ValidationMode` associated with this instance.
`boolean`	`isAllowNewSchema()` Get whether the recording of new schema versions should be allowed.
`boolean`	`isReadOnly()` Get whether new transactions should be marked read-only.
`boolean`	`isTransactionOpen()` Determine whether there is a transaction already associated with this instance.
`boolean`	`performSessionAction(Session.Action action)` Perform the given action in the context of this session.
`boolean`	`performSessionActionWithCurrentTransaction(Session.Action action)` Associate the current `JTransaction` with this instance, if not already associated, while performing the given action.
`protected void`	`reportException(Exception e)` Handle an exception thrown during an invocation of `performSessionAction()`.
`void`	`setAllowNewSchema(boolean allowNewSchema)`
`void`	`setDatabaseDescription(String databaseDescription)`
`void`	`setInitialRetryDelay(int initialRetryDelay)`
`void`	`setMaximumRetryDelay(int maximumRetryDelay)`
`void`	`setMaxRetries(int maxRetries)`
`void`	`setMode(SessionMode mode)` Change this instance's `SessionMode`.
`void`	`setReadOnly(boolean readOnly)`
`void`	`setRollbackOnly()` Mark the current transaction to be rolled back.
`void`	`setSchemaModel(SchemaModel schemaModel)`
`void`	`setSchemaVersion(int schemaVersion)`
`void`	`setValidationMode(ValidationMode validationMode)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_MAX_RETRIES
```
public static final int DEFAULT_MAX_RETRIES
```
    Default value for the maximum number of retry attempts.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_INITIAL_RETRY_DELAY
```
public static final int DEFAULT_INITIAL_RETRY_DELAY
```
    Default value for the initial retry delay (in milliseconds).
    
    See Also:
    
    Constant Field Values
  - DEFAULT_MAXIMUM_RETRY_DELAY
```
public static final int DEFAULT_MAXIMUM_RETRY_DELAY
```
    Default value for the maximum retry delay (in milliseconds).
    
    See Also:
    
    Constant Field Values
  - log
```
protected final Logger log
```
- Constructor Detail
  - Session
```
public Session(KVDatabase kvdb)
```
    Constructor for SessionMode.KEY_VALUE.
    
    Parameters:
    
    kvdb - key/value database
    
    Throws:
    
    IllegalArgumentException - if kvdb is null
  - Session
```
public Session(Database db)
```
    Constructor for SessionMode.CORE_API.
    
    Parameters:
    
    db - core database
    
    Throws:
    
    IllegalArgumentException - if db is null
  - Session
```
public Session(JSimpleDB jdb)
```
    Constructor for SessionMode.JSIMPLEDB.
    
    Parameters:
    
    jdb - database
    
    Throws:
    
    IllegalArgumentException - if jdb is null
- Method Detail
  - getMode
```
public SessionMode getMode()
```
    Get this instance's SessionMode.
    
    Returns:
    
    this instance's SessionMode.
  - setMode
```
public void setMode(SessionMode mode)
```
    Change this instance's SessionMode.
    
    Parameters:
    
    mode - new SessionMode
    
    Throws:
    
    IllegalArgumentException - if mode is null
    
    IllegalArgumentException - if mode requires a JSimpleDB (i.e., SessionMode.JSIMPLEDB), or Database (i.e., SessionMode.CORE_API) instance, but none was provided at construction
  - getKVDatabase
```
public KVDatabase getKVDatabase()
```
    Get the associated KVDatabase.
    
    Returns:
    
    the associated KVDatabase
  - getDatabase
```
public Database getDatabase()
```
    Get the associated Database, if any.
    
    Returns:
    
    the associated Database or null if this instance is not in SessionMode.JSIMPLEDB or SessionMode.CORE_API
  - getJSimpleDB
```
public JSimpleDB getJSimpleDB()
```
    Get the associated JSimpleDB, if any.
    
    Returns:
    
    the associated JSimpleDB or null if this instance is not in SessionMode.JSIMPLEDB
  - getKVTransaction
```
public KVTransaction getKVTransaction()
```
    Get the open KVTransaction currently associated with this instance.
    
    Returns:
    
    the open KVTransaction in which to do work
    
    Throws:
    
    IllegalStateException - if performSessionAction() is not currently being invoked
  - getTransaction
```
public Transaction getTransaction()
```
    Get the open Transaction currently associated with this instance.
    
    Returns:
    
    the open Transaction in which to do work
    
    Throws:
    
    IllegalStateException - if performSessionAction() is not currently being invoked
    
    IllegalStateException - if this instance is not in mode SessionMode.CORE_API or SessionMode.JSIMPLEDB
  - getJTransaction
```
public JTransaction getJTransaction()
```
    Get the open JTransaction currently associated with this instance.
    This method just invokes JTransaction.getCurrent() and returns the result.
    
    Returns:
    
    the open JTransaction in which to do work
    
    Throws:
    
    IllegalStateException - if performSessionAction() is not currently being invoked
    
    IllegalStateException - if this instance is not in mode SessionMode.JSIMPLEDB
  - getSchemaModel
```
public SchemaModel getSchemaModel()
```
    Get the SchemaModel configured for this instance. If this is left unconfigured, after the first transaction it will be updated with the schema model actually used.
    In SessionMode.KEY_VALUE, this always returns null.
    
    Returns:
    
    the schema model used by this session if available, otherwise null
  - setSchemaModel
```
public void setSchemaModel(SchemaModel schemaModel)
```
  - getNameIndex
```
public NameIndex getNameIndex()
```
    Get the NameIndex for this instance's SchemaModel.
    
    Returns:
    
    name index for the schema model assumed by this session
  - getDatabaseDescription
```
public String getDatabaseDescription()
```
    Get a description of the database.
    
    Returns:
    
    a short description of the underlying database
  - setDatabaseDescription
```
public void setDatabaseDescription(String databaseDescription)
```
  - getSchemaVersion
```
public int getSchemaVersion()
```
    Get the schema version associated with this instance. If this is left unconfigured, the highest numbered schema version will be used and after the first transaction this property will be updated accordingly.
    In SessionMode.KEY_VALUE, this always returns zero.
    
    Returns:
    
    the schema version used by this session if known, otherwise zero
  - setSchemaVersion
```
public void setSchemaVersion(int schemaVersion)
```
  - getValidationMode
```
public ValidationMode getValidationMode()
```
    Get the ValidationMode associated with this instance. If this is left unconfigured, ValidationMode.AUTOMATIC is used for new transactions.
    This property is only relevant in SessionMode.JSIMPLEDB.
    
    Returns:
    
    the validation mode used by this session
  - setValidationMode
```
public void setValidationMode(ValidationMode validationMode)
```
  - isAllowNewSchema
```
public boolean isAllowNewSchema()
```
    Get whether the recording of new schema versions should be allowed. Default value is false.
    In SessionMode.KEY_VALUE, this setting is ignored.
    
    Returns:
    
    whether this session allows recording a new schema version
  - setAllowNewSchema
```
public void setAllowNewSchema(boolean allowNewSchema)
```
  - isReadOnly
```
public boolean isReadOnly()
```
    Get whether new transactions should be marked read-only. Default value is false.
    
    Returns:
    
    whether this session creates read-only transactions
  - setReadOnly
```
public void setReadOnly(boolean readOnly)
```
  - getMaxRetries
```
public int getMaxRetries()
```
    Get the maximum number of allowed retries when a Session.RetryableAction is given to performSessionAction().
    Default value is DEFAULT_MAX_RETRIES.
    
    Returns:
    
    maximum number of retry attempts, or zero if retries are disabled
    
    See Also:
    
    Session.performSessionAction()
  - setMaxRetries
```
public void setMaxRetries(int maxRetries)
```
  - getInitialRetryDelay
```
public int getInitialRetryDelay()
```
    Get the initial retry delay when a Session.RetryableAction is given to performSessionAction().
    Default value is DEFAULT_INITIAL_RETRY_DELAY.
    
    Returns:
    
    initial retry delay in milliseconds
    
    See Also:
    
    Session.performSessionAction()
  - setInitialRetryDelay
```
public void setInitialRetryDelay(int initialRetryDelay)
```
  - getMaximumRetryDelay
```
public int getMaximumRetryDelay()
```
    Configure the maximum retry delay when a Session.RetryableAction is given to performSessionAction().
    Default value is DEFAULT_MAXIMUM_RETRY_DELAY.
    
    Returns:
    
    maximum retry delay in milliseconds
    
    See Also:
    
    Session.performSessionAction()
  - setMaximumRetryDelay
```
public void setMaximumRetryDelay(int maximumRetryDelay)
```
  - reportException
```
protected void reportException(Exception e)
```
    Handle an exception thrown during an invocation of performSessionAction().
    The implementation in Session logs an error message. Subclasses are encouraged to handle errors more gracefully within the context of the associated application.
    
    Parameters:
    
    e - exception thrown during performSessionAction()
  - performSessionActionWithCurrentTransaction
```
public boolean performSessionActionWithCurrentTransaction(Session.Action action)
```
    Associate the current JTransaction with this instance, if not already associated, while performing the given action.
    If action throws an Exception, it will be caught and handled by reportException() and then false returned.
    This instance must be in SessionMode.JSIMPLEDB, there must be a JTransaction open and associated with the current thread, and this instance must not already have a different JTransaction associated with it (it may already have the same JTransaction associated with it). The JTransaction will be left open when this method returns.
    This method safely handles re-entrant invocation.
    
    Parameters:
    
    action - action to perform
    
    Returns:
    
    true if action completed successfully, false if action threw an exception
    
    Throws:
    
    IllegalStateException - if there is a different open transaction already associated with this instance
    
    IllegalStateException - if this instance is not in mode SessionMode.JSIMPLEDB
    
    IllegalArgumentException - if action is null
  - performSessionAction
```
public boolean performSessionAction(Session.Action action)
```
    Perform the given action in the context of this session.
    If action is a Session.TransactionalAction, and there is no transaction currently associated with this instance, a new transaction will be created, held open while action executes, then committed; any transaction options from action implementing Session.HasTransactionOptions will be appied. Otherwise, action is just executed directly.
    In either case, if action throws an Exception, it will be caught and handled by reportException() and then false returned.
    If there is already a transaction currently associated with this instance, it is left open while action executes and upon return.
    If action is a Session.RetryableAction, and a newly created transaction throws a RetryTransactionException, it will be retried automatically up to the configured maximum number of retry attempts. An exponential back-off algorithm is used: after the first failed attempt, the current thread sleeps for the initial retry delay. After each subsequent failed attempt, the retry delay is doubled, up to the limit imposed by the configured maximum retry delay.
    
    Parameters:
    
    action - action to perform, possibly within a transaction
    
    Returns:
    
    true if action completed successfully, false if a transaction could not be created or action threw an exception
    
    Throws:
    
    IllegalArgumentException - if action is null
  - isTransactionOpen
```
public boolean isTransactionOpen()
```
    Determine whether there is a transaction already associated with this instance.
    
    Returns:
    
    true if a transaction is already open
  - setRollbackOnly
```
public void setRollbackOnly()
```
    Mark the current transaction to be rolled back.
    
    Throws:
    
    IllegalStateException - if there is no transaction associated with this instance

Class Session

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_MAX_RETRIES

DEFAULT_INITIAL_RETRY_DELAY

DEFAULT_MAXIMUM_RETRY_DELAY

log

Constructor Detail

Session

Session

Session

Method Detail

getMode

setMode

getKVDatabase

getDatabase

getJSimpleDB

getKVTransaction

getTransaction

getJTransaction

getSchemaModel

setSchemaModel

getNameIndex

getDatabaseDescription

setDatabaseDescription

getSchemaVersion

setSchemaVersion

getValidationMode

setValidationMode

isAllowNewSchema

setAllowNewSchema

isReadOnly

setReadOnly

getMaxRetries

setMaxRetries

getInitialRetryDelay

setInitialRetryDelay

getMaximumRetryDelay

setMaximumRetryDelay

reportException

performSessionActionWithCurrentTransaction

performSessionAction

isTransactionOpen

setRollbackOnly