IBM WebSphere Application ServerTM
Release 7

com.ibm.wsspi.rasdiag
Class DiagnosticProviderHelper

java.lang.Object
  extended by com.ibm.wsspi.rasdiag.DiagnosticProviderHelper

public class DiagnosticProviderHelper
extends java.lang.Object

The DiagnosticProviderHelper class provides numerous methods used by implementers of the DiagnosticProvider interface to simplify and commonize implementation of that interface.


Constructor Summary
DiagnosticProviderHelper()
           
 
Method Summary
static void addDiagnosticProviderIDtoLogger(java.util.logging.Logger aLogger, java.lang.String aDPid)
          adds the DiagnosticProvider ID information to a logger for static update of the logger.
static java.lang.Object callJmxServer(com.ibm.websphere.management.AdminService aAdminSvc, javax.management.ObjectName aObjectName, java.lang.String aMethod, java.lang.Object[] aParms, java.lang.String[] aSignatures)
          performs JMX invoke function against DiagnosticProvider objects.
static void deregisterMBeanFromDiagnosticService(java.lang.String dPName, javax.management.ObjectName dPid, boolean aDiagnosticConfigRlse)
          deregisters this MBean with DiagnosticService MBean to clean up resources, including DiagnosticConfig resources Input can specify dPName, dPid, or both.
static void filterEventPayload(java.lang.String aAttributeId, java.util.HashMap payLoad)
          filter a payload generated by a DiagnosticProvider down to what was requested with the AttributeId passed in on the JMX invocation.
static int findAttrib(java.lang.String attribId, AttributeInfo[] attribInfo)
          find first match between the regular expression ID field in the AttributeInfo object array and the string with the name of hte current object
static javax.management.ObjectName getDiagnosticService(com.ibm.websphere.management.AdminService adminSvc)
          retrieves the JMX ObjectName for the DiagnosticService MBean in this JMX server.
static java.lang.Object getJmxAttrib(com.ibm.websphere.management.AdminService aAdminSvc, javax.management.ObjectName aObjectName, java.lang.String aAttrName)
          performs JMX invoke function to retrieve attribute values.
static boolean isPropertyReportable(java.lang.String aAttributeId, AttributeInfo[] inAttrs, java.lang.String nameToCheck, boolean aRegisteredOnly)
          returns a boolean indicating whether the Property name argument should be included in the currently requested DP operation or not.
static DiagnosticProviderInfo loadRegistry(java.io.File aFile, java.lang.String aDPName)
          parses an XML config file and extracts the data for the DiagnosticProviderInfo object.
static DiagnosticProviderInfo loadRegistry(java.io.InputStream aInStream, java.lang.String aDPName)
          parses an XML config input stream and extracts the data for the DiagnosticProviderInfo object.
static java.lang.String[] localize(java.util.ResourceBundle aResourceBundle, java.lang.String[] aKeys)
          localizes a set of keys for display.
static java.lang.String[] localize(java.lang.String aResourceBundleName, java.lang.String[] aKeys, java.util.Locale aLocale)
          localizes a set of keys for display.
static AttributeInfo[] queryMatchingDPInfoAttributes(java.lang.String aAttributeId, AttributeInfo[] inAttrs, java.lang.String[] namesToCheck, boolean aRegisteredOnly)
          returns a populated AttributeInfo structure (with fully qualified name having replaced regular expression name) for all Property names in the array that match both the AttributeId, and a registry entry (registry checking only if required).
static AttributeInfo queryMatchingDPInfoAttributes(java.lang.String aAttributeId, AttributeInfo[] inAttrs, java.lang.String nameToCheck, boolean aRegisteredOnly)
          returns a populated AttributeInfo structure (with fully qualified name having replaced regular expression name) for Property name if it matches the AttributeId and a registry entry (registry checking only if required).
static void registerMBeanWithDiagnosticService(java.lang.String dPName, javax.management.ObjectName dPid)
          registers this MBean with DiagnosticService MBean so that DiagnosticService can be the front-end for this DiagnosticProvider.
static java.util.Iterator resolveObjNm(com.ibm.websphere.management.AdminService sAdminSvc, javax.management.ObjectName aDPidOn)
          resolves the incoming objectName via a jmx query from which it will return a list of matching object names (in most cases, just one)
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DiagnosticProviderHelper

public DiagnosticProviderHelper()
Method Detail

localize

public static java.lang.String[] localize(java.util.ResourceBundle aResourceBundle,
                                          java.lang.String[] aKeys)
localizes a set of keys for display.

Parameters:
aResourceBundle - ResourceBundle object to use in localization. This added since not all RBNames resolvable based on origin of MBean
aKeys - array of keys into the resource bundle
Returns:
array of localized strings. If problems exist: if RBundle or Input String array is null, then the return is null If a key in the input string is not found in the RBundle, that entry is retured negative

localize

