javax.slee

Interface Sbb

public interface Sbb

The Sbb interface is implemented by every Service Building Block (SBB) abstract class. Every SBB must include an SBB abstract class. The SLEE uses the methods defined in this interface to notify SBB objects of lifecycle events.

Additional method declarations
An SBB developer may define or implement a number of additional methods in the SBB abstract class that follow certain design patterns. These are:

• Methods invoked by the SLEE on an SBB object:
  • Event-handler methods:
    Event handler methods are implemented in the SBB abstract class with either of the following signatures. Each event handler method must be implemented with only one of these variants:
    public void on<event-name>(<event-class-name> event, <activity-context-interface-name> aci) { ... }
public void on<event-name>(<event-class-name> event, <activity-context-interface-name> aci, EventContext context) { ... }

    where:

    event-name is the name of the event given in the SBB's deployment descriptor.
    event-class-name is the class name of event objects of the repective event type.
    activity-context-interface-name is the name of the Activity Context Interface used by the SBB, as defined in the SBB's deployment descriptor.

    Event-handler methods are invoked with a valid transaction context on an SBB in the Ready state.

  • Initial event selector method:
    This method is invoked on an SBB object in the Pooled state. It allows the SBB to determine the selection criteria for the convergence name variables used in event routing. The initial event selector method has the following signature:
    public InitialEventSelector <method-name>(InitialEventSelector ies) { ... }

    where:

    method-name is the name of the method as defined in the SBB's deployment descriptor.

    Initial event selector methods are invoked on an SBB in the Pooled state with an unspecified transaction context.

• Methods invoked by SBB objects. These methods are all abstract and are implemented by the SLEE when the SBB is deployed. All these methods may throw a javax.slee.SLEEException if the operation could not be successfully completed due to a system-level failure.
  • CMP field accessor methods:
    A CMP field is defined in the SBB abstract class using methods with the following signatures:
    public abstract void set<field-name>(<field-type> value);
public abstract <field-type> get<field-name>();

    where:

    field-type is the Java type of the CMP field.
    field-name is the name of the CMP field as declared in the SBB's deployment descriptor, with the first letter capitalized.

    These methods are mandatory transactional methods. If they are invoked without a valid transaction context a javax.slee.TransactionRequiredLocalException will be thrown. In addition, these methods may only be invoked on an SBB object that has been assigned to an SBB entity, or is in the process of being assigned to an SBB entity via the sbbCreate() method. If the SBB object is not assigned to an SBB entity (with the exclusion of the sbbCreate method), a java.lang.IllegalStateException is thrown.

  • Fire-event methods:
    Methods that the SBB uses to fire events into the SLEE are defined in the SBB abstract class with either one of the following signatures:
    public abstract void fire<event-name>(<event-class-name> event, ActivityContextInterface aci, Address defautAddress);
