org.apache.tinkerpop.gremlin.server.handler

Class AbstractSession

java.lang.Object

org.apache.tinkerpop.gremlin.server.handler.AbstractSession

All Implemented Interfaces:

AutoCloseable, Runnable, Session

Direct Known Subclasses:

MultiTaskSession, SingleTaskSession

public abstract class AbstractSession
extends Object
implements Session, AutoCloseable

A base implementation of Session which offers some common functionality that matches typical Gremlin Server request response expectations for script, bytecode and graph operations. The class is designed to be extended but take care in understanding the way that different methods are called as they do depend on one another a bit. It maybe best to examine the source code to determine how best to use this class or to extend from the higher order classes of SingleTaskSession or MultiTaskSession.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	AbstractSession.CloseReason The reason that a particular session closed.

Field Summary

Fields

Modifier and Type	Field and Description
protected Set<String>	aliasesUsedBySession
protected AtomicReference<AbstractSession.CloseReason>	closeReason
protected GraphManager	graphManager
protected boolean	maintainStateAfterException
protected ConcurrentMap<String,Session>	sessions
protected Thread	sessionThread The session thread is a reference to the thread that is running the session and should be set by an implementation as the first line of the Runnable.run() method.

Fields inherited from interface org.apache.tinkerpop.gremlin.server.handler.Session

evalOpTimer, traversalOpTimer

Method Summary

Modifier and Type	Method and Description
protected void	cancel(boolean mayInterruptIfRunning)
void	close() Removes the session from the session list and cancels the future that manages the lifetime of the session.
protected void	closeTransaction(SessionTask sessionTask, Transaction.Status status) Closes a transaction with commit or rollback.
protected void	closeTransaction(Transaction.Status status) Close the transaction without a SessionTask which supplies null to that argument for closeTransaction(SessionTask, Transaction.Status).
protected void	closeTransactionSafely(SessionTask sessionTask, Transaction.Status status) Tries to close the transaction but will catch exceptions and log them.
protected void	closeTransactionSafely(Transaction.Status status) Tries to close the transaction but will catch exceptions and log them.
protected Optional<Throwable>	determineIfTemporaryException(Throwable ex) Check if any exception in the chain is TemporaryException then we should respond with the right error code so that the client knows to retry.
protected Optional<Iterator<?>>	fromBytecode(SessionTask sessionTask, Bytecode bytecode) Constructs an Iterator from Bytecode provided in the SessionTask.
protected Iterator<?>	fromScript(SessionTask sessionTask, String script) Constructs an Iterator from the results of a script evaluation provided in the SessionTask.
protected Map<String,Object>	generateResponseMetaData(SessionTask sessionTask, ResponseStatusCode code, Iterator<?> itty) Generates response result meta-data to put on a ResponseMessage.
protected Map<String,Object>	generateStatusAttributes(SessionTask sessionTask, ResponseStatusCode code, Iterator<?> itty) Generates response status meta-data to put on a ResponseMessage.
long	getActualTimeoutLengthWhenClosed()
Optional<AbstractSession.CloseReason>	getCloseReason()
GremlinScriptEngine	getScriptEngine(SessionTask sessionTask, String language) Gets the script engine from the cached one in the GremlinExecutor.
String	getSessionId() Gets the identifier for the session.
protected Bindings	getWorkerBindings()
protected void	handleException(SessionTask sessionTask, Throwable t)
protected void	handleGraphOperation(SessionTask sessionTask, Bytecode bytecode, Graph graph) If Bytecode is detected to contain a GraphOp then it gets processed by this method.
protected void	handleIterator(SessionTask sessionTask, Iterator<?> itty) Provides a generic way of iterating a result set back to the client.
boolean	isBoundTo(Channel channel) Determines if the supplied Channel object is the same as the one bound to the Session.
boolean	isTransactionManaged()
protected void	iterateComplete(SessionTask sessionTask, Iterator<?> itty) Called when iteration within handleIterator(SessionTask, Iterator) is on its final pass and the final frame is about to be sent back to the client.
protected Frame	makeFrame(SessionTask sessionTask, List<Object> aggregate, ResponseStatusCode code, Iterator<?> itty)
protected Bindings	mergeBindingsFromRequest(SessionTask sessionTask, Bindings bindings)
protected void	process(SessionTask sessionTask)
void	setSessionCancelFuture(ScheduledFuture<?> f) Sets a reference to the job that will cancel this session if it exceeds its timeout period.
void	setSessionFuture(Future<?> f) Sets a reference to the job itself that is running this session.
protected void	startTransaction(SessionTask sessionTask) Called right before a transaction starts within Runnable.run().
void	triggerTimeout(long timeout, boolean causedBySession) Provides a general way to interrupt the session by way of a timeout.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.tinkerpop.gremlin.server.handler.Session

