org.apache.commons.workflow.base
Class BaseContext

java.lang.Object
  org.apache.commons.workflow.base.BaseContext

All Implemented Interfaces:

Context

Direct Known Subclasses:

WebContext

public class BaseContext
extends Object
implements Context

BaseContext is a basic Context implementation that can serve as a convenient base class for more sophisticated Context implementations.

WARNING - No synchronization is performed within this class. If it is used in a multiple thread environment, callers must take suitable precations.

Version:

$Revision: 155475 $ $Date: 2005-02-26 13:31:11 +0000 (Sat, 26 Feb 2005) $

Author:

Craig R. McClanahan

Field Summary

protected Activity	activity The Activity that we are associated with and executing Steps from (if any).
protected BaseContextBean	bean The bean representing the information about this Context made visible through JXPath.
protected org.apache.commons.collections.ArrayStack	calls The suspended "next step" Step for each in-progress Activity that has issued a call() to execute a subordinate Activity.
protected String[]	names The set of names associated with the registered Scopes.
protected Step	nextStep The Step that will be executed first the next time that execute() is called.
protected Scope[]	scopes The set of Scopes that have been associated with this Context.
protected org.apache.commons.collections.ArrayStack	stack The evaluation stack of nameless objects being processed.
protected org.apache.commons.collections.ArrayStack	state The BlockState stack of BlockState objects used to manage iteration.
protected ContextSupport	support The event listener support object for this Context.
protected boolean	suspend The suspension flag.

Fields inherited from interface org.apache.commons.workflow.Context

LOCAL_SCOPE, MAX_SCOPES

Constructor Summary

BaseContext()
Construct a new BaseContext with all default values.

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 (ie the currently assigned next step) of the Activity we are currently executing, and begin executing the specified Activity.
void	clear() Clear the evaluation stack.
void	clearBlockState() Clear the BlockState stack.
boolean	contains(String key) Return true if a bean with the specified key exist in any specified 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.
Step[]	getCalls() Return the set of pending Step executions that are pending because of calls to subordinate Activities have occurred.
org.apache.commons.jxpath.JXPathContext	getJXPathContext() Return the JXPathContext object that represents a unified namespace covering all of our registered Scopes.
Scope	getLocal() Return the Scope instance for our local Scope as a simple property.
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 -1.
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.

Methods inherited from class java.lang.Object

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

Field Detail

activity

protected Activity activity

The Activity that we are associated with and executing Steps from (if any).

bean

protected BaseContextBean bean

The bean representing the information about this Context made visible through JXPath.

calls

protected org.apache.commons.collections.ArrayStack calls

The suspended "next step" Step for each in-progress Activity that has issued a call() to execute a subordinate Activity.

names

protected String[] names

The set of names associated with the registered Scopes.

nextStep

protected Step nextStep

The Step that will be executed first the next time that execute() is called. This is maintained dynamically as execution proceeds, much like the "next instruction pointer" of a CPU tracks what instruction will be executed next.

scopes

protected Scope[] scopes

The set of Scopes that have been associated with this Context. When initially created, every Context has a Scope attached to identifier LOCAL_SCOPE already created.

stack

protected org.apache.commons.collections.ArrayStack stack

The evaluation stack of nameless objects being processed.

state

protected org.apache.commons.collections.ArrayStack state

The BlockState stack of BlockState objects used to manage iteration.

support

protected ContextSupport support

The event listener support object for this Context.

suspend

protected boolean suspend

The suspension flag. If this is set when a particular Step returns, control will be returned from our execute() method to allow interaction with the rest of the application. The next time that execute() is called, execution will resume with the next scheduled step.

Constructor Detail

BaseContext

public BaseContext()

Construct a new BaseContext with all default values.

Method Detail

contains

public boolean contains(String key)

Return true if 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.

Specified by:

contains in interface Context

Parameters:

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

contains

public boolean contains(String key,
                        int scope)

Does a bean with the specified key exist in the specified scope?

Specified by:

contains in interface Context

Parameters:

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

scope - Identifier of the scope to be returned.

get

public 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.

Specified by:

get in interface Context

Parameters:

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

get

public 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.

Specified by:

get in interface Context

Parameters:

key - Key of the bean to be searched for

scope - Identifier of the scope to be searched

put

public 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.

Specified by:

put in interface Context

Parameters:

key - Key of the bean to be stored (cannot be null)

