edu.umd.cs.findbugs

Class SourceLineAnnotation

java.lang.Object

edu.umd.cs.findbugs.SourceLineAnnotation

All Implemented Interfaces:

BugAnnotation, XMLWriteable, XMLWriteableWithMessages, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<BugAnnotation>

public class SourceLineAnnotation
extends java.lang.Object
implements BugAnnotation

A BugAnnotation that records a range of source lines in a class.

Author:

David Hovemeyer

See Also:

BugAnnotation, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static char	CANONICAL_PACKAGE_SEPARATOR
static java.lang.String	DEFAULT_ROLE
static java.lang.String	DEFAULT_ROLE_UNKNOWN_LINE
static java.lang.String	DESCRIPTION_LAST_CHANGE
static java.lang.String	DESCRIPTION_LOOP_BOTTOM
static java.lang.String	ROLE_ANOTHER_INSTANCE
static java.lang.String	ROLE_CALLED_FROM_SUPERCLASS_AT
static java.lang.String	ROLE_FIELD_SET_TOO_LATE_AT
static java.lang.String	ROLE_GENERATED_AT
static java.lang.String	ROLE_LOCK_OBTAINED_AT
static java.lang.String	ROLE_OBLIGATION_CREATED
static java.lang.String	ROLE_OBLIGATION_CREATED_BY_WILLCLOSE_PARAMETER
static java.lang.String	ROLE_PATH_CONTINUES
static java.lang.String	ROLE_UNREACHABLE_CODE
static java.lang.String	UNKNOWN_SOURCE_FILE String returned if the source file is unknown.

Fields inherited from interface edu.umd.cs.findbugs.BugAnnotation

MESSAGE_TAG

Constructor Summary

Constructors

Constructor and Description
SourceLineAnnotation(java.lang.String className, java.lang.String sourceFile, int startLine, int endLine, int startBytecode, int endBytecode) Constructor.

Method Summary

