Package com.opencloud.rhino.slee

Interface RhinoSbbContext

All Superinterfaces:

SbbContext

public interface RhinoSbbContext
extends SbbContext

An extension of the JAIN SLEE-defined interface that provides access to Rhino-specific features.

All SbbContext objects that Rhino provides to an SBB will implement this extension interface, therefore a typecast to this interface will always succeed.

Since:

Rhino 2.4.0

Method Summary

Modifier and Type	Method	Description
void	disableEntityTreePersistence()	Disable key/value store persistence for the SBB entity tree and related transactional state.
void	enableEntityTreePersistence()	Enable key/value store persistence for the SBB entity tree and related transactional state.
RhinoActivityContextInterface[]	getActivities()
RhinoActivityContextInterface[]	getActivities(Class<?> type)	Get the set of Activity Contexts that the SBB entity currently associated with the instance is currently attached to, where the type of the underlying activity object is assignable to the specified type.
ChildRelationFacility	getChildRelationFacility()	Get the Child Relation Facility for this SBB.
CMPFields	getCMPFields()	Get the CMP fields accessor object for this SBB.
ConvergenceName	getConvergenceName()	Get the convergence name that this SBB was created for.
ConvergenceNameSessionOwnershipRecord	getConvergenceNameSessionOwnershipRecord()	Obtain a Rhino-managed session ownership record for the SBB entity tree by either retrieving a pre-existing record or creating a new record if one does not already exist.
ConvergenceNameSessionOwnershipRecord	getConvergenceNameSessionOwnershipRecord(long ttl)	Obtain a Rhino-managed session ownership record for the SBB entity tree by either retrieving a pre-existing record or creating a new record if one does not already exist.
Map<String,JndiBinding>	getJndiBindings()	Get a map describing the JNDI bindings available to the SBB.
int	getPartitionKey()	Get the partition key for the SBB entity tree.
<T> T	getServiceContext()	Get the service context object.
Tracer	getTracer(String tracerName)
<T> void	setEncodableContext(T context)	Set the encodable context object.
<T> void	setServiceContext(T context)	Set the service context object.

Methods inherited from interface javax.slee.SbbContext

getEventMask, getRollbackOnly, getSbb, getSbbLocalObject, getService, maskEvent, setRollbackOnly

Method Detail

getConvergenceName

ConvergenceName getConvergenceName()
                            throws TransactionRequiredLocalException,
                                   IllegalStateException,
                                   SLEEException

Get the convergence name that this SBB was created for. This method only returns a non-null value if the SBB entity is the root SBB of an SBB entity tree.

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:

the convergence name, or null if this SBB entity is not a root SBB entity.

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 convergence name could not be obtained due to a system-level failure.

Since:

Rhino 2.4.0

getTracer

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

Specified by:

getTracer in interface SbbContext

Throws:

NullPointerException

IllegalArgumentException

SLEEException

Since:

Rhino 2.4.0

getActivities

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

Specified by:

getActivities in interface SbbContext

Throws:

TransactionRequiredLocalException

IllegalStateException

SLEEException

Since:

Rhino 2.4.0

getActivities

RhinoActivityContextInterface[] getActivities(Class<?> type)
                                       throws NullPointerException,
                                              TransactionRequiredLocalException,
                                              IllegalStateException,
                                              SLEEException

Get the set of Activity Contexts that the SBB entity currently associated with the instance is currently attached to, where the type of the underlying activity object is assignable to the specified type. The returned 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().

Parameters:

type - the type of activity object to return Activity Contexts for. If this parameter is null, this method behaves the same as getActivities().

Returns:

an array of generic Activity Context Interface objects that represent the Activity Contexts the SBB entity is attached to where the activity object is assignable to type.

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.

NullPointerException

Since:

Rhino 2.4.0

getChildRelationFacility

ChildRelationFacility getChildRelationFacility()
                                        throws SLEEException

Get the Child Relation Facility for this SBB.

This method is a non-transactional method.

Returns:

the Child Relation Facility.

Throws:

SLEEException - if the Child Relation Facility could not be obtained due to a system-level failure.

Since:

Rhino 2.4.0

getCMPFields

