ServiceUsageMBean.java

package javax.slee.management;

import javax.slee.SbbID;
import javax.slee.ServiceID;
import javax.slee.InvalidArgumentException;
import javax.slee.UnrecognizedSbbException;
import javax.slee.usage.UnrecognizedUsageParameterSetNameException;
import javax.management.ObjectName;

/**
 * The <code>ServiceUsageMBean</code> interface defines service usage-related
 * management operations.  Using a <code>ServiceUsageMBean</code> object a management
 * client may get access to <code>UsageMBean</code> 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.
 * <p>
 * Each SBB maintains seperate sets of usage information for each Service that it
 * participates in.   A <code>ServiceUsageMBean</code> object provides management of
 * usage information accumulated for a single Service for all the SBBs participating
 * in that Service.
 * <p>
 * The base JMX Object Name of a <code>ServiceUsageMBean</code> object is specified by
 * the {@link #BASE_OBJECT_NAME} constant.  The {@link #SERVICE_NAME_KEY},
 * {@link #SERVICE_VENDOR_KEY}, and {@link #SERVICE_VERSION_KEY} constants define additional
 * Object Name properties that uniquely identify a Service Usage MBean.  The complete
 * Object Name of a <code>ServiceUsageMBean</code> object can be obtained by a
 * management client via the {@link ServiceManagementMBean#getServiceUsageMBean} method.
 */
public interface ServiceUsageMBean {
    /**
     * 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
     * <code>BASE_OBJECT_NAME + ",*"</code> 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
     * {@link #SERVICE_NAME_KEY}, {@link #SERVICE_VENDOR_KEY}, and {@link #SERVICE_VERSION_KEY}
     * constants.
     * @since SLEE 1.1
     */
    public static final String BASE_OBJECT_NAME = "javax.slee.management.usage:type=ServiceUsage";

    /**
     * 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".
     * @see #BASE_OBJECT_NAME
     * @see #SERVICE_VENDOR_KEY
     * @see #SERVICE_VERSION_KEY
     * @since SLEE 1.1
     */
    public static final String SERVICE_NAME_KEY = "serviceName";

    /**
     * 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".
     * @see #BASE_OBJECT_NAME
     * @see #SERVICE_NAME_KEY
     * @see #SERVICE_VERSION_KEY
     * @since SLEE 1.1
     */
    public static final String SERVICE_VENDOR_KEY = "serviceVendor";

    /**
     * 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".
     * @see #BASE_OBJECT_NAME
     * @see #SERVICE_NAME_KEY
     * @see #SERVICE_VENDOR_KEY
     * @since SLEE 1.1
     */
    public static final String SERVICE_VERSION_KEY = "serviceVersion";


    /**
     * Get the component identifier of the Service that this MBean provides usage
     * management access for.
     * @return 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.
     */
    public ServiceID getService()
        throws 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.
     * @param 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.
     * @param paramSetName the usage parameter set name.  Names must be non-null and
     *        greater than 0 in length.
     * @throws NullPointerException if either argument is <code>null</code>.
     * @throws UnrecognizedSbbException if <code>id</code> is not a recognizable
     *        <code>SbbID</code> 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.
     * @throws InvalidArgumentException if <code>paramSetName</code> is zero-length or the identified
     *        SBB participates in this service but does not define a usage parameters interface.
     * @throws UsageParameterSetNameAlreadyExistsException if the name has already been used to
     *        create a usage parameter set for the SBB.
     * @throws ManagementException if the usage parameter set could not be created due to
     *        a system-level failure.
     */
    public void createUsageParameterSet(SbbID id, String paramSetName)
        throws NullPointerException, UnrecognizedSbbException,
               InvalidArgumentException, UsageParameterSetNameAlreadyExistsException,
               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.
     * @param 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.
     * @param paramSetName the usage parameter set name.
     * @throws NullPointerException if either argument is <code>null</code>.
     * @throws UnrecognizedSbbException if <code>id</code> is not a recognizable
     *        <code>SbbID</code> 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.
     * @throws InvalidArgumentException if the identified SBB participates in this service
     *        but does not define a usage parameters interface.
     * @throws UnrecognizedUsageParameterSetNameException if the name does not identify a
     *        usage parameter set that has been created for the SBB.
     * @throws ManagementException if the name could not be removed due to a system-level failure.
     */
    public void removeUsageParameterSet(SbbID id, String paramSetName)
        throws NullPointerException, UnrecognizedSbbException,
               InvalidArgumentException, UnrecognizedUsageParameterSetNameException,
               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.
     * @param 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.
     * @return the names of the usage parameter sets that the SBB can use.
     * @throws NullPointerException if either argument is <code>null</code>.
     * @throws InvalidArgumentException if the identified SBB participates in this service
     *        but does not define a usage parameters interface.
     * @throws UnrecognizedSbbException if <code>id</code> is not a recognizable
     *        <code>SbbID</code> 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.
     * @throws ManagementException if the names could not be obtained due to a system-level
     *        failure.
     */
    public String[] getUsageParameterSets(SbbID id)
        throws NullPointerException, UnrecognizedSbbException, 
               InvalidArgumentException, ManagementException;

