IBM WebSphere Application ServerTM
Release 7

com.ibm.wsspi.pmi.factory
Class StatsFactory

java.lang.Object
  extended by com.ibm.wsspi.pmi.factory.StatsFactory

public class StatsFactory
extends java.lang.Object

StatsFactory is main class in Custom PMI. It is designed to simplify the process of "PMI enabling" a WebSphere application or runtime component.

The following steps are required to instrument a component using Custom PMI:

  1. Define a Stats template
  2. Create Stats object using StatsFactory
  3. Instrument code and update the Stats object.

StatsFactory allows runtime component to create a custom Stats/PMI (Stats is the J2EE terminology) module using an XML template. The template should follow the DTD com/ibm/websphere/pmi/xml/stats.dtd.

The statistics created via Custom PMI will be available to the external client programs via JMX MBean and PMI API. The Custom PMI will support all the Statistic types (CountStatistic, TimeStatistic, etc.) defined in the J2EE 1.4 Performance Data Framework. The Custom PMI cannot support any user-defined Statistic type.

This factory class can create objects of type StatsInstance and StatsGroup. The StatsInstance/StatsGroup will be part of the Performance Monitoring Infrastructure (PMI) tree structure. Each StatsInstance/StatsGroup is identified by a unique name in the PMI tree. It is suggested that the name be prefixed with the component/product name. By default each StatsInstance/StatsGroup will be added to the PMI tree at the root level. StatsFactory allows to add a StatsInstance/StatsGroup to a parent StatsInstance/StatsGroup.

Each StatsInstance or StatsGroup should be associated with an MBean in order to access the statistics via JMX interface. There are two ways to access the statistics via JMX:

In order to access the statistics via managed object MBean the user should provide the MBean when creating the StatsInstance or StatsGroup.

All Stats (with or without an MBean) can be fetched via the Perf MBean. Stats without an MBean is identified using the StatDescriptor. Stats with an MBean can be identified using the StatDescriptor or the javax.management.ObjectName.


Constructor Summary
StatsFactory()
           
 
Method Summary
static StatsGroup createStatsGroup(java.lang.String groupName, java.lang.String statsTemplate, javax.management.ObjectName mBean)
          Create a StatsGroup using the Stats template and add to the PMI tree at the root level.
static StatsGroup createStatsGroup(java.lang.String groupName, java.lang.String statsTemplate, StatsGroup parentGroup, javax.management.ObjectName mBean)
          Create a StatsGroup using the Stats template and add to the PMI tree under the specified parent group.
static StatsGroup createStatsGroup(java.lang.String groupName, java.lang.String statsTemplate, StatsInstance parentInstance, javax.management.ObjectName mBean)
          Create a StatsGroup using the Stats template and add to the PMI tree under the specified parent instance.
static StatsInstance createStatsInstance(java.lang.String instanceName, StatsGroup parentGroup, javax.management.ObjectName mBean, com.ibm.wsspi.pmi.factory.StatisticActionListener listener)
          Deprecated. As of 6.1, replaced by createStatsInstance(String, StatsGroup, ObjectName, StatisticActions ).
static StatsInstance createStatsInstance(java.lang.String instanceName, StatsGroup parentGroup, javax.management.ObjectName mBean, StatisticActions listener)
          Create a StatsInstance under the specified parent group.
static StatsInstance createStatsInstance(java.lang.String instanceName, java.lang.String statsTemplate, javax.management.ObjectName mBean, com.ibm.wsspi.pmi.factory.StatisticActionListener listener)
          Deprecated. As of 6.1, replaced by createStatsInstance(String, String, ObjectName, StatisticActions ).
static StatsInstance createStatsInstance(java.lang.String instanceName, java.lang.String statsTemplate, javax.management.ObjectName mBean, StatisticActions listener)
          Create a StatsInstance using the Stats template and add to the PMI tree at the root level.
static StatsInstance createStatsInstance(java.lang.String instanceName, java.lang.String statsTemplate, StatsGroup parentGroup, javax.management.ObjectName mBean, com.ibm.wsspi.pmi.factory.StatisticActionListener listener)
          Deprecated. As of 6.1, replaced by createStatsInstance(String, String, StatsGroup, StatsGroup, ObjectName, StatisticActions ).
static StatsInstance createStatsInstance(java.lang.String instanceName, java.lang.String statsTemplate, StatsGroup parentGroup, javax.management.ObjectName mBean, StatisticActions listener)
          Create a StatsInstance using the template and add to the PMI tree under the specified parent group.
static StatsGroup getStatsGroup(java.lang.String[] path)
          This method may be used to retrieve an existing StatsGroup object.
static StatsInstance getStatsInstance(java.lang.String[] path)
          This method may be used to retrieve an existing StatsInstance object.