public static java.lang.String[] localize(java.lang.String aResourceBundleName,
                                          java.lang.String[] aKeys,
                                          java.util.Locale aLocale)
localizes a set of keys for display.

Parameters:
aResourceBundleName - name of the ResourceBundle to use in localization
aKeys - array of keys into the resource bundle
Returns:
array of localized strings. Simply drives the other signatured localize after resolving RBundleName to an RBundle

registerMBeanWithDiagnosticService

public static void registerMBeanWithDiagnosticService(java.lang.String dPName,
                                                      javax.management.ObjectName dPid)
registers this MBean with DiagnosticService MBean so that DiagnosticService can be the front-end for this DiagnosticProvider. Avoids JMX initially due to Z sync issues

Parameters:
dPName - DiagnosticProvider name to register (required)
dPid - JMX ObjectName for the DiagnosticProvider being registered.

deregisterMBeanFromDiagnosticService

public static void deregisterMBeanFromDiagnosticService(java.lang.String dPName,
                                                        javax.management.ObjectName dPid,
                                                        boolean aDiagnosticConfigRlse)
deregisters this MBean with DiagnosticService MBean to clean up resources, including DiagnosticConfig resources Input can specify dPName, dPid, or both. If specifying only one, leave the other null. aDiagnosticConfigRlse allows this call to take care of the DiagnosticConfig object for this DiagnosticProvider

Parameters:
dPName - DiagnosticProvider name to register. Caller can specify this parm, or leave it null and specify the dPid parm (or specify both). CrossRef is held, so whichever is available can be used.
dPid - JMX ObjectName for the DiagnosticProvider being registered. Caller can specify this parm, or leave it null and specify the dPName parm (or specify both). CrossRef is held, so whichever is available can be used.
aDiagnosticConfigRlse - true or false to free up DiagnosticConfig object. If false, then a call to DiagnosticConfigHome.releaseDiagnosticConfig(String aDPName) should also be called

getDiagnosticService

public static javax.management.ObjectName getDiagnosticService(com.ibm.websphere.management.AdminService adminSvc)
retrieves the JMX ObjectName for the DiagnosticService MBean in this JMX server. Not needed for registration as the registerMBeanWithDiagnosticSerivce method will retrieve it if called with a null for the DiagnosticService ObjectName.

Parameters:
adminSvc - JMX AdminService object from the factory. Can be null and method will retrieve one if it is.
Returns:
the DiagnosticService JMX ObjectName

loadRegistry

public static DiagnosticProviderInfo loadRegistry(java.io.File aFile,
                                                  java.lang.String aDPName)
parses an XML config file and extracts the data for the DiagnosticProviderInfo object. Uses SAX2 as dynamic navigation was not needed.

Parameters:
aFile - File containing the XML
aDPName - diagnostic provider name
Returns:
class containing all config, state, and selfDiagnostic registry entries along with the associated ResourceBundleName

loadRegistry

public static DiagnosticProviderInfo loadRegistry(java.io.InputStream aInStream,
                                                  java.lang.String aDPName)
parses an XML config input stream and extracts the data for the DiagnosticProviderInfo object. Uses SAX2 as dynamic navigation was not needed.

Parameters:
aInStream - containing the XML
aDPName - diagnostic provider name
Returns:
class containing all config, state, and selfDiagnostic registry entries along with the associated ResourceBundleName

addDiagnosticProviderIDtoLogger

public static void addDiagnosticProviderIDtoLogger(java.util.logging.Logger aLogger,
                                                   java.lang.String aDPid)
adds the DiagnosticProvider ID information to a logger for static update of the logger. This would be used where the class/logger maps to just one DiagnosticProvider. If a class can do work for multiple DiagnosticProviders, then the dynamic means of doing this via arg 1 should be used.

Parameters:
aLogger - Logger to extend with the DiagnosticProvider ID
aDPid - DiagnosticProvider ID with which to extend the Logger

callJmxServer

public static java.lang.Object callJmxServer(com.ibm.websphere.management.AdminService aAdminSvc,
                                             javax.management.ObjectName aObjectName,
                                             java.lang.String aMethod,
                                             java.lang.Object[] aParms,
                                             java.lang.String[] aSignatures)
performs JMX invoke function against DiagnosticProvider objects. Security context must be created by the caller of the method as needed.

Parameters:
aAdminSvc - Admin Service object for JMX calls
aObjectName - JMX ObjectName containing method to be invoked
aMethod - Method to drive on the JMX Object
aParms - Array of parms to send to invocation
aSignatures - Array of signatures matching the parms
Returns:
Object that is returned from invoke call

getJmxAttrib

public static java.lang.Object getJmxAttrib(com.ibm.websphere.management.AdminService aAdminSvc,
                                            javax.management.ObjectName aObjectName,
                                            java.lang.String aAttrName)
