Package io.permazen.cli

Class Session

java.lang.Object

io.permazen.cli.Session

public class Session
extends Object

Holds Permazen-specific state during a CLI session.

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	Description
static interface	Session.Action	Callback interface used by Session.performSessionAction() and Session.performSessionActionWithCurrentTransaction().
static interface	Session.RetryableTransactionalAction	Extension of Session.TransactionalAction that indicates the transaction should be retried if a RetryTransactionException 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.

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)	Close a transaction.
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 open 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 open PermazenTransaction currently associated with this instance.
SchemaModel	getSchemaModel()	Get the SchemaModel configured for 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 schemas should be allowed.
boolean	isGarbageCollectSchemas()	Get whether the garbage collection of old schemas is enabled.
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	isVerbose()
boolean	openTransaction(Map<String,?> options)	Open a transaction.
boolean	performSessionAction(Session.Action action)	Perform the given action in the context of this session.
boolean	performSessionActionWithCurrentTransaction(Session.Action action)	Associate the current PermazenTransaction with this instance, if not already associated, while performing the given action.
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)	Set prefix to use when displaying error messages.
void	setGarbageCollectSchemas(boolean garbageCollectSchemas)
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	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

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

getPermazenTransaction

public PermazenTransaction getPermazenTransaction()

Get the open PermazenTransaction currently associated with this instance.

This method just invokes PermazenTransaction.getCurrent() and returns the result.

Returns:

the open PermazenTransaction in which to do work

Throws:

IllegalStateException - if performSessionAction() is not currently being invoked

IllegalStateException - if this instance is not in mode SessionMode.PERMAZEN

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. If this is left unconfigured, ValidationMode.AUTOMATIC is used for new transactions.

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

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)

isGarbageCollectSchemas

public boolean isGarbageCollectSchemas()

Get whether the garbage collection of old schemas is enabled. Default value is false.

This setting is ignored except in SessionMode.CORE_API.

Returns:

whether this session allows recording a new schema version

setGarbageCollectSchemas

public void setGarbageCollectSchemas(boolean garbageCollectSchemas)

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.

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)

Set prefix to use when displaying error messages.

Parameters:

prefix - error message prefix

isVerbose

public boolean isVerbose()

setVerbose

public void setVerbose(boolean verbose)

performSessionActionWithCurrentTransaction

public boolean performSessionActionWithCurrentTransaction(Session.Action action)
                                                   throws InterruptedException

Associate the current PermazenTransaction 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.PERMAZEN, there must be a PermazenTransaction open and associated with the current thread, and this instance must not already have a different PermazenTransaction associated with it (it may already have the same PermazenTransaction associated with it). The PermazenTransaction 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.PERMAZEN

InterruptedException - if the current thread is interrupted

IllegalArgumentException - if action is null

performSessionAction

public boolean performSessionAction(Session.Action action)
                             throws InterruptedException

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.TransactionalActionWithOptions 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.RetryableTransactionalAction, 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:

InterruptedException - if the current thread is interrupted

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

openTransaction

public boolean openTransaction(Map<String,?> options)
                        throws Exception

Open a transaction.

For experts only.

Throws:

Exception

closeTransaction

public void closeTransaction(boolean commit)
                      throws Exception

Close a transaction.

For experts only.

Throws:

Exception