com.opencloud.rhino.facilities.usage

Interface UsageParametersInterface

public interface UsageParametersInterface

Base interface for a usage parameters interface. A usage parameters interface must be public and defined in a named package, and may extend this interface to obtain common functionality. While it is generally recommended that a usage parameters interface extend this interface, there may be legitimate reasons why this might not be desirable, for example the application doesn’t want to expose these API methods to third-party code plugins that just need to define their own usage parameters.

A usage parameters interface may be annotated with the @UsageParameters annotation in order to provide additional information to the SLEE about the usage parameter set.

The usage parameters interface defines usage parameters as follows:

Counter-type usage parameters

Counter-type usage parameters are defined using either or both an increment method:

public void increment<usage-parameter-name>(long value);

or set method:

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

Usage counter methods may be annotated with the @UsageCounter annotation in order to provide additional information to the SLEE about the parameter. In the case where both an increment and set method has been defined for a given parameter, only one of the methods need be annotated. If both methods are annotated the annotation used is chosen arbitrarily.

An accessor method may also be defined for a counter-type usage parameter with the signature:

public long get<usage-parameter-name>(long value);

Sample-type usage parameters

Sample-type usage parameters are defined using a sample method:

public void sample<usage-parameter-name>(long value);

An accessor method may also be defined for a sample-type usage parameter with the signature:

public SampleStatistics get<usage-parameter-name>();

SampleStatistics is a JSLEE-defined class.

In the above method declarations, usage-parameter-name is the name of the usage parameter, where the first letter has been uppercased. Usage methods must not have a throws clause. Usage methods, and all methods defined in this interface, run in an unspecified transaction context. Updates to usage parameters occur regardless of the outcome of any transaction active at the time of the update.

Since:

Rhino 2.4.0

Method Summary

Modifier and Type	Method and Description
Collection<? extends UsageParametersInterface>	children() Get all child usage parameter sets of this usage parameter set.
<T extends UsageParametersInterface> T	getOrCreateChild(String name) Get the child usage parameter set with the given name.
<T extends UsageParametersInterface> T	getOrCreateChild(String name, String type) Get the child usage parameter set with the given name.
boolean	hasChild(String name) Determine if a child usage parameter set with the given name currently exists.
String	key() Get the key that identifies this usage parameter set.
String	name() Get the name of this parameter set.
<T extends UsageParametersInterface> T	parent() Get the parent usage parameter set of this usage parameter set.
void	remove() Remove this usage parameter set.
String	type() Get the type of this usage parameter set.

Method Detail

name

String name()

Get the name of this parameter set. This is the name that the parameter set was created with. The root usage parameter set has no name, so this method will return null for that usage parameter set.

This method is a non-transactional method.

Returns:

the name of the usage parameter set, or null if this is the root usage parameter set.

Since:

Rhino 2.4.0

type

String type()

Get the type of this usage parameter set.

This method is a non-transactional method.

Returns:

the type of the usage parameter set, or null if this usage parameter set has no type.

Since:

Rhino 2.4.0

key

String key()

Get the key that identifies this usage parameter set. This key can be used to recover the same usage parameter set at a later time using the Usage Facility.

The key for the root usage parameter set is the empty string.

This method is a non-transactional method.

Returns:

the key for this usage parameter set.

Since:

Rhino 2.4.0

getOrCreateChild

<T extends UsageParametersInterface> T getOrCreateChild(String name)
                                                 throws NullPointerException,
                                                        IllegalArgumentException,
                                                        SLEEException

Get the child usage parameter set with the given name. If the child doesn’t currently exist it will be created with the same type as this usage parameter set.

This method is a non-transactional method.

Parameters:

name - the name of the child usage parameter set.

Returns:

the child usage parameter set.

Throws:

NullPointerException - if name is null.

IllegalArgumentException - if name is zero-length.

SLEEException - if a system-level failure occurs.

Since:

Rhino 2.4.0

getOrCreateChild

<T extends UsageParametersInterface> T getOrCreateChild(String name,
                                                        String type)
                                                 throws NullPointerException,
                                                        IllegalArgumentException,
                                                        UnrecognizedUsageParameterSetTypeException,
                                                        SLEEException

Get the child usage parameter set with the given name. If the child doesn’t currently exist it will be created with the given type.

This method is a non-transactional method.

Parameters:

name - the name of the child usage parameter set.

type - the type of the usage parameter set, if it is created. May be null to create a usage parameter set with no type.

Returns:

the child usage parameter set.

Throws:

NullPointerException - if name is null.

IllegalArgumentException - if name is zero-length.

UnrecognizedUsageParameterSetTypeException - if type is not null and is not recognized as a declared usage parameter set type.

SLEEException - if a system-level failure occurs.

Since:

Rhino 2.4.0

hasChild

boolean hasChild(String name)
          throws NullPointerException,
                 SLEEException

Determine if a child usage parameter set with the given name currently exists.

This method is a non-transactional method.

Parameters:

name - the name of the child usage parameter set.

Returns:

true if a child usage parameter set with the given name currently exists, false otherwise.

Throws:

NullPointerException - if name is null.

SLEEException - if a system-level failure occurs.

Since:

Rhino 2.4.0

children

Collection<? extends UsageParametersInterface> children()
                                                 throws SLEEException

Get all child usage parameter sets of this usage parameter set.

This method is a non-transactional method.

Returns:

a collection of all child usage parameter sets.

Throws:

SLEEException - if a system-level failure occurs.

Since:

Rhino 2.4.0

parent

<T extends UsageParametersInterface> T parent()
                                       throws SLEEException

Get the parent usage parameter set of this usage parameter set.

This method is a non-transactional method.

Returns:

the parent usage parameter set, or null if this is the root usage parameter set.

Throws:

SLEEException - if a system-level failure occurs.

Since:

Rhino 2.4.0

remove

void remove()
     throws SLEEException

Remove this usage parameter set. All child usage parameter sets are also removed.

While it is not possible to remove the root usage parameter set, this method may be invoked on the root usage parameter set in order to easily remove all its child usage parameter sets. Invoking this method on the root usage parameter set will also reset all usage statistics as if the parameter set had been removed and immediately recreated.

This method is a non-transactional method.

Throws:

SLEEException - if a system-level failure occurs.

Since:

Rhino 2.4.0