sofya.base
Class ByteSourceHandler

java.lang.Object
  extended by sofya.base.Handler
      extended by sofya.base.ByteSourceHandler

public class ByteSourceHandler
extends Handler

The ByteSourceHandler provides routines to retrieve bytecode information from Java binary class files.

Version:
05/03/2005
Author:
Alex Kinneer
See Also:
ByteSourceViewer

Field Summary
 
Fields inherited from class sofya.base.Handler
HANDLER_EXTENSIONS, LINE_SEP
 
Constructor Summary
ByteSourceHandler()
           
 
Method Summary
 boolean classIsAbstract()
          Reports whether the loaded class is an abstract class.
 boolean classIsInterface()
          Reports whether the loaded class represents an interface.
 boolean containsMethod(MethodSignature signature)
          Reports whether the classfile contains a given method.
 boolean containsMethod(java.lang.String methodName)
          Reports whether the classfile contains a given method.
 org.apache.bcel.generic.ConstantPoolGen getConstantPool()
          Returns an unmodifiable view of the BCEL ConstantPoolGen object for the class file loaded in the handler, which is required to obtain information about certain types of instructions.
 org.apache.bcel.generic.InstructionList getInstructionList(MethodSignature signature)
          Gets bytecode source for a method as a BCEL InstructionList.
 org.apache.bcel.generic.Instruction[] getInstructionList(MethodSignature signature, int startOffset, int endOffset)
          Gets the bytecode source in a method between two instruction offsets, inclusive.
 org.apache.bcel.generic.InstructionList getInstructionList(java.lang.String methodName)
          Gets bytecode source for a method as a BCEL InstructionList.
 org.apache.bcel.generic.Instruction[] getInstructionList(java.lang.String methodName, int startOffset, int endOffset)
          Gets the bytecode source in a method between two instruction offsets, inclusive.
 java.lang.String[] getInstructions(MethodSignature signature)
          Gets bytecode source for a method as a list of string representations of the bytecode instructions.
 java.lang.String[] getInstructions(MethodSignature signature, int startOffset, int endOffset)
          Gets the bytecode source in a method between two instruction offsets, inclusive.
 java.lang.String[] getInstructions(java.lang.String methodName)
          Gets bytecode source for a method as a list of string representations of the bytecode instructions.
 java.lang.String[] getInstructions(java.lang.String methodName, int startOffset, int endOffset)
          Gets the bytecode source in a method between two instruction offsets, inclusive.
 org.apache.bcel.generic.MethodGen getMethod(MethodSignature signature)
          Retrieves the BCEL full representation of a method present in the class file.
 org.apache.bcel.generic.MethodGen getMethod(java.lang.String methodName)
          Retrieves the BCEL full representation of a method present in the class file.
 java.lang.String[] getMethodList()
          Gets the list of methods read from the class file.
 MethodSignature[] getSignatureList()
          Gets the list of signatures of methods read from the class file.
 java.lang.String getSource(MethodSignature signature)
          Gets bytecode source for a method in human-readable form.
 java.lang.String getSource(java.lang.String methodName)
          Gets bytecode source for a method in human-readable form.
static void main(java.lang.String[] args)
          Test driver for ByteSourceHandler.
 void readSourceFile(java.lang.String className)
          Reads bytecode source from file.
 void readSourceFile(java.lang.String location, java.lang.String className)
          Reads bytecode source for a class from a given location.
 
Methods inherited from class sofya.base.Handler
copyFile, createCacheFile, disableParseNumbers, ensureTagExists, formatSignature, isIntAvailable, isStringAvailable, newCache, openCacheFile, openInputFile, openInputFile, openOutputFile, openOutputFile, parseClass, prepareTokenizer, readInt, readIntIgnoreEOL, readJarClasses, readNextLine, readProgFile, readString, readStringIgnoreEOL, readToEOL, readToNextDataLine, toBinary, toHex
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ByteSourceHandler

public ByteSourceHandler()
Method Detail

readSourceFile

public void readSourceFile(java.lang.String className)
                    throws java.io.IOException
Reads bytecode source from file.

The bytecode source is read from the class file and stored to internal data structures. This data can then be retrieved via other accessor functions in this class, such as getInstructions(java.lang.String).