    /**
     * Get the JMX Object Name of a {@link javax.slee.usage.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.
     * @param 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.
     * @return the Object Name of a <code>UsageMBean</code> object for the SBB.
     * @throws NullPointerException if <code>id</code> is <code>null</code>.
     * @throws UnrecognizedSbbException if <code>id</code> is not a recognizable
     *        <code>SbbID</code> 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.
     * @throws InvalidArgumentException if the identified SBB participates in this service
     *        but does not define a usage parameters interface.
     * @throws ManagementException if the Object Name could not be obtained due to a
     *        system-level failure.
     */
    public ObjectName getSbbUsageMBean(SbbID id)
        throws NullPointerException, UnrecognizedSbbException,
               InvalidArgumentException, ManagementException;

    /**
     * Get the JMX Object Name of a {@link javax.slee.usage.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.
     * @param 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.
     * @param paramSetName the name of the usage parameter set.  The name must be one of the names
     *        returned by {@link #getUsageParameterSets getUsageParameterSets}<code>(id)</code>.
     * @return the Object Name of a <code>UsageMBean</code> object for the SBB.
     * @throws NullPointerException if either parameter is <code>null</code>.
     * @throws UnrecognizedSbbException if <code>id</code> is not a recognizable
     *        <code>SbbID</code> 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.
     * @throws InvalidArgumentException if the identified SBB participates in this service
     *        but does not define a usage parameters interface.
     * @throws UnrecognizedUsageParameterSetNameException if the named usage parameter set
     *        has not been created for the SBB.
     * @throws ManagementException if the Object Name could not be obtained due to a
     *        system-level failure.
     */
    public ObjectName getSbbUsageMBean(SbbID id, String paramSetName)
        throws NullPointerException, UnrecognizedSbbException,
               InvalidArgumentException, UnrecognizedUsageParameterSetNameException,
               ManagementException;

    /**
     * Get the JMX Object Name of a {@link javax.slee.usage.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.
     * @param 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 NullPointerException if <code>id</code> is <code>null</code>.
     * @throws UnrecognizedSbbException if <code>id</code> is not a recognizable
     *        <code>SbbID</code> 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.
     * @throws InvalidArgumentException if the identified SBB participates in this service
     *        but does not define a usage parameters interface.
     * @throws ManagementException if the Object Name could not be obtained due to a
     *        system-level failure.
     * @since SLEE 1.1
     */
    public ObjectName getSbbUsageNotificationManagerMBean(SbbID id)
        throws 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
     * <tt>0</tt> and sample-type usage parameters have all samples deleted.
     * @param 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 NullPointerException if <code>id</code> is <code>null</code>.
     * @throws UnrecognizedSbbException if <code>id</code> is not a recognizable
     *        <code>SbbID</code> 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.
     * @throws InvalidArgumentException if the identified SBB participates in this service
     *        but does not define a usage parameters interface.
     * @throws ManagementException if the values of the usage parameters could not be
     *        reset due to a system-level failure.
     */
    public void resetAllUsageParameters(SbbID id)
        throws NullPointerException, UnrecognizedSbbException, 
               InvalidArgumentException, 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 <tt>0</tt>
     * 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.
     */
    public void resetAllUsageParameters()
        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.
     */
    public void close()
        throws ManagementException;
}