javax.slee

Interface SbbContext

public interface SbbContext

The SbbContext interface provides an SBB object with access to SLEE-managed state that is dependent on the SBB's currently executing context.

An SbbContext object is given to an SBB object after the SBB object is created via the setSbbContext method. The SbbContext object remains associated with the SBB object for the lifetime of that SBB object. Note that the information that the SBB object obtains from the SbbContext object may change as the SLEE assigns the SBB object to different SBB entities during the SBB object's lifecycle.

Method Summary

Methods

Modifier and Type	Method and Description
ActivityContextInterface[]	getActivities() Get the set of Activity Contexts that the SBB entity currently associated with the instance is currently attached to.
String[]	getEventMask(ActivityContextInterface aci) Get the event mask currently set for an Activity Context for the SBB entity currently associated with the instance.
boolean	getRollbackOnly() Test if the current transaction has been marked for rollback only.
SbbID	getSbb() Get the SBB component identifier that identifies the SBB component of the SBB object.
SbbLocalObject	getSbbLocalObject() Get a local object reference to the SBB entity currently associated with the instance.
ServiceID	getService() Get the Service component identifier that identifies the Service component that the SBB object is executing on behalf of.
Tracer	getTracer(String tracerName) Get a tracer for the specified tracer name.
void	maskEvent(String[] eventNames, ActivityContextInterface aci) Mask events fired on an Activity Context from delivery to the SBB entity currently associated with the instance.
void	setRollbackOnly() Mark the current transaction for rollback.

Method Detail

getSbbLocalObject

SbbLocalObject getSbbLocalObject()
                                 throws TransactionRequiredLocalException,
                                        IllegalStateException,
                                        SLEEException

Get a local object reference to the SBB entity currently associated with the instance.

This method is a mandatory transactional method. The SBB object must have an assigned SBB entity when it invokes this method. The only transactional method where an SBB object is not assigned to an SBB entity is sbbCreate().

Returns:

an SbbLocalObject reference for the SBB entity currently associated with the instance.

Throws:

TransactionRequiredLocalException - if this method is invoked without a valid transaction context.

IllegalStateException - if the SBB object invoking this method is not assigned to an SBB entity.

SLEEException - if the local object reference could not be obtained due to a system-level failure.

getService

ServiceID getService()
                     throws SLEEException

Get the Service component identifier that identifies the Service component that the SBB object is executing on behalf of.

This method is a non-transactional method.

Returns:

the Service component identifier.

Throws:

SLEEException - if the Service component identifier could not be obtained due to a system-level failure.

getSbb

SbbID getSbb()
             throws SLEEException

Get the SBB component identifier that identifies the SBB component of the SBB object.

This method is a non-transactional method.

Returns:

the SBB component identifier.

Throws:

SLEEException - if the SBB component identifier could not be obtained due to a system-level failure.

getActivities

ActivityContextInterface[] getActivities()
                                         throws TransactionRequiredLocalException,
                                                IllegalStateException,
                                                SLEEException

Get the set of Activity Contexts that the SBB entity currently associated with the instance is currently attached to. The return array contains generic Activity Context Interface objects that can be converted to the SBB's own activity context interface type using the SBB's asSbbActivityContextInterface method.

This method is a mandatory transactional method. The SBB object must have an assigned SBB entity when it invokes this method. The only transactional method where an SBB object is not assigned to an SBB entity is sbbCreate().

Returns:

an array of generic Activity Context Interface objects that represent the Activity Contexts the SBB entity is attached to.

Throws:

TransactionRequiredLocalException - if this method is invoked without a valid transaction context.

IllegalStateException - if the SBB object invoking this method is not assigned to an SBB entity.

SLEEException - if the set of attached Activity Contexts could not be obtained due to a system-level failure.

maskEvent

void maskEvent(String[] eventNames,
             ActivityContextInterface aci)
               throws NullPointerException,
                      TransactionRequiredLocalException,
                      IllegalStateException,
                      UnrecognizedEventException,
                      NotAttachedException,
                      SLEEException

Mask events fired on an Activity Context from delivery to the SBB entity currently associated with the instance. The masking affects only that SBB entity and only in the context of the specified Activity Context.

When an SBB entity is initially attached (or reattached) to an Activity Context, the event types that are masked are the event types identified by <event> elements whose mask-on-attach attribute is set set to "true".

The effects of this method are not incremental or cumulative. If this method is invoked twice with two different sets of event names, the second set overwrites the first set as the event mask. Therefore an SBB entity unmasks events by invoking this method with a subset of the previously specified set of masked event names. This subset would exclude the event names of the event types that should be unmasked.