performs JMX invoke function to retrieve attribute values. Security context must be created by the caller of the method as needed.

Parameters:
aAdminSvc - Admin Service object for JMX calls
aObjectName - JMX ObjectName containing method to be invoked
aAttrName - name attribute for which to get value
Returns:
Object that is returned from invoke call

isPropertyReportable

public static boolean isPropertyReportable(java.lang.String aAttributeId,
                                           AttributeInfo[] inAttrs,
                                           java.lang.String nameToCheck,
                                           boolean aRegisteredOnly)
returns a boolean indicating whether the Property name argument should be included in the currently requested DP operation or not. If it does not match the Attributeid regular expression, then it false is returned. If it matches and registry checking is not required, then true is returned. If registry checking is required, then a check is made to see if it matches any of the regular expression id fields in the AttributeInfo array. The Pattern is compiled even though this method only uses each one once, as it is likely that the method will be called numerous times, and that other DiagnosticProvider methods may be used.

Parameters:
aAttributeId - AttributeId as passed in on the method call
inAttrs - Appropriate attributeArray (likely from ConfigInfo or StateInfo object)
nameToCheck - Property names which may be sent
aRegisteredOnly - boolean to determine if we are only delivering registered Properties, or if non-Registered properties can be sent
Returns:
boolean indicating whether or not this property should be reported

queryMatchingDPInfoAttributes

public static AttributeInfo[] queryMatchingDPInfoAttributes(java.lang.String aAttributeId,
                                                            AttributeInfo[] inAttrs,
                                                            java.lang.String[] namesToCheck,
                                                            boolean aRegisteredOnly)
returns a populated AttributeInfo structure (with fully qualified name having replaced regular expression name) for all Property names in the array that match both the AttributeId, and a registry entry (registry checking only if required). If registeredOnly is false, it creates the id with the Property name, and the descriptionKey with the property name with .descriptionKey appended.

Parameters:
aAttributeId - AttributeId as passed in on the method call
inAttrs - Appropriate attributeArray (likely from ConfigInfo or StateInfo object)
namesToCheck - Array of Property names which may be sent
aRegisteredOnly - boolean to determine if we are only delivering registered Properties, or if non-Registered properties can be sent
Returns:
AttributeInfo array. Entries only for entries in the Property array that match what is required

queryMatchingDPInfoAttributes

public static AttributeInfo queryMatchingDPInfoAttributes(java.lang.String aAttributeId,
                                                          AttributeInfo[] inAttrs,
                                                          java.lang.String nameToCheck,
                                                          boolean aRegisteredOnly)
returns a populated AttributeInfo structure (with fully qualified name having replaced regular expression name) for Property name if it matches the AttributeId and a registry entry (registry checking only if required). If registeredOnly is false, it creates the id with the Property name, and the descriptionKey with the property name with .descriptionKey appended.

Parameters:
aAttributeId - AttributeId as passed in on the method call
inAttrs - Appropriate attributeArray (likely from ConfigInfo or StateInfo object)
nameToCheck - Property name which may be sent
aRegisteredOnly - boolean to determine if we are only delivering registered Properties, or if non-Registered properties can be sent
Returns:
AttributeInfo that will work for this property, null if prop should not be reported

filterEventPayload

public static void filterEventPayload(java.lang.String aAttributeId,
                                      java.util.HashMap payLoad)
filter a payload generated by a DiagnosticProvider down to what was requested with the AttributeId passed in on the JMX invocation. In general, the filtering is done as the payload is generated. This method is used for situations where the cost of filtering during generation would be prohibitive, or if the context necessary for that filtering is not available. It modifies the input HashMap in place as this allows special HashMap implementations to not be disturbed. There will be 0 or more remove methods driven against HashMap.

Parameters:
aAttributeId - regular expression string used to filter contents of the HashMap
payLoad - HashMap containing the current payload, but possibly with entries that should not be returned This HashMap is updated in place to preserve any special HashMap handling/types of the caller.

findAttrib

public static int findAttrib(java.lang.String attribId,
                             AttributeInfo[] attribInfo)
find first match between the regular expression ID field in the AttributeInfo object array and the string with the name of hte current object

Parameters:
attribId - name of the Attribute to look for
attribInfo - array of Attribute objects in which to look for that name
Returns:
offset into the AttributeArray that matches. -1 if string does not match any of the attribId regexp patterns

resolveObjNm

public static java.util.Iterator resolveObjNm(com.ibm.websphere.management.AdminService sAdminSvc,
                                              javax.management.ObjectName aDPidOn)
resolves the incoming objectName via a jmx query from which it will return a list of matching object names (in most cases, just one)

Parameters:
sAdminSvc - JMX AdminService reference, can be null ... if it is, this method will retrieve one
aDPidOn - The incoming objectName that is used in the query
Returns:
An iterator through the results (often just one) from the JMX query

IBM WebSphere Application ServerTM
Release 7