Package io.permazen.cli

Class Session

java.lang.Object

io.permazen.cli.Session

@ThreadSafe
public class Session
extends Object

Holds Permazen-specific state during a CLI session, include the current open transaction, if any.

Instances operate in one of three modes; see SessionMode.

Instances are thread safe.

See Also:

• SessionMode

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Session.Action	Callback interface used by Session.performSessionAction()
static interface	Session.RetryableTransactionalAction	Extension of Session.TransactionalAction that indicates the transaction should be retried if a RetryKVTransactionException is thrown.
static interface	Session.TransactionalAction	Extension of Session.Action that indicates the action requires an open transaction.
static interface	Session.TransactionalActionWithOptions	Extension of Session.TransactionalAction that indicates the action provides custom transaction options.
static final class	Session.TxInfo	Information about the a transaction associated with a Session.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DEFAULT_ERROR_MESSAGE_PREFIX	Default error message prefix.
static final int	DEFAULT_INITIAL_RETRY_DELAY	Default value for the initial retry delay (in milliseconds).
static final int	DEFAULT_MAX_RETRIES	Default value for the maximum number of retry attempts.
static final int	DEFAULT_MAXIMUM_RETRY_DELAY	Default value for the maximum retry delay (in milliseconds).
protected final Logger	log

Constructor Summary

Constructors

Constructor	Description
Session(org.dellroad.jct.core.ConsoleSession<?,?> consoleSession, Database db)	Constructor for SessionMode.CORE_API.
Session(org.dellroad.jct.core.ConsoleSession<?,?> consoleSession, KVDatabase kvdb)	Constructor for SessionMode.KEY_VALUE.
Session(org.dellroad.jct.core.ConsoleSession<?,?> consoleSession, Permazen pdb)	Constructor for SessionMode.PERMAZEN.

Method Summary

Modifier and Type	Method	Description
void	closeTransaction(boolean commit)	Closed the transaction previously opened and associated with this instance by openTransaction().
Database	getDatabase()	Get the associated Database, if any.
String	getDatabaseDescription()	Get a description of the database.
PrintStream	getError()	Get the error output for this CLI session.
String	getErrorMessagePrefix()	Get prefix to use when displaying error messages.
int	getInitialRetryDelay()	Get the initial retry delay when a Session.RetryableTransactionalAction is given to performSessionAction().
KVDatabase	getKVDatabase()	Get the associated KVDatabase.
KVTransaction	getKVTransaction()	Get the KVTransaction currently associated with this instance.
int	getMaximumRetryDelay()	Configure the maximum retry delay when a Session.RetryableTransactionalAction is given to performSessionAction().
int	getMaxRetries()	Get the maximum number of allowed retries when a Session.RetryableTransactionalAction is given to performSessionAction().
SessionMode	getMode()	Get this instance's SessionMode.
PrintStream	getOutput()	Get the standard output for this CLI session.
Permazen	getPermazen()	Get the associated Permazen, if any.
PermazenTransaction	getPermazenTransaction()	Get the PermazenTransaction currently associated with this instance.
SchemaModel	getSchemaModel()	Get the SchemaModel configured for this instance.
TransactionConfig.SchemaRemoval	getSchemaRemoval()	Get the obsolete schema removal policy.
Transaction	getTransaction()	Get the Transaction currently associated with this instance.
Session.TxInfo	getTxInfo()	Get information about the transaction currently associated with this instance.
ValidationMode	getValidationMode()	Get the ValidationMode associated with this instance.
boolean	hasTransaction()	Determine whether there is a transaction associated with this instance.
boolean	isAllowNewSchema()	Get whether the recording of new schemas should be allowed.
boolean	isReadOnly()	Get whether new transactions should be marked read-only.
boolean	isVerbose()	Get whether to always show stack traces with error messages.
TransactionConfig	newTransactionConfig()	Build a new Core API TransactionConfig based on this instance.
Session.TxInfo	openBranchedTransaction(SessionMode txMode, Map<String,?> openOptions, Map<String,?> syncOptions)	Open a new branched transaction and associate it with this instance.
Session.TxInfo	openTransaction(SessionMode txMode, Map<String,?> kvoptions)	Open a new transaction in the specified mode and associate it with this instance.
boolean	performSessionAction(Session.Action action)	Perform the given action in the context of this session and (optionally) an open transaction.
protected void	reportException(Exception e)	Handle an exception thrown during execution of a command.
void	setAllowNewSchema(boolean allowNewSchema)
void	setDatabaseDescription(String databaseDescription)
void	setErrorMessagePrefix(String prefix)
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	setSchemaModel(SchemaModel schemaModel)
void	setSchemaRemoval(TransactionConfig.SchemaRemoval schemaRemoval)
void	setValidationMode(ValidationMode validationMode)
void	setVerbose(boolean verbose)
protected boolean	showStackTrace(Exception e)	Determine whether a stack trace should be included in error messages by default for the given exception.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

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