Parameters:
className - Name of Java class file from which bytecode source data is to be read.
Throws:
java.io.IOException - If there is an error reading the class file.

readSourceFile

public void readSourceFile(java.lang.String location,
                           java.lang.String className)
                    throws java.io.IOException
Reads bytecode source for a class from a given location.

The location provided to this method may be a directory or jar file. This method will not attempt to load a class from the classpath.

Parameters:
location - Name of the directory or jar file from which the class should be loaded.
className - Name of the class which is to be loaded. This parameter should include any additional path information relative to the location parameter that is required to find the class, using path separator characters (not '.').
Throws:
java.io.IOException - If there is an error reading the class file.

getMethodList

public java.lang.String[] getMethodList()
Gets the list of methods read from the class file.

Returns:
List of names of the methods read from the class file.

getSignatureList

public MethodSignature[] getSignatureList()
Gets the list of signatures of methods read from the class file.

Returns:
List of signatures of the methods read from the class file.

containsMethod

public boolean containsMethod(java.lang.String methodName)
Reports whether the classfile contains a given method.

Parameters:
methodName - Name of the method which the handler should check for existence.
Returns:
true if a method of the given name exists in the classfile, false otherwise.

containsMethod

public boolean containsMethod(MethodSignature signature)
Reports whether the classfile contains a given method.

Parameters:
signature - Signature of the method which the handler should check for existence.
Returns:
true if a method with the given signature exists in the classfile, false otherwise.

getSource

public java.lang.String getSource(java.lang.String methodName)
                           throws MethodNotFoundException
Gets bytecode source for a method in human-readable form.

Parameters:
methodName - Name of the method for which the bytecode source is to be retrieved.
Returns:
String containing list of instructions constituting the specified method, in human-readable format using Java Virtual Machine specification assembly mnemonics for instructions, or null if the specified method cannot be found.
Throws:
MethodNotFoundException - If the handler has no bytecode listing associated with a method of the specified name.

getSource

public java.lang.String getSource(MethodSignature signature)
                           throws MethodNotFoundException
Gets bytecode source for a method in human-readable form.

Parameters:
signature - Signature of the method for which the bytecode source is to be retrieved.
Returns:
String containing list of instructions constituting the specified method, in human-readable format using Java Virtual Machine specification assembly mnemonics for instructions, or null if the specified method cannot be found.
Throws:
MethodNotFoundException - If the handler has no bytecode listing associated with a method with the specified signature.

getInstructions

public java.lang.String[] getInstructions(java.lang.String methodName)
                                   throws MethodNotFoundException
Gets bytecode source for a method as a list of string representations of the bytecode instructions.

Parameters:
methodName - Name of the method for which the bytecode source is to be retrieved.
Returns:
List of strings constituting the instructions of the specified method, which may be zero-length if the instruction is abstract or otherwise contains no instructions.
Throws:
MethodNotFoundException - If the handler has no bytecode listing associated with a method of the specified name.

getInstructions

public java.lang.String[] getInstructions(MethodSignature signature)
                                   throws MethodNotFoundException
Gets bytecode source for a method as a list of string representations of the bytecode instructions.

Parameters:
signature - Signature of the method for which the bytecode source is to be retrieved.
Returns:
List of strings constituting the instructions of the specified method, which may be zero-length if the instruction is abstract or otherwise contains no instructions.
Throws:
MethodNotFoundException - If the handler has no bytecode listing associated with a method with the specified signature.

getInstructionList

public org.apache.bcel.generic.InstructionList getInstructionList(java.lang.String methodName)
                                                           throws MethodNotFoundException
Gets bytecode source for a method as a BCEL InstructionList.

Parameters:
methodName - Name of the method for which the bytecode source is to be retrieved.
Returns:
BCEL InstructionList object containing the bytecode instructions that constitute the specified method.
Throws:
MethodNotFoundException - If the handler has no bytecode listing associated with a method of the specified name.

getInstructionList

public org.apache.bcel.generic.InstructionList getInstructionList(MethodSignature signature)
                                                           throws MethodNotFoundException
Gets bytecode source for a method as a BCEL InstructionList.

