Package org.rapidcontext.core.proc

Class CallContext

java.lang.Object
org.rapidcontext.core.proc.CallContext
public class CallContext extends Object
A procedure call context. Each procedure call occurs within a specific call context that contains the environment, library and currently used adapter connections. The context also keeps track of the call stack and other information relevant to the procedure call.
Version:
1.0

  • Field Details

    • ATTRIBUTE_PROCEDURE

      public static final String ATTRIBUTE_PROCEDURE
      The attribute used for storing the execution root procedure. This attribute value is automatically stored by the execute() method.
      See Also:

    • ATTRIBUTE_START_TIME

      public static final String ATTRIBUTE_START_TIME
      The attribute used for storing the execution start time. This attribute value is automatically stored by the execute() method.
      See Also:

    • ATTRIBUTE_END_TIME

      public static final String ATTRIBUTE_END_TIME
      The attribute used for storing the execution end time. This attribute value is automatically stored by the execute() method.
      See Also:

    • ATTRIBUTE_PROGRESS

      public static final String ATTRIBUTE_PROGRESS
      The attribute used for storing the progress ratio. The progress value should be a double between 0.0 and 1.0, corresponding to the "percent complete" of the overall call. It is generally only safe to set this value for a top-level procedure, i.e. when the call stack height is one (1).
      See Also:

    • ATTRIBUTE_USER

      public static final String ATTRIBUTE_USER
      The attribute used for storing the user information.
      See Also:

    • ATTRIBUTE_SOURCE

      public static final String ATTRIBUTE_SOURCE
      The attribute used for storing call source information.
      See Also:

    • ATTRIBUTE_RESULT

      public static final String ATTRIBUTE_RESULT
      The attribute used for storing the result data.
      See Also:

    • ATTRIBUTE_ERROR

      public static final String ATTRIBUTE_ERROR
      The attribute used for storing the error message.
      See Also:

    • ATTRIBUTE_TRACE

      public static final String ATTRIBUTE_TRACE
      The attribute used for storing the trace flag.
      See Also:

    • ATTRIBUTE_LOG_BUFFER

      public static final String ATTRIBUTE_LOG_BUFFER
      The attribute used for storing the log string buffer.
      See Also:

    • MAX_LOG_LENGTH

      public static final int MAX_LOG_LENGTH
      The maximum number of characters to store in the log buffer.
      See Also:

  • Constructor Details

    • CallContext

      public CallContext(Storage storage, Environment env, Library library)
      Creates a new procedure call context.
      Parameters:
      storage - the data storage to use
      env - the environment to use
      library - the procedure library to use

  • Method Details

    • getStorage

      public Storage getStorage()
      Returns the data storage used by this context.
      Returns:
      the data storage used by this context

    • getEnvironment

      public Environment getEnvironment()
      Returns the connectivity environment used by this context.
      Returns:
      the connectivity environment

    • getLibrary

      public Library getLibrary()
      Returns the procedure library used by this context.
      Returns:
      the procedure library

    • getInterceptor

      public Interceptor getInterceptor()
      Returns the local procedure call interceptor. If no local interceptor has been set, the library procedure call interceptor will be returned instead.
      Returns:
      the call interceptor to use

    • setInterceptor

      public void setInterceptor(Interceptor i)
      Sets the local procedure call interceptor, overriding the default library procedure call interceptor for calls in this context.
      Parameters:
      i - the interceptor to use

    • getAttribute

      public Object getAttribute(String name)
      Returns a call attribute value.
      Parameters:
      name - the attribute name
      Returns:
      the call attribute value, or null if not defined

    • setAttribute

      public void setAttribute(String name, Object value)
      Sets a call attribute value.
      Parameters:
      name - the attribute name
      value - the attribute value

    • getCallStack

      public CallStack getCallStack()
      Returns the procedure call stack.
      Returns:
      the procedure call stack

    • readPermission

      public String readPermission(int depth)
      Returns the permission required to read a path at the current call stack height. If the current call stack height is less or equal to the specified depth, a normal read permission is returned. Otherwise an internal permission is returned.
      Parameters:
      depth - the max stack depth for read permission
      Returns:
      the permission required for reading (read or internal)
      See Also:

    • checkAccess

      public static void checkAccess(String path, String permission) throws ProcedureException
      Checks if the currently authenticated user has the specified access permission to a storage path.
      Parameters:
      path - the object storage path
      permission - the requested permission
      Throws:
      ProcedureException - if the current user didn't have the requested access permission

    • checkInternalAccess

      public static void checkInternalAccess(String path) throws ProcedureException
      Checks if the currently authenticated user has internal access to a storage path.
      Parameters:
      path - the object storage path
      Throws:
      ProcedureException - if the current user didn't have internal access

    • checkReadAccess

      public static void checkReadAccess(String path) throws ProcedureException
      Checks if the currently authenticated user has read access to a storage path.
      Parameters:
      path - the object storage path
      Throws:
      ProcedureException - if the current user didn't have read access

    • checkSearchAccess

      public static void checkSearchAccess(String path) throws ProcedureException
      Checks if the currently authenticated user has search access to a storage path.
      Parameters:
      path - the object storage path
      Throws:
      ProcedureException - if the current user didn't have search access

    • checkWriteAccess

      public static void checkWriteAccess(String path) throws ProcedureException
      Checks if the currently authenticated user has write access to a storage path.
      Parameters:
      path - the object storage path
      Throws:
      ProcedureException - if the current user didn't have write access

    • isInterrupted

      public boolean isInterrupted()
      Checks if the call has been interrupted. Once a call has been interrupted the procedure call chain will be stopped as soon as possible. Any further procedure calls in this call context will terminate immediately with an error.
      Returns:
      true if this call has been interrupted, or false otherwise
      See Also:

    • interrupt

      public void interrupt()
      Interrupts the current procedure call. Once a call has been interrupted the procedure call chain will be stopped as soon as possible. Any further procedure calls in this call context will terminate immediately with an error.
      See Also:

    • execute

      public Object execute(String name, Object[] args) throws ProcedureException
      Executes a procedure with the specified name and arguments. This is a convenience method for performing a procedure lookup and proper calls to reserve(), call() and releaseAll(). Before execution all required resources will be reserved, and once the execution terminates they will be released (if at the bottom of the call stack). The arguments must be specified in the same order as in the default bindings for the procedure.
      Parameters:
      name - the procedure name
      args - the call arguments
      Returns:
      the result of the call, or null if the call produced no result
      Throws:
      ProcedureException - if the call execution caused an error

    • reserve

      @Deprecated(forRemoval=true) public void reserve(Procedure proc) throws ProcedureException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Replaced with org.rapidcontext.core.type.Procedure signature.
      Reserves all adapter connections needed for executing the specified procedure. The reservation will be forwarded to the current call interceptor. Any connection or procedure in the default procedure bindings will be reserved recursively in this call context.
      Parameters:
      proc - the procedure definition
      Throws:
      ProcedureException - if the connections couldn't be reserved

    • reserve

      public void reserve(Procedure proc) throws ProcedureException
      Reserves all adapter connections needed for executing the specified procedure. The reservation will be forwarded to the current call interceptor. Any connection or procedure in the default procedure bindings will be reserved recursively in this call context.
      Parameters:
      proc - the procedure definition
      Throws:
      ProcedureException - if the connections couldn't be reserved

    • releaseAll

      public void releaseAll(boolean commit)
      Releases all currently reserved adapter connections. The release will be forwarded to the current call interceptor. Each reserved connection will either be committed or rolled back, depending on the commit flag.
      Parameters:
      commit - the commit (or rollback) flag

    • call

      @Deprecated(forRemoval=true) public Object call(Procedure proc, Object[] args) throws ProcedureException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Replaced with org.rapidcontext.core.type.Procedure signature.
      Calls a procedure with the specified arguments. The call will be forwarded to the current call interceptor. The arguments must be specified in the same order as in the default bindings for the procedure. All the required arguments must be provided and all connections must already have been reserved. Use execute() when a procedure is to be called from outside a prepared call context.
      Parameters:
      proc - the procedure definition
      args - the call arguments
      Returns:
      the call bindings
      Throws:
      ProcedureException - if the argument binding failed

    • call

      public Object call(Procedure proc, Object[] args) throws ProcedureException
      Calls a procedure with the specified arguments. The call will be forwarded to the current call interceptor. The arguments must be specified in the same order as in the default bindings for the procedure. All the required arguments must be provided and all connections must already have been reserved. Use execute() when a procedure is to be called from outside a prepared call context.
      Parameters:
      proc - the procedure definition
      args - the call arguments
      Returns:
      the call bindings
      Throws:
      ProcedureException - if the argument binding failed

    • call

      @Deprecated(forRemoval=true) public Object call(Procedure proc, Bindings bindings) throws ProcedureException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Replaced with org.rapidcontext.core.type.Procedure signature.
      Calls a procedure with the specified arguments. The call will be forwarded to the current call interceptor. All the required arguments must be provided and all connections must already have been reserved. Use execute() when a procedure is to be called from outside a prepared call context.
      Parameters:
      proc - the procedure definition
      bindings - the bindings to use
      Returns:
      the result of the call, or null if the call produced no result
      Throws:
      ProcedureException - if the call execution caused an error
      See Also:

    • call

      public Object call(Procedure proc, Bindings bindings) throws ProcedureException
      Calls a procedure with the specified arguments. The call will be forwarded to the current call interceptor. All the required arguments must be provided and all connections must already have been reserved. Use execute() when a procedure is to be called from outside a prepared call context.
      Parameters:
      proc - the procedure definition
      bindings - the bindings to use
      Returns:
      the result of the call, or null if the call produced no result
      Throws:
      ProcedureException - if the call execution caused an error
      See Also:

    • connectionReserve

      public Channel connectionReserve(String id, String permission) throws ProcedureException
      Reserves a connection channel. The reserved channel will be stored in this context until all channels are released.
      Parameters:
      id - the connection identifier
      permission - the required permission level
      Returns:
      the reserved connection channel
      Throws:
      ProcedureException - if the channel couldn't be reserved
      See Also:

    • connectionReleaseAll

      public void connectionReleaseAll(boolean commit)
      Releases all reserved adapter connections. The connections will either be committed or rolled back, depending on the commit flag.
      Parameters:
      commit - the commit (or rollback) flag
      See Also:

    • isTracing

      public boolean isTracing()
      Checks if this call context has call trace logging enabled.
      Returns:
      true if call trace logging is enabled, or false otherwise

    • log

      public void log(String message)
      Logs the specified message to the log if tracing is enabled.
      Parameters:
      message - the message text

    • logCall

      public void logCall(String proc, Bindings bindings) throws ProcedureException
      Logs the specified call to the log if tracing is enabled.
      Parameters:
      proc - the procedure name
      bindings - the procedure call bindings
      Throws:
      ProcedureException - if the call logging caused an error

    • logCall

      public void logCall(String name, Object[] args)
      Logs the specified call to the log if tracing is enabled.
      Parameters:
      name - the procedure or object method
      args - the arguments, or null for none

    • logResponse

      public void logResponse(Object obj)
      Logs the specified call response to the log if tracing is enabled.
      Parameters:
      obj - the call response

    • logError

      public void logError(Exception e)
      Logs the specified call error to the log if tracing is enabled.
      Parameters:
      e - the exception to log