Rhino Extended APIs

Other documentation for the Rhino TAS can be found on the Rhino TAS product page.

An "SBB part", as its name implies, can be thought of as a sub-component of a JAIN SLEE SBB (Service Building Block). An SBB part is an installable SLEE component in its own right. It may have dependencies, and other components may depend on it. The concept of the SBB part component was borne from a use case where the developer wanted to put a number of common shared classes into a library-type component; but the classes had dependencies on various profile specifications, event types, and resource adaptor types — all of which a standard JAIN SLEE library component cannot provide (a library component may only depend on other library components). We thought it might be desirable to extend the definition of the standard library component with the option to declare these other types of references, mainly because a library component was always seen as a passive "primitive" type of component that sat at the top of the dependency hierarchy. Adding dependency links to other component types would significantly complicate the SLEE component dependency hierarchy. In particular, it would create the possibility of cyclic dependencies between different component types — which must be avoided, as in practise they cannot be mapped to a realistic runtime class loader hierarchy. So instead, a new component type was created to fulfill this need: the SBB part.

SBB part components have one other feature that make them distinct from library components: at runtime the SBB part component classes are included in the same class loader as the SBB classes for the service, rather than in a parent class loader (as standard library components are).

An SBB part component may define:

An SBB part component can only be referenced by SBB components or other SBB part components.

An SBB may depend on one or more SBB parts. An SBB part may also depend on other SBB parts. An SBB that depends on one or more SBB parts, both directly and indirectly, has its definition implicitly extended in the following ways:

Put simply, an SBB becomes the union of the declarations made by itself and all its dependent SBB parts; and there must be no conflict between components that make the same declarations.

An SBB part may optionally declare an SBB part class. The SBB part class contains the event-processing logic of the SBB part component. An instance of the SBB part class is known as an SBB part object.

The lifecycle of an SBB part object is tightly coupled to the lifecycle of an SBB object. When an SBB object is created, an SBB part object for each dependent SBB part that declares an SBB part class is also created; and the SBB object maintains a reference to this SBB part object for the lifetime of the SBB object. When the SBB object undergoes a lifecycle state transition, for example from the Pooled state to the Ready state, each dependent SBB part object also undergoes the same lifecycle transition. If the SLEE determines that the SBB object is no longer required and becomes eligible for JVM garbage collection, then so too do the dependent SBB part objects.

During the lifetime of an SBB part object, it may be assigned to different SBB entities. When the SBB part object is assigned to an SBB part entity, it can receive events destined for the SBB entity and can manipulate the persistent state of the SBB entity. It can also access the relationships of the SBB entity.

An SBB part must define an SBB part class if the SBB part declares event handler methods. In any other case, the definition of an SBB part class is optional. An SBB part class must:

The SBB developer implements the SBB part class. In it, they may define lifecycle and event handler methods, and an exception callback. The SBB part class may also use Dependency Injection for various types of fields.

The SLEE provides each SBB part object, if requested through an SBB part class constructor argument or dependency injection, with an SbbPartContext object. The SbbPartContext object gives the SBB part object access to the SBB part object’s context maintained by the SLEE, allows the SBB part object to invoke functions provided by the SLEE, and obtains information about the SBB entity assigned to the SBB part object.

An SbbPartContext object is associated with one service and one SBB; and the associated service and SBB do not change during the lifetime of that SbbPartContext object.

The SbbPartContext object implements the SbbPartContext interface. The SbbPartContext interface extends the JAIN SLEE defined SbbContext interface with additional functionality, as described below.

An SBB part has access to the same JNDI environment bindings as its owning SBB. All the SLEE facilities, environment entries, and resource adaptor type bindings that are available to an SBB are also available to all its dependent SBB parts. An SBB part accesses its JNDI environment in exactly the same way as an SBB.

The current specification of SBB parts does not yet allow an SBB part component to declare its own environment entries. An SBB part component may however define its own resource adaptor type bindings.

Below is an example of an SBB part class. The SBB part declares an event handler method that receives a SLEE timer event, which logs the event and increments a CMP field and a usage counter:

As an extension to the JAIN SLEE specification, Rhino supports CMP field declarations of arrays for the following SLEE-defined types:

Arrays may be declared with any dimension. Array support is automatic wherever the basic type is supported in CMP fields; in other words, no user prompt or directive is necessary.

Rhino introduces a number of enhancements that offer significantly more control and flexibility over how CMP field values are serialized, and much better serialization performance, when compared with standard Java serialization. These include:

Often it is necessary, when a new persistent entity (such as an SBB entity) is created, to initialise various CMP fields to a value different than the standard Java default. For example: a CMP field storing a counter may need to be initialised to 1 instead of the default value of 0; a CMP field storing an array may need to be initialised to an empty array rather than default null; or a CMP field storing a list may need to be initialised to an empty list. The standard way to achieve this is to add the necessary CMP setter method invocations to the entity’s create lifecycle method; this is acceptable, but means that the initial value is separated from the CMP field declaration, making the code less obvious than it could be. Also this technique doesn’t work if, for example, an arbitrary CMP extension interface is linked in to the SBB — the SBB needs to know a priori what CMP fields need initialising — which means CMP fields in CMP extension interfaces dynamically added after compilation cannot be initialised this way.

To solve this problem, Rhino introduces an annotation that can be used to specify the initial value for a CMP field.

The JAIN SLEE 1.1 specification, as written, prescribes that CMP fields have pass-by-value semantics. This means that when an object value is stored in a CMP field, the SLEE will make and store a copy of that value, rather than store the original value. Similarly when a stored value is retrieved from a CMP field, the SLEE will name a copy of the stored value and return the copied value. The effect of this is that the stored object is unaffected by any subsequent changes made by the application to the original or retrieved object — a value retrieved from the CMP field will always have the exact same state as it did when stored in the CMP field.

Generally speaking, this is desired behaviour, and it makes application code easier to understand. However there are times when pass-by-value semantics get in the way of efficient programming, requiring additional coding to work around the limitations of these semantics. As an example, consider an application that needs to use some unchanging session state across multiple transactions. The correct SLEE technique here is to store the state in a CMP field, then retrieve that state in each transaction as required. Unfortunately the pass-by-value semantics mean that the application incurs the overhead of a stored value copy every time it retrieves the value from the CMP field, even though the stored value is never changed. A typical workaround to avoid this overhead is to:

…​all of which is cumbersome, particularly when there are many CMP fields that require this treatment.

To simplify the application developer’s effort in situations like these, Rhino introduces the option to declare pass-by-reference semantics to CMP fields.

Normally, when an SBB entity of a replicated service is replicated between Rhino cluster nodes, the values of all SBB CMP fields form part of the replicated state. There may be some cases though where the replication of certain CMP fields is not meaningful, for example the CMP field value might refer to a resource whose identity is only meaningful on the node where that identity is obtained.

Replication of individual CMP fields can be suppressed using the @com.opencloud.rhino.cmp.CMPFieldReplication annotation. This annotation may be used on:

It is illegal for a single CMP field’s getter and setter methods to be annotated with different replication suppression modes.

If replication of a CMP field is suppressed by this annotation then the state of that CMP field is excluded from the replicated state stream if and when replication of the SBB occurs. If entities of the SBB are never replicated, then this annotation has no effect.

In the event that the CMP state of an SBB entity is retrieved from a replicated storage resource then CMP fields with their replication suppressed will revert to the initial value defined by their @InitialValueField annotation, if present, otherwise the default initial value for the field type: null for reference types, 0 for numeric types, etc.

Below is an example of a CMP field with replication suppressed:

CMP field tagging allows arbitrarily-named tags to be assigned to CMP fields at compile time so that they can be iterated over and processed at runtime.

It can be useful, for example, to group a set of CMP fields that have a particular function or purpose that needs to be interrogated during application execution, without the application code having to know the names of each individual CMP field, something that may not even be possible if the application is composed using dynamic bindings.

The SLEE specification requires the SBB CMP fields be defined using abstract getter and setter methods. For example, the SBB CMP field named firstName of type java.lang.String must have the following method declarations in the SBB abstract class:

Rhino allows SBB CMP fields alternatively to be defined in separate CMP extension interfaces. A CMP extension interface is simply an interface that declares methods related only to CMP fields. One use of a CMP extension interface is to allow an SBB to store additional state that may not be 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 of which may require its own CMP state. The plug-in components can define the CMP state they need using CMP extension interfaces; then these interfaces can be declared in the SBB deployment descriptor when the SBB is packaged.

CMP extension interfaces are also the sole mechanism by which an SBB part component can define CMP fields.

The firstName CMP field example above could be defined in a CMP extension interface as shown below:

A CMP extension interface may also optionally include has and reset methods for each CMP field.

Adding the has and reset methods to the MySbbCMPInterface example shown above results in the interface shown below:

Below is an example of a how the reset method is influenced by an @InitialValueField annotation:

A CMP extension interface must be public, and optionally may extend the com.opencloud.rhino.cmp.CMPFields interface. A single SBB or SBB part may declare as many CMP extension interfaces as desired. An SBB declares its CMP extension interfaces in the oc-sbb-jar.xml extension deployment descriptor, while an SBB part declares its CMP extension interfaces in the oc-sbb-part-jar.xml deployment descriptor. Since a CMP extension interface defines only CMP fields, an SBB deployment descriptor does not need to specify <cmp-field> elements for any CMP field defined only in a CMP extension interface. The CMP fields will be determined by class introspection.

