Rhino provides many extensions to the standard facilities and application functions provided by the JAIN SLEE specification, as detailed below.

On this page...

SBB child relations

The JAIN SLEE specification defines that an SBB child relation requires:

  • an abstract get child relation method declared in the SBB abstract class; and

  • a <get-child-relation-method> deployment descriptor entry that binds the get child relation method to a particular SBB type.

The get child relation method returns a ChildRelation object, which the SBB developer uses to create, remove, or manage the SBBs in the child relation.

A difficulty with this approach is that child relations cannot be added to an SBB without code changes to the SBB abstract class. For example, consider an SBB that delegates call processing to different child SBBs based on the protocol in use for the call (CAPv2, CAPv3, ETSI INAP CS1, and so on). Since the child SBB for each protocol needs its own get child relation method in the SBB abstract class, it’s not easy to decide at build time what protocols will be supported without modifying the SBB abstract class and recompiling. Code changes are also extremely undesirable when service bindings are used to change the child relationships of the SBB after the SBB has been installed in the SLEE.

Rhino provides an alternative mechanism to declare and use SBB child relations, which eliminates the recompilation part of the build cycle in these types of use cases. Child relations are still declared in the deployment descriptor, but the SBB accesses the child relations using a Child Relation Facility provided by the SLEE.

Extended child relation declarations

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:

Sub-element What it does 
description

Provides information (optional).

 
child-relation-name

Defines the name of the declarative child relation. The SBB uses this name with the Child Relation Facility to access the child relation. This name must be unique within the scope of the SBB’s declarative child relations.

 
sbb-alias-ref

References an SBB by its sbb-alias that is specified within the corresponding sbb element in the standard sbb-jar.xml deployment descriptor. This element defines the type of the child SBB.

 
default-priority

Specifies the default event delivery priority of the child SBB relative to its sibling SBBs.

Child Relation Facility

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.

ChildRelationFacility interface

SBB objects access the Child Relation Facility through a ChildRelationFacility object that implements the ChildRelationFacility interface. A ChildRelationFacility object can be obtained from the SBB’s RhinoSbbContext object (an extension of the standard SbbContext object).

The ChildRelationFacility interface is as follows:

package com.opencloud.rhino.facilities.childrelations;

import java.util.Collection;
import javax.slee.ChildRelation;
import javax.slee.SbbLocalObject;
import javax.slee.TransactionRequiredLocalException;
import javax.slee.facilities.FacilityException;
import com.opencloud.rhino.slee.RhinoSbbContext;
import com.opencloud.rhino.slee.RhinoSbbLocalHome;

public interface ChildRelationFacility {
    public Collection<String> getChildRelationNames()
        throws FacilityException;

    public ChildRelation getChildRelation(String name)
        throws NullPointerException, TransactionRequiredLocalException, IllegalStateException,
               UnrecognizedChildRelationException, FacilityException;

    public Collection<SbbLocalObject> getChildSbbs()
        throws TransactionRequiredLocalException, IllegalStateException, FacilityException;

    public <T> Collection<T> getChildSbbs(Class<T> type)
        throws NullPointerException, TransactionRequiredLocalException,
               IllegalStateException, FacilityException;

    public RhinoSbbLocalHome getChildSbbLocalHome(String name)
        throws NullPointerException, UnrecognizedChildRelationException, FacilityException;
}
Note

  • All methods of the ChildRelationFacility interface, except for the getChildRelationNames method and the getChildSbbLocalHome method, are required transactional methods. The getChildRelationNames method and the getChildSbbLocalHome method are non-transactional.

  • The SLEE provides a concrete class implementing the ChildRelationFacility interface.

  • The methods of this interface throw the javax.slee.facilities.FacilityException if the requested operation cannot be completed because of a system-level failure.

ChildRelationFacility interface getChildRelationNames method

The getChildRelationNames method returns the set of declarative child relation names declared by the SBB. Each name contained by this set corresponds with a name contained by a <child-relation-name> element in the oc-sbb-jar.xml extension deployment descriptor.

ChildRelationFacility interface getChildRelation method

The getChildRelation method returns a standard ChildRelation object for the named declarative child relation. The specified name argument must be one of the names contained by the <child-relation-name> elements in the oc-sbb-jar.xml extension deployment descriptor; that is, it must be one of the names contained in the set of names returned by the getChildRelationNames method.

This method performs the same function as the get child relation methods declared in the SBB abstract class for standard JAIN SLEE child relation declarations. A ChildRelation object returned from this method can be used in exactly the same way as a ChildRelation object returned by a get child relation method.

