com.ibm.commerce.component.contextservice

Interface BusinessContextService

public interface BusinessContextService

This interface defines the required methods to implement the Business Context Service. Business Context Service provides services to create, manage the life cycle of and associate different contexts to a business activity. An activity is a sequence of requests initiated by the same user against the same store.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	COPYRIGHT IBM copyright notice field.

Method Summary

Modifier and Type	Method and Description
ActivityToken	begin(com.ibm.commerce.component.contextservice.ActivityData initData) This method creates an activity with the given initialization data.
ActivityToken	begin(java.lang.String logonId, java.lang.String pwd, com.ibm.commerce.component.contextservice.ActivityData initData) This method returns an activity for a given valid user logon ID and password.
ActivityToken	begin(java.lang.String logonId, java.lang.String pwd, ActivityDataNameValuePairs initDataNVPs) This method is the same as begin(String, String, ActivityData), but accepts initialization data as an ActivityDataNameValuePairs object, as per Web service requirements.
void	complete(ActivityToken token) This method completes a given activity.
ActivityToken	copyActivity(ActivityToken currentToken, com.ibm.commerce.component.contextservice.ActivityData sessionData) This method creates a new activity based on the contexts associated with a given token and session data.
ActivityToken	copyActivity(ActivityToken currentToken, ActivityDataNameValuePairs initDataNVPs) This method is the same as copyActivity(ActivityToken, ActivityData), but accepts session data as an ActivityDataNameValuePairs object, as per Web service requirements.
ActivityToken	createTransientClonedActivity(ActivityToken oldToken) Reserved for IBM internal use.
void	endRequest(ActivityToken token) Reserved for IBM internal use.
void	expire(ActivityToken token) Reserved for IBM internal use.
ActivityToken	findActivityTokenById(java.lang.Long activityTokenId) Reserved for IBM internal use.
ActivityToken	findActivityTokenForUserAndStore(java.lang.Long callerId, java.lang.Integer storeId) Reserved for IBM internal use.
Context	findContext(ActivityToken token, java.lang.String strContextName) This method finds the context with a given name that is associated with a given activity.
void	flushCache() Reserved for IBM internal use.
java.util.Map	getContextMap(ActivityToken token) Reserved for IBM internal use.
java.util.List	getContextSPIs(ActivityToken token) Reserved for IBM internal use.
boolean	isContextDirty(ActivityToken token) Reserved for IBM internal use.
boolean	isValidToken(ActivityToken token) This method checks the validity of a given token.
ActivityToken	resolveActivity(ActivityToken token, com.ibm.commerce.component.contextservice.ActivityData initData) Reserved for IBM internal use.
void	rollbackRequest(ActivityToken token) Reserved for IBM internal use.
void	setContextMap(ActivityToken token, java.util.Map ctxMap) Reserved for IBM internal use.
void	startRequest(ActivityToken token, com.ibm.commerce.component.contextservice.ActivityData sessionData) Reserved for IBM internal use.
void	stopActivities(java.lang.Long nUserId) Reserved for IBM internal use.
void	stopActivity(ActivityToken token) Stop the activity.
void	synchronizeContexts(ActivityToken token, boolean bRequestStarted) Reserved for IBM internal use.

Field Detail

COPYRIGHT

static final java.lang.String COPYRIGHT

IBM copyright notice field.

See Also:

Constant Field Values

Method Detail

begin

ActivityToken begin(com.ibm.commerce.component.contextservice.ActivityData initData)
             throws BusinessContextServiceException

This method creates an activity with the given initialization data. The implementation of this method will pass the initialization data down to the initialize(ActivityToken, ActivityData) method of each business context, where all the required parameters are extracted and used to populate the context. This method is called by a local client to indicate the beginning of an activity.

Parameters:

initData - the initialization data

Returns:

a valid token for the new activity

Throws:

BusinessContextServiceException - on any error encountered

begin

ActivityToken begin(java.lang.String logonId,
                    java.lang.String pwd,
                    com.ibm.commerce.component.contextservice.ActivityData initData)
             throws BusinessContextServiceException,
                    BusinessContextServiceAuthenticationException

This method returns an activity for a given valid user logon ID and password. The implementation of this method will:

1. Authenticate the user logon ID and password.
2. If successful, check whether an activity for the user already exists.
3. If no such activity exists - this is the first request - creates a new activity.
4. After an activity is found or created, updates the callerID and runAsID attributes of the activity.

Parameters:

logonId - the logon ID of the user who is trying to initiate an activity

pwd - the user's password

initData - the initialization data

Returns:

a valid token for the activity found or created

Throws:

BusinessContextServiceException - on any other error encountered

BusinessContextServiceAuthenticationException - if the user cannot be authenticated

begin