All methods defined in a CMP extension interface are mandatory transactional methods. If they are invoked without a valid transaction context, a javax.slee.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 using 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 java.lang.IllegalStateException is thrown.

An SBB or SBB part obtains access to the CMP fields defined in CMP extension interfaces using a com.opencloud.rhino.cmp.CMPFields object. The CMPFields object may be typecast to any CMP extension interface declared by the SBB or SBB part, regardless of whether or not the CMP extension interface extends the CMPFields interface, thus exposing the CMP field accessor methods defined by the interface.

The CMP fields defined by an SBB in its SBB abstract class, in any CMP extension interfaces, and in any CMP extension interfaces used by dependent SBB parts, all share the same namespace. As such, if the same CMP field is defined in multiple places, for example in the SBB abstract class and in a CMP extension interface, then it must be declared with the same type. All these CMP accessor methods will refer to the same underlying SBB CMP field.

There are sometimes occasions when an SBB needs to store arbitrary CMP state which cannot be predetermined at development time. For example, arbitrary session state could be created in response to interactions with some other network element. The typical response is to define a CMP field that stores a map and store the session state in the map as key, value pairs. This is an acceptable solution; however, serialization of the stored map value can be a performance hit if not explicitly managed; and even then a change to any mapped value requires serialization of the entire map as it is read from CMP, updated, then rewritten to CMP.

To help in these situations, Rhino allows an SBB or SBB part to optionally permit the use of arbitrary CMP fields. Arbitrary CMP fields are simply CMP fields that have not been explicitly defined in the SBB abstract class or any CMP extension interface. Support for arbitrary CMP fields not permitted by default but can be permitted using the arbitrary-cmp-fields-allowed attribute in the oc-sbb-jar.xml SBB extension deployment descriptor or oc-sbb-part-jar.xml SBB part deployment descriptor. Note that if an SBB has a dependency on an SBB part that has permitted support for arbitrary CMP fields, then that permission for arbitrary CMP fields extends back to the SBB and all its dependent SBB parts. It is not possible for an SBB or SBB part to override permission for arbitrary CMP fields from some other dependent SBB part (or the SBB itself in the case of an SBB part).

Arbitrary CMP fields have only a few basic rules and restrictions:

Arbitrary CMP fields are accessed and managed using a CMPFields object.

The CMPFields interface provides a means to access CMP fields indirectly by name, access metadata about CMP fields, and obtain information about and determine which CMP fields currently have a value. Arbitrary CMP fields are also managed using a CMPFields object.

The CMPFields interface is shown below:

The get, set, has, and parameterised reset methods allow any CMP field to be accessed by name parameter. These methods provide an alternative access mechanism for CMP fields predefined in the SBB abstract class or a CMP extension interface. These methods also allow arbitrary CMP fields to be created and managed if support for this feature is permitted by the SBB or SBB part. Predefined and arbitrary CMP fields all share the same namespace. If any of these methods are invoked with a name parameter that matches a predefined CMP field name, then the name refers to the predefined CMP field; otherwise it refers to an arbitrary CMP field. These methods throw an UnrecognisedFieldNameException if the name refers to an arbitrary CMP field and arbitrary CMP fields are not permitted by the component.

When any of these methods are used to access a predefined CMP field, the invocation is equivalent to the corresponding CMP field method declaration. The example below illustrates this point:

The unparameterised reset method resets all predefined CMP fields to their initial value and removes all arbitrary CMP fields that exist. This method effectively returns the SBB CMP state to as it was when the SBB entity was first created.

The typeOf method returns the Java class type of the named CMP field. For a predefined CMP field the return value is equal to the class used in its CMP field method declarations. For an arbitrary CMP field, this method returns the class of the value stored in the CMP field. The arbitrary CMP field must exist for this method to return a successful result, otherwise an UnrecognisedFieldNameException is thrown.

The isPredefined method returns true if the name corresponds with a predefined CMP field, and false otherwise. The predefinedNames method returns a set containing the names of all predefined CMP fields.

The keySet method returns a set containing the names of all CMP fields that currently have a value. The entrySet method returns a map containing the names and values of all CMP fields that currently have a value. The CMP fields that are deemed to have a value include:

The cmpField method returns a CMPField object that allows direct inspection and/or update to the named CMP field.

The tags method returns the names of all CMP field tags used in the CMP fields defined in the SBB abstract class and CMP extension interfaces.

There are two visit methods. One can be used to iterate over the set of CMP fields tagged with a specified name, invoking the visit method on the provided visitor object for each one. The second can be used to iterate over all CMP fields defined in the SBB abstract class and CMP extension interfaces, optionally including any arbitrarily defined CMP fields.

