com.ibm.dtfj.analyzer.ext
Interface IAnalyzerContext

All Superinterfaces:
IMessageLogger

public interface IAnalyzerContext
extends IMessageLogger

Define the Context in which analyzers will operate. The context provides a starting point in the dump for each analyzer to analyse. Typically this will be a JavaRuntime but it may be a generic ManagedRuntime. In the general case an Image may contain multiple address spaces each of which may contain multiple processes that in turn may contain multiple runtimes. In the usual case we have a single address space, single process and single runtime which is a Java runtime. Hence we can save every analyzer the tedious task of navigating down to the runtime in order to start analysis. At present we give the analyzer the complete context although that might not be such a good idea in the long term since the analyzer might choose to consider the entire image rather than just the runtime. To handle the rare case of dumps with multiple runtimes we allow an analyzer to get hold of an alternative context on the assumption that the required runtimeID string can be pulled from a hat somewhere by the analyzer.


Nested Class Summary
 
Nested classes/interfaces inherited from interface com.ibm.dtfj.analyzer.ext.IMessageLogger
IMessageLogger.LocalLevel
 
Field Summary
 
Fields inherited from interface com.ibm.dtfj.analyzer.ext.IMessageLogger
LEVEL_DBDA_DUMP_MAJOR, LEVEL_DBDA_DUMP_MINOR, LEVEL_DBDA_DUMP_MINOR_FULL, LEVEL_DBDA_INFO, LEVEL_DBDA_OBSERVATION_HIGH, LEVEL_DBDA_OBSERVATION_LOW, LEVEL_DBDA_OBSERVATION_MEDIUM, LEVEL_DBDA_TOOL_MAJOR, LEVEL_DBDA_TOOL_MINOR, LEVEL_DBDA_TOOL_MINOR_FULL
 
Method Summary
 IAnalysisReport allocateReport(java.lang.String name, java.lang.String version)
          Build a report from the given analyzer name and version.
 IAnalysisReport allocateReport(java.lang.String name, java.lang.String version, java.lang.Object refKey)
           
 int analyzeResponse(java.lang.String analyzerName, java.lang.String[] response, java.lang.String rule)
          Invoke a named analyzer to evaluate the given response values and return some indication of the value of a given analyzer-specific rule.
 java.lang.String[] doAnalysis(java.lang.String analyzerName)
          Request a specific named analyzer to do some analysis of the current image and return the response values.
 IAnalyzerContext getAnalyzerForRuntimeID(java.lang.String ID)
          Return an analyzer for a given runtime ID.
 java.util.List getContextAttributes()
          Return a List containing the tag values of all the context attributes previously specified in calls to setContextAttribute(int, String).
 com.ibm.dtfj.image.ImageAddressSpace getCurrentAddressSpace()
          Return the current address space
 java.lang.String getCurrentDumpName()
          Return the current dump name or null if we haven't defined one yet
 com.ibm.dtfj.image.Image getCurrentImage()
          Return the current image
 com.ibm.dtfj.image.ImageFactory getCurrentImageFactory()
          Return the current image factory
 com.ibm.dtfj.java.JavaRuntime getCurrentJavaRuntime()
          Return the current Java runtime or exception if the current runtime is not a Java runtime
 com.ibm.dtfj.image.ImageProcess getCurrentProcess()
          Return the current process
 com.ibm.dtfj.runtime.ManagedRuntime getCurrentRuntime()
          Return the current managed runtime which typically will be be a JavaRuntime
 java.lang.String getCurrentRuntimeID()
          Return a unique identifier for the runtime we are operating on.
 java.util.logging.Logger getLogger()
          Get hold of a logger to record debugging information.
 RuntimeParameters getRuntimeParameters()
          Return the runtime parameters which were used to invoke the analysis.
 java.lang.String getVersion()
          Return the analyzer context version identifier
 java.lang.String[] listRules(java.lang.String analyzerName)
          Request the list of rules that a given named analyzer implements.
 IAnalyzerBase loadAnalyzer(java.lang.String analyzerName)
          Load the requested analyzer and return a reference to it.
 IAnalyzerBase loadAnalyzer(java.lang.String analyzerName, java.lang.Object parent)
          Load the requested analyzer and return a reference to it.
 void notifyAnalysisPhase(IAnalyzerBase analyzer, int phase, int target)
          Used by an analyzer to report the analysis phase and the total expected number of phases.
 boolean notifyAnalysisProgress(IAnalyzerBase analyzer, int progress, int target)
          Used by an analyzer to report the progress of an analysis phase and the expected target value.
 void outputMessage(java.lang.String msg)
          Output a given message to the 'console' of the analyzer.
 IAnalysisReport produceReport(java.lang.String analyzerName)
          Generate a report which will be encapsulated in the IAnalysisReport object for later use by some formatter.
 IAnalysisReport produceReport(java.lang.String analyzerName, java.lang.String[] response, java.lang.String rule, int state)
          When the response has been analysed we have produced some state value.
 void setContextAttribute(int precedence, java.lang.String tag)
          Specify a new attribute associated with this analyzer context.
 
