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

    All Methods Instance Methods Concrete Methods
    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(io.netty.channel.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(io.netty.channel.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.

Copyright © 2013–2022 Apache Software Foundation. All rights reserved.