com.ibm.dtfj.analyzer.helpers.objectwrapper
Class ObjectFinder

java.lang.Object
  extended by TranslatableAnalyzer
      extended by com.ibm.dtfj.analyzer.base.SimpleAnalyzerBean
          extended by com.ibm.dtfj.analyzer.helpers.objectwrapper.ObjectFinder
All Implemented Interfaces:
IAnalyzerBase, IReport, IWrapper

public class ObjectFinder
extends SimpleAnalyzerBean

Find and count instances of particular objects in the Java runtime
Attempts to scan the heap only once and to create a cache of "interesting" objects.

This bean tries to scan the heap only once and to create a cache of "interesting" objects, so that it can quickly find instances of these objects without having to re-scan the entire heap each time when looking for a different object.

We use a regular expression to determine which objects are deemed "interesting" enough to be placed in the cache. That regular expression that is matched against the class name of each object found while scanning the heap. If the class name matches, instances of that object are cached; otherwise they are simply counted, but we don't keep a copy of each instance and thus we cannot return any instances in a call to findObjects().

This allows the cache to be substantially smaller than the heap from which it was built, without much loss of useful information, since in practice, a large percentage of heap objects are usually various arrays and low-level Java library classes that we seldom want to lookup directly anyway.

In addition, the property cachedInstancesMax sets a limit on the number of instances of any one class that are kept in the cache. If there are more than cachedInstancesMax instances of one given class in the heap, any additional instances are not cached. A subsequent call to findObjects() for that class will simply return the first cachedInstancesMax encountered.