static boolean isPMIEnabled()
          Returns PMI service status.
static void registerStatsTemplateLookup(StatsTemplateLookup lookupClass)
          Registers a StatsTemplateLookup object with the PMI service (WebSphere internal use only).
static void removeStatsGroup(StatsGroup group)
          Removes a StatsGroup from the PMI tree.
static void removeStatsInstance(StatsInstance instance)
          Removes a StatsInstance from the PMI tree.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

StatsFactory

public StatsFactory()
Method Detail

isPMIEnabled

public static boolean isPMIEnabled()
Returns PMI service status.

Returns:
true if PMI service is enabled

createStatsGroup

public static StatsGroup createStatsGroup(java.lang.String groupName,
                                          java.lang.String statsTemplate,
                                          javax.management.ObjectName mBean)
                                   throws StatsFactoryException
Create a StatsGroup using the Stats template and add to the PMI tree at the root level. This method will associate the MBean provided by the caller to the Stats group.

Parameters:
groupName - name of the group
statsTemplate - location of the Stats template XML file
mBean - MBean that needs to be associated with the Stats group
Returns:
Stats group
Throws:
StatsFactoryException - if error while creating Stats group

createStatsGroup

public static StatsGroup createStatsGroup(java.lang.String groupName,
                                          java.lang.String statsTemplate,
                                          StatsGroup parentGroup,
                                          javax.management.ObjectName mBean)
                                   throws StatsFactoryException
Create a StatsGroup using the Stats template and add to the PMI tree under the specified parent group. This method will associate the MBean provided by the caller to the Stats group.

Parameters:
groupName - name of the group
statsTemplate - location of the Stats template XML file
parentGroup - parent Stats group
mBean - MBean that needs to be associated with the Stats group
Returns:
Stats group
Throws:
StatsFactoryException - if error while creating Stats group

createStatsGroup

public static StatsGroup createStatsGroup(java.lang.String groupName,
                                          java.lang.String statsTemplate,
                                          StatsInstance parentInstance,
                                          javax.management.ObjectName mBean)
                                   throws StatsFactoryException
Create a StatsGroup using the Stats template and add to the PMI tree under the specified parent instance. This method will associate the MBean provided by the caller to the Stats group.

Parameters:
groupName - name of the group
statsTemplate - location of the Stats template XML file
parentInstance - parent Stats instance
mBean - MBean that needs to be associated with the Stats group
Returns:
Stats group
Throws:
StatsFactoryException - if error while creating Stats group

createStatsInstance

public static StatsInstance createStatsInstance(java.lang.String instanceName,
                                                java.lang.String statsTemplate,
                                                javax.management.ObjectName mBean,
                                                com.ibm.wsspi.pmi.factory.StatisticActionListener listener)
                                         throws StatsFactoryException
Deprecated. As of 6.1, replaced by createStatsInstance(String, String, ObjectName, StatisticActions ).

Create a StatsInstance using the Stats template and add to the PMI tree at the root level. This method will associate the MBean provided by the caller to the Stats instance.

Parameters:
instanceName - name of the instance
statsTemplate - location of the Stats template XML file
mBean - MBean that needs to be associated with the Stats instance
listener - a StatisticActionListener object. This object will be called when a statistic is created for this instance
Returns:
Stats instance
Throws:
StatsFactoryException - if error while creating Stats instance

createStatsInstance

public static StatsInstance createStatsInstance(java.lang.String instanceName,
                                                java.lang.String statsTemplate,
                                                javax.management.ObjectName mBean,
                                                StatisticActions listener)
                                         throws StatsFactoryException
Create a StatsInstance using the Stats template and add to the PMI tree at the root level. This method will associate the MBean provided by the caller to the Stats instance.

Parameters:
instanceName - name of the instance
statsTemplate - location of the Stats template XML file
mBean - MBean that needs to be associated with the Stats instance
listener - A StatisticActions object. This object will be called when events occur on statistics created for this instance
Returns:
Stats instance
Throws:
StatsFactoryException - if error while creating Stats instance

createStatsInstance

public static StatsInstance createStatsInstance(java.lang.String instanceName,
                                                StatsGroup parentGroup,
                                                javax.management.ObjectName mBean,
                                                com.ibm.wsspi.pmi.factory.StatisticActionListener listener)
                                         throws StatsFactoryException
Deprecated. As of 6.1, replaced by createStatsInstance(String, StatsGroup, ObjectName, StatisticActions ).

Create a StatsInstance under the specified parent group. The new Stats instance will use the parent template. This method will associate the MBean provided by the caller to the Stats instance.