CMPFields getCMPFields()
                throws SLEEException

Get the CMP fields accessor object for this SBB.

The object returned from this method provides access to all SBB CMP fields whether defined in the SBB abstract class or a CMP extension interface. The returned object implements all CMP extension interfaces declared by the SBB, so may be typecast to any of these interfaces as required regardless of whether or not such interface extends from CMPFields.

This method runs in an unspecified transaction context, however the CMP state contained within the object can only be accessed or manipulated in contexts where CMP state is normally accessible.

Returns:

a CMP fields accessor object for the SBB.

Throws:

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

Since:

Rhino 2.4.0

getJndiBindings

Map<String,JndiBinding> getJndiBindings()
                                       throws SLEEException

Get a map describing the JNDI bindings available to the SBB. The map is keyed on the fully-qualified name of each binding.

This method is a non-transactional method.

Returns:

a map of JNDI bindings. The returned map is immutable.

Throws:

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

Since:

Rhino 2.4.0

setServiceContext

<T> void setServiceContext(T context)
                    throws SLEEException

Set the service context object.

The service context provides an alternative storage facility to using static class fields for arbitrary, typically constant, data that the SBB wants to share between SBB objects in the same service. The use of static class fields to store shared data becomes problematic when the encapsulating class resides in a library component jar rather than an SBB jar - the static fields end up being shared between all uses of that library, rather than being scoped to a single service. The service context provides similar functionality to that of a static class field, but it is guaranteed to have visibility only within the service.

A typical use of the service context is to store data calculated by the SBB during the serviceActivating lifecycle callback method.

The service context object is stored by reference, and is never serialised. As the service context object may be accessed concurrently by different SBB objects, care must be taken that the service context object provides thread-safe access. A service context object will persist across service deactivation and reactivation cycles unless the SBB explicitly resets the service context to null at the appropriate time.

The service context is scoped to a single SBB type within the service, ie. different SBB types within the same service may each store their own service context object without conflict.

This method is a non-transactional method.

Type Parameters:

T - the type of the context object.

Parameters:

context - the context object.

Throws:

SLEEException - if the service context could not be set due to a system-level failure.

Since:

Rhino 2.4.0

getServiceContext

<T> T getServiceContext()
                 throws SLEEException

Get the service context object.

Refer setServiceContext for a description of the service context.

This method is a non-transactional method.

Type Parameters:

T - the type of the context object.

Returns:

the context object, or null if the context has not been set to a non-null value.

Throws:

SLEEException - if the service context could not be retrieved due to a system-level failure.

Since:

Rhino 2.4.0

setEncodableContext

<T> void setEncodableContext(T context)
                      throws SLEEException

Set the encodable context object. This object can be later retrieved by objects implementing Encodable or providing a DatatypeCodec via EncoderUtils and DecoderUtils when serialised to or deserialised from CMP or extension CMP fields of this SBB.

The encodable context is scoped to an SBB object. Typically the encodable context would be initialised during Sbb.setSbbContext like other similarly scoped values.

This method is a non-transactional method.

Type Parameters:

T - the type of the context object.

Parameters:

context - the context object.

Throws:

SLEEException - if the encodable context could not be set due to a system-level failure.

Since:

Rhino 2.4.0

enableEntityTreePersistence

void enableEntityTreePersistence()
                          throws TransactionRequiredLocalException,
                                 IllegalStateException,
                                 SLEEException

Enable key/value store persistence for the SBB entity tree and related transactional state. This method is only useful if initial persistence of state has been disabled in the extension service deployment descriptor or via the com.opencloud.rhino.management.service.ServiceManagementMBean#setInitialPersistence management operation.

This method has no effect if entity tree persistence is or has already been enabled. It is not valid to invoke this method if persistence has been permanently disabled.

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().

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, or persistence has previously been permanently disabled.

SLEEException - if entity tree persistence could not be enabled due to a system-level failure.

Since:

Rhino 2.6.1

disableEntityTreePersistence

void disableEntityTreePersistence()
                           throws TransactionRequiredLocalException,
                                  IllegalStateException,
                                  SLEEException

Disable key/value store persistence for the SBB entity tree and related transactional state.