This method throws a NullPointerException if the name argument is null. If the name argument does not correspond with a declarative child relation, then this method throws an UnrecognizedChildRelationException. If this method is invoked without a valid transaction context, then the method throws a TransactionRequiredLocalException. If the method is invoked by an SBB object that is not assigned to an SBB entity, then the method throws an IllegalStateException.

ChildRelationFacility interface getChildSbbs methods

The getChildSbbs methods each return a collection of child SBB local interface objects. The no-argument variant returns a collection of all child SBBs. The one-argument variant returns a collection of all child SBBs where the child SBB’s local interface is assignable to the specified Class argument. Both these methods will consider all SBB child relations; that is, child relations declared both in the standard JAIN SLEE manner and declarative child relations.

If either of these methods are invoked without a valid transaction context then a TransactionRequiredLocalException is thrown. If invoked by an SBB object that is not assigned to an SBB entity, then an IllegalStateException is thrown. If the one-argument method variant is invoked with a null argument, then the method throws a NullPointerException.

ChildRelationFacility interface getChildSbbLocalHome method

The getChildSbbLocalHome method returns an object implementing the local home interface of the child SBB of the named declarative child relation. For more information on SBB local home interfaces, please see Miscellaneous SLEE Application API Enhancements.

This method throws a NullPointerException if the name argument is null. If the name argument does not correspond with a declarative child relation, then this method throws an UnrecognizedChildRelationException.

Usage extensions

The JAIN SLEE specification allows SLEE components such as SBBs and resource adaptors to define a single usage parameters interface for the collection of runtime statistics. Statistics may be collected in different usage parameter sets — essentially named buckets each containing the same set of usage parameters as defined by the usage parameters interface. Creation and removal of named usage parameter sets is only supported through JMX management clients.

When building large SLEE applications or complex resource adaptors, the limitations of the SLEE-defined usage mechanism quickly becomes apparent. A single usage parameters interface lacks flexibility, and means that statistics from all parts of the system need to be lumped into a single view; and the inability of an application to be able to control its own named usage parameter sets can create a discord between any dynamic application behaviour and usage parameter set management requirements.

To alleviate these problems, Rhino provides a usage extension mechanism that allows an SBB or resource adaptor to declare multiple usage parameters interfaces, and defines a usage facility with which SBBs and resource adaptors can manage and access their own usage parameter sets. This section describes that extension mechanism.

Usage parameter types

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.

Usage parameter sets

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.

Usage parameter set types

Each usage parameter set may or may not have a type. Usage parameter set types are declared in the deployment descriptor, each with a corresponding usage parameters interface. A usage parameter set with no type has no usage parameters, and can be used as a structural placeholder in the usage parameter set hierarchy.

The type of the root usage parameter set is also declared in the deployment descriptor. This declaration is optional. If declared, the root usage parameter set will be created with the specified type; otherwise the root usage parameter set will be created with no type.

The type of a child usage parameter set is specified at runtime when the usage parameter set is created by the SLEE component. A child usage parameter set may be created with any recognised usage parameter set type, or may be created with no type.

A SLEE component must declare at least one usage parameter set type in order to use the usage facility and manage its usage parameter sets.

Aggregation and extension

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:

  • the parent usage parameter set and the child usage parameter set have the same usage parameter set type; or

  • the child usage parameter set type extends, either directly or indirectly, the parent usage parameter set type; and both usage parameter set types declare a usage parameter of the same type (counter-type or sample-type) with that usage parameter name.

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.

Usage parameters interfaces

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:

  • A usage parameters interface must be defined in a named package; in other words, the class must have a package declaration.

  • A usage parameters interface must be declared as public.

  • A usage parameters interface may optionally extend the com.opencloud.rhino.facilities.usage.UsageParametersInterface interface.

  • Each increment, set, or sample method within the usage parameters interface must declare a lowest-level usage parameter name relevant to the SLEE component.

    • The SLEE derives the usage parameter type associated with this usage parameter name from the method name of the declared method.

  • Each get accessor method within the usage parameters interface provides access to the current approximate value or sample statistics for the lowest-level usage parameter name.

  • A single usage parameter name can only be associated with a single usage parameter type. The SLEE will reject a usage parameters interface that declares both a sample method and an increment or set method for the same usage parameter name.

    • It is legal to declare both increment and set methods for the same usage parameter name. These two methods simply offer alternative ways to update the same counter-type usage parameter.

  • A usage parameter name must be a valid Java identifier and begin with a lowercase letter, as determined by java.lang.Character.isLowerCase.

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.

Counter-type usage parameter set method

