Package com.opencloud.rhino.cmp

Interface CMPFields

public interface CMPFields

This interface provides an alternative access mechanism for all SBB CMP fields. This includes CMP fields declared in the SBB abstract class itself, as well as any CMP extension interfaces. For SBB parts, this interface provides the sole access mechanism for SBB part CMP fields.

An SBB may obtain an instance of this interface from the its SbbContext object. An SBB part may obtain an instance of this interface from its SbbPartContext object.

All methods defined in this interface that return CMP field names return each name with the first letter lowercase. For example "foo" rather than "Foo". However all methods that take a CMP field name as an argument accept names with the first letter either uppercase or lowercase. For example, the CMP field "foo" may be retrieved, set, reset, etc using either the name "foo" or "Foo".

CMP Extension Interfaces
CMP extension interfaces allow an SBB to store additional state that may not be directly known when the SBB abstract class is developed. For example, the SBB build process may allow additional components to be "plugged in" to the base SBB, each which may require their own CMP state. The components can define the CMP state they need using a CMP extension interface then these interfaces can be declared in the SBB deployment descriptor when the SBB is packaged. An SBB’s CMP extension interfaces are declared in the oc-sbb-jar.xml SBB extension deployment descriptor.

CMP extension interfaces are also the mechanism by which an SBB part declares CMP fields. SBB parts declare their CMP extension interfaces in the oc-sbb-part-jar.xml SBB part deployment descriptor.

Defining and Using CMP Extension Interfaces
A CMP extension interface contains methods relating to CMP fields according to the following rules:

• For a given CMP field "foo", the interface must define getFoo and setFoo CMP field accessor methods according to standard JAIN SLEE rules.

• For a given CMP field "foo", the interface may also optionally define either or both of the following methods:

          // returns true if foo has an assigned non-null value
          public boolean hasFoo();
  
          // resets foo to its initial value
          // influenced by any @InitialValueField annotation on the CMP field accessor methods
          public void resetFoo();

• Methods defined in a CMP extension interface must have empty throws clauses.

• The CMP extension interface may optionally extend this CMPFields interface, either directly or indirectly. Extending this interface is only strictly necessary if arbitrary CMP fields, access to the CMP fields via the parameterised get, set, etc methods, or use of any of the other utility methods defined in this interface, are needed and multiple typecasts are undesired.

• All CMP field storage optimisations supported by Rhino for standard CMP fields are also supported for CMP fields declared in a CMP extension interface, eg. FastSerializable, Encodable, etc.

• The PassByReference, DatatypeCodec, and InitialValueField annotations are fully supported as normal on getter and setter CMP field methods declared in a CMP extension interface. A CMP extension interface may also be annotated with PassByReference.

Arbitrary CMP Fields
An SBB or SBB part may optionally permit use of arbitrary CMP fields. Arbitrary CMP fields are simply CMP fields that have not been explicitly declared in the SBB abstract class or any CMP extension interface, and can only be accessed using the parameterised get, set, etc, methods, or a CMPField object.

The following rules apply to arbitrary CMP fields:

• Arbitrary CMP fields are only permitted if indicated in the oc-sbb-jar.xml SBB extension deployment descriptor or oc-sbb-part-jar.xml SBB part deployment descriptor. If arbitrary CMP fields are not permitted, then attempting to access or manipulate a CMP field that has not been declared in the SBB abstract class or any CMP extension interface will result in an UnrecognisedFieldNameException being thrown.

• Arbitrary CMP fields must have a non-null name. If a null name is passed as an argument then a NullPointerException will be thrown.

• The values assigned to arbitrary CMP fields must be serialisable using standard Java serialisation. FastSerializable objects are also supported. Encodable types and those annotated with DatatypeCodec are not currently supported; FastSerializable should be used instead if possible.

• The values assigned to arbitrary CMP fields always exhibit pass-by-value semantics as per standard SLEE-defined CMP field behaviour. Pass by reference is not supported for these CMP fields.

General Usability
All methods defined in a CMP extension interface are mandatory transactional methods. Unless otherwise stated, all methods defined in the CMPFields interface are also mandatory transactional methods. If they are invoked without a valid transaction context a TransactionRequiredLocalException will be thrown. In addition, these methods may only be invoked on an SBB or SBB part object that has been assigned to an SBB entity, or is in the process of being assigned to an SBB entity via the sbbCreate method. If the SBB or SBB part object is not assigned to an SBB entity (with the exclusion of the sbbCreate method), a IllegalStateException is thrown.

