edu.umd.cs.findbugs
Class BugInstance

java.lang.Object
  extended by edu.umd.cs.findbugs.BugInstance
All Implemented Interfaces:
XMLWriteable, java.lang.Comparable

public class BugInstance
extends java.lang.Object
implements java.lang.Comparable, XMLWriteable

An instance of a bug pattern. A BugInstance consists of several parts:

The annotations describe classes, methods, fields, source locations, and other relevant context information about the bug instance. Every BugInstance must have at least one ClassAnnotation, which describes the class in which the instance was found. This is the "primary class annotation".

BugInstance objects are built up by calling a string of add methods. (These methods all "return this", so they can be chained). Some of the add methods are specialized to get information automatically from a BetterVisitor or DismantleBytecode object.

Author:
David Hovemeyer
See Also:
BugAnnotation

Field Summary
private static boolean adjustExperimental
          This value is used to indicate whether BugInstances should be reprioritized very low, when the BugPattern is marked as experimental
private  java.util.ArrayList<BugAnnotation> annotationList
           
private  java.lang.String annotationText
           
private  int cachedHashCode
           
private static java.lang.String ELEMENT_NAME
           
private static int INVALID_HASH_CODE
          This value is used to indicate that the cached hashcode is invalid, and should be recomputed.
private  ClassAnnotation primaryClassAnnotation
           
private  FieldAnnotation primaryFieldAnnotation
           
private  MethodAnnotation primaryMethodAnnotation
           
private  int priority
           
private  java.lang.String type
           
private static java.lang.String USER_ANNOTATION_ELEMENT_NAME
           
 
Constructor Summary
BugInstance(Detector detector, java.lang.String type, int priority)
          Create a new BugInstance.
BugInstance(java.lang.String type, int priority)
          Constructor.
 
Method Summary
(package private)  void add(BugAnnotation annotation)
           
 BugInstance addCalledMethod(DismantleBytecode visitor)
          Add a method annotation for the method which has been called by the method currently being visited by given visitor.
 BugInstance addCalledMethod(org.apache.bcel.generic.MethodGen methodGen, org.apache.bcel.generic.InvokeInstruction inv)
          Add a method annotation for the method which is called by given instruction.
 BugInstance addCalledMethod(java.lang.String className, java.lang.String methodName, java.lang.String methodSig)
          Add a method annotation.
 BugInstance addClass(org.apache.bcel.classfile.JavaClass jclass)
          Add a class annotation.
 BugInstance addClass(PreorderVisitor visitor)
          Add a class annotation for the class that the visitor is currently visiting.
 BugInstance addClass(java.lang.String className)
          Add a class annotation.
 BugInstance addClassAndMethod(org.apache.bcel.generic.MethodGen methodGen, java.lang.String sourceFile)
          Add class and method annotations for given method.
 BugInstance addClassAndMethod(PreorderVisitor visitor)
          Add a class annotation and a method annotation for the class and method which the given visitor is currently visiting.
 BugInstance addField(FieldAnnotation fieldAnnotation)
          Add a field annotation
 BugInstance addField(FieldVariable field)
          Add a field annotation for a FieldVariable matched in a ByteCodePattern.
 BugInstance addField(java.lang.String className, java.lang.String fieldName, java.lang.String fieldSig, boolean isStatic)
          Add a field annotation.
 BugInstance addField(XField xfield)
          Add a field annotation for an XField.
 BugInstance addInt(int value)
          Add an integer annotation.
 BugInstance addMethod(MethodAnnotation methodAnnotation)
          Add a method annotation.
 BugInstance addMethod(org.apache.bcel.generic.MethodGen methodGen, java.lang.String sourceFile)
          Add a method annotation.
 BugInstance addMethod(PreorderVisitor visitor)
          Add a method annotation for the method which the given visitor is currently visiting.
 BugInstance addMethod(java.lang.String className, java.lang.String methodName, java.lang.String methodSig)
          Add a method annotation.
 BugInstance addReferencedField(DismantleBytecode visitor)
          Add a field annotation for the field which has just been accessed by the method currently being visited by given visitor.
 BugInstance addReferencedField(FieldAnnotation fa)
          Add a field annotation for the field referenced by the FieldAnnotation parameter
 BugInstance addSourceLine(DismantleBytecode visitor)
          Add a source line annotation for instruction currently being visited by given visitor.
 BugInstance addSourceLine(org.apache.bcel.generic.MethodGen methodGen, java.lang.String sourceFile, org.apache.bcel.generic.InstructionHandle handle)
          Add a source line annotation for the given instruction in the given method.
 BugInstance addSourceLine(org.apache.bcel.generic.MethodGen methodGen, java.lang.String sourceFile, org.apache.bcel.generic.InstructionHandle start, org.apache.bcel.generic.InstructionHandle end)
          Add a source line annotation describing a range of instructions.
 BugInstance addSourceLine(PreorderVisitor visitor, int pc)
          Add a source line annotation for instruction whose PC is given in the method that the given visitor is currently visiting.
 BugInstance addSourceLine(SourceLineAnnotation sourceLine)
          Add a source line annotation.
 BugInstance addSourceLineRange(PreorderVisitor visitor, int startPC, int endPC)
          Add a source line annotation describing the source line numbers for a range of instructions in the method being visited by the given visitor.