A usage parameter set method must be defined in the usage parameters interface to declare the presence of and to permit updates to a counter-type usage parameter. The method name of the set method is derived by adding a "set" prefix to the usage parameter name. The set method has the following method signature:

public abstract void set<usage parameter name>(long value);
Note

  • The set method must be declared as public and abstract.

  • The first letter of the usage parameter name is uppercased in the definition of the set method.

  • The set method does not have a throws clause.

  • This method runs in an unspecified transaction context. Counter-type usage parameter updates do not require an active transaction. Counter-type usage parameter updates occur regardless of the outcome of any transaction active at the time of the update. If multiple threads update the same usage parameter at the same time, these updates are applied as if the updates were serial.

  • The method throws a javax.slee.SLEEException if the requested operation cannot be performed due to a system-level failure.

UsageParametersInterface interface

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:

package com.opencloud.rhino.facilities.usage;

import java.util.Collection;
import javax.slee.SLEEException;
import javax.slee.usage.SampleStatistics;

public interface UsageParametersInterface {
    public String name();
    public String type();
    public String key();
    public <T extends UsageParametersInterface> T getOrCreateChild(String name)
        throws NullPointerException, IllegalArgumentException, SLEEException;
    public <T extends UsageParametersInterface> T getOrCreateChild(String name, String type)
        throws NullPointerException, IllegalArgumentException,
               UnrecognizedUsageParameterSetTypeException, SLEEException;
    public boolean hasChild(String name)
        throws NullPointerException, SLEEException;
    public Collection<? extends UsageParametersInterface> children()
        throws SLEEException;
    public <T extends UsageParametersInterface> T parent()
        throws SLEEException;
    public void remove()
        throws SLEEException;
}

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.

UsageParametersInterface interface name method

The name method returns the name of the usage parameter set that the UsageParametersInterface object is providing usage access to. This name is the name that the usage parameter set was created with. The root usage parameter set has no name; therefore this method will return null if invoked on the root usage parameter set.

UsageParametersInterface interface type method

The type method returns the type name of the usage parameter set that the UsageParametersInterface object is providing usage access to. If the usage parameter set was created with no type, this method returns null.

UsageParametersInterface interface key method

The key method returns a unique identifier that identifies the usage parameter set that the UsageParametersInterface object is providing usage access to. The key differs from the parameter set name in that the key is an absolute identifier that takes into account the usage parameter set’s place in the usage parameter set hierarchy, and is able to identify the usage parameter set without any other context; whereas the usage parameter set name is relative to the usage parameter set’s parent usage parameter set only.

UsageParametersInterface interface getOrCreateChild methods

The getOrCreateChild methods return the child usage parameter set with the name specified by the name argument. If the usage parameter set already exists, then the existing usage parameter set is returned; otherwise a new usage parameter set is created. If a new usage parameter set is created, and the type argument is specified, then the child usage parameter set is created with the specified type; otherwise it is created with the same type as the usage parameter set the method is invoked on.

These methods throw a NullPointerException if the name argument is null. The methods throw an IllegalArgumentException if the name argument is zero-length. If the type argument is specified and not null, but is not recognised as a defined usage parameters interface type, the method throws an UnrecognizedUsageParameterSetTypeException.

UsageParametersInterface interface hasChild method

The hasChild method returns a Boolean value indicating if a child usage parameter set with a name equal to the name argument currently exists.

This method throws a NullPointerException if the name argument is null.

UsageParametersInterface interface children method

The children method returns a collection containing all the child usage parameter sets of the usage parameter set that the UsageParametersInterface object is providing usage access to.

UsageParametersInterface interface parent method

The parent method returns the usage parameter set that is the parent of the usage parameter set that the UsageParametersInterface object is providing usage access to. If the UsageParametersInterface object represents the root usage parameter set, then this method returns null.

UsageParametersInterface interface remove method

The remove method removes the usage parameter set that the UsageParametersInterface object is providing usage access to. All child usage parameter sets are also removed, recursively.

The root usage parameter set cannot be removed; however, this method may be invoked on a root usage parameter set, in which case the following behaviour is observed:

  • All child usage parameter sets are removed as usual.

  • All usage parameters in the root usage parameter set are reset to their initial value, as if the root usage parameter set had been removed and recreated in a single atomic action.

Annotations

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.

@UsageParameters annotation

A usage parameters interface may be annotated with the @UsageParameters annotation. The @UsageParameters annotation is shown below:

package com.opencloud.rhino.facilities.usage;

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
public @interface UsageParameters {
    String description() default "";
    String oid() default "";
}
Note

  • The description parameter provides a general description for the usage parameters interface.

  • The oid parameter defines the base SNMP Object Identifier (OID) to use for all the usage parameter sets created from the usage parameters interface. The base OID must be specified using dotted string notation, such as 1.3.6.1.4.1.19808.2.1.1001. If a base OID is not specified, or is specified as a zero-length string, then a base OID is dynamically generated for the usage parameters interface. See SNMP statistics for OID detailed explanation.
Warning When installing a SLEE component that has default oid parameter specified, please make sure the base oid mapping is not in-use. Otherwise a duplicate oid mapping alarm will be raised. If the mapping is in-use, rhino console commands setsnmpoidmapping or removesnmpmappingconfig can be used to clear/remove it.

@UsageCounter annotation

A counter-type usage parameter increment or set method may be annotated with the @UsageCounter annotation. The @UsageCounter annotation is shown below:

package com.opencloud.rhino.facilities.usage;

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Documented
public @interface UsageCounter {
    String description() default "";
    CounterType counterType();
    boolean aggregate() default true;
    String shortName() default "";
    String unitLabel() default "";
    int mapping() default -1;
}
Note

  • The description parameter provides a general description for the usage parameter.

  • The counterType parameter identifies the specific type of counter that the usage parameter represents. A counter-type usage parameter may be one of the following subtypes:

    • counter — an unbounded counter that typically only either increments or decrements.

    • gauge — a counter that typically has a lower and/or upper bound with a value that may oscillate within the bounds.

  • The aggregate parameter indicates whether or not updates to the usage parameter may aggregate to the parent usage parameter set.

  • The shortName parameter defines a short, possibly abbreviated version of the usage parameter name.

  • The unitLabel parameter specifies a label for the counter’s unit type.

  • The mapping parameter specifies a numeric SNMP ID for the usage parameter. This ID is appended to the usage parameter interface’s base SNMP OID to form the OID of the usage parameter. Defining a static ID for each usage parameter can eliminate renumbering issues if the usage parameters interface is later expanded with new usage parameters.

If both an increment method and a set method are defined for a single counter-type usage parameter, and both methods are annotated with @UsageCounter, then Rhino will arbitrarily choose one of the annotations to use for the usage parameter, and ignore the other annotation. In this case it is recommended only one of the methods be annotated.

@UsageSample annotation

A sample-type usage parameter sample method may be annotated with the @UsageSample annotation. The @UsageSample annotation is shown below:

package com.opencloud.rhino.facilities.usage;

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Documented
public @interface UsageSample {
    String description() default "";
    SampleUnits sourceUnits();
    SampleUnits displayUnits();
    boolean aggregate() default true;
    String shortName() default "";
    String unitLabel() default "";
}
Note

  • The description parameter provides a general description for the usage parameter.

  • The sourceUnits parameter identifies the units that the sample values are recorded with. Units must be one of: time in seconds, time in milliseconds, time in nanoseconds, or a dimensionless count.

  • The displayUnits parameter identifies the units with which the sample statistics should be displayed.

    • This parameter has no effect on how sample values are reported when using a JMX Usage MBean interface to inspect usage parameters. The parameter is only meaningful to statistics clients using Rhino’s proprietary statistics API.

  • The aggregate parameter indicates whether or not updates to the usage parameter may aggregate to the parent usage parameter set.

  • The shortName parameter defines a short, possibly abbreviated, version of the usage parameter name.

  • The unitLabel parameter specifies a label for the sample’s unit type.

SBB usage parameters interface deployment descriptor

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:

Sub-element What it does 
description

This is an optional informational element.

 
sbb-usage-parameters-interface

Each usage parameters interface type defined by the SBB must be identified by a sbb-usage-parameters-interface element.

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

Sub-element or attribute What it does 
root

This attribute indicates if this usage parameters interface should be used as the root usage parameter set type. At most one usage parameters interface may be declared as the root usage parameter set type.

 
description

This is an optional informational element.

 
sbb-usage-parameters-interface-type

This element specifies the usage parameters interface type name. This type name identifies the usage parameters interface when creating new child usage parameter sets. Each usage parameters interface declared in the deployment descriptor must have a unique type name.

 
sbb-usage-parameters-interface-name

This element identifies the interface name of the usage parameters interface.

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

Attribute What it does 
extends

This attribute indicates if the usage parameters interface type extends another usage parameters interface type. The extends attribute contains the type name of the usage parameters interface that this usage parameters interface type extends.

Resource adaptor usage parameters interface deployment descriptor

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:

Sub-element What it does 
description

This is an optional informational element.

 
resource-adaptor-usage-parameters-interface

Each usage parameters interface type defined by the resource adaptor must be identified by a resource-adaptor-usage-parameters-interface element.

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

