org.rapidcontext.core.proc

Class CallContext

java.lang.Object

org.rapidcontext.core.proc.CallContext

public class CallContext
extends java.lang.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

Author:

Per Cederberg

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ATTRIBUTE_END_TIME The attribute used for storing the execution end time.
static java.lang.String	ATTRIBUTE_ERROR The attribute used for storing the error message.
static java.lang.String	ATTRIBUTE_LOG_BUFFER The attribute used for storing the log string buffer.
static java.lang.String	ATTRIBUTE_PROCEDURE The attribute used for storing the execution root procedure.
static java.lang.String	ATTRIBUTE_PROGRESS The attribute used for storing the progress ratio.
static java.lang.String	ATTRIBUTE_RESULT The attribute used for storing the result data.
static java.lang.String	ATTRIBUTE_SOURCE The attribute used for storing call source information.
static java.lang.String	ATTRIBUTE_START_TIME The attribute used for storing the execution start time.
static java.lang.String	ATTRIBUTE_TRACE The attribute used for storing the trace flag.
static java.lang.String	ATTRIBUTE_USER The attribute used for storing the user information.
static int	MAX_LOG_LENGTH The maximum number of characters to store in the log buffer.

Constructor Summary

Constructors

Constructor and Description
CallContext(Storage storage, Environment env, Library library) Creates a new procedure call context.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	call(Procedure proc, Bindings bindings) Calls a procedure with the specified arguments.
java.lang.Object	call(Procedure proc, java.lang.Object[] args) Calls a procedure with the specified arguments.
static void	checkAccess(java.lang.String path, java.lang.String permission) Checks if the currently authenticated user has the specified access permission to a storage path.
static void	checkInternalAccess(java.lang.String path) Checks if the currently authenticated user has internal access to a storage path.
static void	checkReadAccess(java.lang.String path) Checks if the currently authenticated user has read access to a storage path.
static void	checkSearchAccess(java.lang.String path) Checks if the currently authenticated user has search access to a storage path.
static void	checkWriteAccess(java.lang.String path) Checks if the currently authenticated user has write access to a storage path.
void	connectionReleaseAll(boolean commit) Releases all reserved adapter connections.
Channel	connectionReserve(java.lang.String id) Reserves a connection channel.
java.lang.Object	execute(java.lang.String name, java.lang.Object[] args) Executes a procedure with the specified name and arguments.
java.lang.Object	getAttribute(java.lang.String name) Returns a call attribute value.
CallStack	getCallStack() Returns the procedure call stack.
Environment	getEnvironment() Returns the connectivity environment used by this context.
Interceptor	getInterceptor() Returns the local procedure call interceptor.
Library	getLibrary() Returns the procedure library used by this context.
Storage	getStorage() Returns the data storage used by this context.
void	interrupt() Interrupts the current procedure call.
boolean	isInterrupted() Checks if the call has been interrupted.
boolean	isTracing() Checks if this call context has call trace logging enabled.
void	log(java.lang.String message) Logs the specified message to the log if tracing is enabled.
void	logCall(java.lang.String name, java.lang.Object[] args) Logs the specified call to the log if tracing is enabled.
void	logError(java.lang.Exception e) Logs the specified call error to the log if tracing is enabled.
void	logResponse(java.lang.Object obj) Logs the specified call response to the log if tracing is enabled.
java.lang.String	readPermission(int depth) Returns the permission required to read a path at the current call stack height.
void	releaseAll(boolean commit) Releases all currently reserved adapter connections.
void	reserve(Procedure proc) Reserves all adapter connections needed for executing the specified procedure.
void	setAttribute(java.lang.String name, java.lang.Object value) Sets a call attribute value.
void	setInterceptor(Interceptor i) Sets the local procedure call interceptor, overriding the default library procedure call interceptor for calls in this context.

Methods inherited from class java.lang.Object

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

Field Detail

ATTRIBUTE_PROCEDURE

public static final java.lang.String ATTRIBUTE_PROCEDURE

The attribute used for storing the execution root procedure. This attribute value is automatically stored by the execute() method.

See Also:

Constant Field Values

ATTRIBUTE_START_TIME

public static final java.lang.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:

Constant Field Values

ATTRIBUTE_END_TIME

public static final java.lang.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:

Constant Field Values

ATTRIBUTE_PROGRESS

public static final java.lang.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:

Constant Field Values

ATTRIBUTE_USER

public static final java.lang.String ATTRIBUTE_USER

The attribute used for storing the user information.

See Also:

Constant Field Values

ATTRIBUTE_SOURCE

public static final java.lang.String ATTRIBUTE_SOURCE

The attribute used for storing call source information.

See Also:

Constant Field Values

ATTRIBUTE_RESULT

public static final java.lang.String ATTRIBUTE_RESULT

The attribute used for storing the result data.

See Also:

Constant Field Values

ATTRIBUTE_ERROR

public static final java.lang.String ATTRIBUTE_ERROR

The attribute used for storing the error message.

See Also:

Constant Field Values

ATTRIBUTE_TRACE

public static final java.lang.String ATTRIBUTE_TRACE

The attribute used for storing the trace flag.

See Also:

Constant Field Values

ATTRIBUTE_LOG_BUFFER

public static final java.lang.String ATTRIBUTE_LOG_BUFFER

The attribute used for storing the log string buffer.

See Also:

Constant Field Values

MAX_LOG_LENGTH

public static final int MAX_LOG_LENGTH

The maximum number of characters to store in the log buffer.

See Also:

Constant Field Values

Constructor Detail

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 Detail

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 java.lang.Object getAttribute(java.lang.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(java.lang.String name,
                         java.lang.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 java.lang.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:

Role.PERM_INTERNAL, Role.PERM_READ

checkAccess

public static void checkAccess(java.lang.String path,
                               java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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()

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:

isInterrupted()

execute

public java.lang.Object execute(java.lang.String name,
                                java.lang.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. 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

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

public java.lang.Object call(Procedure proc,
                             java.lang.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

public java.lang.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:

execute(String, Object[])

connectionReserve

public Channel connectionReserve(java.lang.String id)
                          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

Returns:

the reserved connection channel

Throws:

ProcedureException - if the channel couldn't be reserved

See Also:

connectionReleaseAll(boolean)

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:

connectionReserve(String)

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(java.lang.String message)

Logs the specified message to the log if tracing is enabled.

Parameters:

message - the message text

logCall

public void logCall(java.lang.String name,
                    java.lang.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(java.lang.Object obj)

Logs the specified call response to the log if tracing is enabled.

Parameters:

obj - the call response

logError

public void logError(java.lang.Exception e)

Logs the specified call error to the log if tracing is enabled.

Parameters:

e - the exception to log