Modifier and Type	Method and Description
void	accept(BugAnnotationVisitor visitor) Accept a BugAnnotationVisitor.
static void	clearGenerateRelativeSource()
java.lang.Object	clone()
int	compareTo(BugAnnotation o)
static SourceLineAnnotation	createReallyUnknown(java.lang.String className) Factory method to create an unknown source line annotation.
static SourceLineAnnotation	createUnknown(java.lang.String className) Factory method to create an unknown source line annotation.
static SourceLineAnnotation	createUnknown(java.lang.String className, java.lang.String sourceFile) Factory method to create an unknown source line annotation.
static SourceLineAnnotation	createUnknown(java.lang.String className, java.lang.String sourceFile, int startBytecode, int endBytecode) Factory method to create an unknown source line annotation.
boolean	equals(java.lang.Object o)
static SourceLineAnnotation	forEntireMethod(org.apache.bcel.classfile.JavaClass javaClass, org.apache.bcel.classfile.Method method) Create a SourceLineAnnotation covering an entire method.
static SourceLineAnnotation	forEntireMethod(org.apache.bcel.classfile.JavaClass javaClass, XMethod xmethod) Create a SourceLineAnnotation covering an entire method.
static SourceLineAnnotation	forEntireMethod(java.lang.String className, java.lang.String sourceFile, org.apache.bcel.classfile.LineNumberTable lineNumberTable, int codeSize) Create a SourceLineAnnotation covering an entire method.
static SourceLineAnnotation	forFirstLineOfMethod(MethodDescriptor methodDescriptor) Make a best-effort attempt to create a SourceLineAnnotation for the first line of a method.
java.lang.String	format(java.lang.String key, ClassAnnotation primaryClass) Format the annotation as a String.
static SourceLineAnnotation	fromRawData(java.lang.String className, java.lang.String sourceFile, int startLine, int endLine, int startPC, int endPC)
static SourceLineAnnotation	fromVisitedInstruction(BytecodeScanningDetector visitor) Factory method for creating a source line annotation describing the source line number for the instruction being visited by given visitor.
static SourceLineAnnotation	fromVisitedInstruction(BytecodeScanningDetector visitor, int pc) Factory method for creating a source line annotation describing the source line number for the instruction being visited by given visitor.
static SourceLineAnnotation	fromVisitedInstruction(ClassContext classContext, org.apache.bcel.generic.MethodGen methodGen, java.lang.String sourceFile, org.apache.bcel.generic.InstructionHandle handle) Factory method for creating a source line annotation describing the source line number for a visited instruction.
static SourceLineAnnotation	fromVisitedInstruction(ClassContext classContext, org.apache.bcel.classfile.Method method, org.apache.bcel.generic.InstructionHandle handle) Create from Method and InstructionHandle in a visited class.
static SourceLineAnnotation	fromVisitedInstruction(ClassContext classContext, org.apache.bcel.classfile.Method method, int pc) Create from Method and bytecode offset in a visited class.
static SourceLineAnnotation	fromVisitedInstruction(ClassContext classContext, org.apache.bcel.classfile.Method method, Location loc) Create from Method and Location in a visited class.
static SourceLineAnnotation	fromVisitedInstruction(ClassContext classContext, PreorderVisitor visitor, int pc) Factory method for creating a source line annotation describing the source line number for the instruction being visited by given visitor.
static SourceLineAnnotation	fromVisitedInstruction(org.apache.bcel.classfile.JavaClass jclass, org.apache.bcel.classfile.Method method, int pc) Create from Method and bytecode offset in a visited class.
static SourceLineAnnotation	fromVisitedInstruction(MethodDescriptor methodDescriptor, int position)
static SourceLineAnnotation	fromVisitedInstruction(MethodDescriptor methodDescriptor, Location location) Create from MethodDescriptor and Location of visited instruction.
static SourceLineAnnotation	fromVisitedInstructionRange(BytecodeScanningDetector visitor, int startPC, int endPC) Factory method for creating a source line annotation describing the source line numbers for a range of instructions in the method being visited by the given visitor.
static SourceLineAnnotation	fromVisitedInstructionRange(ClassContext classContext, org.apache.bcel.generic.MethodGen methodGen, java.lang.String sourceFile, org.apache.bcel.generic.InstructionHandle start, org.apache.bcel.generic.InstructionHandle end) Factory method for creating a source line annotation describing the source line numbers for a range of instruction in a method.
static SourceLineAnnotation	fromVisitedInstructionRange(ClassContext classContext, PreorderVisitor visitor, int startPC, int endPC) Factory method for creating a source line annotation describing the source line numbers for a range of instructions in the method being visited by the given visitor.
static SourceLineAnnotation	fromVisitedMethod(org.apache.bcel.generic.MethodGen methodGen, java.lang.String sourceFile) Factory method for creating a source line annotation describing an entire method.
static SourceLineAnnotation	fromVisitedMethod(PreorderVisitor visitor) Factory method for creating a source line annotation describing an entire method.
static void	generateRelativeSource(java.io.File relativeSourceBase, Project project)
java.lang.String	getClassName()
java.lang.String	getDescription() Get a description of this bug annotation.
int	getEndBytecode() Get end bytecode (inclusive).
int	getEndLine() Get the ending line (inclusive).
java.lang.String	getPackageName()
java.lang.String	getSimpleClassName() Get the simple class name (the part of the name after the dot)
java.lang.String	getSourceFile() Get the source file name.
java.lang.String	getSourcePath()
int	getStartBytecode() Get start bytecode (inclusive).
int	getStartLine() Get the start line (inclusive).
int	hashCode()
boolean	isSignificant() Is this annotation used to compute instance hashes or match bug instances across versions
boolean	isSourceFileKnown() Is the source file known?
boolean	isSynthetic()
boolean	isUnknown() Is this an unknown source line annotation?
void	setDescription(java.lang.String description) Set a description of this bug annotation.
void	setSourceFile(java.lang.String sourceFile) Set the source file name.
void	setSynthetic(boolean synthetic)
java.lang.String	toString()
java.lang.String	toString(ClassAnnotation primaryClass)
void	writeXML(XMLOutput xmlOutput) Write this object to given XMLOutput.
void	writeXML(XMLOutput xmlOutput, boolean addMessages, boolean isPrimary)

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_ROLE