This method method is a mandatory transactional method. The effects of an invocation of this method are not persistent and visible beyond the current transaction until after the transaction commits. The SBB object must have an assigned SBB entity when it invokes this method. The only transactional method where an SBB object is not assigned to an SBB entity is sbbCreate().

Parameters:

eventNames - this specifies the event names of the event types that should be masked. The set of event names specified must identify a subset of the event types that the SBB can receive, ie. event names defined in event elements whose event-direction attribute is set to "Receive" or "FireAndReceive". A null or empty array value unmasks all previously masked event types.

aci - the Activity Context object that represents the Activity Context whose events should be masked from the SBB entity.

Throws:

NullPointerException - if aci is null.

TransactionRequiredLocalException - if this method is invoked without a valid transaction context.

IllegalStateException - if the SBB object invoking this method is not assigned to an SBB entity.

UnrecognizedEventException - if one of the event names does not correspond with the name of an event the SBB receives.

NotAttachedException - if the SBB entity is not attached to the specified Activity Context.

SLEEException - if the event mask could not be set due to a system-level failure.

See Also:

getEventMask(javax.slee.ActivityContextInterface)

getEventMask

String[] getEventMask(ActivityContextInterface aci)
                      throws NullPointerException,
                             TransactionRequiredLocalException,
                             IllegalStateException,
                             NotAttachedException,
                             SLEEException

Get the event mask currently set for an Activity Context for the SBB entity currently associated with the instance.

If the SBB entity has not invoked the maskEvent method to set an event mask after the SBB entity has (re)attached to the Activity Context, then the set of event names returned by this method is the set of event names of <event> elements whose mask-on-attach attribute is set to True. Otherwise, the set of event names returned by this method is the same as the set of event names specified by the most recent maskEvent method for the same SBB entity and Activity Context.

This method is a mandatory transactional method. The SBB object must have an assigned SBB entity when it invokes this method. The only transactional method where an SBB object is not assigned to an SBB entity is sbbCreate().

Parameters:

aci - the Activity Context object that represents the Activity Context whose event mask should be returned.

Returns:

an array of event names identifying the event types that have been masked.

Throws:

NullPointerException - if aci is null.

TransactionRequiredLocalException - if this method is invoked without a valid transaction context.

IllegalStateException - if the SBB object invoking this method is not assigned to an SBB entity.

NotAttachedException - if the SBB entity is not attached to the specified Activity Context.

SLEEException - if the event mask could not be obtained due to a system-level failure.

See Also:

maskEvent(java.lang.String[], javax.slee.ActivityContextInterface)

setRollbackOnly

void setRollbackOnly()
                     throws TransactionRequiredLocalException,
                            SLEEException

Mark the current transaction for rollback. The transaction will become permanently marked for rollback. A transaction marked for rollback can never commit.

An SBB object invokes this method when it does not want the current transaction to commit.

This method is a mandatory transactional method.

Throws:

TransactionRequiredLocalException - if this method is invoked without a valid transaction context.

SLEEException - if the current transaction could not be marked for rollback due to a system-level failure.

getRollbackOnly

boolean getRollbackOnly()
                        throws TransactionRequiredLocalException,
                               SLEEException

Test if the current transaction has been marked for rollback only. An SBB object invokes this method while executing within a transaction to determine if the transaction has been marked for rollback.

This method is a mandatory transactional method.

Returns:

true if the current transaction has been marked for rollback, false otherwise.

Throws:

TransactionRequiredLocalException - if this method is invoked without a valid transaction context.

SLEEException - if the current state of the transaction could not be obtained due to a system-level failure.

getTracer

Tracer getTracer(String tracerName)
                 throws NullPointerException,
                        IllegalArgumentException,
                        SLEEException

Get a tracer for the specified tracer name. The notification source used by the tracer is an SbbNotification that contains the service and SBB component identifiers returned by getService() and getSbb().

Refer Tracer for a complete discussion on tracers and tracer names.

Trace notifications generated by a tracer obtained using this method are of the type SbbNotification.TRACE_NOTIFICATION_TYPE.

This method is a non-transactional method.

Parameters:

tracerName - the name of the tracer.

Returns:

a tracer for the specified tracer name. Trace messages generated by this tracer will contain a notification source that is an SbbNotification object containing service and SBB component identifiers equal to that obtained from the getService() and getSbb() methods on this SbbContext.

Throws:

NullPointerException - if tracerName is null.

IllegalArgumentException - if tracerName is an invalid name. Name components within a tracer name must have at least one character. For example, "com.mycompany" is a valid tracer name, whereas "com..mycompany" is not.

SLEEException - if the Tracer could not be obtained due to a system-level failure.

Since:

SLEE 1.1