Methods inherited from interface com.ibm.dtfj.analyzer.ext.IMessageLogger
getMessages, getMessages, getMessages, getResourceBundleName, logMessage, logMessage, logTranslatedMessage, logTranslatedMessage, printReportStatistics
 

Method Detail

getVersion

java.lang.String getVersion()
Return the analyzer context version identifier

Returns:
analyzer context version

getCurrentImage

com.ibm.dtfj.image.Image getCurrentImage()
Return the current image

Returns:
current image

getCurrentImageFactory

com.ibm.dtfj.image.ImageFactory getCurrentImageFactory()
Return the current image factory

Returns:
current image factory

getCurrentAddressSpace

com.ibm.dtfj.image.ImageAddressSpace getCurrentAddressSpace()
Return the current address space

Returns:
current address space

getCurrentProcess

com.ibm.dtfj.image.ImageProcess getCurrentProcess()
Return the current process

Returns:
current process

getCurrentRuntime

com.ibm.dtfj.runtime.ManagedRuntime getCurrentRuntime()
Return the current managed runtime which typically will be be a JavaRuntime

Returns:
current managed runtime

getCurrentJavaRuntime

com.ibm.dtfj.java.JavaRuntime getCurrentJavaRuntime()
Return the current Java runtime or exception if the current runtime is not a Java runtime

Returns:
current Java runtime

getCurrentRuntimeID

java.lang.String getCurrentRuntimeID()
Return a unique identifier for the runtime we are operating on.

Returns:
the unique string ID for this context

getAnalyzerForRuntimeID

IAnalyzerContext getAnalyzerForRuntimeID(java.lang.String ID)
Return an analyzer for a given runtime ID.

Parameters:
ID - the context ID
Returns:
the analyzer context for that ID

getCurrentDumpName

java.lang.String getCurrentDumpName()
Return the current dump name or null if we haven't defined one yet

Returns:
current dump name

loadAnalyzer

IAnalyzerBase loadAnalyzer(java.lang.String analyzerName)
Load the requested analyzer and return a reference to it. Also record it in the analyzers table although it will have no values set for it so we know it hasn't been run.

Parameters:
analyzerName - - analyzer to load
Returns:
- loaded instance already associated with this analyzer

loadAnalyzer

IAnalyzerBase loadAnalyzer(java.lang.String analyzerName,
                           java.lang.Object parent)
Load the requested analyzer and return a reference to it. Also record it in the analyzers table although it will have no values set for it so we know it hasn't been run. If the parent is non null then associate this new analyzer with the given parent. For this to succeed the analyzer must implement IWrapper.

Parameters:
analyzerName - - analyzer to load
parent - - parent analyzer
Returns:
- loaded instance already associated with this analyzer

doAnalysis

java.lang.String[] doAnalysis(java.lang.String analyzerName)
Request a specific named analyzer to do some analysis of the current image and return the response values.

Parameters:
analyzerName - - analyzer to operate on
Returns:
- a sequence of String which in general should be name value pairs or some structured type such as xml.

analyzeResponse

int analyzeResponse(java.lang.String analyzerName,
                    java.lang.String[] response,
                    java.lang.String rule)
Invoke a named analyzer to evaluate the given response values and return some indication of the value of a given analyzer-specific rule. Typically the response values will have come from an invocation of doAnalysis method on the same named analyzer but there are occasions in which it will be invoked on a different analyzer.

