Field Detail

• 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)

• 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. 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.

  In either case, if there is already a transaction currently associated with this instance, it is left open while action executes and upon return.

  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