javax.slee.management
Interface ServiceUsageMBean

public interface ServiceUsageMBean

The ServiceUsageMBean interface defines service usage-related management operations. Using a ServiceUsageMBean object a management client may get access to UsageMBean objects for SBBs, reset the usage parameters for an individual SBB used in the represented Service, reset usage parameters for all SBBs used in the represented Service, or modify the list of named usage parameter sets an SBB is allowed to use.

Each SBB maintains seperate sets of usage information for each Service that it participates in. A ServiceUsageMBean object provides management of usage information accumulated for a single Service for all the SBBs participating in that Service.

The base JMX Object Name of a ServiceUsageMBean object is specified by the BASE_OBJECT_NAME constant. The SERVICE_NAME_KEY, SERVICE_VENDOR_KEY, and SERVICE_VERSION_KEY constants define additional Object Name properties that uniquely identify a Service Usage MBean. The complete Object Name of a ServiceUsageMBean object can be obtained by a management client via the ServiceManagementMBean.getServiceUsageMBean(javax.slee.ServiceID) method.

Field Summary

static java.lang.String	BASE_OBJECT_NAME The base JMX Object Name string of all SLEE Service Usage MBeans.
static java.lang.String	SERVICE_NAME_KEY The JMX Object Name property key that identifies the name of the Service that the Service Usage MBean is providing service usage-related management operations for.
static java.lang.String	SERVICE_VENDOR_KEY The JMX Object Name property key that identifies the vender of the Service that the Service Usage MBean is providing service usage-related management operations for.
static java.lang.String	SERVICE_VERSION_KEY The JMX Object Name property key that identifies the version of the Service that the Service Usage MBean is providing service usage-related management operations for.

Method Summary

void	close() Notify the SLEE that this Service Usage MBean is no longer required by the management client.
void	createUsageParameterSet(SbbID id, java.lang.String paramSetName) Create a new usage parameter set that the specified SBB is permitted to use in the one-argument form of the get-usage-parameters methods, when the service component identifier argument of the get-usage-parameters method identifies the Service that this MBean provides usage management access for.
javax.management.ObjectName	getSbbUsageMBean(SbbID id) Get the JMX Object Name of a UsageMBean object that provides management access to the unnamed usage parameter set for the specified SBB.
javax.management.ObjectName	getSbbUsageMBean(SbbID id, java.lang.String paramSetName) Get the JMX Object Name of a UsageMBean object that provides management access to the named usage parameter set for the specified SBB.
javax.management.ObjectName	getSbbUsageNotificationManagerMBean(SbbID id) Get the JMX Object Name of a UsageNotificationManagerMBean that provides management access to the usage notification manager for the specified SBB.
ServiceID	getService() Get the component identifier of the Service that this MBean provides usage management access for.
java.lang.String[]	getUsageParameterSets(SbbID id) Get the names of the usage parameter sets that the specified SBB is permitted to use in the one-argument form of the get-usage-parameters methods, when the service component identifier argument of the get-usage-parameters method identifies the Service that this MBean provides usage management access for.
void	removeUsageParameterSet(SbbID id, java.lang.String paramSetName) Remove an existing usage parameter set that the specified SBB is permitted to use in the one-argument form of the get-usage-parameters methods, when the service component identifier argument of the get-usage-parameters method identifies the Service that this MBean provides usage management access for.
void	resetAllUsageParameters() Reset all usage parameters in the unamed usage parameter set, and all named usage parameter sets, of all SBB participating in the Service whose usage information is being managed by this MBean.
void	resetAllUsageParameters(SbbID id) Reset all usage parameters in the unamed usage parameter set, and all named usage parameter sets, of the specified SBB.

Field Detail

BASE_OBJECT_NAME

static final java.lang.String BASE_OBJECT_NAME

The base JMX Object Name string of all SLEE Service Usage MBeans. This string is equal to "javax.slee.management.usage:type=ServiceUsage" and the string BASE_OBJECT_NAME + ",*" defines a JMX Object Name property pattern which matches with all Service Usage MBeans that are registered with the MBean Server. A Service Usage MBean is registered with the MBean Server using this base name in conjunction with properties whose keys are specified by the SERVICE_NAME_KEY, SERVICE_VENDOR_KEY, and SERVICE_VERSION_KEY constants.

Since:

SLEE 1.1

See Also:

Constant Field Values

SERVICE_NAME_KEY

static final java.lang.String SERVICE_NAME_KEY

The JMX Object Name property key that identifies the name of the Service that the Service Usage MBean is providing service usage-related management operations for. This key is equal to the string "serviceName".

Since:

SLEE 1.1

See Also:

BASE_OBJECT_NAME, SERVICE_VENDOR_KEY, SERVICE_VERSION_KEY, Constant Field Values

SERVICE_VENDOR_KEY

static final java.lang.String SERVICE_VENDOR_KEY