ActivityToken begin(java.lang.String logonId,
                    java.lang.String pwd,
                    ActivityDataNameValuePairs initDataNVPs)
             throws ServiceException

This method is the same as begin(String, String, ActivityData), but accepts initialization data as an ActivityDataNameValuePairs object, as per Web service requirements. This method is called by a remote client if user ID and password are available to begin an activity.

Parameters:

logonId - the logon ID of the user who is trying to initiate an activity

pwd - the user's password

initDataNVPs - the initialization data

Returns:

a valid token for the activity found or created

Throws:

ServiceException - whenever begin(String, String, ActivityData) throws an exception

findContext

Context findContext(ActivityToken token,
                    java.lang.String strContextName)
             throws BusinessContextServiceException,
                    BusinessContextNotFoundException

This method finds the context with a given name that is associated with a given activity. This method is used by business logic to retrieve session information of a given activity.

Parameters:

token - the activity token

strContextName - the context name

Returns:

the context; null if not found

Throws:

BusinessContextServiceException - if any generic error occurs

BusinessContextNotFoundException - if the specified context can not be loaded from the database

complete

void complete(ActivityToken token)
       throws ServiceException

This method completes a given activity. Changes the status of the activity to T in the CTXMGMT table to indicate that the activity is no longer active.

Parameters:

token - the activity token

Throws:

ServiceException - on any error encountered

expire

void expire(ActivityToken token)
     throws BusinessContextServiceException

Reserved for IBM internal use.

This method marks a given activity as expired. Changes the status of the activity to E in the CTXMGMT table to indicate that the activity has expired.

Parameters:

token - the activity token

Throws:

BusinessContextServiceException - on any error encountered

startRequest

void startRequest(ActivityToken token,
                  com.ibm.commerce.component.contextservice.ActivityData sessionData)
           throws BusinessContextServiceException

Reserved for IBM internal use.

This method is called before request execution for any necessary setup. The implementation of this method will pass the session data down to the preInvoke(ActivityData) method of each business context associated with the given activity. Next, all the required parameters are extracted and used to update the context. This method is called by a local client before the processing of a request.

Parameters:

token - the activity token

sessionData - the map of name-value pairs for the parameters that are passed in the request

Throws:

BusinessContextServiceException - on any error encountered

endRequest

void endRequest(ActivityToken token)
         throws BusinessContextServiceException

Reserved for IBM internal use.

This method is called after request execution for any necessary cleanup. The implementation of this method will, in turn, call the postInvoke(ActivityData) method of each business context associated with the given activity. This method is called by a local client after the processing of a request.

Parameters:

token - the activity token

Throws:

BusinessContextServiceException - on any error encountered

rollbackRequest

void rollbackRequest(ActivityToken token)
              throws BusinessContextServiceException

Reserved for IBM internal use.

This method is called when a request is rolled back. The implementation of this method will, in turn, call the reset() method of each business context associated with the given activity. This method is called by a local client to indicate when a request is rolled back.

Parameters:

token - the activity token

Throws:

BusinessContextServiceException - on any error encountered

copyActivity

ActivityToken copyActivity(ActivityToken currentToken,
                           com.ibm.commerce.component.contextservice.ActivityData sessionData)
                    throws BusinessContextServiceException

This method creates a new activity based on the contexts associated with a given token and session data. The implementation of this method will pass both arguments to the initialize(ActivityToken, ActivityToken, ActivityData) method of each business context, where the context is first initialized based on the input activity's context and then updated based on the session data. This method is called when it is required to switch to another activity under the following circumstances:

1. a different storeId is specified than previous requests
2. a different customer is served
3. request is initiated by a different user

Parameters:

currentToken - the activity token of the input activity

sessionData - the name-value pairs for the parameters that are passed in the request

Returns:

the activity token for the newly created activity

Throws:

BusinessContextServiceException - on any error encountered

copyActivity

ActivityToken copyActivity(ActivityToken currentToken,
                           ActivityDataNameValuePairs initDataNVPs)
                    throws ServiceException

This method is the same as copyActivity(ActivityToken, ActivityData), but accepts session data as an ActivityDataNameValuePairs object, as per Web service requirements. This method is called by a remote client.

Parameters:

currentToken - the activity token of the input activity

initDataNVPs - the name-value pairs for the parameters that are passed in the request

Returns:

the activity token for the newly created activity

Throws:

ServiceException - on any error encountered

resolveActivity

ActivityToken resolveActivity(ActivityToken token,
                              com.ibm.commerce.component.contextservice.ActivityData initData)
                       throws BusinessContextServiceException

Reserved for IBM internal use.

This method gets the valid activity token that is associated with a particular user and store. This method is mainly used when a user switches from one store to another. The implementation of this method will iterate through all existing activities and return an active one if possible.

Parameters:

token - an activity token that identifies the user

initData - initialization data that identifies the store