Sub-element or attribute What it does 
root

This attribute indicates if this usage parameters interface should be used as the root usage parameter set type. At most one usage parameters interface may be declared as the root usage parameter set type.

 
description

This is an optional informational element.

 
resource-adaptor-usage-parameters-interface-type

This element specifies the usage parameters interface type name. This type name identifies the usage parameters interface when creating new child usage parameter sets. Each usage parameters interface declared in the deployment descriptor must have a unique type name.

 
resource-adaptor-usage-parameters-interface-name

This element identifies the interface name of the usage parameters interface.

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

Attribute What it does 
extends

This attribute indicates if the usage parameters interface type extends another usage parameters interface type. The extends attribute contains the type name of the usage parameters interface that this usage parameters interface type extends.

Usage facility

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.

UsageFacility interface

The com.opencloud.rhino.facilities.usage.UsageFacility interface is shown below:

package com.opencloud.rhino.facilities.usage;

import java.util.Collection;
import javax.slee.facilities.FacilityException;

public interface UsageFacility {
    public static final String JNDI_NAME = "java:comp/env/slee/facilities/usage";
    public static final String CONFIG_PROPERTY_NAME = "slee-vendor:com.opencloud.rhino.facilities.usage";

    public <T extends UsageParametersInterface> T getRootUsageParameterSet();

    public <T extends UsageParametersInterface> T getUsageParameterSet(String key)
        throws NullPointerException, UnrecognizedUsageParameterSetException, FacilityException;

    public <T extends UsageParametersInterface> T getOrCreateChild(UsageParametersInterface parent, String name)
        throws NullPointerException, IllegalArgumentException,
               UnrecognizedUsageParameterSetException, FacilityException;

    public <T extends UsageParametersInterface> T getOrCreateChild(UsageParametersInterface parent, String name, String type)
        throws NullPointerException, IllegalArgumentException, UnrecognizedUsageParameterSetException,
               UnrecognizedUsageParameterSetTypeException, FacilityException;

    public boolean hasChild(UsageParametersInterface parent, String name)
        throws NullPointerException, UnrecognizedUsageParameterSetException, FacilityException;

    public Collection<? extends UsageParametersInterface> getChildren(UsageParametersInterface parent)
        throws NullPointerException, FacilityException;

    public void removeUsageParameterSet(UsageParametersInterface paramSet)
        throws NullPointerException, UnrecognizedUsageParameterSetException, FacilityException;
}
Note

  • The JNDI_NAME constant specifies the JNDI location where a UsageFacility object may be located by an SBB component in its component environment.

  • The CONFIG_PROPERTY_NAME constant specifies the configuration property name where a UsageFacility object may be located by a resource adaptor component in the ConfigProperties object passed to it in the raVerifyConfiguration, raConfigure, and raConfigurationUpdate methods.

  • All methods of the UsageFacility interface are non-transactional methods.

  • The SLEE provides a concrete class implementing the UsageFacility interface.

  • The methods of this interface throw the javax.slee.facilities.FacilityException if the requested operation cannot be completed because of a system-level failure.

UsageFacility interface getRootUsageParameterSet method

The getRootUsageParameterSet method returns the root usage parameter set for the SLEE component. If the SLEE component declares a root usage parameter set type, then the object returned from this method will be castable to the corresponding usage parameters interface for that type.

UsageFacility interface getUsageParameterSet method

The getUsageParameterSet method returns the usage parameter set with the key specified by the key argument. A usage parameter set’s identifying key can be obtained using the key method of the UsageParametersInterface interface.

The usage parameter set object returned from this method will be castable to the usage parameters interface corresponding with its type, as returned by the type method of the UsageParametersInterface interface.

This method throws a NullPointerException if the key argument is null. The method throws an UnrecognizedUsageParameterSetException if no usage parameter set currently exists with the specified key.

UsageFacility interface getOrCreateChild methods

The getOrCreateChild methods return the child usage parameter set of the usage parameter set specified by the parent argument with the name specified by the name argument. If the usage parameter set already exists, then the existing usage parameter set is returned; otherwise a new usage parameter set is created. If a new usage parameter set is created, and the type argument is specified, then the child usage parameter set is created with the specified type; otherwise it is created with the same type as the usage parameter set the method is invoked on.

These methods throw a NullPointerException if the name argument is null. The methods throw an UnrecognizedUsageParameterSetException if the parent argument is not recognised by this usage facility object, for example if the usage parameter set was created by some other usage facility object. The methods throw an IllegalArgumentException if the name argument is zero-length. If the type argument is specified and not null, but is not recognised as a defined usage parameters interface type, the method throws an UnrecognizedUsageParameterSetTypeException.

