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
 ActivityContextInterface[] getActivities()
          Get the set of Activity Contexts that the SBB entity currently associated with the instance is currently attached to.
 java.lang.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.
 void maskEvent(java.lang.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

public SbbLocalObject getSbbLocalObject()
                                 throws TransactionRequiredLocalException,
                                        java.lang.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.
java.lang.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

public 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

public 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

public ActivityContextInterface[] getActivities()
                                         throws TransactionRequiredLocalException,
                                                java.lang.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.
java.lang.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

public void maskEvent(java.lang.String[] eventNames,
                      ActivityContextInterface aci)
               throws java.lang.NullPointerException,
                      TransactionRequiredLocalException,
                      java.lang.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:
java.lang.NullPointerException - if aci is null.
TransactionRequiredLocalException - if this method is invoked without a valid transaction context.
java.lang.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

public java.lang.String[] getEventMask(ActivityContextInterface aci)
                                throws java.lang.NullPointerException,
                                       TransactionRequiredLocalException,
                                       java.lang.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:
java.lang.NullPointerException - if aci is null.
TransactionRequiredLocalException - if this method is invoked without a valid transaction context.
java.lang.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

public 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

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