private  void addSourceLinesForMethod(MethodAnnotation methodAnnotation, SourceLineAnnotation sourceLineAnnotation)
           
 BugInstance addSuperclass(PreorderVisitor visitor)
          Add a class annotation for the superclass of the class the visitor is currently visiting.
 BugInstance addUnknownSourceLine(java.lang.String className, java.lang.String sourceFile)
          Add a non-specific source line annotation.
 BugInstance addVisitedField(PreorderVisitor visitor)
          Add a field annotation for the field which is being visited by given visitor.
 java.util.Iterator<BugAnnotation> annotationIterator()
          Get an Iterator over all bug annotations.
 boolean annotationTextContainsWord(java.lang.String word)
          Determine whether or not the annotation text contains the given word.
 int compareTo(java.lang.Object o)
           
 BugInstance describe(java.lang.String description)
          Add a description to the most recently added bug annotation.
 boolean equals(java.lang.Object o)
           
 java.lang.String getAbbrev()
          Get the abbreviation of this bug instance's BugPattern.
 java.lang.String getAnnotationText()
          Get the user annotation text.
 BugPattern getBugPattern()
          Get the BugPattern.
 java.lang.String getMessage()
          Format a string describing this bug instance.
 ClassAnnotation getPrimaryClass()
          Get the primary class annotation, which indicates where the bug occurs.
 FieldAnnotation getPrimaryField()
          Get the primary method annotation, which indicates where the bug occurs.
 MethodAnnotation getPrimaryMethod()
          Get the primary method annotation, which indicates where the bug occurs.
 SourceLineAnnotation getPrimarySourceLineAnnotation()
          Get the primary source line annotation.
 int getPriority()
          Get the bug priority.
 java.util.Set<java.lang.String> getTextAnnotationWords()
          Get set of words in the text annotation.
 java.lang.String getType()
          Get the bug type.
 int hashCode()
           
 boolean isExperimental()
          Is this bug instance the result of an experimental detector?
static void setAdjustExperimental(boolean adjust)
           
 void setAnnotationText(java.lang.String annotationText)
          Set the user annotation text.
 void setPriority(int p)
          Set the bug priority.
 java.lang.String toString()
          Convert to String.
 void writeXML(XMLOutput xmlOutput)
          Write this object to given XMLOutput.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

type

private java.lang.String type

priority

private int priority

annotationList

private java.util.ArrayList<BugAnnotation> annotationList

primaryClassAnnotation

private ClassAnnotation primaryClassAnnotation

primaryMethodAnnotation

private MethodAnnotation primaryMethodAnnotation

primaryFieldAnnotation

private FieldAnnotation primaryFieldAnnotation