UsageFacility interface hasChild method

The hasChild method returns a boolean value indicating if the usage parameter set identified by the parent argument contains a child usage parameter set with a name equal to the name argument.

This method throws a NullPointerException if the name argument is null. This method throws an UnrecognizedUsageParameterSetException if the parent argument is not recognised by this usage facility object, for example if the usage parameter set was created by some other usage facility object.

UsageFacility interface getChildren method

The getChildren method returns a collection containing all the child usage parameter sets of the usage parameter set identified by the parent argument.

This method throws a NullPointerException if the parent argument is null.

UsageFacility interface removeUsageParameterSet method

The getRootUsageParameterSet method removes the usage parameter set identified by the paramSet argument. All child usage parameter sets are also removed, recursively.

This method throws a NullPointerException if the paramSet argument is null. This method throws an UnrecognizedUsageParameterSetException if the paramSet argument is not recognised by this usage facility object, for example if the usage parameter set was created by some other usage facility object.

Profile facility extensions

Rhino extends the standard javax.slee.facilities.ProfileFacility interface with the com.opencloud.rhino.facilities.profile.ProfileFacility interface, which adds additional functionality over what the JAIN SLEE specification provides.

ProfileFacility interface

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

package com.opencloud.rhino.facilities.profile;

import javax.slee.facilities.FacilityException;
import javax.slee.profile.UnrecognizedProfileTableNameException;

public interface ProfileFacility extends javax.slee.profile.ProfileFacility {
    public boolean profileTableExists(String profileTableName)
        throws NullPointerException, FacilityException;

    public ProfileTableDescriptor getProfileTableDescriptor(String profileTableName)
        throws NullPointerException, UnrecognizedProfileTableNameException, FacilityException;

    public Class<?> getProfileLocalInterface(String profileTableName)
        throws NullPointerException, UnrecognizedProfileTableNameException, FacilityException;
}

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.

ProfileFacility interface profileTableExists method

The profileTableExists method returns a boolean value that reports whether or not a profile table with the name specified by the profileTableName argument currently exists in the SLEE.

This method throws a NullPointerException if the profileTableName argument is null.

ProfileFacility interface getProfileTableDescriptor method

The getProfileTableDescriptor method returns a metadata object that provides information about the profile table with the name specified by the profileTableName argument. The ProfileTableDescriptor interface is described below.

This method throws a NullPointerException if the profileTableName argument is null. The method throws an UnrecognizedProfileTableNameException if no profile table exists with the name specified by the profileTableName argument.

ProfileFacility interface ProfileTableDescriptor interface

The ProfileTableDescriptor interface provides metadata information about a profile table. This information might be useful, for example, to determine if a profile table contains profiles of an expected type before querying the profile table or retrieving profiles from it.

The ProfileTableDescriptor interface is shown below:

package com.opencloud.rhino.facilities.profile;

import javax.slee.profile.ProfileSpecificationID;
import javax.slee.profile.ProfileTable;

public interface ProfileTableDescriptor {
    public ProfileSpecificationID getProfileSpecification();

    public Class<? extends ProfileTable> getProfileTableInterface();

    public Class<?> getProfileLocalInterface();
}

All methods in the ProfileTableDescriptor interface are non-transactional methods.

ProfileFacility interface getProfileSpecification method

The getProfileSpecification method returns the component identifier of the profile specification of the profile table the metadata object describes.

ProfileFacility interface getProfileTableInterface method

The getProfileTableInterface method returns the Class object of the profile table interface declared by the profile specification of the profile table the metadata object describes. If the profile specification does not declare a profile table interface, then this method returns the Class object for the default SLEE-defined javax.slee.profile.ProfileTable interface instead.

ProfileFacility interface getProfileLocalInterface method

The getProfileLocalInterface method returns the Class object of the profile local interface declared by the profile specification of the profile table the metadata object describes. If the profile specification does not declare a profile local interface, then this method returns the Class object of the profile CMP interface instead.

Tracer extensions

Rhino extends the standard javax.slee.Tracer interface with the com.opencloud.rhino.facilities.Tracer interface, which adds additional functionality over what the JAIN SLEE specification provides.

Tracer interface

The com.opencloud.rhino.facilities.Tracer interface is shown below:

package com.opencloud.rhino.facilities;

import javax.slee.facilities.FacilityException;

public interface Tracer extends javax.slee.facilities.Tracer {
    public Tracer getParentTracer();

    public Tracer getChildTracer(String name)
        throws NullPointerException, IllegalArgumentException, FacilityException;
}

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

The extended 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.

Tracer interface getParentTracer method