All methods defined in the CMPFields interface, with the exception of isPredefined, predefinedNames, and tags, are mandatory transactional methods. If they are invoked without a valid transaction context, a javax.slee.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 using 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 java.lang.IllegalStateException is thrown.

The CMPField interface provides a means to inspect and/or update an individual CMP field.

The CMPField interface is shown below:

The getName and getType methods return the name and type of the CMP field respectively. For an arbitrary CMP field, the type is determined from the CMP field’s current value.

The getTags method returns the set of tags, if any, that have been assigned to the CMP field.

The getValue, setValue, hasValue, and reset methods perform the named function against the CMP field. For predefined CMP fields, these methods are equivalent to the get, set, has, and reset methods respectively that can be defined for a CMP field, and invoking any of these methods is equivalent to invoking the corresponding CMP field method. For example, invoking getValue() on a CMPField object for a field named firstName is equivalent to invoking the getFirstName() CMP field method.

The isPredefined method determines whether or not the CMP field was defined in the SBB abstract class or a CMP interface, or is an arbitrary CMP field. This method returns true if the CMPField object represents a predefined CMP field, and false otherwise.

The getName, getTags, and isPredefined methods are non-transactional methods. This means that a valid transaction context is not required in order to invoke these methods. The getType method is also a non-transactional method if the CMPField object represents a predefined CMP field.

All other methods, and getType when invoked on a CMPField object representing an arbitrary CMP field, are mandatory transactional methods. If they are invoked without a valid transaction context, a javax.slee.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 using 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 java.lang.IllegalStateException is thrown.

Under normal conditions, transactional state of replicated activities and SBBs that gets stored into Rhino’s internal memory database automatically gets scheduled for persistence to an external key/value store if one is configured as the replication resource for the application namespace. At the early stages of a call or session though it may not make sense to replicate intermediate state changes as the state changes rapidly, for example during preconditions negotiation. Therefore, it may only be meaningful to replicate state changes once a call or session is in a so-called stable state, where the state is not expected to immediately change. Typically a session is in a semi-stable state during the alerting phase. The next stable state is answered.

An application can choose to suppress the initial replication of its state at deployment time using the service-properties element in the extension service deployment descriptor. Alternatively, an administrator can change the initial replication persistence mode of an already deployed service using the ServiceManagementMBean.setInitialPersistence management operation.

At an appropriate time in its lifecycle, an SBB entity can enable replicated persistence of its state using RhinoSbbContext.enableEntityTreePersistence.

Rhino allows an SBB to declare a child relation with an extension deployment descriptor entry only; in other words, no corresponding get child relation method is needed in the SBB abstract class. As such, these child relations are termed "declarative" child relations, to differentiate them from the standard child relations defined by the SLEE specification. Declarative child relations may be added to or removed from an SBB without the need to recompile any code.

Declarative child relations are declared in the oc-sbb-jar.xml extension deployment descriptor using the <child-relations> element. The child-relations element contains a child-relation element that defines each declarative child relation. A child-relation element contains the following sub-elements:

The Child Relation Facility is a Rhino extension that is used by SBBs to gain access to their declarative child relations. The Child Relation Facility bypasses the need for the SBB developer to declare a get child relation method in the SBB abstract class for each child SBB that the SBB desires.

The com.opencloud.rhino.facilities.Tracer extended tracer interface adds two new methods to the standard tracer. Like all methods defined by the standard interface, both new methods are non-transactional; that is, they do not require an active transaction to return a successful result.

See the ExtendedTracer interface Javadoc.

Rhino extensions to the SLEE-defined Tracer interface.

Since 2.6.0 Rhino tracer extensions support use of a string interpolation format that allows deferring final string construction until it is certain that the message will be logged somewhere.

Methods taking object parameters and a string message expect the string to use "{}" to mark object insertion points. Parameters will be inserted in argument order.

will log "An example string with 2 object parameters".

Rhino tracer extensions were written to support garbage free tracing. To support that unrolled overloads for up to 10 object parameters are provided. More than 10 object parameters to these methods should be avoided as these are incompatible with garbage free tracing.

For situations where simple string interpolation is not sufficient, we offer the full flexibility of java.util.Formatter string formatting using the printf method.

MDC(Mapped Diagnostic Context) support was added in 2.6.0. This provides a mechanism to associate logging context with activities. associated context will be automatically included in every Trace/log message in {name=value, name=value} format. as a consequence of this, some care must be taken when deciding what to add as context to avoid overly long and unweildy log messages.

The JAIN SLEE specification defines two types of usage parameters: counter-type and sample-type. Rhino’s extension mechanism does not add any new type of usage parameter, but does allow counter-type usage parameters to be set to a specific value rather than only incremented or decremented.

