public static enum PassByReference.Scope extends Enum<PassByReference.Scope>
Pass-by-reference scopes.
Enum Constant and Description |
---|
DISABLED
Reference scope indicating that any pass-by-reference semantics should be removed.
|
PERMANENT
Reference scope indicating that pass-by-reference semantics should apply permanently.
|
TRANSACTIONAL
Reference scope indicating that pass-by-reference semantics should apply on a per-transaction basis only.
|
WHILE_READY
Reference scope indicating that pass-by-reference semantics should apply while the SBB object is in the READY state.
|
Modifier and Type | Method and Description |
---|---|
boolean |
isWiderScope(PassByReference.Scope s)
Determine if this scope is wider than the specified scope.
|
static PassByReference.Scope |
valueOf(String name)
Returns the enum constant of this type with the specified name.
|
static PassByReference.Scope[] |
values()
Returns an array containing the constants of this enum type, in
the order they are declared.
|
public static final PassByReference.Scope DISABLED
Reference scope indicating that any pass-by-reference semantics should be removed. This reference scope can be used to override an inherited pass-by-reference setting when pass-by-reference is not desired in the current declaration.
public static final PassByReference.Scope TRANSACTIONAL
Reference scope indicating that pass-by-reference semantics should apply on a per-transaction basis only. An intermediate reference cache is used to store the CMP field value during a transaction. On transaction commit, any cached value is written back to persistent storage, if the CMP field was modified during the transaction, and the cache invalidated.
public static final PassByReference.Scope WHILE_READY
Reference scope indicating that pass-by-reference semantics should apply while the SBB object is in the READY state. An intermediate reference cache is used to store the CMP field value during a transaction. On transaction commit, any cached value is written back to persistent storage, if the CMP field was modified during the transaction, however the cached reference will be retained while the SBB object remains in the READY state.
This reference scope is safe to use with any generic CMP object that does not hold, either directly or indirectly, references to SLEE-defined objects that are only valid in the transaction they were materialised in, such as ActivityContextInterface or EventContext.
public static final PassByReference.Scope PERMANENT
Reference scope indicating that pass-by-reference semantics should apply permanently. The object will only ever be stored by reference (exceptions apply in the replicated case, see below).
Unlike other reference scopes, a permanent reference loses all transactional semantics. Any changes made to the referenced object will persist irrespective of whether the current transaction commits or rolls back. As such, permanent references are best suited to objects that are unlikely to change during the lifetime of an SBB, for example input network messages that need to be retained across event handler transaction boundaries but serialisation of such messages is undesirable.
Replication
By default, the current state of all CMP fields is included in the replicated state stream of an SBB entity if and when replication occurs.
Replication of individual CMP fields can be suppressed using the @CMPFieldReplication
annotation.
Careful consideration must be given to CMP fields with permanent pass-by-reference semantics as to whether or not their state should or should not be available for replication.
A replication-enabled CMP field with permanent pass-by-reference semantics may only be used in a replicated SBB if the CMP field type is serialisable by some normally supported method, ie. if the CMP field is still meaningful with standard pass-by-value semantics.
The following conditions apply to permanent pass-by-reference CMP fields that are replicated:
A cluster node that makes a transactional update to the CMP field will retain the reference set by the SBB while that node remains the exclusive source of transactional updates to the CMP field.
A cluster node that receives a replicated state update from another cluster node will forget any previous reference it may have had for the CMP field and will create a new instance of the referenced value from the received serialised state.
Updates to a value stored by reference may, at the discretion of the SLEE implementation, only be replicated on transaction commit if the CMP field setter method is invoked during the transaction in order to flag the CMP field as dirty. If the CMP field is not flagged as dirty during the transaction, then the SLEE implementation may choose to lazily replicate a previously encoded version of the CMP field value rather than eagerly re-encode the CMP field value after every transaction commit.
Example:
An SBB containing a replication-enabled permanent pass-by-reference CMP field "foo
" is replicated across two cluster nodes 101 and 102.
On node 101, the SBB sets CMP field "foo
" to the reference X
. The stored value is replicated to node 102.
On node 102, the SBB reads the deserialised value with reference Y
from the CMP field, then updates the CMP field.
The update is replicated back to node 101.
On node 101, the SBB reads the CMP field again.
The CMP field no longer returns a reference to the value X
, but instead returns a reference, Z
, to the value deserialised from the update that occurred on node 102.
public static PassByReference.Scope[] values()
for (PassByReference.Scope c : PassByReference.Scope.values()) System.out.println(c);
public static PassByReference.Scope valueOf(String name)
name
- the name of the enum constant to be returned.IllegalArgumentException
- if this enum type has no constant with the specified nameNullPointerException
- if the argument is nullpublic boolean isWiderScope(PassByReference.Scope s)
Determine if this scope is wider than the specified scope. A "wider" scope means that the reference may be maintained for a longer duration.
s
- the scope to compare this to.true
if this scope is wider than the specified scope, false
otherwise.