Package com.opencloud.rhino.facilities.usage

Interface UsageFacility

public interface UsageFacility

The Usage Facility is used by SBBs and resource adaptors to gain access to the their usage parameter sets. Using this facility, usage parameter interface accessor methods are no longer needed or used, instead components may use the facility to create and remove child usage parameter sets of any declared type as needed.

Many methods in this interface return a generic subclass of UsageParametersInterface. If the expected usage parameters interface does not extend UsageParametersInterface then a typecast to the target interface will be necessary. Note that a usage parameter set object will still implement UsageParametersInterface even if the corresponding usage parameters interface does not, so a typecast back to UsageParametersInterface will always be possible.

All methods in this interface are non-transactional methods. The effects of operations invoked on the Usage Facility occur regardless of the state or outcome of any enclosing transaction.

SBB JNDI Location:

java:comp/env/slee/facilities/usage

An instance of the Usage Facility is only bound into an SBB’s JNDI environment if the SBB declares at least one usage parameters interface using the extensions provided in oc-sbb-jar.xml.

Resource Adaptor Config Property:

slee-vendor:com.opencloud.rhino.facilities.usage

An instance of the Usage Facility is only included in a resource adaptor entity’s config properties if the resource adaptor declares at least one usage parameters interface using the extensions provided in oc-resource-adaptor-jar.xml.

Since:

Rhino 2.4.0

Field Summary

Fields

Modifier and Type	Field	Description
static String	CONFIG_PROPERTY_NAME	Constant declaring the resource adaptor config property name where a UsageFacility object can be obtained by a resource adaptor.
static String	JNDI_NAME	Constant declaring the JNDI name where a UsageFacility object is bound into an SBB object’s JNDI environment.

Method Summary

Modifier and Type	Method	Description
Collection<? extends UsageParametersInterface>	getChildren(UsageParametersInterface parent)	Get all child usage parameter sets of the specified usage parameter set.
<T> T	getOrCreateChild(UsageParametersInterface parent, String name)	Create a new child usage parameter set of the given parent usage parameter set.
<T> T	getOrCreateChild(UsageParametersInterface parent, String name, String type)	Create a new child usage parameter set of the given parent usage parameter set.
<T> T	getRootUsageParameterSet()	Get the root usage parameter set.
<T> T	getUsageParameterSet(String key)	Get a usage parameter set by its identifying key.
boolean	hasChild(UsageParametersInterface parent, String name)	Determine if a child usage parameter set with the given name currently exists.
void	removeUsageParameterSet(UsageParametersInterface paramSet)	Remove the specified usage parameter set.

Field Detail

JNDI_NAME

static final String JNDI_NAME

Constant declaring the JNDI name where a UsageFacility object is bound into an SBB object’s JNDI environment.

The value of this constant is "java:comp/env/slee/facilities/usage".

Since:

Rhino 2.4.0

See Also:

Constant Field Values

CONFIG_PROPERTY_NAME

static final String CONFIG_PROPERTY_NAME

Constant declaring the resource adaptor config property name where a UsageFacility object can be obtained by a resource adaptor.

The value of this constant is "slee-vendor:com.opencloud.rhino.facilities.usage".

Since:

Rhino 2.4.0

See Also:

Constant Field Values

Method Detail

getRootUsageParameterSet

<T> T getRootUsageParameterSet()

Get the root usage parameter set.

Returns:

the root usage parameter set.

Since:

Rhino 2.4.0

getUsageParameterSet

<T> T getUsageParameterSet(String key)
                    throws NullPointerException,
                           UnrecognizedUsageParameterSetException,
                           FacilityException

Get a usage parameter set by its identifying key. A usage parameter set’s key can be obtained using UsageParametersInterface.key().

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

Parameters:

key - the key.

Returns:

the corresponding usage parameter set.

Throws:

NullPointerException - if key is null.

UnrecognizedUsageParameterSetException - if key is not recognized as a valid usage parameter set for this usage facility.

FacilityException - if a system-level failure occurs.

Since:

Rhino 2.4.0

getOrCreateChild

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

Create a new child usage parameter set of the given parent usage parameter set. The child with have the specified name and will be of the same type as the parent.

Parameters:

parent - the usage parameter set that will be the parent of the new usage parameter set.

name - the name of the new child usage parameter set.

Returns:

the new child usage parameter set.

Throws:

NullPointerException - if either argument is null.

IllegalArgumentException - if name is zero-length.

UnrecognizedUsageParameterSetException - if parent is not recognized as a valid usage parameter set for this usage facility.

FacilityException - if a system-level failure occurs.

Since:

Rhino 2.4.0

getOrCreateChild

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

Create a new child usage parameter set of the given parent usage parameter set. The child with have the specified name and specified type.

Parameters:

parent - the usage parameter set that will be the parent of the new usage parameter set.

name - the name of the new child usage parameter set.

type - the type of the new child usage parameter set.

Returns:

the new child usage parameter set.

Throws:

NullPointerException - if any argument is null.

IllegalArgumentException - if name is zero-length.

UnrecognizedUsageParameterSetException - if parent is not recognized as a valid usage parameter set for this usage facility.

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

FacilityException - if a system-level failure occurs.

Since:

Rhino 2.4.0

hasChild

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

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

Parameters:

parent - the parent usage parameter set.

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 either argument is null.

UnrecognizedUsageParameterSetException - if parent is not recognized as a valid usage parameter set for this usage facility.

FacilityException - if a system-level failure occurs.

Since:

Rhino 2.4.0

getChildren

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

Get all child usage parameter sets of the specified usage parameter set.

Parameters:

parent - the parent usage parameter set.

Returns:

a collection of all child usage parameter sets.

Throws:

NullPointerException - if parent is null.

FacilityException - if a system-level failure occurs.

Since:

Rhino 2.4.0

removeUsageParameterSet

void removeUsageParameterSet(UsageParametersInterface paramSet)
                      throws NullPointerException,
                             UnrecognizedUsageParameterSetException,
                             FacilityException

Remove the specified usage parameter set. If the usage parameter set has any child usage parameter sets they will be removed also.

While it is not possible to remove the root usage parameter set, a reference to the root parameter set may be passed to this method in order to easily remove all its child usage parameter sets.

Parameters:

paramSet - the usage parameter set to remove.

Throws:

NullPointerException - if paramSet is null.

UnrecognizedUsageParameterSetException - if paramSet is not recognized as a valid usage parameter set for this usage facility.

FacilityException - if a system-level failure occurs.

Since:

Rhino 2.4.0