com.ibm.dtfj.analyzer.base
Class AnalyzerBase

java.lang.Object
  extended by TranslatableAnalyzer
      extended by com.ibm.dtfj.analyzer.base.AnalyzerBase
All Implemented Interfaces:
IAnalyzerBase
Direct Known Subclasses:
ClassInstanceCounter

public abstract class AnalyzerBase
extends TranslatableAnalyzer
implements IAnalyzerBase

Define a convenience base class for a set of analysers that will implement the IAnalyzer interfaces.


Constructor Summary
protected AnalyzerBase()
           
 
Method Summary
 IAnalysisReport allocateReport()
          A helper function to allocate a report to hold analysis results
 int analyzeResponse(java.lang.String[] response, java.lang.String ruleName)
          When the analysis has been done and produced some strings we need to decide what to do next.
protected  DTFJIterator buildSafeIterator(java.util.Iterator it)
          A simple approach to handling corrupt data from DTFJ.
protected  DTFJIterator buildSortedIterator(java.util.Iterator it)
          A simple approach to handling corrupt data and imposing ordering on the iterators that come back from DTFJ.
 void defineRule(java.lang.String name, java.lang.String[] rules)
          Define a rule which can be executed in order to analyse the response from this analyzer.
 int getCachingPriority()
          Return an indication of how desirable it is for the AnalyzerContext to cache instances of this analyzer, so that multiple calls to loadAnalyzer() will return the cached instance instead of allocating and initializing a new one each time.
 java.lang.String[] getCategories()
           
 IAnalyzerContext getContext()
          (non-Javadoc)
 java.lang.String getLongDescription()
          Return a description of the analyser purpose.
 java.lang.String getName()
          Get the name of the analyzer.
 java.lang.String getResourceBundleName()
          (non-Javadoc) AnalyzerBase uses AnalyzerBase.properties because it is not derived from MessageLogger
abstract  java.lang.String getShortDescription()
          Return a short description of the analyser purpose.
static int getState(java.lang.String state)
          A simple helper function to assist the rule checking process when converting from a state defined as a string to a state defined as an integer.
static java.lang.String getStateString(int state)
          A simple helper function to assist the rule checking process when converting from a state defined as an integer to a state defined as a string.
protected  int getTotalCorruptDataErrors()
          Return the total number of CorruptDataExceptions reported against this analyzer.
protected  int getTotalDataUnavailable()
          Return the total number of DataUnavailable errors reported against this analyzer.
protected  int getTotalErrors()
          Return the total number of errors reported against this analyzer (includes all DataUnavailable, CorruptData ,UnexpectedNullException,NullPointerException and other errors found).
protected  int getTotalNullPointerExceptions()
          Return the total number of NullPointerExceptions reported against this analyzer.
protected  int getTotalOtherErrors()
          Return the total number of errors that were reported against this analyzer and were not DataUnavailable or CorruptDataExceptions .
protected  int getTotalUnexpectedNullExceptions()
          Return the total number of UnexpectedNullExceptions reported against this analyzer.
 java.lang.String getVersion()
          Get the version of the analyzer.
 void handleError(java.lang.String err, java.lang.Exception e)
          To be used by analyzers and utility classes to handle any exceptions thrown during an analyzer run.
 void handleTypeError(java.lang.String err, java.lang.Object obj)
          To be used by analyzers and utility classes to handle any type exceptions thrown during an analyzer run, for example, if the analyzer was expecting a JavaHeap object but didn't find one then this method should be called to handle this.
 boolean isPrimaryAnalyzer()
          Some Analyzers are designed to perform analysis tasks and others are designed to perform supporting tasks such as wrapping a DTFJ object and providing extra information.
 java.lang.String[] listRules()
          List the rules which have been defined for this analyzer.
 void logTranslatedMessage(java.util.logging.Level level, java.lang.String msg, java.lang.Throwable exc, IAnalysisReport report)
          Add the analyzer name to the exception message
 IAnalysisReport produceReport(java.lang.String[] response, java.lang.String rule, int state)
          When the response has been analysed we have produced some state value.
 void setContext(IAnalyzerContext a)
          (non-Javadoc)
static int testRules(java.lang.String[] xrules, java.lang.String[] response)
          Match some responses against a set of rules.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AnalyzerBase

protected AnalyzerBase()
Method Detail

setContext

public final void setContext(IAnalyzerContext a)
(non-Javadoc)

Specified by:
setContext in interface IAnalyzerBase
Parameters:
a - - the context to be associated with this analyser
See Also:
IAnalyzerBase.setContext(com.ibm.dtfj.analyzer.ext.IAnalyzerContext)

getContext

public IAnalyzerContext getContext()
(non-Javadoc)

Specified by:
getContext in interface IAnalyzerBase
Returns:
- the context associated with this analyser instance
See Also:
IAnalyzerBase.getContext()

getName

public java.lang.String getName()
Get the name of the analyzer. By default this is the class name.