cachedHashCode

private int cachedHashCode

annotationText

private java.lang.String annotationText

INVALID_HASH_CODE

private static final int INVALID_HASH_CODE
This value is used to indicate that the cached hashcode is invalid, and should be recomputed.

See Also:
Constant Field Values

adjustExperimental

private static boolean adjustExperimental
This value is used to indicate whether BugInstances should be reprioritized very low, when the BugPattern is marked as experimental


ELEMENT_NAME

private static final java.lang.String ELEMENT_NAME
See Also:
Constant Field Values

USER_ANNOTATION_ELEMENT_NAME

private static final java.lang.String USER_ANNOTATION_ELEMENT_NAME
See Also:
Constant Field Values
Constructor Detail

BugInstance

public BugInstance(java.lang.String type,
                   int priority)
Constructor.

Parameters:
type - the bug type
priority - the bug priority

BugInstance

public BugInstance(Detector detector,
                   java.lang.String type,
                   int priority)
Create a new BugInstance. This is the constructor that should be used by Detectors.

Parameters:
detector - the Detector that is reporting the BugInstance
type - the bug type
priority - the bug priority
Method Detail

setAdjustExperimental

public static void setAdjustExperimental(boolean adjust)

getType

public java.lang.String getType()
Get the bug type.


getBugPattern

public BugPattern getBugPattern()
Get the BugPattern.


getPriority

public int getPriority()
Get the bug priority.


setPriority

public void setPriority(int p)
Set the bug priority.


isExperimental

public boolean isExperimental()
Is this bug instance the result of an experimental detector?


getPrimaryClass

public ClassAnnotation getPrimaryClass()
Get the primary class annotation, which indicates where the bug occurs.


getPrimaryMethod

public MethodAnnotation getPrimaryMethod()
Get the primary method annotation, which indicates where the bug occurs.


getPrimaryField

public FieldAnnotation getPrimaryField()
Get the primary method annotation, which indicates where the bug occurs.


getPrimarySourceLineAnnotation

public SourceLineAnnotation getPrimarySourceLineAnnotation()
Get the primary source line annotation.

Returns:
the source line annotation, or null if there is no source line annotation

annotationIterator

public java.util.Iterator<BugAnnotation> annotationIterator()
Get an Iterator over all bug annotations.


getAbbrev

public java.lang.String getAbbrev()
Get the abbreviation of this bug instance's BugPattern. This is the same abbreviation used by the BugCode which the BugPattern is a particular species of.


setAnnotationText

public void setAnnotationText(java.lang.String annotationText)
Set the user annotation text.

Parameters:
annotationText - the user annotation text

getAnnotationText

public java.lang.String getAnnotationText()
Get the user annotation text.

Returns:
the user annotation text

annotationTextContainsWord

public boolean annotationTextContainsWord(java.lang.String word)
Determine whether or not the annotation text contains the given word.

Parameters:
word - the word
Returns:
true if the annotation text contains the word, false otherwise

getTextAnnotationWords

public java.util.Set<java.lang.String> getTextAnnotationWords()
Get set of words in the text annotation.


addClassAndMethod

public BugInstance addClassAndMethod(PreorderVisitor visitor)
Add a class annotation and a method annotation for the class and method which the given visitor is currently visiting.

Parameters:
visitor - the BetterVisitor
Returns:
this object

addClassAndMethod

public BugInstance addClassAndMethod(org.apache.bcel.generic.MethodGen methodGen,
                                     java.lang.String sourceFile)
Add class and method annotations for given method.

Parameters:
methodGen - the method
sourceFile - source file the method is defined in
Returns:
this object

addClass

public BugInstance addClass(java.lang.String className)
Add a class annotation. If this is the first class annotation added, it becomes the primary class annotation.

Parameters:
className - the name of the class
Returns:
this object

addClass

public BugInstance addClass(org.apache.bcel.classfile.JavaClass jclass)
Add a class annotation. If this is the first class annotation added, it becomes the primary class annotation.