public static final java.lang.String DEFAULT_ROLE

See Also:

Constant Field Values

DEFAULT_ROLE_UNKNOWN_LINE

public static final java.lang.String DEFAULT_ROLE_UNKNOWN_LINE

See Also:

Constant Field Values

ROLE_ANOTHER_INSTANCE

public static final java.lang.String ROLE_ANOTHER_INSTANCE

See Also:

Constant Field Values

ROLE_CALLED_FROM_SUPERCLASS_AT

public static final java.lang.String ROLE_CALLED_FROM_SUPERCLASS_AT

See Also:

Constant Field Values

ROLE_FIELD_SET_TOO_LATE_AT

public static final java.lang.String ROLE_FIELD_SET_TOO_LATE_AT

See Also:

Constant Field Values

ROLE_GENERATED_AT

public static final java.lang.String ROLE_GENERATED_AT

See Also:

Constant Field Values

ROLE_OBLIGATION_CREATED

public static final java.lang.String ROLE_OBLIGATION_CREATED

See Also:

Constant Field Values

ROLE_OBLIGATION_CREATED_BY_WILLCLOSE_PARAMETER

public static final java.lang.String ROLE_OBLIGATION_CREATED_BY_WILLCLOSE_PARAMETER

See Also:

Constant Field Values

ROLE_PATH_CONTINUES

public static final java.lang.String ROLE_PATH_CONTINUES

See Also:

Constant Field Values

ROLE_LOCK_OBTAINED_AT

public static final java.lang.String ROLE_LOCK_OBTAINED_AT

See Also:

Constant Field Values

ROLE_UNREACHABLE_CODE

public static final java.lang.String ROLE_UNREACHABLE_CODE

See Also:

Constant Field Values

UNKNOWN_SOURCE_FILE

public static final java.lang.String UNKNOWN_SOURCE_FILE

String returned if the source file is unknown. This must match what BCEL uses when the source file is unknown.

See Also:

Constant Field Values

CANONICAL_PACKAGE_SEPARATOR

public static final char CANONICAL_PACKAGE_SEPARATOR

See Also:

Constant Field Values

DESCRIPTION_LAST_CHANGE

public static final java.lang.String DESCRIPTION_LAST_CHANGE

See Also:

Constant Field Values

DESCRIPTION_LOOP_BOTTOM

public static final java.lang.String DESCRIPTION_LOOP_BOTTOM

See Also:

Constant Field Values

Constructor Detail

SourceLineAnnotation

public SourceLineAnnotation(@Nonnull @DottedClassName
                            java.lang.String className,
                            @Nonnull
                            java.lang.String sourceFile,
                            int startLine,
                            int endLine,
                            int startBytecode,
                            int endBytecode)

Constructor.

Parameters:

className - the class to which the line number(s) refer

sourceFile - the name of the source file

startLine - the first line (inclusive)

endLine - the ending line (inclusive)

startBytecode - the first bytecode offset (inclusive)

endBytecode - the end bytecode offset (inclusive)

Method Detail

clone

public java.lang.Object clone()

Specified by:

clone in interface BugAnnotation

Overrides:

clone in class java.lang.Object

createUnknown

public static SourceLineAnnotation createUnknown(@DottedClassName
                                                 java.lang.String className,
                                                 java.lang.String sourceFile)

Factory method to create an unknown source line annotation.

Parameters:

className - the class name

sourceFile - the source file name

Returns:

the SourceLineAnnotation

createUnknown

public static SourceLineAnnotation createUnknown(@DottedClassName
                                                 java.lang.String className)

Factory method to create an unknown source line annotation. This variant looks up the source filename automatically based on the class using best effort.

Parameters:

className - the class name

Returns:

