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 that follow certain design patterns. These are:


Method Summary
 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(java.lang.Exception exception, java.lang.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

public 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

public void unsetSbbContext()
Unset the SbbContext object for the SBB object. If the SBB stored a reference to the SbbConect 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public void sbbExceptionThrown(java.lang.Exception exception,
                               java.lang.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

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