isAcceptingTasks, submitTask

Methods inherited from interface java.lang.Runnable

run

Field Detail

sessionThread

protected Thread sessionThread

The session thread is a reference to the thread that is running the session and should be set by an implementation as the first line of the Runnable.run() method.

maintainStateAfterException

protected final boolean maintainStateAfterException

closeReason

protected final AtomicReference<AbstractSession.CloseReason> closeReason

graphManager

protected final GraphManager graphManager

sessions

protected final ConcurrentMap<String,Session> sessions

aliasesUsedBySession

protected final Set<String> aliasesUsedBySession

Method Detail

cancel

protected void cancel(boolean mayInterruptIfRunning)

isTransactionManaged

public boolean isTransactionManaged()

getSessionId

public String getSessionId()

Description copied from interface: Session

Gets the identifier for the session.

Specified by:

getSessionId in interface Session

isBoundTo

public boolean isBoundTo(Channel channel)

Description copied from interface: Session

Determines if the supplied Channel object is the same as the one bound to the Session.

Specified by:

isBoundTo in interface Session

getActualTimeoutLengthWhenClosed

public long getActualTimeoutLengthWhenClosed()

getCloseReason

public Optional<AbstractSession.CloseReason> getCloseReason()

getScriptEngine

public GremlinScriptEngine getScriptEngine(SessionTask sessionTask,
                                           String language)

Gets the script engine from the cached one in the GremlinExecutor.

setSessionCancelFuture

public void setSessionCancelFuture(ScheduledFuture<?> f)

Description copied from interface: Session

Sets a reference to the job that will cancel this session if it exceeds its timeout period.

Specified by:

setSessionCancelFuture in interface Session

setSessionFuture

public void setSessionFuture(Future<?> f)

Description copied from interface: Session

Sets a reference to the job itself that is running this session.

Specified by:

setSessionFuture in interface Session

triggerTimeout

public void triggerTimeout(long timeout,
                           boolean causedBySession)

Description copied from interface: Session

Provides a general way to interrupt the session by way of a timeout.

Specified by:

triggerTimeout in interface Session

Parameters:

timeout - the length of time that passed for the timeout to have triggered