the SourceLineAnnotation

createReallyUnknown

public static SourceLineAnnotation createReallyUnknown(@DottedClassName
                                                       java.lang.String className)

Factory method to create an unknown source line annotation. This doesn't use the analysis context.

Parameters:

className - the class name

Returns:

the SourceLineAnnotation

createUnknown

@Nonnull
public static SourceLineAnnotation createUnknown(@DottedClassName
                                                          java.lang.String className,
                                                          java.lang.String sourceFile,
                                                          int startBytecode,
                                                          int endBytecode)

Factory method to create an unknown source line annotation. This variant is used when bytecode offsets are known, but not source lines.

Parameters:

className - the class name

sourceFile - the source file name

Returns:

the SourceLineAnnotation

fromVisitedMethod

public static SourceLineAnnotation fromVisitedMethod(PreorderVisitor visitor)

Factory method for creating a source line annotation describing an entire method.

Parameters:

visitor - a BetterVisitor which is visiting the method

Returns:

the SourceLineAnnotation

fromVisitedMethod

public static SourceLineAnnotation fromVisitedMethod(org.apache.bcel.generic.MethodGen methodGen,
                                                     java.lang.String sourceFile)

Factory method for creating a source line annotation describing an entire method.

Parameters:

methodGen - the method being visited

Returns:

the SourceLineAnnotation, or null if we do not have line number information for the method

forEntireMethod

public static SourceLineAnnotation forEntireMethod(@DottedClassName
                                                   java.lang.String className,
                                                   java.lang.String sourceFile,
                                                   org.apache.bcel.classfile.LineNumberTable lineNumberTable,
                                                   int codeSize)

Create a SourceLineAnnotation covering an entire method.

Parameters:

className - name of the class the method is in

sourceFile - source file containing the method

lineNumberTable - the method's LineNumberTable

codeSize - size in bytes of the method's code

Returns:

a SourceLineAnnotation covering the entire method

forEntireMethod

public static SourceLineAnnotation forEntireMethod(org.apache.bcel.classfile.JavaClass javaClass,
                                                   @CheckForNull
                                                   org.apache.bcel.classfile.Method method)

Create a SourceLineAnnotation covering an entire method.

Parameters:

javaClass - JavaClass containing the method

method - the method

Returns:

a SourceLineAnnotation for the entire method

forEntireMethod

public static SourceLineAnnotation forEntireMethod(org.apache.bcel.classfile.JavaClass javaClass,
                                                   XMethod xmethod)

Create a SourceLineAnnotation covering an entire method.

Parameters:

javaClass - JavaClass containing the method

xmethod - the method

Returns:

a SourceLineAnnotation for the entire method

forFirstLineOfMethod

public static SourceLineAnnotation forFirstLineOfMethod(MethodDescriptor methodDescriptor)

Make a best-effort attempt to create a SourceLineAnnotation for the first line of a method.

Parameters:

methodDescriptor - a method

Returns:

SourceLineAnnotation describing the first line of the method (insofar as we can actually figure that out from the bytecode)

fromVisitedInstruction

public static SourceLineAnnotation fromVisitedInstruction(BytecodeScanningDetector visitor,
                                                          int pc)

Factory method for creating a source line annotation describing the source line number for the instruction being visited by given visitor.

Parameters:

visitor - a BetterVisitor which is visiting the method

pc - the bytecode offset of the instruction in the method

Returns:

the SourceLineAnnotation, or null if we do not have line number information for the instruction

fromVisitedInstruction

public static SourceLineAnnotation fromVisitedInstruction(ClassContext classContext,
                                                          PreorderVisitor visitor,
                                                          int pc)

Factory method for creating a source line annotation describing the source line number for the instruction being visited by given visitor.

Parameters:

classContext - the ClassContext

visitor - a BetterVisitor which is visiting the method

pc - the bytecode offset of the instruction in the method

Returns:

the SourceLineAnnotation, or null if we do not have line number information for the instruction

fromVisitedInstruction