Parameters:
jclass - the JavaClass object for the class
Returns:
this object

addClass

public BugInstance addClass(PreorderVisitor visitor)
Add a class annotation for the class that the visitor is currently visiting.

Parameters:
visitor - the BetterVisitor
Returns:
this object

addSuperclass

public BugInstance addSuperclass(PreorderVisitor visitor)
Add a class annotation for the superclass of the class the visitor is currently visiting.

Parameters:
visitor - the BetterVisitor
Returns:
this object

addField

public BugInstance addField(java.lang.String className,
                            java.lang.String fieldName,
                            java.lang.String fieldSig,
                            boolean isStatic)
Add a field annotation.

Parameters:
className - name of the class containing the field
fieldName - the name of the field
fieldSig - type signature of the field
isStatic - whether or not the field is static
Returns:
this object

addField

public BugInstance addField(FieldAnnotation fieldAnnotation)
Add a field annotation

Parameters:
fieldAnnotation - the field annotation
Returns:
this object

addField

public BugInstance addField(FieldVariable field)
Add a field annotation for a FieldVariable matched in a ByteCodePattern.

Parameters:
field - the FieldVariable
Returns:
this object

addField

public BugInstance addField(XField xfield)
Add a field annotation for an XField.

Parameters:
xfield - the XField
Returns:
this object

addReferencedField

public BugInstance addReferencedField(DismantleBytecode visitor)
Add a field annotation for the field which has just been accessed by the method currently being visited by given visitor. Assumes that a getfield/putfield or getstatic/putstatic has just been seen.

Parameters:
visitor - the DismantleBytecode object
Returns:
this object

addReferencedField

public BugInstance addReferencedField(FieldAnnotation fa)
Add a field annotation for the field referenced by the FieldAnnotation parameter


addVisitedField

public BugInstance addVisitedField(PreorderVisitor visitor)
Add a field annotation for the field which is being visited by given visitor.

Parameters:
visitor - the visitor
Returns:
this object

addMethod

public BugInstance addMethod(java.lang.String className,
                             java.lang.String methodName,
                             java.lang.String methodSig)
Add a method annotation. If this is the first method annotation added, it becomes the primary method annotation.

Parameters:
className - name of the class containing the method
methodName - name of the method
methodSig - type signature of the method
Returns:
this object

addMethod

public BugInstance addMethod(org.apache.bcel.generic.MethodGen methodGen,
                             java.lang.String sourceFile)
Add a method annotation. If this is the first method annotation added, it becomes the primary method annotation. If the method has source line information, then a SourceLineAnnotation is added to the method.

Parameters:
methodGen - the MethodGen object for the method
sourceFile - source file method is defined in
Returns:
this object

addMethod

public BugInstance addMethod(PreorderVisitor visitor)
Add a method annotation for the method which the given visitor is currently visiting. If the method has source line information, then a SourceLineAnnotation is added to the method.

Parameters:
visitor - the BetterVisitor
Returns:
this object

addCalledMethod

public BugInstance addCalledMethod(DismantleBytecode visitor)
Add a method annotation for the method which has been called by the method currently being visited by given visitor. Assumes that the visitor has just looked at an invoke instruction of some kind.

Parameters:
visitor - the DismantleBytecode object
Returns:
this object

addCalledMethod

public BugInstance addCalledMethod(java.lang.String className,
                                   java.lang.String methodName,
                                   java.lang.String methodSig)
Add a method annotation.

Returns:
this object

addCalledMethod

public BugInstance addCalledMethod(org.apache.bcel.generic.MethodGen methodGen,
                                   org.apache.bcel.generic.InvokeInstruction inv)
Add a method annotation for the method which is called by given instruction.

Parameters:
methodGen - the method containing the call
inv - the InvokeInstruction
Returns:
this object

addMethod

public BugInstance addMethod(MethodAnnotation methodAnnotation)
Add a method annotation. If this is the first method annotation added, it becomes the primary method annotation.

Parameters:
methodAnnotation - the method annotation
Returns:
this object

