Package org.rapidcontext.core.proc

Class CallContext

java.lang.Object
org.rapidcontext.core.ctx.Context
org.rapidcontext.core.ctx.ThreadContext
org.rapidcontext.core.proc.CallContext
public class CallContext extends ThreadContext
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.

  • Field Details

    • ATTRIBUTE_PROCEDURE

      @Deprecated(forRemoval=true) public static final String ATTRIBUTE_PROCEDURE
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use procedure() instead.
      The attribute used for storing the execution root procedure. This attribute value is automatically stored by the execute() method.
      See Also:

    • ATTRIBUTE_START_TIME

      @Deprecated(forRemoval=true) public static final String ATTRIBUTE_START_TIME
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use ThreadContext.created() instead.
      The attribute used for storing the execution start time. This attribute value is automatically stored by the execute() method.
      See Also:

    • ATTRIBUTE_END_TIME

      @Deprecated(forRemoval=true) public static final String ATTRIBUTE_END_TIME
      Deprecated, for removal: This API element is subject to removal in a future version.
      Call processing time is being removed.
      The attribute used for storing the execution end time. This attribute value is automatically stored by the execute() method.
      See Also:

    • ATTRIBUTE_PROGRESS

      @Deprecated(forRemoval=true) public static final String ATTRIBUTE_PROGRESS
      Deprecated, for removal: This API element is subject to removal in a future version.
      Progress tracking is being removed.
      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

      @Deprecated(forRemoval=true) public static final String ATTRIBUTE_USER
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use ThreadContext.user() instead.
      The attribute used for storing the user information.
      See Also:

    • ATTRIBUTE_SOURCE

      @Deprecated(forRemoval=true) public static final String ATTRIBUTE_SOURCE
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use Context.id() for the ancestor request context.
      The attribute used for storing call source information.
      See Also:

    • ATTRIBUTE_RESULT

      @Deprecated(forRemoval=true) public static final String ATTRIBUTE_RESULT
      Deprecated, for removal: This API element is subject to removal in a future version.
      Call result storage is being removed.
      The attribute used for storing the result data.
      See Also:

    • ATTRIBUTE_ERROR

      @Deprecated(forRemoval=true) public static final String ATTRIBUTE_ERROR
      Deprecated, for removal: This API element is subject to removal in a future version.
      Call result storage is being removed.
      The attribute used for storing the error message.
      See Also:

    • ATTRIBUTE_TRACE

      @Deprecated(forRemoval=true) public static final String ATTRIBUTE_TRACE
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use isLogging() instead.
      The attribute used for storing the trace flag.
      See Also:

    • ATTRIBUTE_LOG_BUFFER

      @Deprecated(forRemoval=true) public static final String ATTRIBUTE_LOG_BUFFER
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use ThreadContext.log() instead.
      The attribute used for storing the log string buffer.
      See Also:

    • CX_PROCEDURE

      public static final String CX_PROCEDURE
      The procedure context attribute.
      See Also:

    • CX_CONNECTIONS

      public static final String CX_CONNECTIONS
      The connections context attribute. This contains a map of reserved connection channels, indexed by connection id. Before executing a procedure tree, all the required connection channels are reserved and stored here.
      See Also:

    • CX_INTERRUPTED

      public static final String CX_INTERRUPTED
      The call interrupted attribute.
      See Also:

  • Constructor Details

    • CallContext

      protected CallContext(String id)
      Creates a new procedure call context.
      Parameters:
      id - the context identifier (name)

  • Method Details

    • active

      public static CallContext active()
      Returns the currently active call context. If no call context is available, null is returned.
      Returns:
      the currently active call context, or null

    • init

      public static CallContext init(String id) throws ProcedureException
      Creates a new procedure call context.
      Parameters:
      id - the procedure identifier
      Returns:
      a new call context
      Throws:
      ProcedureException - if the procedure wasn't found or access was denied

    • init

      public static CallContext init(Procedure proc) throws ProcedureException
      Creates a new procedure call context.
      Parameters:
      proc - the procedure to call
      Returns:
      a new call context
      Throws:
      ProcedureException - if access was denied

    • execute

      public static Object execute(String name, Object... args) throws ProcedureException
      Executes a procedure with the specified name and arguments. This is a convenience method that creates a new call context, locates the procedure, and calls reserve(), call() and releaseAll() (when applicable). Before execution all required resources will be reserved, and once the execution terminates they will (eventually) be released. 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

    • getStorage

      @Deprecated(forRemoval=true) public Storage getStorage()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use storage() instead.
      Returns the data storage used by this context.
      Returns:
      the data storage used by this context
      See Also:

    • getEnvironment

      @Deprecated(forRemoval=true) public Environment getEnvironment()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use environment() instead.
      Returns the connectivity environment used by this context.
      Returns:
      the connectivity environment
      See Also:

    • getLibrary

      @Deprecated(forRemoval=true) public Library getLibrary()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Procedures and interceptors are now initialized as normal storage objects instead. The Library API will be removed.
      Returns the procedure library used by this context.
      Returns:
      the procedure library

    • getInterceptor

      @Deprecated(forRemoval=true) public Interceptor getInterceptor()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Handled by CallInterceptor or ReserveInterceptor instead.
      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
      See Also:

    • setInterceptor

      @Deprecated(forRemoval=true) public void setInterceptor(Interceptor i)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Create a CallInterceptor or ReserveInterceptor instead.
      Sets the local procedure call interceptor, overriding the default library procedure call interceptor for calls in this context.
      Parameters:
      i - the interceptor to use
      See Also:

    • getAttribute

      @Deprecated(forRemoval=true) public Object getAttribute(String name)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use Context.get(String, Class) instead.
      Returns a call attribute value.
      Parameters:
      name - the attribute name
      Returns:
      the call attribute value, or null if not defined

    • setAttribute

      @Deprecated(forRemoval=true) public void setAttribute(String name, Object value)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use Context.set(String, Object) instead.
      Sets a call attribute value.
      Parameters:
      name - the attribute name
      value - the attribute value

    • isTop

      public boolean isTop()
      Checks if this is the top call context.
      Returns:
      true if this is the top call context, or false otherwise

    • top

      public CallContext top()
      Returns the top call context in the call chain.
      Returns:
      the top call context

    • procedure

      public Procedure procedure()
      Returns the call context procedure.
      Returns:
      the call context procedure

    • isCalledBy

      public boolean isCalledBy(Procedure proc)
      Checks if the specified procedure exists in the call context chain.
      Parameters:
      proc - the procedure to search for
      Returns:
      true if the procedure was found in the call context chain, or false otherwise

    • caller

      public Procedure caller()
      Returns the parent call context procedure (i.e. the calling procedure)
      Returns:
      the calling procedure, or null if this is the top call context

    • stackTrace

      public List<String> stackTrace()
      Returns a procedure stack trace for debugging purposes.
      Returns:
      an array with all procedures in the call context chain

    • getCallStack

      @Deprecated(forRemoval=true) public CallStack getCallStack()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use methods directly on the CallContext instance.
      Returns the procedure call stack.
      Returns:
      the procedure call stack

    • readPermission

      @Deprecated(forRemoval=true) public String readPermission(int depth)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Internal access is now achieved by combining read access with access via "procedure/**" (or a more limited pattern).
      Returns the permission required to read a path considering the call stack. If the call stack height is less or equal to the specified depth, a normal read permission is returned. Otherwise an internal permission is returned. All system procedures are ignored when calculating the call stack height.
      Parameters:
      depth - the depth for read/internal breakpoint
      Returns:
      the permission required for reading (read or internal)
      See Also:

    • checkAccess

      @Deprecated(forRemoval=true) public static void checkAccess(String path, String permission) throws ProcedureException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use ThreadContext.requireAccess(String, String) instead.
      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

      @Deprecated(forRemoval=true) public static void checkInternalAccess(String path) throws ProcedureException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use ThreadContext.requireAccess(String,String) with Role.PERM_INTERNAL instead.
      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

      @Deprecated(forRemoval=true) public static void checkReadAccess(String path) throws ProcedureException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use ThreadContext.requireReadAccess(String) instead.
      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

      @Deprecated(forRemoval=true) public static void checkSearchAccess(String path) throws ProcedureException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use ThreadContext.requireSearchAccess(String) instead.
      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

      @Deprecated(forRemoval=true) public static void checkWriteAccess(String path) throws ProcedureException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use ThreadContext.requireWriteAccess(String) instead.
      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 chain has been interrupted. Active threads may continue until completion, but any additional calls will terminate with an error.
      Returns:
      true if this call chain 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:

    • exec

      @Deprecated(forRemoval=true) public Object exec(Object[] args) throws ProcedureException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use execute(String, Object[]) instead.
      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:
      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

      protected void reserve() throws ProcedureException
      Recursively reserves all connections needed for executing the call context procedure (and dependencies). Each reservation will be forwarded to the reserve interceptor.
      Throws:
      ProcedureException - if the connections couldn't be reserved

    • reserveImpl

      protected void reserveImpl() throws ProcedureException
      Recursively reserves all connections needed for executing the call context procedure (and dependencies).
      Throws:
      ProcedureException - if the connections couldn't be reserved

    • call

      public Object call(Object[] args) throws ProcedureException
      Calls the call context procedure with the specified arguments. The arguments must be specified in the same order as in the procedure bindings. All required arguments must be provided and all connections must already have been reserved. The call will be forwarded to the call interceptor. This is an internal method. Use execute() when a procedure is to be called from outside a prepared call context.
      Parameters:
      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
      See Also:

    • callImpl

      protected Object callImpl(Bindings bindings) throws ProcedureException
      Calls the call context procedure with the specified bindings.
      Parameters:
      bindings - the procedure call bindings
      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

      @Deprecated(forRemoval=true) public Channel connectionReserve(String id, String permission) throws ProcedureException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use #connectionReserve(String) instead.
      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:

    • connectionReserve

      public Channel connectionReserve(String id) throws ProcedureException
      Reserves a connection channel. The reserved channel will be stored in this context until all channels are released. Note that no access controls will be made.
      Parameters:
      id - the connection identifier
      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:

    • isLogging

      public boolean isLogging()
      Checks if trace logging is enabled. This method also verifies that the current user has read permission for the procedure, as internal procedure calls should *not* be traced logged.
      Overrides:
      isLogging in class ThreadContext
      Returns:
      true if trace logging is enabled, or false otherwise

    • isTracing

      @Deprecated(forRemoval=true) public boolean isTracing()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use isLogging() instead.
      Checks if this call context has call trace logging enabled.
      Returns:
      true if call trace logging is enabled, or false otherwise

    • logCall

      @Deprecated(forRemoval=true) public void logCall(String proc, Bindings bindings)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use ThreadContext#logRequest(String, Object[]) instead.
      Logs the specified call to the log if tracing is enabled.
      Parameters:
      proc - the procedure name
      bindings - the procedure call bindings

    • logCall

      @Deprecated(forRemoval=true) public void logCall(String name, Object[] args)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use ThreadContext#logRequest(String, Object[]) instead.
      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