This method invokes a permanent, irrevocable request that any state maintained for the SBB entity tree and any state related to it, for example state for activities that the SBB entity interacts with, should never be persisted to the key/value store. This is a different state of being to that of an SBB entity tree whose initial persistence has been disabled, as state for such an SBB entity may be persisted at some point in the future if persistence is subsequently enabled or a state-buffering timeout is exceeded in the key/value store. State for an SBB entity tree whose persistence is permanently disabled using this method will never be persisted.

Typically, this method would be invoked by an SBB entity whose initial persistence has been disabled and early on in the SBB entity’s session processing lifecycle in order to avoid the possibility that some state may end up persisted. However, it’s possible to invoke this method at any point in an SBB entity’s lifecycle to suppress persistence of any state not yet persisted. Already persisted state may remain in the key/value store, but not further updated, until the local state is removed.

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 entity tree persistence could not be disabled due to a system-level failure.

getConvergenceNameSessionOwnershipRecord

ConvergenceNameSessionOwnershipRecord getConvergenceNameSessionOwnershipRecord()
                                                                        throws TransactionRequiredLocalException,
                                                                               IllegalStateException,
                                                                               SLEEException

Obtain a Rhino-managed session ownership record for the SBB entity tree by either retrieving a pre-existing record or creating a new record if one does not already exist.

This method is equivalent to, and has the same behaviour and contract as, getConvergenceNameSessionOwnershipRecord(0).

Returns:

the SBB entity tree’s session ownership record.

Throws:

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

IllegalStateException - if session ownership functionality isn’t available in the namespace the SBB is deployed in.

SLEEException - if the session ownership record could not be retrieved due to a system-level failure.

Since:

Rhino 2.6.2

getConvergenceNameSessionOwnershipRecord

ConvergenceNameSessionOwnershipRecord getConvergenceNameSessionOwnershipRecord(long ttl)
                                                                        throws TransactionRequiredLocalException,
                                                                               IllegalStateException,
                                                                               SLEEException

Obtain a Rhino-managed session ownership record for the SBB entity tree by either retrieving a pre-existing record or creating a new record if one does not already exist.

The primary key of this session ownership record is allocated by Rhino and is based on the convergence name of the SBB entity tree. The record will be automatically removed by Rhino when the SBB entity tree is removed.

The convergence name session ownership record will be automatically refreshed in the session ownership store by Rhino if at least half the record’s TTL has passed. However, this only occurs if the SBB entity tree receives an event after the second half of that TTL lifespan has started. After a refresh, the TTL period resets back to zero, and the SBB entity tree must repeatedly receive an event after the second half of the following TTL lifespan period has started in order to keep the record alive. As an example, if the convergence name session ownership record was created with a TTL of 60s, then the SBB entity tree must receive an event approximately every 31-59s (factoring in a margin of error in event delivery timing) in order to keep the record alive.

If the SBB entity tree does not receive an event during the TTL refresh time period, the convergence name session ownership record will expire and any record attributes set by the application will be lost.

The ttl method parameter is used in two ways:

• if this is the first time that the session ownership record has been requested, the record is created with the specified ttl, if ttl is a positive number, or the default TTL of the session ownership store otherwise

• if this is not the first time that the session ownership record has been requested and ttl is a positive number and different to the previous TTL of the record, the record is updated with the new TTL.

This method is a mandatory transactional method.

Parameters:

ttl - the record’s time-to-live, measured in milliseconds. Any non-positive value means that the default TTL of the session ownership store should be used instead.

Returns:

the convergence name session ownership record for the SBB entity tree.

Throws:

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

IllegalStateException - if session ownership functionality isn’t available in the namespace the SBB is deployed in.

SLEEException - if the session ownership record could not be retrieved due to a system-level failure.

Since:

Rhino 2.6.2

getPartitionKey

int getPartitionKey()

Get the partition key for the SBB entity tree.

The partition key is a session-related hash that can be used by a key/value store, for example, to aggregate related state.

The partition key of an SBB entity tree is determined from the activity handle of the activity whose event caused the creation of the SBB entity tree.

Returns:

the partition key.

Since:

Rhino 3.0.0