com.opencloud.rhino.slee

Interface RhinoSbbLocalHome

public interface RhinoSbbLocalHome

The RhinoSbbLocalHome interface may be used by an SBB as its local home interface. It declares SBB methods that are not specific to an SBB entity and are invoked on an SBB object in the Pooled state.

If an SBB declares a local home interface in its deployment descriptor, then the home interface methods must be implemented in the SBB abstract class using a method name constructed by capitalising the first letter of the method name as defined in this interface then prefixing "sbbHome". For example, the verifyConfiguration method must be implemented in the SBB abstract class with the method name sbbHomeVerifyConfiguration. The method parameters and return type must be identical, and the throws clause of the implemented method must be a subset of the interface method declaration, excluding any runtime exceptions.

Rhino currently does not permit this interface to be extended with SBB-defined methods.

Since:

Rhino 2.4.0

Method Summary

Methods

Modifier and Type	Method and Description
void	serviceActivating(Object config) The SLEE invokes this method on the root SBB of a service when the service is about to transition from Inactive to Active.
void	serviceDeactivating() The SLEE invokes this method on the root SBB object of a service when no SBB entity trees remain in the service and it is about to transition from the Stopping state to the Inactive state.
Object	verifyConfiguration() The SLEE invokes this method on the root SBB of a service when the service is about to transition from Inactive to Active.

Method Detail

verifyConfiguration

Object verifyConfiguration()
                           throws InvalidConfigurationException,
                                  TransactionRequiredLocalException

The SLEE invokes this method on the root SBB of a service when the service is about to transition from Inactive to Active. The SLEE will also invoke this method on any child SBB (recursively) where the corresponding cascade-service-lifecycle-callbacks child relation option in the extension deployment descriptor is set to "True". The SLEE will invoke this method at most once for each SBB type present in the service, regardless of how many times a given SBB appears as a child SBB in the service.

This method is invoked by Rhino on the SBBs in a service on every cluster node where the service is about to transition to the Active state.

Other than SLEE-initiated invocations, an SBB may also choose to manually invoke this method on any of its child SBBs by obtaining the child SBBs local home object from the Child Relation Facility.

This callback can be used by an SBB, for example, to check that its configuration in environment entries or elsewhere is valid.

If an SBB declares a local home interface then a corresponding method with the following signature must be implemented in the SBB abstract class:

     public Object sbbHomeVerifyConfiguration() throws InvalidConfigurationException;
 

The throws clause is optional. The implementation of this method may throw an InvalidConfigurationException if it determines that the service should not be activated at this time, eg. there is a configuration error.

• If this method throws an exception when the administrator has requested activation of the service on a node that is currently operational, then the activation request fails and the service remains in the Inactive state.
• If this method throws an exception when a node (re)starts, where the per-node state for that node indicates that the service should be reactivated, then the reactivation attempt fails, the service transition back to the Inactive state on this node, and an alarm is raised to indicate that the service could not be activated.

The return result from this method is passed as an argument to the serviceActivating(Object) method if the service successfully activates. The object can be used, for example, to pass some configuration information calculated during this method to serviceActivating() if that method would otherwise need to recalculate the same information again.

This method is a mandatory transactional method. When this method is invoked by the SLEE it is invoked with an active transaction context.

Returns:

a configuration object.

Throws:

InvalidConfigurationException - if the service should not be activated for some user-defined reason.

TransactionRequiredLocalException - if the method is invoked by an SBB without a valid transaction context.

Since:

Rhino 2.4.0

serviceActivating

void serviceActivating(Object config)
                       throws TransactionRequiredLocalException

The SLEE invokes this method on the root SBB of a service when the service is about to transition from Inactive to Active. The SLEE will also invoke this method on any child SBB (recursively) where the corresponding cascade-service-lifecycle-callbacks child relation option in the extension deployment descriptor is set to "True". The SLEE will invoke this method at most once for each SBB type present in the service, regardless of how many times a given SBB appears as a child SBB in the service.

This method is invoked by Rhino on the SBBs in a service on every cluster node where the service is about to transition to the Active state. This method is invoked after the verifyConfiguration() method has returned successfully and the SLEE has determined that the service activation can proceed to completion. The service transitions to the Active state on the corresponding node after this method returns.

Other than SLEE-initiated invocations, an SBB may also choose to manually invoke this method on any of its child SBBs by obtaining the child SBBs local home object from the Child Relation Facility.

An SBB can use this callback, for example, to initialise common state shared between SBB objects of the same SBB. The service context is a recommended place to store such state.

If an SBB declares a local home interface then a corresponding method with the following signature must be implemented in the SBB abstract class:

     public void sbbHomeServiceActivating(Object config);
 

When this method is invoked by the SLEE, the object passed as an argument to this method is the return result from the previous corresponding verifyConfiguration() method invocation.

This method is a mandatory transactional method. When this method is invoked by the SLEE it is invoked with an active transaction context.

Parameters:

config - the object returned from the previous invocation of verifyConfiguration, if this method is invoked by the SLEE.

Throws:

TransactionRequiredLocalException - if the method is invoked by an SBB without a valid transaction context.

Since:

Rhino 2.4.0

serviceDeactivating

void serviceDeactivating()
                         throws TransactionRequiredLocalException

The SLEE invokes this method on the root SBB object of a service when no SBB entity trees remain in the service and it is about to transition from the Stopping state to the Inactive state. The SLEE will also invoke this method on any child SBB (recursively) where the corresponding cascade-service-lifecycle-callbacks child relation option in the extension deployment descriptor is set to "True". The SLEE will invoke this method at most once for each SBB type present in the service, regardless of how many times a given SBB appears as a child SBB in the service.

This method is invoked by Rhino on every cluster node where the service is about to transition to the Inactive state. The service transitions to the Inactive state on the corresponding node after this method returns.

Other than SLEE-initiated invocations, an SBB may also choose to manually invoke this method on any of its child SBBs by obtaining the child SBBs local home object from the Child Relation Facility.

An SBB can use this callback, for example, to clean up any shared state that is no longer required after the service has deactivated.

If an SBB declares a local home interface then a corresponding method with the following signature must be implemented in the SBB abstract class:

     public void sbbHomeServiceDeactivating();
 

This method is a mandatory transactional method. When this method is invoked by the SLEE it is invoked with an active transaction context.

Throws:

TransactionRequiredLocalException - if the method is invoked by an SBB without a valid transaction context.

Since:

Rhino 2.4.0