Specified by:
getName in interface IAnalyzerBase
Returns:
- the name of this analyzer

getVersion

public java.lang.String getVersion()
Get the version of the analyzer. By default this is the string 'Base version'.

Specified by:
getVersion in interface IAnalyzerBase
Returns:
- the version string

getCategories

public java.lang.String[] getCategories()
Specified by:
getCategories in interface IAnalyzerBase
Returns:
- the set of categories the analyzer associated with. Categories can have tree type hierarchy with '.' used as a path separator. This method should never return null - "no category" should be indicated by an empty array or an empty string.
See Also:
IAnalyzerBase.getCategories()

getShortDescription

public abstract java.lang.String getShortDescription()
Return a short description of the analyser purpose. This will be printed prior to running the analyser.

Specified by:
getShortDescription in interface IAnalyzerBase
Returns:
- the short description

getLongDescription

public java.lang.String getLongDescription()
Return a description of the analyser purpose. This will typically be used as help text which describes the analyser.

Specified by:
getLongDescription in interface IAnalyzerBase
Returns:
- the description

handleError

public void handleError(java.lang.String err,
                        java.lang.Exception e)
To be used by analyzers and utility classes to handle any exceptions thrown during an analyzer run. If the exception is a DataUnavailable or CorruptDataException then we just count them. All other exceptions are counted and logged. This is because during the run of an analyzer many DataUnavailable or CorruptDataExceptions may be thrown and in some cases they may be expected. We do not therefore want to fill the log up with these. Anything else is unexpected and so is logged.

Parameters:
err - - the error message to be associated with the exception
e - - the exception to be handled

handleTypeError

public void handleTypeError(java.lang.String err,
                            java.lang.Object obj)
To be used by analyzers and utility classes to handle any type exceptions thrown during an analyzer run, for example, if the analyzer was expecting a JavaHeap object but didn't find one then this method should be called to handle this. If the object found is a CorruptData object then we just count the number of them. This is because the DTFJ API specifies that CorruptData can be returned from iterators. All other unexpected object types are logged as this possibly indicates an internal DTFJ error. To substitute "my message" text in the caller for the report the message file needs to contain something like {0}:my\ message={0}:My translated message To substitute "my message" text in the caller for the logger the logger message file needs to contain something like Type error\ :\ my\ message\ {1} {0}={0}: Translated Type error : my new message {1}

Parameters:
err - - the error message to be associated with the type error
obj - - the unexpected object that was found

logTranslatedMessage

public void logTranslatedMessage(java.util.logging.Level level,
                                 java.lang.String msg,
                                 java.lang.Throwable exc,
                                 IAnalysisReport report)
Add the analyzer name to the exception message


getTotalErrors

protected int getTotalErrors()
Return the total number of errors reported against this analyzer (includes all DataUnavailable, CorruptData ,UnexpectedNullException,NullPointerException and other errors found).

Returns:
the total number of errors reported against this analyzer

getTotalDataUnavailable

protected int getTotalDataUnavailable()
Return the total number of DataUnavailable errors reported against this analyzer.

Returns:
the total number of DataUnavailable errors against this analyzer

getTotalCorruptDataErrors

protected int getTotalCorruptDataErrors()
Return the total number of CorruptDataExceptions reported against this analyzer.

Returns:
the total number of CorruptDataExceptions reported against this analyzer

getTotalUnexpectedNullExceptions

protected int getTotalUnexpectedNullExceptions()
Return the total number of UnexpectedNullExceptions reported against this analyzer.

Returns:
the total number of UnexpectedNullExceptions reported against this analyzer

getTotalNullPointerExceptions

protected int getTotalNullPointerExceptions()
Return the total number of NullPointerExceptions reported against this analyzer.

Returns:
the total number of NullPointerExceptions reported against this analyzer

getTotalOtherErrors

protected int getTotalOtherErrors()
Return the total number of errors that were reported against this analyzer and were not DataUnavailable or CorruptDataExceptions .

Returns:
the total number of errors reported against this analyzer that were not DataUnvailable or CorruptDataExceptions

analyzeResponse

public int analyzeResponse(java.lang.String[] response,
                           java.lang.String ruleName)
When the analysis has been done and produced some strings we need to decide what to do next. If the analysis has produced nothing concrete then we should run the next analyzer. If the analysis has detected an error we can tell the user about it. If the error is clearly a serious one then we can probably stop doing any more analysis.

Parameters:
response - - the set of strings which was produced by running this analyzer
ruleName - - the rule which we are analysing
Returns:
an integer indicating the rule value. See the STATE_ values above.

defineRule

public void defineRule(java.lang.String name,
                       java.lang.String[] rules)
Define a rule which can be executed in order to analyse the response from this analyzer.

Parameters:
name - - the name of the rule
rules - - the set of strings defining the rule

listRules

public java.lang.String[] listRules()
List the rules which have been defined for this analyzer.

Returns:
- the set of rule names or null if none are defined

produceReport

