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
.
Modifier and Type | Field and 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. |
Modifier and Type | Method and Description |
---|---|
Collection<? extends UsageParametersInterface> |
getChildren(UsageParametersInterface parent)
Get all child usage parameter sets of the specified usage parameter set.
|
<T extends UsageParametersInterface> |
getOrCreateChild(UsageParametersInterface parent,
String name)
Create a new child usage parameter set of the given parent usage parameter set.
|
<T extends UsageParametersInterface> |
getOrCreateChild(UsageParametersInterface parent,
String name,
String type)
Create a new child usage parameter set of the given parent usage parameter set.
|
<T extends UsageParametersInterface> |
getRootUsageParameterSet()
Get the root usage parameter set.
|
<T extends UsageParametersInterface> |
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.
|
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".
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".
<T extends UsageParametersInterface> T getRootUsageParameterSet()
Get the root usage parameter set.
<T extends UsageParametersInterface> 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.
key
- the key.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.<T extends UsageParametersInterface> 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.
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.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.<T extends UsageParametersInterface> 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.
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.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.boolean hasChild(UsageParametersInterface parent, String name) throws NullPointerException, UnrecognizedUsageParameterSetException, FacilityException
Determine if a child usage parameter set with the given name currently exists.
parent
- the parent usage parameter set.name
- the name of the child usage parameter set.true
if a child usage parameter set with the given name currently exists, false
otherwise.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.Collection<? extends UsageParametersInterface> getChildren(UsageParametersInterface parent) throws NullPointerException, FacilityException
Get all child usage parameter sets of the specified usage parameter set.
parent
- the parent usage parameter set.NullPointerException
- if parent
is null
.FacilityException
- if a system-level failure occurs.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.
paramSet
- the usage parameter set to remove.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.