public abstract void fire<event-name>(<event-class-name> event, ActivityContextInterface aci, Address defautAddress, ServiceID service);

    where:

    event-name is the name of the event given in the SBB's deployment descriptor.
    event-class-name is the class name of event objects of the repective event type.

    These methods are mandatory transactional methods. If they are invoked without a valid transaction context a javax.slee.TransactionRequiredLocalException will be thrown. In addition, these methods may only be invoked on an SBB object that has been assigned to an SBB entity, or is in the process of being assigned to an SBB entity via the sbbCreate() method. If the SBB object is not assigned to an SBB entity (with the exclusion of the sbbCreate method), a java.lang.IllegalStateException is thrown.

  • Activity Context Interface narrow method:
    This method can only be defined in the SBB abstract class if the SBB defines an Activity Context Interface that is a subtype of javax.slee.ActivityContextInterface. This method allows the SBB to obtain an object that implements the SBB's Activity Context Inteface from an object that implements the generic javax.slee.ActivityContextInterface. If declared, the method's signature must be:
    public abstract <activity-context-interface-name> asSbbActivityContextInterface(ActivityContextInterface aci);

    where:

    activity-context-interface-name is the name of the Activity Context Interface used by the SBB, as defined in the SBB's deployment descriptor.

    This method is a mandatory transactional method. If it is invoked without a valid transaction context a javax.slee.TransactionRequiredLocalException will be thrown. In addition, this method may only be invoked on an SBB object that has been assigned to an SBB entity, or is in the process of being assigned to an SBB entity via the sbbCreate() method. If the SBB object is not assigned to an SBB entity (with the exclusion of the sbbCreate method), a java.lang.IllegalStateException is thrown.

  • Child relation accessor methods:
    For each child relation the SBB has, a method with the following signature must be declared:
    public abstract ChildRelation <method-name>();

    where:

    method-name is the name of the child relation method as defined in the SBB's deployment descriptor.

    These methods are mandatory transactional methods. If they are invoked without a valid transaction context a javax.slee.TransactionRequiredLocalException will be thrown. In addition, these methods may only be invoked on an SBB object that has been assigned to an SBB entity. If the SBB object is not assigned to an SBB entity a java.lang.IllegalStateException is thrown.

  • Profile CMP Interface accessor methods:
    Deprecated. Profile interaction should now be performed via Profile Local Interface objects rather than Profile CMP Interface objects. Profile Local Interface objects can be obtained by using the methods on the profile table's Profile Table Interface. A profile table's Profile Table Interface object can be obtained from the Profile Facility.

    For each profile specification used by the SBB, the SBB abstract class may declare a method with the following signature:

    public abstract <profile-CMP-interface-name> <method-name>(ProfileID id) throws javax.slee.profile.UnrecognizedProfileTableNameException, javax.slee.profile.UnrecognizedProfileNameException;

    where:

    profile-CMP-interface-name is the name of the profile's CMP interface.
    method-name is the name of the profile CMP accessor method as defined in the SBB's deployment descriptor.

    These methods are mandatory transactional methods. If they are invoked without a valid transaction context a javax.slee.TransactionRequiredLocalException will be thrown. In addition, these methods may only be invoked on an SBB object that has been assigned to an SBB entity, or is in the process of being assigned to an SBB entity via the sbbCreate() method. If the SBB object is not assigned to an SBB entity (with the exclusion of the sbbCreate method), a java.lang.IllegalStateException is thrown.

  • Usage Parameters Interface accessor methods:
    These two methods are only defined in the SBB abstract class if the SBB defines a Usage Parameters Interface. The first method provides access to the SBB's unnamed usage parameter set while the second provides access to a named usage parameter set.
    public abstract <usage-parameters-interface-name> getDefaultSbbUsageParameterSet();
    public abstract <usage-parameters-interface-name> getSbbUsageParameterSet(String paramSetName) throws javax.slee.usage.UnrecognizedUsageParameterSetNameException;

    where:

    usage-parameters-interface-name is the name of the SBB's usage parameters interface.

    These methods run in an unspecified transaction context, therefore an active transaction is not necessary in order for these methods to be successfully invoked. Additionally these method may be invoked by an SBB object in any state.

Method Summary

Methods

Modifier and Type	Method and Description
void	sbbActivate() The SLEE invokes this method on an SBB object in the Pooled state when the SLEE reassigns the SBB object to an existing SBB entity.
void	sbbCreate() The SLEE invokes this method on an SBB object in the Pooled state when it needs to create a new SBB entity.
void	sbbExceptionThrown(Exception exception, Object event, ActivityContextInterface aci) This SLEE invokes this method on an SBB object when a mandatory transactional method of the SBB object throws an unchecked exception.
void	sbbLoad() The SLEE invokes this method on an SBB entity when the state of the SBB entity needs to be synchronized with the state in the underlying data source.
void	sbbPassivate() The SLEE invokes this method on an SBB object in the Ready state when the SLEE needs to reclaim the SBB object assigned to an SBB entity.
void	sbbPostCreate() The SLEE invokes this method on an SBB object in the Pooled state when it needs to create a new SBB entity.
void	sbbRemove() The SLEE invokes this method on an SBB entity when the SBB entity is going to be removed.
void	sbbRolledBack(RolledBackContext context) The SLEE invokes this method on an SBB entity when a transaction started immediately prior to invoking the SBB entity rolls back.
void	sbbStore() The SLEE invokes this method on an SBB entity when the state of the underlying data source needs to be synchronized with the state of the SBB entity.
void	setSbbContext(SbbContext context) Set the SbbContext object for the SBB object.
void	unsetSbbContext() Unset the SbbContext object for the SBB object.

Method Detail

setSbbContext

void setSbbContext(SbbContext context)

Set the SbbContext object for the SBB object. The SLEE invokes this method immediately after a new SBB object has been created. If the SBB object needs to use the SbbContext object during its lifetime, it should store the SbbContext object reference in an instance variable.

This method is invoked with an unspecified transaction context. The SBB object cannot access its persistent CMP state or invoke mandatory transactional methods during this method invocation.

Parameters:

context - the SbbContext object given to the SBB object by the SLEE.

unsetSbbContext

void unsetSbbContext()

Unset the SbbContext object for the SBB object. If the SBB stored a reference to the SbbContext object given to it in the setSbbContext(javax.slee.SbbContext) method, the SBB should clear that reference during this method.