Since:

Rhino 2.4.0

Method Summary

Modifier and Type	Method	Description
CMPField	cmpField(String name)	Get a CMP field object for the CMP field with the specified name.
Set<Map.Entry<String,Object>>	entrySet()	Get the names and values of CMP fields that currently have a value.
<T> T	get(String name)	Get the value of the CMP field with the specified name.
boolean	has(String name)	Determine if the extension CMP field with the specified name currently has a value.
boolean	isPredefined(String name)	Determine if the CMP field with the specified name is defined in the SBB abstract class or any CMP extension interface.
Set<String>	keySet()	Get the names of all CMP fields that currently have a value.
Set<String>	predefinedNames()	Get the names of all CMP fields defined in the SBB abstract class and CMP extension interfaces.
void	reset()	Resets all CMP fields to their initial value.
void	reset(String name)	Reset the specified CMP field to its initial value.
<T> void	set(String name, T value)	Set the value of the CMP field with the specified name to the specified value.
Set<String>	tags()	Get the set of all CMP field tags used in the CMP fields defined in the SBB abstract class and CMP extension interfaces.
Class<?>	typeOf(String name)	Obtains the expected or current type of the specified CMP field.
void	visit(boolean includeArbitraries, CMPFieldVisitor visitor)	Iterate over all CMP fields defined in the SBB abstract class and CMP extension interfaces.
void	visit(String tag, CMPFieldVisitor visitor)	Iterate over CMP fields tagged with a specified tag name, invoking a visitor object for each CMP field visited by the iterator.

Method Detail

get

<T> T get(String name)
   throws NullPointerException,
          UnrecognisedFieldNameException,
          ClassCastException

Get the value of the CMP field with the specified name.

Type Parameters:

T - the expected type of the value.

Parameters:

name - the name of the CMP field.

Returns:

the field value, or null if it currently has no value.

Throws:

NullPointerException - if name is null.

UnrecognisedFieldNameException - if arbitrary CMP fields are not permitted and name is not the name of a CMP field defined in the SBB abstract class or any CMP extension interface.

ClassCastException - if T is not a compatible type for the field’s value.

Since:

Rhino 2.4.0

set

<T> void set(String name,
             T value)
      throws NullPointerException,
             UnrecognisedFieldNameException,
             ClassCastException

Set the value of the CMP field with the specified name to the specified value.

Type Parameters:

T - the value type.

Parameters:

name - the name of the CMP field.

value - the value. May be null.

Throws:

NullPointerException - if name is null, or if the named CMP field was defined in the SBB abstract class or a CMP extension interface with a primitive type and value is null.

UnrecognisedFieldNameException - if arbitrary CMP fields are not permitted and name is not the name of a CMP field defined in the SBB abstract class or any CMP extension interface.

ClassCastException - if the named CMP field was defined in the SBB abstract class or a CMP extension interface and the specified value is not a compatible type.

Since:

Rhino 2.4.0

has

boolean has(String name)
     throws NullPointerException,
            UnrecognisedFieldNameException

Determine if the extension CMP field with the specified name currently has a value.

Parameters:

name - the name of the CMP field.

Returns:

true if the field currently has a value, false otherwise. This method will always return true for primitive type CMP fields defined in the SBB abstract class or a CMP extension interface.

Throws:

NullPointerException - if name is null.

UnrecognisedFieldNameException - if arbitrary CMP fields are not permitted and name is not the name of a CMP field defined in the SBB abstract class or any CMP extension interface.

Since:

Rhino 2.4.0

reset

void reset(String name)
    throws NullPointerException,
           UnrecognisedFieldNameException

Reset the specified CMP field to its initial value. The initial value for a CMP field is defined as follows:

• If the named CMP field was defined in the SBB abstract class or a CMP extension interface and has an @InitialValueField annotation, then the CMP field is reset to the specified initial value.

• If the named CMP field was defined in the SBB abstract class or a CMP extension interface without an @InitialValueField annotation, then the CMP field is reset to the default Java-defined initial value for that type, eg. 0 for numeric primitives, null for object references.

• Otherwise the named CMP field must be an arbitrary CMP field, and the CMP field is reset to null.

Parameters:

name - the name of the CMP field.

Throws:

NullPointerException - if name is null.