Returns:

the activity token if one exists; null otherwise

Throws:

BusinessContextServiceException - on any error encountered

findActivityTokenForUserAndStore

ActivityToken findActivityTokenForUserAndStore(java.lang.Long callerId,
                                               java.lang.Integer storeId)
                                        throws BusinessContextServiceException

Reserved for IBM internal use.

This method finds an activity token for a particular caller and store.

Parameters:

callerId - the caller ID

storeId - the store ID

Returns:

the activity token if one exists; null otherwise

Throws:

BusinessContextServiceException - on any error encountered

findActivityTokenById

ActivityToken findActivityTokenById(java.lang.Long activityTokenId)
                             throws BusinessContextServiceException

Reserved for IBM internal use.

This method finds an activity token by the specified activity token id.

Parameters:

activityTokenId - The activity token ID

Returns:

The activity token if exists; null otherwise

Throws:

BusinessContextServiceException - on any error encountered

isValidToken

boolean isValidToken(ActivityToken token)
              throws InvalidActivityTokenException

This method checks the validity of a given token. The implementation of this method will check the status of the activity and validate that the activity token has not been tampered with.

Parameters:

token - the token

Returns:

true if the token is valid

Throws:

InvalidActivityTokenException - if the token is not valid

getContextMap

java.util.Map getContextMap(ActivityToken token)
                     throws BusinessContextServiceException

Reserved for IBM internal use.

This method gets a map of string representations of all the contexts associated with a given activity. This method is provided for generic user support where contexts persist in a cookie instead of in a database.

Parameters:

token - the token that identifies the activity

Returns:

the map of string representations of all the contexts associated with the activity

Throws:

BusinessContextServiceException - on any error encountered

setContextMap

void setContextMap(ActivityToken token,
                   java.util.Map ctxMap)
            throws BusinessContextServiceException

Reserved for IBM internal use.

This method initializes the contexts of a given activity based on a map of string representations of all of the activity's contexts. This method is provided for generic user support where contexts are persisted in cookie instead of database.

Parameters:

token - the token that identifies the activity

ctxMap - the map of string representations of all the contexts associated with the activity

Throws:

BusinessContextServiceException - on any error encountered

isContextDirty

boolean isContextDirty(ActivityToken token)

Reserved for IBM internal use.

This method checks whether any of the contexts associated with a given token are dirty. The implementation of this method will iterate through all the business contexts of the activity and check whether each of them is dirty. This method is used by a local client.

Parameters:

token - the token

Returns:

true if any of the contexts are dirty; false otherwise

createTransientClonedActivity

ActivityToken createTransientClonedActivity(ActivityToken oldToken)

Reserved for IBM internal use.

This method creates a transient cloned token from a given token. The resulting token is a transient object to be used within a request and will not be persisted. Its contexts are copies of the input token's contexts. This method is used when a temporary change is required to the business context. Changes will not affect the original copies of the business context.

Parameters:

oldToken - the token to be cloned

Returns:

the transient cloned token created

stopActivities

void stopActivities(java.lang.Long nUserId)

Reserved for IBM internal use.

This method stops all activities for a given user. The implementation of this method will change the status of all active activities related to the user to 'T'. Once the status is moved from 'A' to 'T', the activity can no longer be used. This method is used to ensure that only one activity related to the given user can be active.

Parameters:

nUserId - the ID of the user for whom all activities are to be stopped

stopActivity

void stopActivity(ActivityToken token)

Stop the activity. Change its status from 'A' to 'T' and invalidate its context data.

Parameters:

token - The token of the activity to stop.

flushCache

void flushCache()

Reserved for IBM internal use.

This method flushes all activities from the activity cache for the current thread. Business contexts of an activity are cached in the Business Context Service for performance reason to save on context initialization. Activities are stored in the cache in a per thread basis. This method is called to clear the cache for the current thread at the exit point of a request.

getContextSPIs

java.util.List getContextSPIs(ActivityToken token)

Reserved for IBM internal use.

This method gets all the context service provider interface objects that are associated with a given activity. This is similar to the getContextMap(ActivityToken) method, but this method returns the business context in its context service provider interface objects instead of string representations.

Parameters:

token - the token that identifies the activity

Returns:

a list of the context service provider interface objects for the activity

synchronizeContexts

void synchronizeContexts(ActivityToken token,
                         boolean bRequestStarted)
                  throws BusinessContextServiceException

Reserved for IBM internal use.

This method is called by the base context in response to various changes therein. This method, in turn, calls the recalibrate() method of each context that depends on the base context so that they can recalibrate themselves accordingly.

Parameters:

token - the token that identifies the activity

bRequestStarted - true if startRequest(ActivityToken, ActivityData) has been called; false otherwise

Throws:

BusinessContextServiceException - on any error encountered