com.opencloud.rhino.cmp

Enum PassByReference.Scope

java.lang.Object

java.lang.Enum<PassByReference.Scope>

com.opencloud.rhino.cmp.PassByReference.Scope

All Implemented Interfaces:

Serializable, Comparable<PassByReference.Scope>

Enclosing class:

PassByReference

public static enum PassByReference.Scope
extends Enum<PassByReference.Scope>

Pass-by-reference scopes.

Since:

Rhino 2.4.0

Enum Constant Summary

Enum Constants

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.

Method Summary

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.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

DISABLED

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.

Since:

Rhino 2.4.0

TRANSACTIONAL

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.

Since:

Rhino 2.4.0

WHILE_READY

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.

Since:

Rhino 2.4.0

PERMANENT

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.

Since:

Rhino 2.4.0

Method Detail

values

public static PassByReference.Scope[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (PassByReference.Scope c : PassByReference.Scope.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static PassByReference.Scope valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null

isWiderScope

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

Parameters:

s - the scope to compare this to.

Returns:

true if this scope is wider than the specified scope, false otherwise.

Since:

Rhino 2.4.0