We've already seen examples of how our sample analyzer uses some other analyzers from the standard library, like
ObjectWrapperCollection and
ObjectWrapper, specifically to help find and access data structures in the dump being analyzed.
That is just one example. In general, a new analyzer may want to call on other pre-existing analyzers to perform a variety of functions that help implement parts of its own new function. Let us extend our sample WASThreadPoolsSample analyzer to call on two other analyzers from the library:
- an analyzer called WASHeader, that produces a standardized informational header suitable for putting at the start of all reports produced by analyzers that deal with WebSphere Application Server processes. This header shows common information like the WebSphere Application Server cell name, server name, the software version, the install root, etc.
- an analyzer called WASVersion, that checks if the version of the WebSphere Application Server process being analyzed, is supported by our new analyzer (since our new analyzer uses knowledge of the names of various WebSphere Application Server data structures and their fields, it may be that these data structures are different in different WebSphere Application Server versions)
public IAnalysisReport produceReport() { ... /*
* Print a global header for this report
*/
WASHeader wasHeader = (WASHeader) getContext().loadAnalyzer(WASHeader.class.getName());
IAnalysisReport headerReport = wasHeader.produceReport();
out.printReport("Common WebSphere header information", headerReport, IAnalysisReport.TAG_MAJORHEADING); /*
* Check that the WebSphere Application Server version is compatible with this analyzer (but continue anyway even if not)
*/
WASVersion wasVersion = (WASVersion) getContext().loadAnalyzer(WASVersion.class.getName());
wasVersion.checkCompatibleVersion(out, "WASThreadPoolsBasic", new String[] { "7.0" }, false); out.startSection("Scanning all thread pools", IAnalysisReport.TAG_MAJORHEADING); ....
The key points are as follows:
In both cases, we use the construct
getContext().loadAnalyzer(analyzerName)
to obtain a reference to the desired analyzer.
getContext() returns a reference to the
AnalyzerContext object that is part of the tool infrastructure available to all analyzers, and its
loadAnalyzer() method finds the analyzer with a given name (normally its class name) and loads it. Since an analyzer is just a Java™ class, this method returns a reference to an instance of that Java class, that corresponds to the desired analyzer. We can tell call any methods exported by this analyzer class to perform whichever functions we need from this analyzer.
Note that you will often see other constructs like
WASVersion wasversion = WASVersion.getInstance(getContext(), getContext().getCurrentJavaRuntime())
to load an analyzer. The
getInstance() static method is a short-cut, defined in many - but not all - analyzers, to simplify allocation of instances of that analyzer. This method does not do anything more than what the
getContext().loadAnalyzer() construct does. But it has the advantage of performing static type checking on the type of analyzer returned, rather than having to do a type-cast that can only be checked at run time. It also can perform static type checking on the (optional) second argument to
getInstance() (in this case
getContext().getCurrentJavaRuntime(), which is used to pass a
parent object to
IWrapper-type analyzers. See the API documentation for the various analyzers and the tool framework for further details.
In the case of the
WASHeader analyzer, what we want to do is to obtain the (small) report produced by that analyzer and insert it inside the report generated by our new analyzer. Since
WASHeader produces a report, it must implement the
IReport interface, so we can just invoke its
produceReport() method. This method returns a report object that contains just the report from the
WASHeader analyzer. We then insert this report object into the larger report that we are busy generating inside our new analyzer, using the
printReport() method.
Note that
printReport(), in addition to the report to be inserted, takes two other parameters:
- a title for the report being inserted
- some formatting tags, in this case TAG_MAJORHEADING, which will cause this title to appear as a major heading in the top-level report.
Because we will now have a major heading in the report at the start of the section contributed by the
WASHeader analyzer, we also create a new subsection with a major heading "Scanning all thread pools" for the main body of the report. Otherwise, the part of the report listing all the thread pools would appear to be under the heading associated with the
WASHeader information.
As noted above, each analyzer is a Java class, which may export any number of specialized methods in addition to or instead of standardized methods like
produceReport(). In this case, the
WASVersion analyzer implements a method
checkCompatibleVersion(). The purpose of that method is to check if the version of WebSphere Application Server in the dump being analyzed is compatible with a given set of versions specified as a parameter, and to emit a warning message if it is not. In this case, since we wrote our new analyzer primarily to work with WebSphere Application Server 7.0 data structures, we use this method to emit a warning if the WebSphere Application Server version in the dump is anything other than "7.0". This method has several other variations and options; please refer to the API documentation for the
WASVersion analyzer for details.
As noted earlier, the Dump Analyzer tool ships with a extensive collection of pre-defined "helper" analyzers that can be used to perform various common functions in your analyzers, beside the
WASHeader and
WASVersion analyzers used in this example.
Some of these "helper" analyzers operate at the WebSphere Application Server level (providing functions related to WebSphere Application Server information in a dump); other "helper" analyzers operate at the JVM level (providing functions related to JVM information in a dump, such as threads, monitors, heaps, etc.). Please refer to the API documentation for the Dump Analyzer tool for a complete list of these analyzers and their functions.
Generating Observations