DEFAULT_ERROR_MESSAGE_PREFIX

public static final String DEFAULT_ERROR_MESSAGE_PREFIX

Default error message prefix.

See Also:

• Constant Field Values

log

protected final Logger log

Constructor Details

Session

public Session(org.dellroad.jct.core.ConsoleSession<?,?> consoleSession,
 KVDatabase kvdb)

Constructor for SessionMode.KEY_VALUE.

Parameters:

consoleSession - console session

kvdb - key/value database

Throws:

IllegalArgumentException - if either parameter is null

Session

public Session(org.dellroad.jct.core.ConsoleSession<?,?> consoleSession,
 Database db)

Constructor for SessionMode.CORE_API.

Parameters:

consoleSession - console session

db - core database

Throws:

IllegalArgumentException - if either parameter is null

Session

public Session(org.dellroad.jct.core.ConsoleSession<?,?> consoleSession,
 Permazen pdb)

Constructor for SessionMode.PERMAZEN.

Parameters:

consoleSession - console session

pdb - database

Throws:

IllegalArgumentException - if either parameter is null

Method Details

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 Permazen (i.e., SessionMode.PERMAZEN), 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.PERMAZEN or SessionMode.CORE_API

getPermazen

public Permazen getPermazen()

Get the associated Permazen, if any.

Returns:

the associated Permazen or null if this instance is not in SessionMode.PERMAZEN

getTxInfo

public Session.TxInfo getTxInfo()

Get information about the transaction currently associated with this instance.

Returns:

info for the transaction associated with this instance

Throws:

IllegalStateException - if there is no transaction associated with this instance

getKVTransaction

public KVTransaction getKVTransaction()

Get the KVTransaction currently associated with this instance.

Equivalent to getTxInfo().getKVTransaction().

Returns:

KVTransaction associated with this instance

Throws:

IllegalStateException - if there is no transaction associated with this session

getTransaction

public Transaction getTransaction()

Get the Transaction currently associated with this instance.

Equivalent to getTxInfo().getTransaction().

Returns:

Transaction associated with this instance

Throws:

IllegalStateException - if there is no transaction associated with this instance

IllegalStateException - if this instance was not in mode SessionMode.CORE_API or SessionMode.PERMAZEN when the transaction was opened

getPermazenTransaction

public PermazenTransaction getPermazenTransaction()

Get the PermazenTransaction currently associated with this instance.

Equivalent to getTxInfo().getPermazenTransaction().

Returns:

PermazenTransaction associated with this instance

Throws:

IllegalStateException - if there is no transaction associated with this instance

IllegalStateException - if this instance was not in mode SessionMode.PERMAZEN when the transaction was opened

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)

getDatabaseDescription

public String getDatabaseDescription()

Get a description of the database.

Returns:

a short description of the underlying database

setDatabaseDescription

public void setDatabaseDescription(String databaseDescription)

getValidationMode

public ValidationMode getValidationMode()

Get the ValidationMode associated with this instance.

Default value is ValidationMode.AUTOMATIC.

This property is only relevant in SessionMode.PERMAZEN.

Returns:

the validation mode used by this session

setValidationMode

public void setValidationMode(ValidationMode validationMode)

isAllowNewSchema

public boolean isAllowNewSchema()

Get whether the recording of new schemas should be allowed. Default value is true.

This setting is ignored except in SessionMode.CORE_API.

Returns:

whether this session allows recording a new schema version

setAllowNewSchema

public void setAllowNewSchema(boolean allowNewSchema)

getSchemaRemoval