public static SourceLineAnnotation fromVisitedInstruction(ClassContext classContext,
                                                          org.apache.bcel.classfile.Method method,
                                                          Location loc)

Create from Method and Location in a visited class.

Parameters:

classContext - ClassContext of visited class

method - Method in visited class

loc - Location in visited class

Returns:

SourceLineAnnotation describing visited Location

fromVisitedInstruction

public static SourceLineAnnotation fromVisitedInstruction(ClassContext classContext,
                                                          org.apache.bcel.classfile.Method method,
                                                          org.apache.bcel.generic.InstructionHandle handle)

Create from Method and InstructionHandle in a visited class.

Parameters:

classContext - ClassContext of visited class

method - Method in visited class

handle - InstructionHandle in visited class

Returns:

SourceLineAnnotation describing visited instruction

fromVisitedInstruction

public static SourceLineAnnotation fromVisitedInstruction(MethodDescriptor methodDescriptor,
                                                          Location location)

Create from MethodDescriptor and Location of visited instruction.

Parameters:

methodDescriptor - MethodDescriptor identifying analyzed method

location - Location of instruction within analyed method

Returns:

SourceLineAnnotation describing visited instruction

fromVisitedInstruction

public static SourceLineAnnotation fromVisitedInstruction(MethodDescriptor methodDescriptor,
                                                          int position)

fromVisitedInstruction

public static SourceLineAnnotation fromVisitedInstruction(ClassContext classContext,
                                                          org.apache.bcel.classfile.Method method,
                                                          int pc)

Create from Method and bytecode offset in a visited class.

Parameters:

classContext - ClassContext of visited class

method - Method in visited class

pc - bytecode offset in visited method

Returns:

SourceLineAnnotation describing visited instruction

fromVisitedInstruction

public static SourceLineAnnotation fromVisitedInstruction(org.apache.bcel.classfile.JavaClass jclass,
                                                          org.apache.bcel.classfile.Method method,
                                                          int pc)

Create from Method and bytecode offset in a visited class.

Parameters:

jclass - JavaClass of visited class

method - Method in visited class

pc - bytecode offset in visited method

Returns:

SourceLineAnnotation describing visited instruction

fromVisitedInstructionRange

public static SourceLineAnnotation fromVisitedInstructionRange(BytecodeScanningDetector visitor,
                                                               int startPC,
                                                               int endPC)

Factory method for creating a source line annotation describing the source line numbers for a range of instructions in the method being visited by the given visitor.

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:

the SourceLineAnnotation, or null if we do not have line number information for the instruction

fromVisitedInstructionRange

@Nonnull
public static SourceLineAnnotation fromVisitedInstructionRange(ClassContext classContext,
                                                                        PreorderVisitor visitor,
                                                                        int startPC,
                                                                        int endPC)

Factory method for creating a source line annotation describing the source line numbers for a range of instructions in the method being visited by the given visitor.

Parameters:

classContext - the ClassContext

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:

the SourceLineAnnotation, or null if we do not have line number information for the instruction

fromRawData

public static SourceLineAnnotation fromRawData(java.lang.String className,
                                               java.lang.String sourceFile,
                                               int startLine,
                                               int endLine,
                                               int startPC,
                                               int endPC)

fromVisitedInstruction

public static SourceLineAnnotation fromVisitedInstruction(BytecodeScanningDetector visitor)

Factory method for creating a source line annotation describing the source line number for the instruction being visited by given visitor.

Parameters:

visitor - a DismantleBytecode visitor which is visiting the method

Returns:

the SourceLineAnnotation, or null if we do not have line number information for the instruction

fromVisitedInstruction

@Nonnull
public static SourceLineAnnotation fromVisitedInstruction(ClassContext classContext,
                                                                   org.apache.bcel.generic.MethodGen methodGen,
                                                                   java.lang.String sourceFile,
                                                                   @Nonnull
                                                                   org.apache.bcel.generic.InstructionHandle handle)

Factory method for creating a source line annotation describing the source line number for a visited instruction.