The JMX Object Name property key that identifies the vender of the Service that the Service Usage MBean is providing service usage-related management operations for. This key is equal to the string "serviceVendor".

Since:

SLEE 1.1

See Also:

BASE_OBJECT_NAME, SERVICE_NAME_KEY, SERVICE_VERSION_KEY, Constant Field Values

SERVICE_VERSION_KEY

static final java.lang.String SERVICE_VERSION_KEY

The JMX Object Name property key that identifies the version of the Service that the Service Usage MBean is providing service usage-related management operations for. This key is equal to the string "serviceVersion".

Since:

SLEE 1.1

See Also:

BASE_OBJECT_NAME, SERVICE_NAME_KEY, SERVICE_VENDOR_KEY, Constant Field Values

Method Detail

getService

ServiceID getService()
                     throws ManagementException

Get the component identifier of the Service that this MBean provides usage management access for.

Returns:

the component identifier of the Service that this MBean provides usage management access for.

Throws:

ManagementException - if the Service component identifier could not be obtained due to a system-level failure.

createUsageParameterSet

void createUsageParameterSet(SbbID id,
                             java.lang.String paramSetName)
                             throws java.lang.NullPointerException,
                                    UnrecognizedSbbException,
                                    InvalidArgumentException,
                                    UsageParameterSetNameAlreadyExistsException,
                                    ManagementException

Create a new usage parameter set that the specified SBB is permitted to use in the one-argument form of the get-usage-parameters methods, when the service component identifier argument of the get-usage-parameters method identifies the Service that this MBean provides usage management access for.

Parameters:

id - the component identifier of the SBB. The SBB must be an SBB that is used in the Service whose usage information is being managed by this MBean.

paramSetName - the usage parameter set name. Names must be non-null and greater than 0 in length.

Throws:

java.lang.NullPointerException - if either argument is null.

UnrecognizedSbbException - if id is not a recognizable SbbID for the SLEE, does not correspond with an SBB installed in the SLEE, or is not an SBB that participates in the Service whose usage information is being managed by this MBean.

InvalidArgumentException - if paramSetName is zero-length or the identified SBB participates in this service but does not define a usage parameters interface.

UsageParameterSetNameAlreadyExistsException - if the name has already been used to create a usage parameter set for the SBB.

ManagementException - if the usage parameter set could not be created due to a system-level failure.

removeUsageParameterSet

void removeUsageParameterSet(SbbID id,
                             java.lang.String paramSetName)
                             throws java.lang.NullPointerException,
                                    UnrecognizedSbbException,
                                    InvalidArgumentException,
                                    UnrecognizedUsageParameterSetNameException,
                                    ManagementException

Remove an existing usage parameter set that the specified SBB is permitted to use in the one-argument form of the get-usage-parameters methods, when the service component identifier argument of the get-usage-parameters method identifies the Service that this MBean provides usage management access for.

Parameters:

id - the component identifier of the SBB. The SBB must be an SBB that is used in the Service whose usage information is being managed by this MBean.

paramSetName - the usage parameter set name.

Throws:

java.lang.NullPointerException - if either argument is null.

UnrecognizedSbbException - if id is not a recognizable SbbID for the SLEE, does not correspond with an SBB installed in the SLEE, or is not an SBB that participates in the Service whose usage information is being managed by this MBean.

InvalidArgumentException - if the identified SBB participates in this service but does not define a usage parameters interface.

UnrecognizedUsageParameterSetNameException - if the name does not identify a usage parameter set that has been created for the SBB.

ManagementException - if the name could not be removed due to a system-level failure.

getUsageParameterSets

java.lang.String[] getUsageParameterSets(SbbID id)
                                         throws java.lang.NullPointerException,
                                                UnrecognizedSbbException,
                                                InvalidArgumentException,
                                                ManagementException

Get the names of the usage parameter sets that the specified SBB is permitted to use in the one-argument form of the get-usage-parameters methods, when the service component identifier argument of the get-usage-parameters method identifies the Service that this MBean provides usage management access for.

Parameters:

id - the component identifier of the SBB. The SBB must be an SBB that is used in the Service whose usage information is being managed by this MBean.

Returns:

the names of the usage parameter sets that the SBB can use.

Throws:

java.lang.NullPointerException - if either argument is null.

InvalidArgumentException - if the identified SBB participates in this service but does not define a usage parameters interface.

UnrecognizedSbbException - if id is not a recognizable SbbID for the SLEE, does not correspond with an SBB installed in the SLEE, or is not an SBB that participates in the Service whose usage information is being managed by this MBean.

ManagementException - if the names could not be obtained due to a system-level failure.

getSbbUsageMBean

javax.management.ObjectName getSbbUsageMBean(SbbID id)
                                             throws java.lang.NullPointerException,
                                                    UnrecognizedSbbException,
                                                    InvalidArgumentException,
                                                    ManagementException

Get the JMX Object Name of a UsageMBean object that provides management access to the unnamed usage parameter set for the specified SBB. The SBB must be participating in the Service that this MBean provides usage management access for, and must have defined a usage parameter interface.

