com.webify.wsf.engine.context
Interface ContextManager


public interface ContextManager

Interface for Context management including lifecyle and storage. Note that particular care must be taken when using this interface in a clustered environment! Non-clustered implementations (MemoryContextManager in particular) allow direct changes to Context objects returned by applicable methods. However, in clustered environments, these changes will not be propagated to the distributed cache unless an explicit call is made to updateContext(Context context). For example, if you were to do this:

     ContextManager manager = getContextManager();
     Context parent = manager.begin();
     Context child = manager.begin(parent);
     ...
     String parentId = parent.getContextIdentifier();
     Context reloadedParent = manager.getContext(parentId);
 
The parent object reference and the reloadedParent object reference would have object equality, but not reference equality. That is:
     (parent == reloadedParent)
 
would evaluate to false; however:
     (parent.equals(reloadedParent))
 
would evaluate to true. To be safe, users of this interface should take care to appropriately use updateContext(Context context).

Version:
$Revision: $
Author:
msanchez, pmschnei@us.ibm.com

Field Summary
static long DEFAULT_TIMEOUT
          The default timeout for new context instances.
static long ETERNITY
          Value used to indicate an eternal context.
static java.lang.String LOCAL_ID
          Valud used as the identifier for local context instances.
 
Method Summary
 void addContextListener(ContextListener listener)
          Adds a context lifecycle listener to the manager.
 Context begin()
          Mark the beginning of a business activity by creating a new context instance with the default timeout.
 Context begin(Context parentContext)
          Mark the beginning of a new step in a existing business activity using the given context as the parent and the setting the timeout to the default value.
 Context begin(Context parentContext, long timeout)
          Mark the beginning of a new step in a existing business activity using the given context as the parent and the setting the timeout to specified value.
 Context begin(long timeout)
          Mark the beginning of a business activity by creating a new context instance with the specified timeout.
 Context begin(java.lang.String parentContextId)
          Mark the beginning of a new step in a existing business activity using the given context as the parent and the setting the timeout to the default value.
 Context begin(java.lang.String parentContextId, long timeout)
          Mark the beginning of a new step in a existing business activity using the given context as the parent and the setting the timeout to specified value.
 void completed(java.lang.String contextId)
          Indicate that the business activity associated with the given context ID is complete.
 Context createLocalContext()
          Creates a new local Context instance.
 Context getContext(java.lang.String contextId)
          Gets the contents of the context specified by given ID.
 void removeContextListener(ContextListener listener)
          Removes a context lifecycle listener from the manager.
 void updateContext(Context context)
          Updates the contents of context identified by Context.getContextIdentifier().
 void updateContextTimeout(java.lang.String contextId, long timeout)
          Updates the timout of the Context specified by the given Id.
 

Field Detail

DEFAULT_TIMEOUT

static final long DEFAULT_TIMEOUT
The default timeout for new context instances.

See Also:
Constant Field Values

ETERNITY

static final long ETERNITY
Value used to indicate an eternal context.

See Also:
Constant Field Values

LOCAL_ID

static final java.lang.String LOCAL_ID
Valud used as the identifier for local context instances.

See Also:
Constant Field Values
Method Detail

createLocalContext

Context createLocalContext()
Creates a new local Context instance. Local contexts are not uniquely identifiable by the context manager and can not be used for tracking purposes. A local context can be used outside of the context manager for any other API that uses context data, but does not rely on context status.

Returns:
a new local context instance

begin

Context begin()
              throws ContextException
Mark the beginning of a business activity by creating a new context instance with the default timeout.

Returns:
a new context instance
Throws:
ContextException - to signal a problem with context creation

begin

Context begin(long timeout)
              throws ContextException
Mark the beginning of a business activity by creating a new context instance with the specified timeout.

Parameters:
timeout - the timeout for the context in milliseconds
Returns:
a new context instance
Throws:
ContextException - to signal a problem with context creation

begin

Context begin(Context parentContext)
              throws ContextException
Mark the beginning of a new step in a existing business activity using the given context as the parent and the setting the timeout to the default value. Note this does not update the parent's context properties.

Parameters:
parentContext - the parent context instance to associate with the activity
Returns:
a new context instance
Throws:
ContextException - to signal a problem with activity creation

begin

Context begin(Context parentContext,
              long timeout)
              throws ContextException
Mark the beginning of a new step in a existing business activity using the given context as the parent and the setting the timeout to specified value. Note this does not update the parent's context properties.

Parameters:
parentContext - the parent context instance to associate with the activity
timeout - the timeout for the context in milliseconds
Returns:
a new context instance
Throws:
ContextException - to signal a problem with activity creation

begin

Context begin(java.lang.String parentContextId)
              throws ContextException
Mark the beginning of a new step in a existing business activity using the given context as the parent and the setting the timeout to the default value. Note this does not update the parent's context properties.

Parameters:
parentContextId - the ID of the parent context instance to associate with the activity
Returns:
a new context instance
Throws:
ContextException - to signal a problem with activity creation

begin

Context begin(java.lang.String parentContextId,
              long timeout)
              throws ContextException
Mark the beginning of a new step in a existing business activity using the given context as the parent and the setting the timeout to specified value. Note this does not update the parent's context properties.

Parameters:
parentContextId - the ID of the parent context instance to associate with the activity
timeout - the timeout for the context in milliseconds
Returns:
a new context instance
Throws:
ContextException - to signal a problem with activity creation

completed

void completed(java.lang.String contextId)
               throws NoContextException,
                      UnknownContextException
Indicate that the business activity associated with the given context ID is complete. This will fail if the context specified by contextId has active children.

Parameters:
contextId -
Throws:
UnknownContextException - to signal that the context is unrecognized by the manager
NoContextException

getContext

Context getContext(java.lang.String contextId)
                   throws NoContextException,
                          UnknownContextException
Gets the contents of the context specified by given ID.

Parameters:
contextId - the ID of the context to query
Returns:
a context populated with its contents
Throws:
UnknownContextException - to signal that the context is unrecognized by the manager
NoContextException

updateContext

void updateContext(Context context)
                   throws NoContextException,
                          InvalidContextException,
                          UnknownContextException
Updates the contents of context identified by Context.getContextIdentifier(). This will fail if the context specified by contextId has active children.

Parameters:
context - the udpated context
Throws:
InvalidContextException - to signal that the contents of the passed context are invalid
UnknownContextException - to signal that the context is unrecognized by the manager
NoContextException

updateContextTimeout

void updateContextTimeout(java.lang.String contextId,
                          long timeout)
                          throws InvalidContextException,
                                 UnknownContextException
Updates the timout of the Context specified by the given Id.

Parameters:
contextId - a non-null Id of the Context to update
timeout - the timeout for the Context in seconds
Throws:
InvalidContextException - to signal that the contents of the passed context are invalid
UnknownContextException - to signal that the context is unrecognized by the manager

addContextListener

void addContextListener(ContextListener listener)
Adds a context lifecycle listener to the manager.

Parameters:
listener -

removeContextListener

void removeContextListener(ContextListener listener)
Removes a context lifecycle listener from the manager.

Parameters:
listener -


Copyright © 2002-2009 IBM. All Rights Reserved.