The getParentTracer method returns a Tracer object for the tracer’s parent tracer. The parent tracer is the tracer with the name returned by the getParentTracerName method defined in the standard Tracer interface.

If this method is invoked on a Tracer object for a root tracer, then null is returned.

Tracer interface getChildTracer method

The getChildTracer method returns a Tracer object for a tracer that is a descendant (in terms of a parent-child relationship) of the invoked tracer. The name argument specifies the name of the child tracer.

Formally:

  • if the invoked tracer is a root tracer, then this method returns a tracer with the name specified by the name argument

  • otherwise, this method returns a tracer with the name: invokedTracer.getName() + . + name.

The name argument must be a valid tracer name. Since any valid name can be specified, this method can be used to create any descendant tracer — child, grandchild, and so on.

This method throws a NullPointerException if the name argument is null. It throws an IllegalArgumentException if the name argument would result in an invalid tracer name. It throws a javax.slee.facilities.FacilityException if the child tracer cannot be returned because of a system-level failure.

Lock Facility

The lock facility allows resource adaptors to obtain transaction-based distributed locks.

In order to use the lock facility, one must obtain:

  • a reference to the LockFacility itself; and

  • a reference to the SLEE Transaction Manager, as all locks must be obtained from within a transaction.

The following code fragment illustrates how you can obtain these references in a resource adaptor:

package ...

import javax.slee.resource.ConfigProperties;
import javax.slee.resource.ResourceAdaptor;
import javax.slee.resource.ResourceAdaptorContext;
import javax.slee.transaction.SleeTransactionManager;
import com.opencloud.rhino.facilities.lock.LockFacility;

public class FooResourceAdaptor implements ResourceAdaptor {
    @Override
    public void setResourceAdaptorContext(ResourceAdaptorContext context) {
        // save context ref
        this.context = context;

        // ...
    }

    @Override
    public void raConfigure(ConfigProperties configProps) {
        // get refs to transaction manager and lock facility
        txManager = context.getSleeTransactionManager();
        lockFacility = (LockFacility)configProps.getProperty(LockFacility.CONFIG_PROPERTY_NAME).getValue();

        // ...
    }

    // ...

    private ResourceAdaptorContext context;
    private SleeTransactionManager txManager;
    private LockFacility lockFacility;
}

With these references, one can then proceed to acquire locks as necessary. For example:

private void doSomeWorkThatRequiresALock() {
    // start a transaction
    SleeTransaction tx = txManager.beginSleeTransaction();
    try {
        // acquire exclusive lock
        lockFacility.acquireExclusive("SomeLock");

        // do the work
        // ...

        // successfully completed work - commit transaction
        // automatically causes the lock to be released
        tx = null;
        txManager.commit();
    }
    catch (Exception e) {
        if (tx != null) {
            // failed to complete work - rollback transaction
            // automatically causes the lock to be released
            tx.rollback();
        }
    }
}

JNDI environment metadata

The JAIN SLEE specification defines that an SBB component has access to a JNDI API namespace where it may obtain access to various SLEE facilities and factories. Using the JNDI API for name lookups in SBB code generally works when you know exactly what you’re looking for, but an SBB that uses SBB parts may have entries in its JNDI namespace introduced by those SBB parts that may not be known at SBB compile time but are still of interest to the SBB. The JNDI API does not differentiate one binding from another; so it’s not easy for an SBB, for example, to find all resource adaptor entity bindings.

As an extension, Rhino provides all JNDI environment bindings to an SBB or SBB part in a separate map structure. The map is keyed on the fully qualified binding name, with map values containing metadata about the type of binding as well as the bound object itself.

An SBB obtains access to the JNDI bindings map from its RhinoSbbContext object (a Rhino extension of SbbContext):

package com.opencloud.rhino.slee;

import java.util.Map;
import javax.slee.SLEEException;
import javax.slee.SbbContext;
import com.opencloud.rhino.slee.environment.JndiBinding;

public interface RhinoSbbContext extends SbbContext {
    public Map<String,JndiBinding> getJndiBindings()
        throws SLEEException;

    ...
}

An SBB part obtains access to the JNDI bindings map from its SbbPartContext object:

package com.opencloud.rhino.slee.sbbpart;

import java.util.Map;
import javax.slee.SLEEException;
import javax.slee.SbbContext;
import com.opencloud.rhino.slee.environment.JndiBinding;

public interface SbbPartContext extends SbbContext {
    public Map<String,JndiBinding> getJndiBindings()
        throws SLEEException;

    ...
}

JndiBinding class

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

package com.opencloud.rhino.slee.environment;