public IAnalysisReport produceReport(java.lang.String[] response,
                                     java.lang.String rule,
                                     int state)
When the response has been analysed we have produced some state value. From the response and the state we can produce a report if required. This simple default implementation simply converts the state value to a string.

Parameters:
response - - the set of strings which was produced by running this analyzer
rule - - the rule which we are analysing
state - - the value returned from analyseResponse.
Returns:
the report describing the response, rule and state

getState

public static int getState(java.lang.String state)
A simple helper function to assist the rule checking process when converting from a state defined as a string to a state defined as an integer.

Parameters:
state - - the state as a string
Returns:
- the state as an int

getStateString

public static java.lang.String getStateString(int state)
A simple helper function to assist the rule checking process when converting from a state defined as an integer to a state defined as a string.

Parameters:
state - - the state as an int
Returns:
- the state as a String

testRules

public static int testRules(java.lang.String[] xrules,
                            java.lang.String[] response)
Match some responses against a set of rules. We stop matching as soon as the state is no longer STATE_OK. Each rule is either an arithmetic test or a presence test. Arithmetic tests take the form arithmeticExpression can be > , < , <= , >= , == , = , != Presence tests take the form presenceExpression can be ? to test for the presence or !? to test for the absence of the given token state is one of OK, ERROR, FATAL, TRUE, FALSE thus some (very bogus) example rules might be String[] analysisRules = { "deadlocks > 0 FATAL", // fatal error if deadlocks > 0 "deadlocks < 0 OK", // OK if deadlocks < 0 (unlikely) "deadlocks <= 0 OK", // OK if deadlocks <= 0 "deadlocks >= 0 OK", // OK if deadlocks >= 0 (not a good test !) "deadlocks == 0 OK", // OK if deadlocks == 0 "deadlocks = 0 OK", // ditto - allow single equals "deadlocks != 0 FATAL", // fatal error if deadlocks not zero "deadlocks !? FALSE", // false if the token 'deadlocks' is not in the response "deadlocks ? TRUE", // true if the token 'deadlocks' is in the response };

Parameters:
xrules - the set of rules to apply
response - the set of responses from the analyzer
Returns:
the state implied by the rules

allocateReport

public IAnalysisReport allocateReport()
A helper function to allocate a report to hold analysis results

Returns:
an empty report

getCachingPriority

public int getCachingPriority()
Description copied from interface: IAnalyzerBase
Return an indication of how desirable it is for the AnalyzerContext to cache instances of this analyzer, so that multiple calls to loadAnalyzer() will return the cached instance instead of allocating and initializing a new one each time. The caching priority is represented as a number between 0 and 10, where 0 means never cache instances of this analyzer, 10 means always cache all instances, and any number in-between indicates that we should try to cache it as long as there is enough memory available and that we give precedence to higher-priority analyzers when memory is scarce.

Specified by:
getCachingPriority in interface IAnalyzerBase
Returns:
the caching priority, as a number between 0 and 10
See Also:

The implementation in the base class returns 10, meaning all analyzers in this group are cacheable unconditionally.


isPrimaryAnalyzer

public boolean isPrimaryAnalyzer()
Description copied from interface: IAnalyzerBase
Some Analyzers are designed to perform analysis tasks and others are designed to perform supporting tasks such as wrapping a DTFJ object and providing extra information. At the end of an analysis run we would like to summarise the analyzers which have been run but we also want to avoid having a huge list. Hence we only choose to list analyzers which are designated 'primary' and typically are doing some specific analysis rather that providing a service to other analyzers.

Specified by:
isPrimaryAnalyzer in interface IAnalyzerBase
Returns:
true if the analyzer should be included in the list of analyzers run
See Also:
IAnalyzerBase.isPrimaryAnalyzer()

buildSafeIterator

protected DTFJIterator buildSafeIterator(java.util.Iterator it)
A simple approach to handling corrupt data from DTFJ. We build a wrapper object that preserves the iterator semantics and counts the corrupt objects and possibly logs them on the context.

Parameters:
it - a DTFJ iterator that returns corrupt objects
Returns:
an iterator that doesn't return CorruptData

buildSortedIterator

protected DTFJIterator buildSortedIterator(java.util.Iterator it)
A simple approach to handling corrupt data and imposing ordering on the iterators that come back from DTFJ. This iterator handles corrupt objects and possibly logs them on the context and in addition will return the objects in an order determined by their characteristics in the original dump (such as their name or address). Thus the order should be independent of the platform that the dump is analyzed on or the Java level of the analysis etc.

Parameters:
it - a DTFJ iterator that returns corrupt objects
Returns:
an iterator that doesn't return CorruptData and is ordered

getResourceBundleName

public java.lang.String getResourceBundleName()
(non-Javadoc) AnalyzerBase uses AnalyzerBase.properties because it is not derived from MessageLogger

See Also:
com.ibm.dtfj.analyzer.util.TranslatableMessageLogger#getResourceBundleName()


© Copyright IBM Corp. 2007, 2008 All Rights Reserved. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.