Parameters:

classContext - the ClassContext

methodGen - the MethodGen object representing the method

handle - the InstructionHandle containing the visited instruction

Returns:

the SourceLineAnnotation, or null if we do not have line number information for the instruction

fromVisitedInstructionRange

public static SourceLineAnnotation fromVisitedInstructionRange(ClassContext classContext,
                                                               org.apache.bcel.generic.MethodGen methodGen,
                                                               java.lang.String sourceFile,
                                                               org.apache.bcel.generic.InstructionHandle start,
                                                               org.apache.bcel.generic.InstructionHandle end)

Factory method for creating a source line annotation describing the source line numbers for a range of instruction in a method.

Parameters:

classContext - theClassContext

methodGen - the method

start - the start instruction

end - the end instruction (inclusive)

getClassName

@Nonnull
 @DottedClassName
public java.lang.String getClassName()

getSourceFile

@Nonnull
public java.lang.String getSourceFile()

Get the source file name.

isSourceFileKnown

public boolean isSourceFileKnown()

Is the source file known?

setSourceFile

public void setSourceFile(java.lang.String sourceFile)

Set the source file name.

Parameters:

sourceFile - the source file name

getSimpleClassName

public java.lang.String getSimpleClassName()

Get the simple class name (the part of the name after the dot)

getPackageName

public java.lang.String getPackageName()

getStartLine

public int getStartLine()

Get the start line (inclusive).

getEndLine

public int getEndLine()

Get the ending line (inclusive).

getStartBytecode

public int getStartBytecode()

Get start bytecode (inclusive).

getEndBytecode

public int getEndBytecode()

Get end bytecode (inclusive).

isUnknown

public boolean isUnknown()

Is this an unknown source line annotation?

accept

public void accept(BugAnnotationVisitor visitor)

Description copied from interface: BugAnnotation

Accept a BugAnnotationVisitor.

Specified by:

accept in interface BugAnnotation

Parameters:

visitor - the visitor to accept

format

public java.lang.String format(java.lang.String key,
                               ClassAnnotation primaryClass)

Description copied from interface: BugAnnotation

Format the annotation as a String. The given key specifies additional information about how the annotation should be formatted. If the key is empty, then the "default" format will be used.

Specified by:

format in interface BugAnnotation

Parameters:

key - how the annotation should be formatted

primaryClass - The primary class for the bug; some bug annotation format msgs are simplified in relation to that class.

getDescription

public java.lang.String getDescription()

Description copied from interface: BugAnnotation

Get a description of this bug annotation. The description is a key for the FindBugsAnnotationDescriptions resource bundle.

Specified by:

getDescription in interface BugAnnotation

setDescription

public void setDescription(java.lang.String description)

Description copied from interface: BugAnnotation

Set a description of this bug annotation. The description is a key for the FindBugsAnnotationDescriptions resource bundle.

Specified by:

setDescription in interface BugAnnotation

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

compareTo

public int compareTo(BugAnnotation o)

Specified by:

compareTo in interface java.lang.Comparable<BugAnnotation>

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

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

generateRelativeSource

public static void generateRelativeSource(java.io.File relativeSourceBase,
                                          Project project)

clearGenerateRelativeSource

public static void clearGenerateRelativeSource()

writeXML

public void writeXML(XMLOutput xmlOutput,
                     boolean addMessages,
                     boolean isPrimary)
              throws java.io.IOException

Specified by:

writeXML in interface XMLWriteableWithMessages

Throws:

java.io.IOException

getSourcePath

public java.lang.String getSourcePath()

setSynthetic

public void setSynthetic(boolean synthetic)

isSynthetic

public boolean isSynthetic()

isSignificant

public boolean isSignificant()

Description copied from interface: BugAnnotation

Is this annotation used to compute instance hashes or match bug instances across versions

Specified by:

isSignificant in interface BugAnnotation

Returns:

true if significant

toString

public java.lang.String toString(ClassAnnotation primaryClass)

Specified by:

toString in interface BugAnnotation