A usage parameter set is a set that contains a usage parameter for each usage parameter name declared in the usage parameters interface of the corresponding SLEE component. Each method of the usage parameters interface declares the usage parameter name and type of a single usage parameter in this set. A SLEE component that generates usage information may access multiple usage parameters with the same lowest-level usage parameter name component, by using multiple usage parameter sets. The JAIN SLEE specification defines: a default usage parameter set, automatically available to any SLEE component that defines a usage parameters interface; and named usage parameter sets — which can also be used by the SLEE component, but can only be created and removed using the JMX management interface. Usage parameter sets in the JAIN SLEE specification occupy a flat namespace, and there is no relationship between any two usage parameter sets.

Rhino’s extension mechanism introduces a hierarchical structure and namespace for usage parameter sets. The SLEE-defined default usage parameter set is replaced with a root usage parameter set, and each usage parameter set can have zero or more child usage parameter sets. A usage parameter set name must be unique amongst its sibling usage parameter sets, but in any other case usage parameter set names may be reused.

A SLEE component creates, removes, or otherwise manages its own usage parameter sets itself using the Usage Facility and the methods defined on the Usage Parameter Interfaces.

Under certain conditions, a usage parameter update to a usage parameter set may aggregate to its parent usage parameter set. Aggregation simply means that the update is also applied to the parent usage parameter set, and then its parent, and so on, so long as an aggregation relationship holds between the parent and child usage parameter sets, or the root usage parameter set is reached. Aggregation is useful, for example, to record total usage in a parent usage parameter set where individual child usage parameter sets record usage for different conditions, such as the triggering protocol of the session.

Aggregation for a given usage parameter name can only occur from a child usage parameter set to a parent usage parameter set if:

Usage parameter set type extension is declarative rather than programmatic. A usage parameter set type declares in the deployment descriptor if it extends another usage parameter set type. The usage parameters interface of a usage parameter set type that extends another usage parameter set type is not required to extend or otherwise be related in any way to the usage parameters interface of the extended usage parameter set type. As long as the two usage parameters interfaces declare a usage parameter with the same name and type (counter-type or sample-type), then aggregation may occur between the two usage parameter set types for that usage parameter name.

Aggregation is enabled by default for all usage parameters. Aggregation can be disabled on a per usage parameter name basis using the relevant annotation on each usage parameters interface usage parameter method declaration.

SLEE components declare their usage parameters using one or more usage parameters interfaces. Each usage parameters interface must be defined according to the following rules:

Counter-type usage parameter increment methods, sample-type usage parameter sample methods, and all usage parameter accessor methods, are declared in the usage parameters interface as defined in the SLEE specification.

A usage parameters interface may optionally extend the UsageParametersInterface. By extending this interface, a usage parameters interface provides its corresponding usage parameter sets with easy access to methods reporting metadata about themselves and methods to manage their child usage parameter sets. The UsageParametersInterface is shown below:

All methods in the UsageParametersInterface are non-transactional methods; that is, they do not require an active transaction to return a successful result, and their effects persist regardless of the outcome of any transaction active at the time of the method call.

The methods throw a SLEEException if the requested operation cannot be performed due to a system-level failure.

A usage parameters interface and its usage parameter methods may all be annotated to provide additional information to Rhino’s statistics and SNMP subsystems. This is supported in both the SLEE-defined usage mechanism and Rhino’s extension mechanism. Information provided to the statistics subsystem helps clients display statistics appropriately, whereas information provided to the SNMP subsystem is used to configure the OIDs included in SNMP notifications for usage parameter set updates.

If an SBB declares one or more usage parameters interfaces using the Rhino usage extension mechanism, the oc-sbb-jar.xml Rhino extension deployment descriptor of the SBB must identify the usage parameters interfaces. The sbb-usage-parameters-interfaces element of the SBB extension deployment descriptor identifies these interfaces. It contains the following sub-elements:

Each sbb-usage-parameters-interface element has the following attributes and sub-elements:

The sbb-usage-parameters-interface-type element has the following attribute:

If a resource adaptor declares one or more usage parameters interfaces using the Rhino usage extension mechanism, the oc-resource-adaptor-jar.xml Rhino extension deployment descriptor of the resource adaptor must identify the usage parameters interfaces. The resource-adaptor-usage-parameters-interfaces element of the resource adaptor extension deployment descriptor identifies these interfaces. It contains the following sub-elements:

Each resource-adaptor-usage-parameters-interface element has the following attributes and sub-elements:

The resource-adaptor-usage-parameters-interface-type element has the following attribute:

The usage facility is used by SBBs and resource adaptors to obtain access to their root usage parameter set and to create and manage child usage parameter sets. The usage facility is defined by the com.opencloud.rhino.facilities.usage.UsageFacility interface. An SBB obtains access to a UsageFacility object using a JNDI name lookup. A resource adaptor obtains access to a UsageFacility object from the ConfigProperties object passed to it by the SLEE.

