Package io.deephaven.server.session

Class SessionState

java.lang.Object
io.deephaven.server.session.SessionState
public class SessionState extends Object
SessionState manages all exports for a single session.

It manages exported LivenessReferent. It cascades failures to child dependencies.

TODO: - cyclical dependency detection - out-of-order dependency timeout

Details Regarding Data Structure of ExportObjects:

  • The exportMap map, exportListeners list, exportListenerVersion, and export object's exportListenerVersion work together to enable a listener to synchronize with outstanding exports in addition to sending the listener updates while they continue to subscribe.
  • SessionState::exportMap's purpose is to map from the export id to the export object
  • SessionState::exportListeners' purpose is to keep a list of active subscribers
  • SessionState::exportListenerVersion's purpose is to know whether or not a subscriber has already seen a status
  • A listener will receive an export notification for export id NON_EXPORT_ID (a zero) to indicate that the run has completed. A listener may see an update for an export before receiving the "run has completed" message. A listener should be prepared to receive duplicate/redundant updates.

  • Field Details

  • Constructor Details

  • Method Details

    • wrapAsExport

      public static <T> SessionState.ExportObject<T> wrapAsExport(T export)
      Wrap an object in an ExportObject to make it conform to the session export API.
      Type Parameters:
      T - the type of the object
      Parameters:
      export - the object to wrap
      Returns:
      a sessionless export object

    • wrapAsFailedExport

      public static <T> SessionState.ExportObject<T> wrapAsFailedExport(Exception caughtException)
      Wrap an exception in an ExportObject to make it conform to the session export API. The export behaves as if it has already failed.
      Type Parameters:
      T - the type of the object
      Parameters:
      caughtException - the exception to propagate
      Returns:
      a sessionless export object

    • initializeExpiration

      @VisibleForTesting protected void initializeExpiration(@NotNull SessionService.TokenExpiration expiration)
      This method is controlled by SessionService to update the expiration whenever the session is refreshed.
      Parameters:
      expiration - the initial expiration time and session token

    • updateExpiration

      @VisibleForTesting protected void updateExpiration(@NotNull SessionService.TokenExpiration expiration)
      This method is controlled by SessionService to update the expiration whenever the session is refreshed.
      Parameters:
      expiration - the new expiration time and session token

    • getSessionId

      public String getSessionId()
      Returns:
      the session id

    • getExpiration

      public SessionService.TokenExpiration getExpiration()
      Returns:
      the current expiration token for this session

    • isExpired

      public boolean isExpired()
      Returns:
      whether or not this session is expired

    • getAuthContext

      public AuthContext getAuthContext()
      Returns:
      the auth context for this session

    • getExecutionContext

      public ExecutionContext getExecutionContext()
      Returns:
      the execution context for this session

    • getExport

      public <T> SessionState.ExportObject<T> getExport(Ticket ticket, String logId)
      Grab the ExportObject for the provided ticket.
      Parameters:
      ticket - the export ticket
      logId - an end-user friendly identification of the ticket should an error occur
      Returns:
      a future-like object that represents this export

    • getExport

      public <T> SessionState.ExportObject<T> getExport(org.apache.arrow.flight.impl.Flight.Ticket ticket, String logId)
      Grab the ExportObject for the provided ticket.
      Parameters:
      ticket - the export ticket
      logId - an end-user friendly identification of the ticket should an error occur
      Returns:
      a future-like object that represents this export

    • getExport

      public <T> SessionState.ExportObject<T> getExport(int exportId)
      Grab the ExportObject for the provided id.
      Parameters:
      exportId - the export handle id
      Returns:
      a future-like object that represents this export

    • getExportIfExists

      public <T> SessionState.ExportObject<T> getExportIfExists(int exportId)
      Grab the ExportObject for the provided id if it already exists, otherwise return null.
      Parameters:
      exportId - the export handle id
      Returns:
      a future-like object that represents this export

    • getExportIfExists

      public <T> SessionState.ExportObject<T> getExportIfExists(Ticket ticket, String logId)
      Grab the ExportObject for the provided id if it already exists, otherwise return null.
      Parameters:
      ticket - the export ticket
      logId - an end-user friendly identification of the ticket should an error occur
      Returns:
      a future-like object that represents this export

    • newServerSideExport

      public <T> SessionState.ExportObject<T> newServerSideExport(T export)
      Create and export a pre-computed element. This is typically used in scenarios where the number of exports is not known in advance by the requesting client.
      Type Parameters:
      T - the export type
      Parameters:
      export - the result of the export
      Returns:
      the ExportObject for this item for ease of access to the export

    • newExport

      public <T> SessionState.ExportBuilder<T> newExport(org.apache.arrow.flight.impl.Flight.Ticket ticket, String logId)
      Create an ExportBuilder to create the export after dependencies are satisfied.
      Type Parameters:
      T - the export type that the callable will return
      Parameters:
      ticket - the grpc Flight.Ticket for this export
      logId - an end-user friendly identification of the ticket should an error occur
      Returns:
      an export builder

    • newExport

      public <T> SessionState.ExportBuilder<T> newExport(Ticket ticket, String logId)
      Create an ExportBuilder to create the export after dependencies are satisfied.
      Type Parameters:
      T - the export type that the callable will return
      Parameters:
      ticket - the grpc Ticket for this export
      logId - an end-user friendly identification of the ticket should an error occur
      Returns:
      an export builder

    • newExport

      @VisibleForTesting public <T> SessionState.ExportBuilder<T> newExport(int exportId)
      Create an ExportBuilder to create the export after dependencies are satisfied.
      Type Parameters:
      T - the export type that the callable will return
      Parameters:
      exportId - the export id
      Returns:
      an export builder

    • nonExport

      public <T> SessionState.ExportBuilder<T> nonExport()
      Create an ExportBuilder to perform work after dependencies are satisfied that itself does not create any exports.
      Returns:
      an export builder

    • addOnCloseCallback

      public void addOnCloseCallback(Closeable onClose)
      Attach an on-close callback bound to the life of the session. Note that Closeable does not require that the close() method be idempotent, but when combined with removeOnCloseCallback(Closeable), close() will only be called once from this class.

      If called after the session has expired, this will throw, and the close() method on the provided instance will not be called.
      Parameters:
      onClose - the callback to invoke at end-of-life

    • removeOnCloseCallback

      public boolean removeOnCloseCallback(Closeable onClose)
      Remove an on-close callback bound to the life of the session.

      A common pattern to use this will be for an object to try to remove itself, and if it succeeds, to call its own Closeable.close(). If it fails, it can expect to have close() be called automatically.

      Parameters:
      onClose - the callback to no longer invoke at end-of-life
      Returns:
      true iff the callback was removed
      ApiNote:
      If this SessionState has already begun expiration processing, onClose will not be removed by this method. This means that if onClose was previously added and not removed, it either has already been invoked or will be invoked by the SessionState.

    • onExpired

      public void onExpired()
      Notes that this session has expired and exports should be released.

    • isExportStateFailure

      public static boolean isExportStateFailure(ExportNotification.State state)
      Returns:
      true iff the provided export state is a failure state

    • isExportStateTerminal

      public static boolean isExportStateTerminal(ExportNotification.State state)
      Returns:
      true iff the provided export state is a terminal state

    • addExportListener

      public void addExportListener(io.grpc.stub.StreamObserver<ExportNotification> observer)

    • removeExportListener

      public io.grpc.stub.StreamObserver<ExportNotification> removeExportListener(io.grpc.stub.StreamObserver<ExportNotification> observer)
      Remove an on-close callback bound to the life of the session.
      Parameters:
      observer - the observer to no longer be subscribed
      Returns:
      The item if it was removed, else null

    • numExportListeners

      @VisibleForTesting public long numExportListeners()

    • toErrorHandler

      public static SessionState.ExportErrorHandler toErrorHandler(SessionState.ExportErrorGrpcHandler errorHandler)
      Convert an SessionState.ExportErrorGrpcHandler to an SessionState.ExportErrorHandler.

      gRPC's error handlers are designed to consume StatusRuntimeException objects. Exports can fail for a variety of reasons, and the SessionState.ExportErrorHandler is designed to richly communicate export failures. This method is the glue between the two error handling APIs; enabling export error propagation to gRPC clients.

      Parameters:
      errorHandler - the gRPC specific error handler
      Returns:
      the generalized error handler