org.apache.commons.workflow
Interface Context

All Known Implementing Classes:
BaseContext, WebContext

public interface Context

A Context represents the dynamic computational state of a workflow process that is currently being executed. If multiple users are executing the same workflow process at the same time, they must have their own instance of Context.

Workflow engine implementations can register zero or more Scope instances, to provide the Steps that are being executed with access to arbitrary collections of JavaBeans. A Context will always have at least one Scope, called the LOCAL scope, which is the default source or destination for bean references. Scope instances can be identified by an integer subscript (which must be in the range 0 .. MAX_SCOPES-1), or a registered name. The registered name of the LOCAL scope is "local".

In addition to Scopes, which can be used for storing beans under specific names, an evaluation stack is provided for the convenience of Step implementations that want to pass temporary results back and forth. As with all Stack-based implementations, it is the responsibility of the Step implementations that are executed to maintain the stack's integrity.

Version:
$Revision: 155475 $ $Date: 2005-02-26 13:31:11 +0000 (Sat, 26 Feb 2005) $
Author:
Craig R. McClanahan

Field Summary
static int LOCAL_SCOPE
          The public identifier of the LOCAL scope, which is always defined by a Context implementation.
static int MAX_SCOPES
          The maximum number of Scopes (including LOCAL_SCOPE) that can be registered.
 