Parameters:
analyzerName - - analyzer to operate on
response - - the set of strings which was produced by running this analyzer
rule - - the rule we want to evaluate
Returns:
- an integer indicating rule value. See the STATE_ values above.

listRules

java.lang.String[] listRules(java.lang.String analyzerName)
Request the list of rules that a given named analyzer implements.

Parameters:
analyzerName - - analyzer to operate on
Returns:
- the list of rules

produceReport

IAnalysisReport produceReport(java.lang.String analyzerName,
                              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 an error report if required. This simple default implementation simply converts the state value to a string.

Parameters:
analyzerName - - the name of the analyzer
response - - the set of strings which was produced by running this analyzer
rule - - the rule which the which was produced by running this analyzer
state - - the value returned from analyzeResponse.
Returns:
- the generic report object which will be given to some formatter

produceReport

IAnalysisReport produceReport(java.lang.String analyzerName)
Generate a report which will be encapsulated in the IAnalysisReport object for later use by some formatter.

Parameters:
analyzerName - - the name of the analyzer
Returns:
- the generic report object which will be given to some formatter

outputMessage

void outputMessage(java.lang.String msg)
Output a given message to the 'console' of the analyzer. This is typically some indication of the result of the analysis which may be an error symptom or may be a request to do some manual analysis etc.

Parameters:
msg - - the message that is to be output to the 'console'

getLogger

java.util.logging.Logger getLogger()
Get hold of a logger to record debugging information.

Returns:
- the logger object on which to write debugging information

allocateReport

IAnalysisReport allocateReport(java.lang.String name,
                               java.lang.String version)
Build a report from the given analyzer name and version.

Parameters:
name -
version -
Returns:
the report

allocateReport

IAnalysisReport allocateReport(java.lang.String name,
                               java.lang.String version,
                               java.lang.Object refKey)
Parameters:
name -
version -
refKey -
Returns:
the report

setContextAttribute

void setContextAttribute(int precedence,
                         java.lang.String tag)
Specify a new attribute associated with this analyzer context. Context attributes are used to modify the behavior of the analyzer context object, and especially the loadAnalyzer() method, according to the nature of the image and the runtime that it represents (for example the version of the DTFJ API in use, the type and version of JVM runtime, or any other characteristics of this runtime)

Parameters:
precedence - an integer representing the order in which multiple attributes should be considered when making decisions based on multiple attributes
tag - a string representing the value of the attribute to add

getContextAttributes

java.util.List getContextAttributes()
Return a List containing the tag values of all the context attributes previously specified in calls to setContextAttribute(int, String). The elements in this list will be ordered according to the precedence specified in the calls to setContextAttribute().

Returns:
a List of strings representing all the context attributes

getRuntimeParameters

RuntimeParameters getRuntimeParameters()
Return the runtime parameters which were used to invoke the analysis. An analysis module might choose different behaviour based on the setting of some of these options.

Returns:
the set of runtime parameters that were used to invoke the analysis

notifyAnalysisPhase

void notifyAnalysisPhase(IAnalyzerBase analyzer,
                         int phase,
                         int target)
Used by an analyzer to report the analysis phase and the total expected number of phases. An example may be an analyzer that makes multiple passes through the heap objects and reports each pass as a phase and then reports progress on every 1000th object scanned.

Parameters:
analyzer - the current analyzer
phase - the analysis phase which will be analyzer dependent
target - the analysis phase at the end of the analysis

notifyAnalysisProgress

boolean notifyAnalysisProgress(IAnalyzerBase analyzer,
                               int progress,
                               int target)
Used by an analyzer to report the progress of an analysis phase and the expected target value. In some cases it may be too expensive to determine a valid target value and thus a value of zero is acceptable. Thus if an analyzer is making multiple passes through the objects in the heap it may choose to report progress every 1000th object but on the first pass may not know the total number of objects. A return of false means that progress is being reported too frequently.

Parameters:
analyzer - the current analyzer
progress - the progress of the analysis phase which will be analyzer dependent
target - the expected value of the progress counter at the end of the analysis phase. this may be 0 if the analyzer cannot cheaply calculate it.
Returns:
true if the information was used by some subscriber


© 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.