causedBySession - determines if the timeout triggered due to a particular request (i.e. false or because of the session lifetime (i.e. true

process

protected void process(SessionTask sessionTask)
                throws SessionException

Throws:

SessionException

handleException

protected void handleException(SessionTask sessionTask,
                               Throwable t)
                        throws SessionException

Throws:

SessionException

determineIfTemporaryException

protected Optional<Throwable> determineIfTemporaryException(Throwable ex)

Check if any exception in the chain is TemporaryException then we should respond with the right error code so that the client knows to retry.

close

public void close()

Removes the session from the session list and cancels the future that manages the lifetime of the session.

Specified by:

close in interface AutoCloseable

fromScript

protected Iterator<?> fromScript(SessionTask sessionTask,
                                 String script)
                          throws Exception

Constructs an Iterator from the results of a script evaluation provided in the SessionTask.

Parameters:

sessionTask - The session task which can be used as a context in constructing the Iterator

script - The script extracted by the calling method from the sessionTask

Throws:

Exception

fromBytecode

protected Optional<Iterator<?>> fromBytecode(SessionTask sessionTask,
                                             Bytecode bytecode)
                                      throws Exception

Constructs an Iterator from Bytecode provided in the SessionTask. If the Bytecode is found to evalute to a GraphOp then it is processed and an empty Optional is returned.

Parameters:

sessionTask - The session task which can be used as a context in constructing the Iterator

bytecode - The Bytecode extracted by the calling method from the sessionTask

Throws:

Exception

getWorkerBindings

protected Bindings getWorkerBindings()
                              throws SessionException

Throws:

SessionException

mergeBindingsFromRequest

protected Bindings mergeBindingsFromRequest(SessionTask sessionTask,
                                            Bindings bindings)
                                     throws SessionException

Throws:

SessionException

handleIterator

protected void handleIterator(SessionTask sessionTask,
                              Iterator<?> itty)
                       throws InterruptedException

Provides a generic way of iterating a result set back to the client.

Parameters:

sessionTask - The Gremlin Server SessionTask object containing settings, request message, etc.

itty - The result to iterator

Throws:

InterruptedException

handleGraphOperation

protected void handleGraphOperation(SessionTask sessionTask,
                                    Bytecode bytecode,
                                    Graph graph)
                             throws Exception

If Bytecode is detected to contain a GraphOp then it gets processed by this method.

Throws:

Exception

iterateComplete

protected void iterateComplete(SessionTask sessionTask,
                               Iterator<?> itty)

Called when iteration within handleIterator(SessionTask, Iterator) is on its final pass and the final frame is about to be sent back to the client. This method only gets called on successful iteration of the entire result.

generateStatusAttributes

protected Map<String,Object> generateStatusAttributes(SessionTask sessionTask,
                                                      ResponseStatusCode code,
                                                      Iterator<?> itty)

Generates response status meta-data to put on a ResponseMessage.

Parameters:

itty - a reference to the current Iterator of results - it is not meant to be forwarded in this method

generateResponseMetaData

protected Map<String,Object> generateResponseMetaData(SessionTask sessionTask,
                                                      ResponseStatusCode code,
                                                      Iterator<?> itty)

Generates response result meta-data to put on a ResponseMessage.

Parameters:

itty - a reference to the current Iterator of results - it is not meant to be forwarded in this method

makeFrame

protected Frame makeFrame(SessionTask sessionTask,
                          List<Object> aggregate,
                          ResponseStatusCode code,
                          Iterator<?> itty)
                   throws Exception

Throws:

Exception

startTransaction

protected void startTransaction(SessionTask sessionTask)

Called right before a transaction starts within Runnable.run(). The default implementation checks for open transactions and throws an exception if it finds any and generally assumes auto-transactions are enabled on graphs (i.e. transaction automatically start on read/write).

Providers who do not follow these sorts of transaction semantics should provide an override to this method.

closeTransaction

protected void closeTransaction(Transaction.Status status)

Close the transaction without a SessionTask which supplies null to that argument for closeTransaction(SessionTask, Transaction.Status). This method is idempotent.

closeTransactionSafely

protected void closeTransactionSafely(Transaction.Status status)

Tries to close the transaction but will catch exceptions and log them. This method is idempotent.

closeTransactionSafely

protected void closeTransactionSafely(SessionTask sessionTask,
                                      Transaction.Status status)

Tries to close the transaction but will catch exceptions and log them. This method is idempotent.

closeTransaction

protected void closeTransaction(SessionTask sessionTask,
                                Transaction.Status status)

Closes a transaction with commit or rollback. Strict transaction management settings are observed when configured as such in Settings.strictTransactionManagement and when aliases are present on the request in the current SessionTask. If the supplied SessionTask is null then "strict" is bypassed so this form must be called with care. Bypassing is often useful to ensure that all transactions are cleaned up when multiple graphs are referenced. Prefer calling closeTransaction(Transaction.Status) in this case instead. This method is idempotent.