com.ibm.wsspi.pmi.factory

Class StatsFactory

  • java.lang.Object
    • 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:

    • via managed object
    • via Perf MBean

    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

      Constructors 
      Constructor and Description
      StatsFactory() 
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      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 8.5