Parameters:

id - the component identifier of the SBB. The SBB must be an SBB that is used in the Service whose usage information is being managed by this MBean.

Returns:

the Object Name of a UsageMBean object for the SBB.

Throws:

java.lang.NullPointerException - if id is null.

UnrecognizedSbbException - if id is not a recognizable SbbID for the SLEE, does not correspond with an SBB installed in the SLEE, or is not an SBB that participates in the Service whose usage information is being managed by this MBean.

InvalidArgumentException - if the identified SBB participates in this service but does not define a usage parameters interface.

ManagementException - if the Object Name could not be obtained due to a system-level failure.

getSbbUsageMBean

javax.management.ObjectName getSbbUsageMBean(SbbID id,
                                             java.lang.String paramSetName)
                                             throws java.lang.NullPointerException,
                                                    UnrecognizedSbbException,
                                                    InvalidArgumentException,
                                                    UnrecognizedUsageParameterSetNameException,
                                                    ManagementException

Get the JMX Object Name of a UsageMBean object that provides management access to the named usage parameter set for the specified SBB. The SBB must be participating in the Service that this MBean provides usage management access for, and must have defined a usage parameters interface.

Parameters:

id - the component identifier of the SBB. The SBB must be an SBB that is used in the Service whose usage information is being managed by this MBean.

paramSetName - the name of the usage parameter set. The name must be one of the names returned by getUsageParameterSets(id).

Returns:

the Object Name of a UsageMBean object for the SBB.

Throws:

java.lang.NullPointerException - if either parameter is null.

UnrecognizedSbbException - if id is not a recognizable SbbID for the SLEE, does not correspond with an SBB installed in the SLEE, or is not an SBB that participates in the Service whose usage information is being managed by this MBean.

InvalidArgumentException - if the identified SBB participates in this service but does not define a usage parameters interface.

UnrecognizedUsageParameterSetNameException - if the named usage parameter set has not been created for the SBB.

ManagementException - if the Object Name could not be obtained due to a system-level failure.

getSbbUsageNotificationManagerMBean

javax.management.ObjectName getSbbUsageNotificationManagerMBean(SbbID id)
                                                                throws java.lang.NullPointerException,
                                                                       UnrecognizedSbbException,
                                                                       InvalidArgumentException,
                                                                       ManagementException

Get the JMX Object Name of a UsageNotificationManagerMBean that provides management access to the usage notification manager for the specified SBB. The SBB must be participating in the Service that this MBean provides usage management access for, and must have defined a usage parameters interface.

Parameters:

id - the component identifier of the SBB. The SBB must be an SBB that is used in the Service whose usage information is being managed by this MBean.

Throws:

java.lang.NullPointerException - if id is null.

UnrecognizedSbbException - if id is not a recognizable SbbID for the SLEE, does not correspond with an SBB installed in the SLEE, or is not an SBB that participates in the Service whose usage information is being managed by this MBean.

InvalidArgumentException - if the identified SBB participates in this service but does not define a usage parameters interface.

ManagementException - if the Object Name could not be obtained due to a system-level failure.

Since:

SLEE 1.1

resetAllUsageParameters

void resetAllUsageParameters(SbbID id)
                             throws java.lang.NullPointerException,
                                    UnrecognizedSbbException,
                                    InvalidArgumentException,
                                    ManagementException

Reset all usage parameters in the unamed usage parameter set, and all named usage parameter sets, of the specified SBB. Counter-type usage parameters are reset to 0 and sample-type usage parameters have all samples deleted.

Parameters:

id - the component identifier of the SBB. The SBB must be an SBB that is used in the Service whose usage information is being managed by this MBean.

Throws:

java.lang.NullPointerException - if id is null.

UnrecognizedSbbException - if id is not a recognizable SbbID for the SLEE, does not correspond with an SBB installed in the SLEE, or is not an SBB that participates in the Service whose usage information is being managed by this MBean.

InvalidArgumentException - if the identified SBB participates in this service but does not define a usage parameters interface.

ManagementException - if the values of the usage parameters could not be reset due to a system-level failure.

resetAllUsageParameters

void resetAllUsageParameters()
                             throws ManagementException

Reset all usage parameters in the unamed usage parameter set, and all named usage parameter sets, of all SBB participating in the Service whose usage information is being managed by this MBean. Counter-type usage parameters are reset to 0 and sample-type usage parameters have all samples cleared.

Throws:

ManagementException - if the values of the usage parameters could not be reset due to a system-level failure.

close

void close()
           throws ManagementException

Notify the SLEE that this Service Usage MBean is no longer required by the management client. As the SLEE may subsequently deregister this MBean from the MBean server, a client that invokes this method should assume that the Object Name they had for the MBean is no longer valid once this method returns.

Throws:

ManagementException - if the Service Usage MBean could not be closed by the SLEE due to a system-level failure.