A UsageFacility object is only made available to SLEE components that declare usage parameter interfaces using the Rhino usage extension mechanism. A SLEE component that does not declare any usage parameters interface, or declares a usage parameters interface using the SLEE-defined mechanism, will not be able to access the usage facility.

The com.opencloud.rhino.facilities.profile.ProfileFacility interface is shown below:

The extended interface is implemented by all ProfileFacility objects provided by Rhino to SBBs and resource adaptors.

The extended interface adds two new methods to the profile facility. Both methods are non-transactional; that is, they do not require an active transaction to return a successful result. The methods throw the javax.slee.facilities.FacilityException if the requested operation cannot be completed because of a system-level failure.

The com.opencloud.rhino.slee.environment.JndiBinding class is shown below:

As MDC is stored in a ThreadLocal Map, it will not follow over thread boundaries. For example, in the asynchronous API of any RA providing such, there will be an RA provided mechanism to hand off work to another thread (the handling thread). In order for any logging done by the handling thread to log the MDC, the handoff mechanism must support this by copying the MDC and clearing it from the handling thread when done.

As the entire MDC map is logged unconditionally with every log message human readable logs require that the MDC map be kept small. Both a small number of total entries, and the shortest practicable entires. A key should only be added to the MDC if it will provide significant value in tracking or sorting log messages,

For example, Rhino includes by default two MDC entries:

The included txId is used for Rhino diagnostics, to track exactly what occured within a given SLEE transaction, at all stages. From the service code to Rhino internals of transaction handling.

Identifiers that are short lived or not meaningful outside of the RA generally should not be added to MDC at all. And certainly not in a persistent manner except in extraordinary circumstances.

As an example of an identifier that should not be added persistently consider the SLEE TransactionID. This is not persisted within the backing Activity across multiple events, as each event takes place within a single transaction. This is a rare exception where an ephemeral key makes sense to add to MDC as processing each event involves at least one transaction, and being able to track the flow of logic within a single transaction can be extremely useful in error conditions. However, the transaction ID becomes meaningless on transaction completion, weather as a commit, or rollback. The txId key is therefore removed from MDC as soon as the transaction is completed.

A bundle file is a YAML document mapping event names to human readable descriptions. SAS requires event decoding bundle files to display the events received. Correlation and storage do not require the bundle file, it is only used at display time.

Rhino extends the SAS bundle model to use composable mini-bundles that are assembled at runtime into a bundle to export for loading into SAS. Each network element may only use one bundle when reporting to a SAS instance so Rhino builds this bundle from all the mini-bundles found in components deployed to a namespace. Developers of resource adaptors and services that use the SAS facility must write mini-bundle files to describe the events their components report.

Mini-bundles contain a set of named event descriptions and enumerated values used to construct a SAS bundle. These are combined with system-identifying information configured in Rhino to produce the bundle SAS will use to decode messages. Each mini-bundle file starts with a version, followed by a set of events and, optionally, enums listing values that can be expanded from integer "static" parameters in event messages. A component may report events from multiple mini-bundles. Events have symbolic names to support use by multiple components. They must be packaged in a deployment jar that is installed into Rhino with the component that reports the events. This may be the same jar as the component or another that the component depends on.

After deployment the system operator exports the merged bundle and installs it into the SAS UI. At this time the component bundles are combined with the configured Resource ID and written with numeric IDs to form a bundle file SAS can load. If multiple versions of a mini-bundle are deployed, only the latest version will be used. For more information on how Rhino combines mini-bundles see SAS Bundle Generation and SAS Bundle Mappings in the Rhino Administration and Deployment Guide

Rhino comes with an Ant task for creating enum classes from bundle files generate-bundle-enums. Java enums are created for the SAS events and enums in the bundle file provided. The bundle files must be named for the package the enums will be created in.

Each event in a bundle must have a summary and a level. It may optionally contain details and call-flow data. Call flow descriptions must contain data, protocol and direction, other attributes are optional but should be provided where available. All text attributes of events can contain parameterised text using the Liquid templating language. For full details of the event structure contact your Metaswitch representative.

For an example of a mini-bundle file, see Service Assurance Server (SAS) Tracing in the HTTP resource adaptor guide.

On event delivery to a service, the invoking Trail is made available through the Invoking Trail Accessor. Calling getInvokingTrail() will return the SAS trail attached to the ACI on which the event was fired. On subsequent downcalls into RAs that result in a new SLEE activity being created via SleeEndpoint.startSuspended, the invoking trail (if one exists) will automatically be attached to the new activity. This behaviour means that a SAS trail will automatically be passed along through any number of downcalls into RAs and asynchronous events as long as the service always attaches to the ACI for the new activity.