public TransactionConfig.SchemaRemoval getSchemaRemoval()

Get the obsolete schema removal policy.

Default value is TransactionConfig.SchemaRemoval.CONFIG_CHANGE

This setting is ignored except in SessionMode.CORE_API.

Returns:

if and when to automatically remove unused schemas

setSchemaRemoval

public void setSchemaRemoval(TransactionConfig.SchemaRemoval schemaRemoval)

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.RetryableTransactionalAction 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.RetryableTransactionalAction 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.RetryableTransactionalAction 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)

getOutput

public PrintStream getOutput()

Get the standard output for this CLI session.

Returns:

output writer

getError

public PrintStream getError()

Get the error output for this CLI session.

Returns:

error writer

reportException

protected void reportException(Exception e)

Handle an exception thrown during execution of a command.

Parameters:

e - exception that occurred

showStackTrace

protected boolean showStackTrace(Exception e)

Determine whether a stack trace should be included in error messages by default for the given exception.

When isVerbose() is true, this method is obviated.

Parameters:

e - error

Returns:

true to include stack trace

getErrorMessagePrefix

public String getErrorMessagePrefix()

Get prefix to use when displaying error messages.

Default is "Error: ".

Returns:

error message prefix

setErrorMessagePrefix

public void setErrorMessagePrefix(String prefix)

isVerbose

public boolean isVerbose()

Get whether to always show stack traces with error messages.

Default is false.

Returns:

whether to always show stack traces

setVerbose

public void setVerbose(boolean verbose)

newTransactionConfig

public TransactionConfig newTransactionConfig()

Build a new Core API TransactionConfig based on this instance.

Returns:

core API transaction configuration

Throws:

IllegalStateException - if no Database was provided at construction

performSessionAction

public boolean performSessionAction(Session.Action action)
                             throws InterruptedException

Perform the given action in the context of this session and (optionally) an open transaction.

If action is not a Session.TransactionalAction, it is just executed with this instance as the parameter.

Otherwise, if there is no transaction currently associated with this instance, a new transaction is created, associated with the current thread while action executes, and then committed; if action implements Session.TransactionalActionWithOptions then its transaction options will be appied.

Otherwise, the already open transaction associated with this instance is associated with the current thread while action executes, and left open when this method returns.

In any case, if action throws an Exception, it will be caught and handled by reportException() and then false returned.

If action is a Session.RetryableTransactionalAction, and a newly created transaction throws a RetryKVTransactionException, 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:

InterruptedException - if the current thread is interrupted

IllegalArgumentException - if action is null

hasTransaction

public boolean hasTransaction()

Determine whether there is a transaction associated with this instance.

Equivalent to getTxInfo() != null.

Returns:

true if there is an associated transaction

openTransaction

public Session.TxInfo openTransaction(SessionMode txMode,
 Map<String,?> kvoptions)

Open a new transaction in the specified mode and associate it with this instance.

Parameters:

txMode - transaction session mode, or null for this session's mode

kvoptions - key/value transaction options, or null for none

Returns:

the newly created Session.TxInfo

Throws:

IllegalStateException - if there is already a transaction associated with this instance

IllegalStateException - if there is already a PermazenTransaction associated with the current thread

openBranchedTransaction

public Session.TxInfo openBranchedTransaction(SessionMode txMode,
 Map<String,?> openOptions,
 Map<String,?> syncOptions)

Open a new branched transaction and associate it with this instance.

Parameters:

txMode - transaction session mode, or null for this session's mode

openOptions - KVDatabase-specific transaction options for the branch's opening transaction, or null for none

syncOptions - KVDatabase-specific transaction options for the branch's commit transaction, or null for none

Returns:

the newly created Session.TxInfo

Throws:

IllegalStateException - if there is already a transaction associated with this instance

IllegalStateException - if there is already a PermazenTransaction associated with the current thread

closeTransaction

public void closeTransaction(boolean commit)

Closed the transaction previously opened and associated with this instance by openTransaction().

This essentially does the reverse of openTransaction().

If commit is false, and there is no transaction associated with this instance, this method does nothing.

Parameters:

commit - true to commit the transaction, false to roll it back

Throws:

IllegalStateException - if commit is true and there is no transaction associated with this instance