Method Summary
 void addContextListener(ContextListener listener)
          Add a listener that is notified each time beans are added, replaced, or removed in this context.
 void addScope(int scope, String name, Scope impl)
          Register a Scope implementation under the specified identifier.
 void call(Activity activity)
          Save the execution state (i.e.
 void clear()
          Clear the evaluation stack.
 void clearBlockState()
          Clear the BlockState stack.
 boolean contains(String key)
          Does a bean with the specified key exist in any specified scope? Scopes will be searched in ascending order of their identifiers, starting with LOCAL_SCOPE.
 boolean contains(String key, int scope)
          Does a bean with the specified key exist in the specified scope?
 void execute()
          Execute the Step currently identified as the next step, and continue execution until there is no next step, or until the suspend property has been set to true.
 Object get(String key)
          Return the bean associated with the specified key, if it exists in any scope.
 Object get(String key, int scope)
          Return the bean associated with the specified key, if it exists in the specified scope.
 Activity getActivity()
          Return the Activity we will be executing when the execute() method is called, if any.
 org.apache.commons.jxpath.JXPathContext getJXPathContext()
          Return the JXPathContext object that represents a unified namespace covering all of our registered Scopes.
 Step getNextStep()
          Return the Step that will be executed the next time that execute() is called, if any.
 Scope getScope(int scope)
          Return the Scope implementation registered for the specified identifier, if any; otherwise, return null.
 Scope getScope(String name)
          Return the Scope implementation registered for the specified name, if any; otherwise, return null.
 int getScopeId(String name)
          Return the Scope identifier registered for the specified name, if any; otherwise, return null.
 boolean getSuspend()
          Return the suspend flag.
 boolean isEmpty()
          Is the evaluation stack currently empty?
 boolean isEmptyBlockState()
          Is the BlockState stack currently empty?
 Object peek()
          Return the top item from the evaluation stack without removing it.
 BlockState peekBlockState()
          Return the top item from the BlockState stack without removing it.
 Object pop()
          Pop and return the top item from the evaluation stack.
 BlockState popBlockState()
          Pop and return the top item from the BlockState stack.
 void push(Object item)
          Push a new item onto the top of the evaluation stack.
 void pushBlockState(BlockState item)
          Push a new item onto the top of the BlockState stack.
 Object put(String key, Object value)
          Store the specified bean under the specified key, in local scope, replacing any previous value for that key.
 Object put(String key, Object value, int scope)
          Store the specified bean under the specified key, in the specified scope, replacing any previous value for that key.
 Object remove(String key)
          Remove any existing value for the specified key, in any scope.
 Object remove(String key, int scope)
          Remove any existing value for the specified key, from the specified scope.
 void removeContextListener(ContextListener listener)
          Remove a listener that is notified each time beans are added, replaced, or removed in this context.
 void setActivity(Activity activity)
          Set the Activity to be executed, and make the first defined Step within this Activity the next action to be performed by execute().
 void setNextStep(Step nextStep)
          Set the Step that will be executed the next time that execute() is called.
 void setSuspend(boolean suspend)
          Set the suspend flag.
 

Field Detail

LOCAL_SCOPE

static final int LOCAL_SCOPE
The public identifier of the LOCAL scope, which is always defined by a Context implementation.

See Also:
Constant Field Values

MAX_SCOPES

static final int MAX_SCOPES
The maximum number of Scopes (including LOCAL_SCOPE) that can be registered.

See Also:
Constant Field Values
Method Detail

contains

boolean contains(String key)
Does a bean with the specified key exist in any specified scope? Scopes will be searched in ascending order of their identifiers, starting with LOCAL_SCOPE.

Parameters:
key - Key of the bean to be searched for (cannot be null)

contains

boolean contains(String key,
                 int scope)
Does a bean with the specified key exist in the specified scope?

Parameters:
key - Key of the bean to be searched for (cannot be null)
scope - Identifier of the scope to be returned.

get

Object get(String key)
Return the bean associated with the specified key, if it exists in any scope. Scopes will be searched in increasing order of their identifiers, starting with LOCAL_SCOPE. If the underlying Scope allows null values, a null return will be ambiguous. Therefore, you can use the contains() method to determine whether the key actually exists.

Parameters:
key - Key of the bean to be retrieved (cannot be null)

get

Object get(String key,
           int scope)
Return the bean associated with the specified key, if it exists in the specified scope. If the underlying Scope allows null values, a null return will be ambiguous. Therefore, you can use the contains() method to determine whether the key actually exists.

Parameters:
key - Key of the bean to be searched for
scope - Identifier of the scope to be searched

put

Object put(String key,
           Object value)
Store the specified bean under the specified key, in local scope, replacing any previous value for that key. Any previous value will be returned.

Parameters:
key - Key of the bean to be stored (cannot be null)
value - Value of the bean to be stored

put

Object put(String key,
           Object value,
           int scope)
Store the specified bean under the specified key, in the specified scope, replacing any previous value for that key. Any previous value will be returned.

Parameters:
key - Key of the bean to be stored (cannot be null)
value - Value of the bean to be stored
scope - Identifier of the scope to use for storage

remove

Object remove(String key)
Remove any existing value for the specified key, in any scope. Scopes will be searched in ascending order of their identifiers, starting with LOCAL_SCOPE. Any previous value for this key will be returned.

Parameters:
key - Key of the bean to be removed

remove

Object remove(String key,
              int scope)
Remove any existing value for the specified key, from the specified scope. Any previous value for this key will be returned.

Parameters:
key - Key of the bean to be removed
scope - Scope the bean to be removed from

addScope

void addScope(int scope,
              String name,
              Scope impl)

Register a Scope implementation under the specified identifier. It is not legal to replace the LOCAL_SCOPE implementation that is provided by the Context implementation.

In addition to registering the new Scope such that it can be accessed dirctly via calls like Context.get(String,int), the Scope impl object will also be added to the LOCAL Scope under the same name. This makes possible a single unified namespace of all accessible objects that can be navigated by expression languages.

Parameters:
scope - Scope identifier to register under
name - Scope name to register under
impl - Scope implementation to be registered (or null to remove a previous registration)
Throws:
IllegalArgumentException - if you attempt to register or deregister the local scope

getScope

Scope getScope(int scope)
Return the Scope implementation registered for the specified identifier, if any; otherwise, return null.

Parameters:
scope - Scope identifier to select

getScope

Scope getScope(String name)
Return the Scope implementation registered for the specified name, if any; otherwise, return null.

Parameters:
name - Scope name to select

getScopeId

int getScopeId(String name)
Return the Scope identifier registered for the specified name, if any; otherwise, return null.

Parameters:
name - Scope name to select

clear

void clear()
Clear the evaluation stack.


isEmpty

boolean isEmpty()
Is the evaluation stack currently empty?


peek

Object peek()
            throws EmptyStackException
Return the top item from the evaluation stack without removing it.

Throws:
EmptyStackException - if the stack is empty

pop

Object pop()
           throws EmptyStackException
Pop and return the top item from the evaluation stack.

Throws:
EmptyStackException - if the stack is empty

push

void push(Object item)
Push a new item onto the top of the evaluation stack.

Parameters:
item - New item to be pushed

clearBlockState

void clearBlockState()
Clear the BlockState stack.


isEmptyBlockState

boolean isEmptyBlockState()
Is the BlockState stack currently empty?


peekBlockState

BlockState peekBlockState()
                          throws EmptyStackException
Return the top item from the BlockState stack without removing it.

Throws:
EmptyStackException - if the stack is empty

popBlockState

BlockState popBlockState()
                         throws EmptyStackException
Pop and return the top item from the BlockState stack.

Throws:
EmptyStackException - if the stack is empty

pushBlockState

void pushBlockState(BlockState item)
Push a new item onto the top of the BlockState stack.

Parameters:
item - New item to be pushed

call

void call(Activity activity)

Save the execution state (i.e. the currently assigned next step) of the Activity we are currently executing, and begin executing the specified Activity. When that Activity exits (either normally or by throwing an exception), the previous Activity will be resumed where it left off.

Parameters:
activity - The Activity to be called

execute

void execute()
             throws StepException

Execute the Step currently identified as the next step, and continue execution until there is no next step, or until the suspend property has been set to true. Upon completion of an activity, any execution state that was saved to due to utilizing the call() method will be restored, and the saved Activity execution shall be resumed.

Throws:
StepException - if an exception is thrown by the execute() method of a Step we have executed
IllegalStateException - if there is no defined next step (either because there is no Activity, or because we have already completed all the steps of this activity)

getActivity

Activity getActivity()

Return the Activity we will be executing when the execute() method is called, if any.


getJXPathContext

org.apache.commons.jxpath.JXPathContext getJXPathContext()
Return the JXPathContext object that represents a unified namespace covering all of our registered Scopes.


getNextStep

Step getNextStep()

Return the Step that will be executed the next time that execute() is called, if any.


getSuspend

boolean getSuspend()

Return the suspend flag.


setNextStep

void setNextStep(Step nextStep)

Set the Step that will be executed the next time that execute() is called. This is called by a Step that wants to perform branching based on some calculated results.

Parameters:
nextStep - The next Step to be executed
Throws:
IllegalArgumentException - if the specified Step is not part of the current Activity

setActivity

void setActivity(Activity activity)

Set the Activity to be executed, and make the first defined Step within this Activity the next action to be performed by execute().

If null is passed, any currently associated Activity will be released, and the evaluation stack and nested call state stack will be cleared.

WARNING - This will have to become more sophisticated in order to support calling nested Activities.

Parameters:
activity - The new Activity to be executed, or null to release resources

setSuspend

void setSuspend(boolean suspend)

Set the suspend flag. This is called by a Step that wants to signal the Context to return control to the caller of the execute() method before executing the next Step in the current activity.

Parameters:
suspend - The new suspend flag

addContextListener

void addContextListener(ContextListener listener)
Add a listener that is notified each time beans are added, replaced, or removed in this context.

Parameters:
listener - The ContextListener to be added

removeContextListener

void removeContextListener(ContextListener listener)
Remove a listener that is notified each time beans are added, replaced, or removed in this context.

Parameters:
listener - The ContextListener to be removed


Copyright © 2001-2010 The Apache Software Foundation. All Rights Reserved.