In most cases, this behaviour is desired and saves one from having to add code that explicitly gets a trail from the invoking ACI and attaches it a new ACI. If necessary, however, one can call setInvokingTrail(Trail) or remove() to manually set or clear the invoking trail before calling into a RA.

SAS Trails that form part of the same call can be associated by calling associate(Trail). If the Rhino SAS facility is configured with multiple SAS servers, different trails may not be using the same server.

Associating trails that are using the same SAS server is more efficient, as a trail association message can be sent to the one server informing it that the trails form part of the same trail group. If the trails being associated are using different servers, then a generic correlation marker gets sent to each SAS server with the UUID of the one trail. The SAS reporting then needs to perform some additional work to correlate the trails.

To ensure related trails are colocated on the same SAS server, SLEE components can call startColocatedTrail(Trail) or startAndAssociateTrail(Trail, Scope). These methods will create a new SAS trail using the same server as the given trail and, in the second case, will automatically send a trail association message to the server.

Sas Facility

Entry point to the SAS event reporting facility.

Users of this facility create a Trail, then use that to create and report events The Trail interface provides two ways to create then report Events and Markers:

The SAS Facility supports communication with a federation of SAS servers. As such, trails created with startTrail() are distributed between servers by simple round-robin. When starting a new trail that will be associated with an existing one, use startColocatedTrail(Trail) or startAndAssociateTrail(Trail, Scope) to start a new trail on the same server as the given trail.

Trail

The primary interface for creating and reporting markers and events. A trail is a sequence of related events and markers representing the processing sequence for a dialog or transaction.

Invoking Trail Accessor

Provides access to the InvokingTrail. The InvokingTrail is the SAS trail attached to the activity owning the current event, at the time the event is delivered.

Message

Superinterface of EventMessage and MarkerMessage with functionality common to both.

A Message sent to SAS may contain parameters to be used when decoding the message on the SAS server for display or correlation.

The JAIN SLEE specification states that every deployable component has an identity specified by a name, vendor, and version tuple. This identity must be unique within the scope of a given component type. A component may reference other components of various types by specifying their type and identity in the component deployment descriptor.

These references are static, that is: they are defined prior to installation in the SLEE; and once the component is installed the references cannot be changed. Static references in general function adequately; however they can make the application upgrade process more complicated that it need be.

For example, if a library component used by an application has a bug fixed and a new version of the library is produced, then all dependent components such as SBBs and profile specifications need to have their references updated and new versions released; and all components dependent on those, such as other SBBs and service components, also need updating and releasing; and so on through the chain of dependencies.

A more dynamic approach to dependency specification and binding would help make the upgrade process easier. Rhino provides such an approach, which is supported by the following concepts:

Each of these concepts is described in detail below.

The JAIN SLEE specification defines that a deployable unit and the components it contains is either installed or not installed in the SLEE. When a deployable unit is installed, its components are verified for correctness, and if verification is successful the components are made ready for use; for example, service components are initialised ready for activation.

To facilitate the management of dynamic component bindings, Rhino provides finer-grained control over the degree to which a deployable unit and its components are installed. Installed components each have one of the following install levels:

Here are some ways you can manage install levels:

In order to maintain compatibility with the JAIN SLEE specification, Rhino does not permit the component references of components installed using a standard SLEE deployable unit — hereinafter termed "original" components — to be dynamically modified. Rather, a virtual copy of each component to be modified must be made, and the references of the copied components modified instead. A copied component is still a SLEE component in its own right, and must have a unique identity within the scope of the component type as for any other component. The only difference between an original SLEE component and a copied component is from where the component originates in the SLEE. A copied component uses the same set of interfaces and classes, and inherits the configuration properties such as environment entries, from the component it is copied from.

Here are some commands for managing copies:

Dynamic component dependencies are specified using a binding descriptor. A binding descriptor is a JSON document that describes the changes that should be made to the deployment descriptors of one or more components. For example, a binding descriptor may change the root SBB of a service, or may add a new library reference to an SBB. A binding descriptor can only add to or change existing information contained in a deployment descriptor; it cannot remove any existing information.

A binding descriptor is a new component type in Rhino. As a component type, a binding descriptor has an identity described by the name, vendor, and version tuple — like all other SLEE component types. A binding descriptor document may be installed in Rhino as a new type of deployable entity.

Rhino provides an extension to the standard javax.slee.SbbContext interface with the com.opencloud.rhino.slee.RhinoSbbContext interface. The RhinoSbbContext interface provides additional functionality to SBBs running in Rhino. The RhinoSbbContext interface is as follows:

The JAIN SLEE specification allows delivery of events to be suspended and resumed using the methods defined in the javax.slee.EventContext interface. An obvious restriction to this is that suspending event delivery requires an EventContext object, and the only way to obtain an EventContext object of an unsuspended event is by event handler method argument; therefore an SBB can only suspend delivery of an event that is being delivered to it. An SBB that attaches to multiple activities may at times desire to suspend delivery of events on a selected subset of these activities while waiting for the result of some asynchronous action. The SLEE specification does not provide a trivial solution to this problem, instead requiring a complicated process of suspending events on those activities as they are received, then resuming and processing those events at an appropriate time in a later transaction.

Rhino simplifies this problem by allowing event delivery on any activity context to be suspended and resumed at any time. Rhino defines the com.opencloud.rhino.slee.RhinoActivityContextInterface interface, an extension to javax.slee.ActivityContextInterface, with methods providing this functionality. The RhinoActivityContextInterface interface is shown below:

All activity context objects that Rhino provides to SBBs implement RhinoActivityContextInterface; therefore a typecast of an activity ccntext object to this interface will always succeed. Rhino will also recognise an event handler method defined with this type, instead of the standard ActivityContextInterface, as the second method argument, removing the need to perform a typecast within the method body if the extensions are required.

An SBB or SBB Part activity context Interface may be declared as extending RhinoActivityContextInterface rather than ActivityContextInterface if desired.

The JAIN SLEE specification allows an SBB component to declare a local interface. An SBB entity can invoke a target SBB entity in a synchronous manner through the SBB local interface of the target SBB. Rhino also allows an SBB to declare a local home interface. Methods invoked on the local home interface are not specific to any SBB entity and are executed by an SBB object in the Pooled state. An SBB local home object is an instance of a SLEE-implemented class that implements an SBB local home interface.

Service Node Activities can be used by SBBs to monitor the managed lifecycle of the service they are a part of on their individual cluster node. Service Node Activities perform the same function as SLEE 1.1 Service Activities, but for each node in a Rhino cluster instead of only once for the whole cluster. This is useful when a service needs to initialise local state on each node in a cluster or perform shutdown tasks without storing replicated SBB state.

When a service is started on a node, a Service Node Activity is created on that node and a com.opencloud.rhino.slee.servicenodeactivity.ServiceNodeStartedEvent is fired on the activity to the service. When the service is stopped on a node, the service node activity on that node is ended and a javax.slee.ActivityEndEvent is fired on the activity. A service starts on a node when either of the following occurs on that node:

The event type name of Service Node Started events is com.opencloud.rhino.slee.servicenodeactivity.ServiceNodeStartedEvent, the vendor is com.opencloud, and the version is 1.0. The event, when fired by the SLEE, will only be delivered to SBBs in the service that is starting, and not any other service.

Service Node Activities are never replicated. Each node has their own Service Node Activity that does not share state with any other node.

The Service Node Activity allows the SBBs making up the service to identify the service. The Service Node Activity for an SBB entity can be obtained by looking it up using the ServiceNodeActivityFactory class, an instance of which can be obtained by JNDI lookup using the name java:comp/env/rhino/servicenodeactivity/factory. An SBB can create an Activity Context Interface for the Service Node Activity using the ServiceNodeActivityContextInterfaceFactory class. An instance of this can be looked up using the JNDI name java:comp/env/rhino/servicenodeactivity/activitycontextinterfacefactory.

The JAIN SLEE specification states that if a method invocation on an SBB or a profile returns by throwing an unchecked exception, then (amongst other things) the transaction is marked for rollback and a javax.slee.TransactionRolledBackLocalException is propagated back to the caller. There may be times, however, in certain applications where this behaviour is undesirable, and the caller would rather catch and handle the exception itself rather than have the transaction forcibly rolled back.

To address this need, Rhino provides the @PropagateUncheckedThrowables annotation. This annotation can be used on any SBB local interface method or profile local interface method to indicate that any unchecked throwable (RuntimeExceptions or Errors) produced by the method must be propagated back to the caller as-is. The transaction is not marked for rollback, and the invoked SBB or profile object remains in the same state; in other words, it is not discarded by a transition to the Does Not Exist state.

An SBB local interface or profile local interface class declaration may also be annotated with @PropagateUncheckedThrowables. When used in this way, the annotation indicates that all methods defined in the interface, and all inherited methods, shall exhibit the behaviour defined by the annotation, as if all these methods were annotated individually.

The propagation of unchecked throwables only applies to exceptions produced by the invoked method itself. The annotation has no effect against container-generated exceptions that cause rollback, such as trying to invoke a local interface method on an SBB that no longer exists. The annotation is also ignored for methods originally defined in the base local interfaces: javax.slee.SbbLocalObject and javax.slee.profile.ProfileLocalObject.