UnrecognisedFieldNameException - if arbitrary CMP fields are not permitted and name is not the name of a CMP field defined in the SBB abstract class or any CMP extension interface.

Since:

Rhino 2.4.0

reset

void reset()

Resets all CMP fields to their initial value. Refer reset(String) for the definition of "initial value".

Since:

Rhino 2.4.0

typeOf

Class<?> typeOf(String name)
         throws NullPointerException,
                UnrecognisedFieldNameException

Obtains the expected or current type of the specified CMP field.

If the named CMP field is defined in the SBB abstract class or a CMP extension interface then the value returned from this method will be the declared class type. Otherwise it is assumed the name refers to an arbitrary CMP field and the value returned will be the class type of the current value assigned to the CMP field.

Parameters:

name - the name of the CMP field.

Returns:

the type of the CMP field’s value.

Throws:

NullPointerException - if name is null.

UnrecognisedFieldNameException - if arbitrary CMP fields are not permitted and name is not the name of a CMP field defined in the SBB abstract class or any CMP extension interface, or if name refers to an arbitrary CMP field that does not exist or has no current value.

Since:

Rhino 2.4.0

isPredefined

boolean isPredefined(String name)
              throws NullPointerException

Determine if the CMP field with the specified name is defined in the SBB abstract class or any CMP extension interface.

This method is a non-transactional method.

Parameters:

name - the name of the CMP field.

Returns:

true if the named CMP field is defined in the SBB abstract class or a CMP extension interface, false otherwise.

Throws:

NullPointerException - if name is null.

Since:

Rhino 2.4.0

predefinedNames

Set<String> predefinedNames()

Get the names of all CMP fields defined in the SBB abstract class and CMP extension interfaces.

This method is a non-transactional method.

Returns:

the CMP field names. The returned set is unmodifiable.

Since:

Rhino 2.4.0

keySet

Set<String> keySet()

Get the names of all CMP fields that currently have a value.

Returns:

the names of all CMP fields that currently have a value. The returned set is unmodifiable.

Since:

Rhino 2.4.0

entrySet

Set<Map.Entry<String,Object>> entrySet()

Get the names and values of CMP fields that currently have a value.

Returns:

the names and values, as map entry objects, of all CMP fields that currently have a value. The returned set is unmodifiable.

Since:

Rhino 2.4.0

cmpField

CMPField cmpField(String name)
           throws NullPointerException,
                  UnrecognisedFieldNameException

Get a CMP field object for the CMP field with the specified name.

If the named CMP field is not defined in the SBB abstract class or a CMP extension interface then it will be assumed to refer to an arbitrary CMP field. If the named arbitrary CMP field does not exist or has no current value, this method will still return a usable CMPField object.

Parameters:

name - the name of the CMP field.

Returns:

a CMP field object for the CMP field.

Throws:

NullPointerException - if name is null.

UnrecognisedFieldNameException - if arbitrary CMP fields are not permitted and name is not the name of a CMP field defined in the SBB abstract class or any CMP extension interface.

Since:

Rhino 2.6.1

tags

Set<String> tags()

Get the set of all CMP field tags used in the CMP fields defined in the SBB abstract class and CMP extension interfaces.

This method is a non-transactional method.

Returns:

the CMP Field tag names. The returned set is unmodifiable.

Since:

Rhino 2.6.1

visit

void visit(String tag,
           CMPFieldVisitor visitor)
    throws NullPointerException,
           UnrecognisedTagNameException

Iterate over CMP fields tagged with a specified tag name, invoking a visitor object for each CMP field visited by the iterator.

Parameters:

tag - the tag name.

visitor - the CMP field visitor.

Throws:

NullPointerException - if either argument is null.

UnrecognisedTagNameException - if tag specifies an unknown tag name.

Since:

Rhino 2.6.1

visit

void visit(boolean includeArbitraries,
           CMPFieldVisitor visitor)
    throws NullPointerException

Iterate over all CMP fields defined in the SBB abstract class and CMP extension interfaces. If the includeArbitraries parameter is true, then the iterator will also visit all arbitrary CMP fields that exist at the time of invocation.

Parameters:

includeArbitraries - flag indicating whether or not arbitrarily defined CMP fields should be included in the iteration. The value of this parameter will be ignored if the SBB does not permit arbitrary CMP fields.

visitor - the CMP field visitor.

Throws:

NullPointerException - if visitor is null.

Since:

Rhino 2.6.1