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.
| Modifier and Type | Method and 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.
|
<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.
|
getEventMask, getRollbackOnly, getSbb, getSbbLocalObject, getService, maskEvent, setRollbackOnlyConvergenceName 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().
null if this SBB entity is not a root SBB entity.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.Tracer getTracer(String tracerName) throws NullPointerException, IllegalArgumentException, SLEEException
getTracer in interface SbbContextNullPointerExceptionIllegalArgumentExceptionSLEEExceptionRhinoActivityContextInterface[] getActivities() throws TransactionRequiredLocalException, IllegalStateException, SLEEException
getActivities in interface SbbContextTransactionRequiredLocalExceptionIllegalStateExceptionSLEEExceptionRhinoActivityContextInterface[] 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().
type - the type of activity object to return Activity Contexts for.
If this parameter is null, this method behaves the same as getActivities().type.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.NullPointerExceptionChildRelationFacility getChildRelationFacility() throws SLEEException
Get the Child Relation Facility for this SBB.
This method is a non-transactional method.
SLEEException - if the Child Relation Facility could not be obtained due to a system-level failure.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.
SLEEException - if the CMP fields could not be obtained due to a system-level failure.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.
SLEEException - if the JNDI bindings could not be obtained due to a system-level failure.<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.
T - the type of the context object.context - the context object.SLEEException - if the service context could not be set due to a system-level failure.<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.
T - the type of the context object.null if the context has not been set to a non-null value.SLEEException - if the service context could not be retrieved due to a system-level failure.<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.
T - the type of the context object.context - the context object.SLEEException - if the encodable context could not be set due to a system-level failure.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().
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.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.
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.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).
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.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.
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.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.