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.

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.

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.

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.

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.

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.

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.

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.

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 {
    public enum Singleton {
        TRUE,
        FALSE,
        UNSPECIFIED
    }

    String description() default "";
    String oid() default "";
    String oidSuffix() default "";
    Singleton singleton() default Singleton.UNSPECIFIED;
    UsageParameterSetNameOIDMapping[] usageParameterSetNameOIDMappings() default {};
}
Note

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

The following parameters relate to the static OID model only:

  • The oidSuffix parameter defines the SNMP Object Identifier (OID) suffix to use for all the usage parameter sets created from the usage parameters interface. The OID suffix must be either a single positive number or a series of number specified using dotted string notation, eg. 5 or 2.1. This suffix must be unique across all usage parameter interfaces (and resource adaptor stats parameter set types if relevant) within any component that uses the usage parameters interface.

  • The singleton parameter specifies the singleton status of the usage parameters interface. A singleton may only have at most one usage parameter set created from it. The UNSPECIFIED value allows the single status to be specified in the deployment descriptor instead.

  • The usageParameterSetNameOIDMappings allows usage parameter set name to OID suffix mappings to be defined for the usage parameters interface.

The following parameter relates to the legacy OID model only:

  • The oid parameter defines the base 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 is not already 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.

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.

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.

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.

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.

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.

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.

Previous page Next page