Parameters:
signature - Signature of the method for which the bytecode source is to be retrieved.
Returns:
BCEL InstructionList object containing the bytecode instructions that constitute the specified method.
Throws:
MethodNotFoundException - If the handler has no bytecode listing associated with a method with the specified signature.

getInstructions

public java.lang.String[] getInstructions(java.lang.String methodName,
                                          int startOffset,
                                          int endOffset)
                                   throws MethodNotFoundException
Gets the bytecode source in a method between two instruction offsets, inclusive.

Parameters:
methodName - Name of the method for which the bytecode source is to be retrieved.
startOffset - Offset to the first instruction to be retrieved.
endOffset - Offset to the last instruction to be retrieved.
Returns:
List of strings representing the instructions in the specified range, which will be of length zero if the method cannot be found or is abstract.
Throws:
MethodNotFoundException - If the handler has no bytecode listing associated with a method of the specified name.

getInstructions

public java.lang.String[] getInstructions(MethodSignature signature,
                                          int startOffset,
                                          int endOffset)
                                   throws MethodNotFoundException
Gets the bytecode source in a method between two instruction offsets, inclusive.

Parameters:
signature - Signature of the method for which the bytecode source is to be retrieved.
startOffset - Offset to the first instruction to be retrieved.
endOffset - Offset to the last instruction to be retrieved.
Returns:
List of strings representing the instructions in the specified range, which will be of length zero if the method cannot be found or is abstract.
Throws:
MethodNotFoundException - If the handler has no bytecode listing associated with a method with the specified signature.

getInstructionList

public org.apache.bcel.generic.Instruction[] getInstructionList(java.lang.String methodName,
                                                                int startOffset,
                                                                int endOffset)
                                                         throws MethodNotFoundException
Gets the bytecode source in a method between two instruction offsets, inclusive.

Parameters:
methodName - Name of the method for which the bytecode source is to be retrieved.
startOffset - Offset to the first instruction to be retrieved.
endOffset - Offset to the last instruction to be retrieved.
Returns:
Array of BCEL Instruction objects representing the bytecode in the given range.
Throws:
MethodNotFoundException - If the handler has no bytecode listing associated with a method of the specified name.

getInstructionList

public org.apache.bcel.generic.Instruction[] getInstructionList(MethodSignature signature,
                                                                int startOffset,
                                                                int endOffset)
                                                         throws MethodNotFoundException
Gets the bytecode source in a method between two instruction offsets, inclusive.

Parameters:
signature - Signature of the method for which the bytecode source is to be retrieved.
startOffset - Offset to the first instruction to be retrieved.
endOffset - Offset to the last instruction to be retrieved.
Returns:
Array of BCEL Instruction objects representing the bytecode in the given range.
Throws:
MethodNotFoundException - If the handler has no bytecode listing associated with a method with the specified signature.

getMethod

public org.apache.bcel.generic.MethodGen getMethod(java.lang.String methodName)
                                            throws MethodNotFoundException
Retrieves the BCEL full representation of a method present in the class file.

Parameters:
methodName - Name of the method to be retrieved.
Returns:
The BCEL abstract representation of the requested method.
Throws:
MethodNotFoundException

getMethod

public org.apache.bcel.generic.MethodGen getMethod(MethodSignature signature)
                                            throws MethodNotFoundException
Retrieves the BCEL full representation of a method present in the class file.

Parameters:
signature - Signature of the method to be retrieved.
Returns:
The BCEL abstract representation of the requested method.
Throws:
MethodNotFoundException

getConstantPool

public org.apache.bcel.generic.ConstantPoolGen getConstantPool()
Returns an unmodifiable view of the BCEL ConstantPoolGen object for the class file loaded in the handler, which is required to obtain information about certain types of instructions.

Returns:
An unmodifiable view of the constant pool for the class currently loaded by the handler. Calling a method on the returned object that would cause a change to the constant pool will result in an UnsupportedOperationException being thrown.

classIsInterface

public boolean classIsInterface()
Reports whether the loaded class represents an interface.

Returns:
true if the class is an interface, false otherwise.

classIsAbstract

public boolean classIsAbstract()
Reports whether the loaded class is an abstract class.

Returns:
true if the class is abstract, false otherwise.

main

public static void main(java.lang.String[] args)
Test driver for ByteSourceHandler.