public abstract class JndiBinding {
    public abstract BindingType getType();
    public String getJndiName() { ... }
    public Object getValue() { ... }

    public boolean equals(Object o) { ... }
    public int hashCode() { ... }
}

JndiBinding class getType method

The getType method returns the type of the JNDI binding. The BindingType enumeration is shown below:

package com.opencloud.rhino.slee.environment;

public enum BindingType {
    ENV_ENTRY,
    ACTIVITY_CONTEXT_INTERFACE_FACTORY,
    RESOURCE_ADAPTOR_ENTITY,
    FACILITY,
    LIMITER_ENDPOINT
}

A JNDI binding may be one of:

  • an environment entry

  • an activity context interface factory, such as the null activity context interface factory

  • a resource adaptor entity link binding

  • a SLEE facility, such as the timer facility and alarm facility

    Note Activity factories, such as the null activity factory and service activity factory are considered to be SLEE facilities for this purpose.

  • a configured Rhino limiter endpoint.

JndiBindingclass getJndiName method

The getJndiName method returns the fully qualified name of the JNDI binding. This value is equal to the key that the JndiBinding object is stored with in the map of bindings.

JndiBindingclass getValue method

The getValue method returns the object bound to the JNDI name. For example, this could be an environment entry value, a SLEE facility, and so on.

Subclasses of JndiBinding

The JndiBinding class is an abstract class. A subclass of JndiBinding exists for each different type of binding. Each of these is described below.

EnvEntry class

The EnvEntry class is used to describe a JNDI binding for an environment entry. The EnvEntry class is shown below:

package com.opencloud.rhino.slee.environment;

public final class EnvEntry extends JndiBinding {
    public EnvEntry(String jndiName, Object value) { ... }
    public BindingType getType() { return BindingType.ENV_ENTRY; }
    public String toString() { ... }
}

Facility class

The Facility class is used to describe a JNDI binding for a SLEE facility such as the timer facility as well as activity factories such as the null activity factory. The Facility class is shown below:

package com.opencloud.rhino.slee.environment;

public final class Facility extends JndiBinding {
    public Facility(String jndiName, Object value) { ... }
    public BindingType getType() { return BindingType.FACILITY; }
    public String toString() { ... }
}

LimiterEndpoint class

The LimiterEndpoint class is used to describe a JNDI binding for a configured limiter endpoint. The LimiterEndpoint class is shown below:

package com.opencloud.rhino.slee.environment;

public final class LimiterEndpoint extends JndiBinding {
    public LimiterEndpoint(String jndiName, Object value) { ... }
    public BindingType getType() { return BindingType.LIMITER_ENDPOINT; }
    public String toString() { ... }
}

ResourceAdaptorTypeBinding class

The ResourceAdaptorTypeBinding class is the superclass for JNDI binding metadata classes related to resource adaptor types. The ResourceAdaptorTypeBinding class is shown below:

package com.opencloud.rhino.slee.environment;

import javax.slee.resource.ResourceAdaptorTypeID;

public abstract class ResourceAdaptorTypeBinding extends JndiBinding {
    public ResourceAdaptorTypeID getResourceAdaptorType() { ... }
    public int hashCode() { ... }
}

The getResourceAdaptorType method returns the component identifier of the resource adaptor type that the binding is associated with.

ActivityContextInterfaceFactoryBinding class

The ActivityContextInterfaceFactoryBinding class is used to describe a JNDI binding for an activity context interface factory. The ActivityContextInterfaceFactoryBinding class is shown below:

package com.opencloud.rhino.slee.environment;

import javax.slee.resource.ResourceAdaptorTypeID;

public final class ActivityContextInterfaceFactoryBinding extends ResourceAdaptorTypeBinding {
    public ActivityContextInterfaceFactoryBinding(String jndiName, ResourceAdaptorTypeID raType, Object value) { ... }
    public BindingType getType() { return BindingType.ACTIVITY_CONTEXT_INTERFACE_FACTORY; }
    public String toString() { ... }
}

ResourceAdaptorEntityBinding class

The ResourceAdaptorEntityBinding class is used to describe a JNDI binding for a resource adaptor entity. The ResourceAdaptorEntityBinding class is shown below:

package com.opencloud.rhino.slee.environment;

import javax.slee.resource.ResourceAdaptorTypeID;

public final class ResourceAdaptorEntityBinding extends ResourceAdaptorTypeBinding {
    public ResourceAdaptorEntityBinding(String jndiName, ResourceAdaptorTypeID raType, Object value) { ... }
    public BindingType getType() { return BindingType.RESOURCE_ADAPTOR_ENTITY; }
    public String toString() { ... }
}
Previous page