public interface CMPFields
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:
foo
", the interface must define getFoo
and setFoo
CMP field accessor methods according to standard JAIN SLEE rules.
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();
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.
FastSerializable
, Encodable
, etc.
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 support 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.
The following rules apply to arbitrary CMP fields:
oc-sbb-jar.xml
SBB
extension deployment descriptor or oc-sbb-part-jar.xml
SBB part deployment
descriptor. If arbitrary CMP fields are not supported, 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.
NullPointerException
will be thrown.
FastSerializable
objects are also supported. Encodable
types and those annotated with DatatypeCodec
are not currently supported;
FastSerializable
should be used instead if possible.
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.
Modifier and Type | Method and Description |
---|---|
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.
|
Class<?> |
typeOf(String name)
Obtains the expected or current type of the specified CMP field.
|
<T> T get(String name) throws NullPointerException, UnrecognisedFieldNameException, ClassCastException
T
- the expected type of the value.name
- the name of the CMP field.null
if it currently has no value.NullPointerException
- if name
is null
.UnrecognisedFieldNameException
- if arbitrary CMP fields are disallowed 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.<T> void set(String name, T value) throws NullPointerException, UnrecognisedFieldNameException, ClassCastException
T
- the value type.name
- the name of the CMP field.value
- the value. May be null
.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 disallowed 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.boolean has(String name) throws NullPointerException, UnrecognisedFieldNameException
name
- the name of the CMP field.true
if the field currently has a value, false
otherwise.
This method will always return true
for CMP fields defined in the SBB abstract
class or a CMP extension interface with a primitive type.NullPointerException
- if name
is null
.UnrecognisedFieldNameException
- if arbitrary CMP fields are disallowed and name
is not the name of a CMP field defined in the SBB abstract class or any CMP extension
interface.void reset(String name) throws NullPointerException, UnrecognisedFieldNameException
@InitialValueField
annotation, then the
CMP field is reset to the specified initial value.
@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.
null
.
name
- the name of the CMP field.NullPointerException
- if name
is null
.UnrecognisedFieldNameException
- if arbitrary CMP fields are disallowed and name
is not the name of a CMP field defined in the SBB abstract class or any CMP extension
interface.void reset()
reset(String)
for the definition
of "initial value".Class<?> typeOf(String name) throws NullPointerException, UnrecognisedFieldNameException
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.
name
- the name of the CMP field.NullPointerException
- if name
is null
.UnrecognisedFieldNameException
- if arbitrary CMP fields are disallowed 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.boolean isPredefined(String name) throws NullPointerException
This method is a non-transactional method.
name
- the name of the CMP field.true
if the named CMP field is defined in the SBB abstract class or a CMP
extension interface, false
otherwise.NullPointerException
- if name
is null
.Set<String> predefinedNames()
This method is a non-transactional method.
Set<String> keySet()