value - Value of the bean to be stored

put

public 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.

Specified by:

put in interface Context

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

public 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.

Specified by:

remove in interface Context

Parameters:

key - Key of the bean to be removed

remove

public 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.

Specified by:

remove in interface Context

Parameters:

key - Key of the bean to be removed

scope - Scope the bean to be removed from

addScope

public 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.

Specified by:

addScope in interface Context

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

getLocal

public Scope getLocal()

Return the Scope instance for our local Scope as a simple property.

getScope

public Scope getScope(int scope)

Return the Scope implementation registered for the specified identifier, if any; otherwise, return null.

Specified by:

getScope in interface Context

Parameters:

scope - Scope identifier to select

getScope

public Scope getScope(String name)

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

Specified by:

getScope in interface Context

Parameters:

name - Scope name to select

getScopeId

public int getScopeId(String name)

Return the Scope identifier registered for the specified name, if any; otherwise, return -1.

Specified by:

getScopeId in interface Context

Parameters:

name - Scope name to select

clear

public void clear()

Clear the evaluation stack.

Specified by:

clear in interface Context

isEmpty

public boolean isEmpty()

Is the evaluation stack currently empty?

Specified by:

isEmpty in interface Context

peek

public Object peek()
            throws EmptyStackException

Return the top item from the evaluation stack without removing it.

Specified by:

peek in interface Context

Throws:

EmptyStackException - if the stack is empty

pop

public Object pop()
           throws EmptyStackException

Pop and return the top item from the evaluation stack.

Specified by:

pop in interface Context

Throws:

EmptyStackException - if the stack is empty

push

public void push(Object item)

Push a new item onto the top of the evaluation stack.

Specified by:

push in interface Context

Parameters:

item - New item to be pushed

clearBlockState

public void clearBlockState()

Clear the BlockState stack.

Specified by:

clearBlockState in interface Context

isEmptyBlockState

public boolean isEmptyBlockState()

Is the BlockState stack currently empty?

Specified by:

isEmptyBlockState in interface Context

peekBlockState

public BlockState peekBlockState()
                          throws EmptyStackException

Return the top item from the BlockState stack without removing it.

Specified by:

peekBlockState in interface Context

Throws:

EmptyStackException - if the stack is empty

popBlockState

public BlockState popBlockState()
                         throws EmptyStackException

Pop and return the top item from the BlockState stack.

Specified by:

popBlockState in interface Context

Throws:

EmptyStackException - if the stack is empty

pushBlockState

public void pushBlockState(BlockState item)

Push a new item onto the top of the BlockState stack.

Specified by:

pushBlockState in interface Context

Parameters:

item - New item to be pushed

call

public void call(Activity activity)

Save the execution state (ie 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.

Specified by:

call in interface Context

Parameters:

activity - The Activity to be called

execute

public 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.

Specified by:

execute in interface Context

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

public Activity getActivity()

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

Specified by:

getActivity in interface Context

getCalls

public Step[] getCalls()

Return the set of pending Step executions that are pending because of calls to subordinate Activities have occurred. If there are no pending Step executions, a zero-length array is returned.

getJXPathContext

public org.apache.commons.jxpath.JXPathContext getJXPathContext()

Return the JXPathContext object that represents a unified namespace covering all of our registered Scopes.

Specified by:

getJXPathContext in interface Context

getNextStep

public Step getNextStep()

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

Specified by:

getNextStep in interface Context

getSuspend

public boolean getSuspend()

Return the suspend flag.

Specified by:

getSuspend in interface Context

setActivity

public 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.

Specified by:

setActivity in interface Context

Parameters:

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

setNextStep

public 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.

Specified by:

setNextStep in interface Context

Parameters:

nextStep - The next Step to be executed

Throws:

IllegalArgumentException - if the specified Step is not part of the current Activity

setSuspend

public 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.

Specified by:

setSuspend in interface Context

Parameters:

suspend - The new suspend flag

addContextListener

public void addContextListener(ContextListener listener)

Add a listener that is notified each time beans are added, replaced, or removed in this context.

Specified by:

addContextListener in interface Context

Parameters:

listener - The ContextListener to be added

removeContextListener

public void removeContextListener(ContextListener listener)

Remove a listener that is notified each time beans are added, replaced, or removed in this context.

Specified by:

removeContextListener in interface Context

Parameters:

listener - The ContextListener to be removed