addInt

public BugInstance addInt(int value)
Add an integer annotation.

Parameters:
value - the integer value
Returns:
this object

addSourceLine

public BugInstance addSourceLine(SourceLineAnnotation sourceLine)
Add a source line annotation.

Parameters:
sourceLine - the source line annotation
Returns:
this object

addSourceLine

public BugInstance addSourceLine(PreorderVisitor visitor,
                                 int pc)
Add a source line annotation for instruction whose PC is given in the method that the given visitor is currently visiting. Note that if the method does not have line number information, then no source line annotation will be added.

Parameters:
visitor - a BetterVisitor that is currently visiting the method
pc - bytecode offset of the instruction
Returns:
this object

addSourceLine

public BugInstance addSourceLine(org.apache.bcel.generic.MethodGen methodGen,
                                 java.lang.String sourceFile,
                                 org.apache.bcel.generic.InstructionHandle handle)
Add a source line annotation for the given instruction in the given method. Note that if the method does not have line number information, then no source line annotation will be added.

Parameters:
methodGen - the method being visited
sourceFile - source file the method is defined in
handle - the InstructionHandle containing the visited instruction
Returns:
this object

addSourceLine

public BugInstance addSourceLine(org.apache.bcel.generic.MethodGen methodGen,
                                 java.lang.String sourceFile,
                                 org.apache.bcel.generic.InstructionHandle start,
                                 org.apache.bcel.generic.InstructionHandle end)
Add a source line annotation describing a range of instructions.

Parameters:
methodGen - the method
sourceFile - source file the method is defined in
start - the start instruction in the range
end - the end instruction in the range (inclusive)
Returns:
this object

addSourceLineRange

public BugInstance addSourceLineRange(PreorderVisitor visitor,
                                      int startPC,
                                      int endPC)
Add a source line annotation describing the source line numbers for a range of instructions in the method being visited by the given visitor. Note that if the method does not have line number information, then no source line annotation will be added.

Parameters:
visitor - a BetterVisitor which is visiting the method
startPC - the bytecode offset of the start instruction in the range
endPC - the bytecode offset of the end instruction in the range
Returns:
this object

addSourceLine

public BugInstance addSourceLine(DismantleBytecode visitor)
Add a source line annotation for instruction currently being visited by given visitor. Note that if the method does not have line number information, then no source line annotation will be added.

Parameters:
visitor - a DismantleBytecode visitor that is currently visiting the instruction
Returns:
this object

addUnknownSourceLine

public BugInstance addUnknownSourceLine(java.lang.String className,
                                        java.lang.String sourceFile)
Add a non-specific source line annotation. This will result in the entire source file being displayed.

Parameters:
className - the class name
sourceFile - the source file name
Returns:
this object

getMessage

public java.lang.String getMessage()
Format a string describing this bug instance.

Returns:
the description

describe

public BugInstance describe(java.lang.String description)
Add a description to the most recently added bug annotation.

Parameters:
description - the description to add
Returns:
this object

toString

public java.lang.String toString()
Convert to String. This method returns the "short" message describing the bug, as opposed to the longer format returned by getMessage(). The short format is appropriate for the tree view in a GUI, where the annotations are listed separately as part of the overall bug instance.

Overrides:
toString in class java.lang.Object

writeXML

public void writeXML(XMLOutput xmlOutput)
              throws java.io.IOException
Description copied from interface: XMLWriteable
Write this object to given XMLOutput.

Specified by:
writeXML in interface XMLWriteable
Parameters:
xmlOutput - the XMLOutput for the document
Throws:
java.io.IOException

add

void add(BugAnnotation annotation)

addSourceLinesForMethod

private void addSourceLinesForMethod(MethodAnnotation methodAnnotation,
                                     SourceLineAnnotation sourceLineAnnotation)

hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object o)
Overrides:
equals in class java.lang.Object

compareTo

public int compareTo(java.lang.Object o)
Specified by:
compareTo in interface java.lang.Comparable