By default, we cache 100 instances of each class that matches com/*, javax/* or org/*. This default can be changed by invoking addCachingPattern.


Constructor Summary
ObjectFinder()
           
 
Method Summary
 void addCachingPattern(java.lang.String regex, int maxInstances)
          Add a pattern (regexp) of class names for which we will cache instances while scanning the heap, so that these instances can be subsequently found by a call to findObjects().
 com.ibm.dtfj.java.JavaObject findObjectByObjectID(com.ibm.dtfj.image.ImagePointer id)
          Given an object ID (address), find the corresponding JavaObjectt (if any).
 java.util.Set findObjects(com.ibm.dtfj.java.JavaClass cls, int maxcount)
          Find all the object instances of a given class identified by JavaClass
 java.util.Set findObjects(java.lang.String clsname, int maxcount)
          Find all the object instances of a given class identified by class name (across all classloaders)
 int getCachingPriority()
          Force caching of this analyzer
 int getCountClassObjects()
           
 int getCountDistinctClassesScanned()
           
 int getCountInstancesCached()
           
 int getCountInstancesScanned()
           
 int getCountObjectArrays()
           
 int getCountPrimitiveArrays()
           
 int getCountSingleObjects()
           
static ObjectFinder getInstance(IAnalyzerContext context, com.ibm.dtfj.java.JavaRuntime parent)
          Find the ObjectFinder bean instance associated with a given parent JavaRuntime (create it if necessary)
 int getMaxInstancesForClass(com.ibm.dtfj.java.JavaClass cls)
          Figure-out if we should be caching a particular class (by JavaClass) and how many instances to cache.
 int getMaxInstancesForClass(java.lang.String clsname)
          Figure-out if we should be caching a particular class (by name) and how many instances to cache
 int getObjectCount(com.ibm.dtfj.java.JavaClass cls)
          Return a count of all the object instances of a given class identified by JavaClass
 int getObjectCount(java.lang.String clsname)
          Return a count of all the object instances of a given class identified by class name (across all classloaders)
 int getObjectCountIncludingSubclasses(com.ibm.dtfj.java.JavaClass cls)
          Return a count of all instances of a given class or any of its subclasses, identified by JavaClass
 int getObjectCountIncludingSubclasses(java.lang.String clsname)
          Return a count of all instances of a given class or any of its subclasses, identified by class name (across all classloaders)
 java.lang.String getShortDescription()
          Return a short description of the analyzer purpose.
 java.lang.String getVersion()
          Get version information for this analyser.
 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.
 int printObjectCount(IAnalysisReport out, java.lang.String label, java.lang.String clsname)
          Print a count of all the object instances of a given class identified by class name (across all classloaders).
 int printObjectCountIncludingSubclasses(IAnalysisReport out, java.lang.String label, java.lang.String clsname)
          Print a count of all instances of a given class or any of its subclasses, identified by class name (across all classloaders).
 void printOneClass(IAnalysisReport out, java.lang.String clsname, int maxcount)
          Print all the object instances of a given class identified by class name (across all classloaders), as a segment of a report
 IAnalysisReport produceReport()
          Generate a report which will be encapsulated in the IAnalysisReport object for later use by some formatter.
 void setParent(java.lang.Object parent)
          Set the parent JavaRuntime underlying this analyzer bean.
 
Methods inherited from class com.ibm.dtfj.analyzer.base.SimpleAnalyzerBean
allocateReport, allocateReportOptions, allocateSecondaryReport, getCategories, getContext, getIdentityString, getInstance, getLogger, getLongDescription, getName, getNextValidObject, getParent, getReportExtensionHelper, getResourceBundleName, printEmbeddedReport, printEmbeddedReport, printEmbeddedReportWithOptions, printEmbeddedReportWithOptions, printReportInfoHeader, recordInternalExceptionStatic, setContext
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ObjectFinder

public ObjectFinder()
Method Detail

getVersion

public java.lang.String getVersion()
Description copied from interface: IAnalyzerBase
Get version information for this analyser.

Specified by:
getVersion in interface IAnalyzerBase
Overrides:
getVersion in class SimpleAnalyzerBean
Returns:
- a String containing the version information
See Also:
IAnalyzerBase.getVersion()

getShortDescription

public java.lang.String getShortDescription()
Description copied from interface: IAnalyzerBase
Return a short description of the analyzer purpose. This will be printed prior to running the analyser.

Specified by:
getShortDescription in interface IAnalyzerBase
Overrides:
getShortDescription in class SimpleAnalyzerBean
Returns:
- the short description
See Also:
IAnalyzerBase.getShortDescription()

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
Overrides:
isPrimaryAnalyzer in class SimpleAnalyzerBean
Returns:
true if this is a primary analyzer, false otherwise
See Also:
IAnalyzerBase.isPrimaryAnalyzer()

getInstance

public static ObjectFinder getInstance(IAnalyzerContext context,
                                       com.ibm.dtfj.java.JavaRuntime parent)
Find the ObjectFinder bean instance associated with a given parent JavaRuntime (create it if necessary)

Parameters:
context - the AnalyzerContext in which to locate this bean instance
parent - the parent JavaRuntime underlying this analyzer bean
Returns:
the desired ObjectFinder analyzer bean

setParent

public void setParent(java.lang.Object parent)
Set the parent JavaRuntime underlying this analyzer bean.

Specified by:
setParent in interface IWrapper
Overrides:
setParent in class SimpleAnalyzerBean
Parameters:
parent - The parent object to set. Must be of type JavaRuntime. compatible with the type of analyzer bean that receives it
See Also:
IWrapper.setParent(java.lang.Object)

getCachingPriority

public int getCachingPriority()
Force caching of this analyzer

Specified by:
getCachingPriority in interface IAnalyzerBase
Overrides:
getCachingPriority in class SimpleAnalyzerBean
Returns:
the caching priority, as a number between 0 and 10
See Also:
SimpleAnalyzerBean.getCachingPriority()

findObjects

public java.util.Set findObjects(com.ibm.dtfj.java.JavaClass cls,
                                 int maxcount)
                          throws com.ibm.dtfj.image.DTFJException
Find all the object instances of a given class identified by JavaClass

Parameters:
cls - the JavaClass for which we want to find all instances
maxcount - the maximum number of objects to return, or 0 for all
Returns:
a Set containing all the JavaObjects found
Throws:
com.ibm.dtfj.image.DTFJException

getObjectCount

public int getObjectCount(com.ibm.dtfj.java.JavaClass cls)
                   throws com.ibm.dtfj.image.DTFJException
Return a count of all the object instances of a given class identified by JavaClass

Parameters:
cls - the JavaClass for which we want to find all instances
Returns:
a count of all object instances for this given class
Throws:
com.ibm.dtfj.image.DTFJException

getObjectCountIncludingSubclasses

public int getObjectCountIncludingSubclasses(com.ibm.dtfj.java.JavaClass cls)
                                      throws com.ibm.dtfj.image.DTFJException
Return a count of all instances of a given class or any of its subclasses, identified by JavaClass

Parameters:
cls - the JavaClass for which we want to count all instances
Returns:
a count of all object instances for this given class and its subclasses
Throws:
com.ibm.dtfj.image.DTFJException

getObjectCountIncludingSubclasses

public int getObjectCountIncludingSubclasses(java.lang.String clsname)
                                      throws com.ibm.dtfj.image.DTFJException
Return a count of all instances of a given class or any of its subclasses, identified by class name (across all classloaders)

Parameters:
clsname - the class name for which we want to count all instances
Returns:
a count of all object instances for this given class and its subclasses
Throws:
com.ibm.dtfj.image.DTFJException

printObjectCountIncludingSubclasses

public int printObjectCountIncludingSubclasses(IAnalysisReport out,
                                               java.lang.String label,
                                               java.lang.String clsname)
Print a count of all instances of a given class or any of its subclasses, identified by class name (across all classloaders).

This method is provided purely as convenience when writing reports. One could also call getObjectCount() and print its return value explicitly (and handle any errors explicitly).

Parameters:
out - a AnalysisReport object to which to write the output
label - a name to use as title for the report entry showing the count
clsname - the class name for which we want to count all instances
Returns:
a count of all object instances for this given class, or -1 if there was an error

findObjects

public java.util.Set findObjects(java.lang.String clsname,
                                 int maxcount)
                          throws com.ibm.dtfj.image.DTFJException
Find all the object instances of a given class identified by class name (across all classloaders)

Parameters:
clsname - the class name for which we want to find all instances
maxcount - the maximum number of objects to return, or 0 for all
Returns:
a Set containing all the JavaObjects found
Throws:
com.ibm.dtfj.image.DTFJException

findObjectByObjectID

public com.ibm.dtfj.java.JavaObject findObjectByObjectID(com.ibm.dtfj.image.ImagePointer id)
                                                  throws com.ibm.dtfj.image.DTFJException
Given an object ID (address), find the corresponding JavaObjectt (if any).

Parameters:
id - object ID of the desired JavaObject
Returns:
the corresponding JavaObject, or null if not found
Throws:
com.ibm.dtfj.image.DTFJException

printOneClass

public void printOneClass(IAnalysisReport out,
                          java.lang.String clsname,
                          int maxcount)
Print all the object instances of a given class identified by class name (across all classloaders), as a segment of a report

Parameters:
out - a AnalysisReport object to which to write the output
clsname - the class name for which we want to find all instances
maxcount - the maximum number of objects to return, or 0 for all

getObjectCount

public int getObjectCount(java.lang.String clsname)
                   throws com.ibm.dtfj.image.DTFJException
Return a count of all the object instances of a given class identified by class name (across all classloaders)

Parameters:
clsname - the class name for which we want to count all instances
Returns:
a count of all object instances for this given class
Throws:
com.ibm.dtfj.image.DTFJException

printObjectCount

public int printObjectCount(IAnalysisReport out,
                            java.lang.String label,
                            java.lang.String clsname)
Print a count of all the object instances of a given class identified by class name (across all classloaders).

This method is provided purely as convenience when writing reports. One could also call getObjectCount() and print its return value explicitly (and handle any errors explicitly).

Parameters:
out - a AnalysisReport object to which to write the output
label - a name to use as title for the report entry showing the count
clsname - the class name for which we want to count all instances
Returns:
a count of all object instances for this given class, or -1 if there was an error

addCachingPattern

public void addCachingPattern(java.lang.String regex,
                              int maxInstances)
Add a pattern (regexp) of class names for which we will cache instances while scanning the heap, so that these instances can be subsequently found by a call to findObjects().

This pattern is used to limit the number object instances that get cached when scanning to heap, to avoid caching hundreds of thousands of "uninteresting" objects.

The pattern added with this call is in addition to the built-in patterns always cached by this analyzer: com/*, javax/*, org/*

Note that adding a pattern after the analyzer has already been used to look-up objects, will have the effect of discarding any previous results of a heap scan, and triggering a new heap scan.

Parameters:
regex - a string representing the pattern in regexp format
maxInstances - an integer representing the maximum number of instances to cache per class

getMaxInstancesForClass

public int getMaxInstancesForClass(java.lang.String clsname)
Figure-out if we should be caching a particular class (by name) and how many instances to cache

Parameters:
clsname - the class name
Returns:
the maximum number of instances cached for a given class

getMaxInstancesForClass

public int getMaxInstancesForClass(com.ibm.dtfj.java.JavaClass cls)
                            throws com.ibm.dtfj.image.DTFJException
Figure-out if we should be caching a particular class (by JavaClass) and how many instances to cache. This check also accounts for superclasses of the specified JavaClass.

Parameters:
cls - the JavaClass to check
Returns:
the maximum number of instances cached for a given JavaClass or its superclasses
Throws:
com.ibm.dtfj.image.DTFJException

getCountClassObjects

public int getCountClassObjects()
                         throws com.ibm.dtfj.image.DTFJException
Returns:
Returns the number of instances of java.lang.Class found while scanning all objects on the heap.
Throws:
com.ibm.dtfj.image.DTFJException

getCountDistinctClassesScanned

public int getCountDistinctClassesScanned()
                                   throws com.ibm.dtfj.image.DTFJException
Returns:
Returns the number of distinct classes found while scanning all objects on the heap.
Throws:
com.ibm.dtfj.image.DTFJException

getCountInstancesCached

public int getCountInstancesCached()
                            throws com.ibm.dtfj.image.DTFJException
Returns:
Returns the number of object instances cached in the cache while scanning all objects on the heap (i.e. that match the globalCachedInstancesPattern)
Throws:
com.ibm.dtfj.image.DTFJException

getCountInstancesScanned

public int getCountInstancesScanned()
                             throws com.ibm.dtfj.image.DTFJException
Returns:
Returns the total number of objects instances of all types encountered and counted (but not necessarily cached) while scanning all objects on the heap
Throws:
com.ibm.dtfj.image.DTFJException

getCountObjectArrays

public int getCountObjectArrays()
                         throws com.ibm.dtfj.image.DTFJException
Returns:
Returns the total number of instances of object arrays encountered and counted (but not necessarily cached) while scanning all objects on the heap
Throws:
com.ibm.dtfj.image.DTFJException

getCountPrimitiveArrays

public int getCountPrimitiveArrays()
                            throws com.ibm.dtfj.image.DTFJException
Returns:
Returns the total number of instances of primitive arrays encountered and counted (but not necessarily cached) while scanning all objects on the heap
Throws:
com.ibm.dtfj.image.DTFJException

getCountSingleObjects

public int getCountSingleObjects()
                          throws com.ibm.dtfj.image.DTFJException
Returns:
Returns the total number of instances of single objects (not arrays) encountered and counted (but not necessarily cached) while scanning all objects on the heap
Throws:
com.ibm.dtfj.image.DTFJException

produceReport

public IAnalysisReport produceReport()
Description copied from interface: IReport
Generate a report which will be encapsulated in the IAnalysisReport object for later use by some formatter.

Specified by:
produceReport in interface IReport
Overrides:
produceReport in class SimpleAnalyzerBean
Returns:
- the generic report object which will be given to some formatter
See Also:
IReport.produceReport()


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