Parameters:
instanceName - name of the instance
parentGroup - parent Stats group
mBean - MBean that needs to be associated with the Stats instance
listener - a StatisticActionListener object. This object will be called when a statistic is created for this instance
Returns:
Stats instance
Throws:
StatsFactoryException - if error while creating Stats instance

createStatsInstance

public static StatsInstance createStatsInstance(java.lang.String instanceName,
                                                StatsGroup parentGroup,
                                                javax.management.ObjectName mBean,
                                                StatisticActions listener)
                                         throws StatsFactoryException
Create a StatsInstance under the specified parent group. The new Stats instance will use the parent template. This method will associate the MBean provided by the caller to the Stats instance.

Parameters:
instanceName - name of the instance
parentGroup - parent Stats group
mBean - MBean that needs to be associated with the Stats instance
listener - A StatisticActions object. This object will be called when events occur on statistics created for this instance
Returns:
Stats instance
Throws:
StatsFactoryException - if error while creating Stats instance

createStatsInstance

public static StatsInstance createStatsInstance(java.lang.String instanceName,
                                                java.lang.String statsTemplate,
                                                StatsGroup parentGroup,
                                                javax.management.ObjectName mBean,
                                                com.ibm.wsspi.pmi.factory.StatisticActionListener listener)
                                         throws StatsFactoryException
Deprecated. As of 6.1, replaced by createStatsInstance(String, String, StatsGroup, StatsGroup, ObjectName, StatisticActions ).

Create a StatsInstance using the template and add to the PMI tree under the specified parent group. This method will associate the MBean provided by the caller to the Stats instance. Note that the parent StatsGroup will only aggregate the child StatsInstances that are created from the same stats template as that of the parent.

Parameters:
instanceName - name of the instance
statsTemplate - location of the Stats template XML file
parentGroup - parent Stats group
mBean - MBean that needs to be associated with the Stats instance
listener - a StatisticActionListener object. This object will be called when a statistic is created for this instance
Returns:
Stats instance
Throws:
StatsFactoryException - if error while creating Stats instance

createStatsInstance

public static StatsInstance createStatsInstance(java.lang.String instanceName,
                                                java.lang.String statsTemplate,
                                                StatsGroup parentGroup,
                                                javax.management.ObjectName mBean,
                                                StatisticActions listener)
                                         throws StatsFactoryException
Create a StatsInstance using the template and add to the PMI tree under the specified parent group. This method will associate the MBean provided by the caller to the Stats instance. Note that the parent StatsGroup will only aggregate the child StatsInstances that are created from the same stats template as that of the parent.

Parameters:
instanceName - name of the instance
statsTemplate - location of the Stats template XML file
parentGroup - parent Stats group
mBean - MBean that needs to be associated with the Stats instance
listener - A StatisticActions object. This object will be called when events occur on statistics created for this instance
Returns:
Stats instance
Throws:
StatsFactoryException - if error while creating Stats instance

removeStatsInstance

public static void removeStatsInstance(StatsInstance instance)
                                throws StatsFactoryException
Removes a StatsInstance from the PMI tree. Note that any children under the instance will also be removed. If the instance is associated with a default CustomStats MBean, the MBean will be de-activated.

Parameters:
instance - StatsInstance to be removed
Throws:
StatsFactoryException - if error while removing Stats instance

removeStatsGroup

public static void removeStatsGroup(StatsGroup group)
                             throws StatsFactoryException
Removes a StatsGroup from the PMI tree. Note that any children under the group will also be removed. If the group is associated with a default CustomStats MBean, the MBean will be de-activated.

Parameters:
group - StatsGroup to be removed
Throws:
StatsFactoryException - if error while removing Stats group

registerStatsTemplateLookup

public static void registerStatsTemplateLookup(StatsTemplateLookup lookupClass)
Registers a StatsTemplateLookup object with the PMI service (WebSphere internal use only).

Parameters:
lookupClass - An instance of StatsTemplateLookup

getStatsGroup

public static StatsGroup getStatsGroup(java.lang.String[] path)
This method may be used to retrieve an existing StatsGroup object. The object should be specified using a String array specifying the path to use to retrieve the object. If a StatsGroup object can not be found using the specified path, a null value is returned.

Parameters:
path - A String array. The string elements in this parameter specify the hierarchy of the stats group being retrieved. If no stats group is found matching the path provided, the response object will be null.

getStatsInstance

public static StatsInstance getStatsInstance(java.lang.String[] path)
This method may be used to retrieve an existing StatsInstance object. The object should be specified using a String array specifying the path to use to retrieve the object. If a StatsInstance object can not be found using the specified path, a null value is returned.

Parameters:
path - A String array. The string elements in this parameter specify the hierarchy of the stats instance being retrieved. If no stats instance is found matching the path provided, the response object will be null.

IBM WebSphere Application ServerTM
Release 7