This is the last method invoked on an SBB object before it becomes a candidate for garbage collection.

This method is invoked with an unspecified transaction context. The SBB object cannot access its persistent CMP state or invoke mandatory transactional methods during this method invocation.

sbbCreate

void sbbCreate()
               throws CreateException

The SLEE invokes this method on an SBB object in the Pooled state when it needs to create a new SBB entity. This method is invoked before the persistent representation of the SBB entity is created. The persistent representation of the SBB entity is created after this method returns.

The SBB entity typically initializes its CMP state during this method. The SLEE guarantees that the initial values returned from CMP accessor methods will be the default initial values as defined by the Java language (eg. 0 for int,

This method is invoked with an active transaction context.

Throws:

CreateException - this exception may be thrown by the SBB code if the SBB entity could not be created successfully.

sbbPostCreate

void sbbPostCreate()
                   throws CreateException

The SLEE invokes this method on an SBB object in the Pooled state when it needs to create a new SBB entity. This method is invoked after the persistent representation of the SBB entity has been created. The SBB object enters the Ready state after this method returns successfully. If this method throws an exception the SBB object does not enter the Ready state.

This method is invoked with the same transaction context that the corresponding sbbCreate() method was invoked with.

Throws:

CreateException - this exception may be thrown by the SBB code if the SBB entity could not be created successfully.

sbbActivate

void sbbActivate()

The SLEE invokes this method on an SBB object in the Pooled state when the SLEE reassigns the SBB object to an existing SBB entity. This method gives the SBB object a chance to initialize additional transient state and acquire additional resources that it needs while it is in the Ready state. The SBB object transitions from the Pooled state to the Ready state after this method returns.

This method is invoked with an unspecified transaction context. The SBB object cannot access its persistent CMP state or invoke mandatory transactional methods during this method invocation.

sbbPassivate

void sbbPassivate()

The SLEE invokes this method on an SBB object in the Ready state when the SLEE needs to reclaim the SBB object assigned to an SBB entity. This method gives the SBB object a chance to release any state or resources, typically allocated during the sbbActivate() method, that should not be held while the SBB object is in the Pooled state.

This method is invoked with an unspecified transaction context. The SBB object cannot access its persistent CMP state or invoke mandatory transactional methods during this method invocation.

sbbLoad

void sbbLoad()

The SLEE invokes this method on an SBB entity when the state of the SBB entity needs to be synchronized with the state in the underlying data source. The SBB entity should reload from CMP fields any transient state that depends on the state stored in those CMP fields.

This method is invoked with an active transaction context.

sbbStore

void sbbStore()

The SLEE invokes this method on an SBB entity when the state of the underlying data source needs to be synchronized with the state of the SBB entity. The SBB entity should store into CMP fields any transient state that depends on the state stored in those CMP fields.

This method is invoked with an active transaction context.

sbbRemove

void sbbRemove()

The SLEE invokes this method on an SBB entity when the SBB entity is going to be removed. An SBB entity can be removed by its parent SBB or by the SLEE when the Service instance the SBB entity executing on behalf of is removed. Any resources obtained by the SBB during sbbCreate(), sbbPostCreate(), or sbbActivate() should be released by the SBB object. The SBB object transitions to the Pooled state after this method returns.

This method is invoked with an active transaction context. If the remove operation was initiated by a parent SBB entity, the transaction context is the same as the transaction context in effect when the remove operation was initiated.

sbbExceptionThrown

void sbbExceptionThrown(Exception exception,
                      Object event,
                      ActivityContextInterface aci)

This SLEE invokes this method on an SBB object when a mandatory transactional method of the SBB object throws an unchecked exception. The SBB object will be in the Pooled state if the sbbCreate() or sbbPostCreate() method threw the exception, otherwise it will be in the Ready state and associated with an SBB entity.

This method is invoked with the same transaction context as that held by the method that threw the exception, however the transaction has been marked for rollback.

Parameters:

exception - the exception that was thrown.

event - if the exception was thrown from an event-handler method, this argument is equal to the event argument passed to the event-handler method.

aci - if the exception was thrown from an event-handler method, this argument is equal to the aci argument passed to the event-handler method.

sbbRolledBack

void sbbRolledBack(RolledBackContext context)

The SLEE invokes this method on an SBB entity when a transaction started immediately prior to invoking the SBB entity rolls back.

This method is invoked with an active transaction context that is different to the transaction context that rolled back. If this new transaction context also rolls back, this method is not reinvoked for that rollback.

Parameters:

context - the context of the rolled back transaction.