sofya.base
Class Handler

java.lang.Object
  sofya.base.Handler

Direct Known Subclasses:

ByteSourceHandler, CFHandler, IRGHandler, MapHandler, MutationHandler, SemanticDataHandler, SourceHandler, TestHistoryHandler, TestSelectionHandler, TraceHandler

public abstract class Handler
extends java.lang.Object

Abstract superclass for all handlers.

All of the file creation and access methods return handles to file streams. This provides the greatest flexibility to subclasses and external applications code, including the ability to write binary streams to file if the need should arise. For character data files the typical usage is to wrap the stream with a reader or writer, such as a BufferedReader or PrintWriter, a technique that is demonstrated by the current handlers.

It is the responsibility of the object receiving the stream to close the stream. If you release all references to the stream without closing it, its resources typically will not be released until the garbage collector runs finalization on the stream object.

Version:

06/09/2006

Author:

Alex Kinneer

Field Summary

protected static boolean	HANDLER_EXTENSIONS Compile flag controlling whether certain handler extensions are enabled.
static java.lang.String	LINE_SEP Convenience string containing the system dependent newline character sequence.

Constructor Summary

Handler()

Method Summary

static boolean	copyFile(java.io.File source, java.io.File dest) Utility method to copy a file.
static java.io.FileOutputStream	createCacheFile(CacheHandle cHandle, java.lang.String fileName, boolean deleteOnExit) Creates a new cache file in a specified cache.
static void	disableParseNumbers(java.io.StreamTokenizer stok) Modifies the syntax table of a stream tokenizer to disable parsing of numbers.
static void	ensureTagExists(java.lang.String tag) Checks whether a given tag exists and creates it if necessary.
static java.lang.String	formatSignature(java.lang.String fullClassName, java.lang.String mSignature, char classDelimiter) Utility method to convert method signatures to a common format.
static boolean	isIntAvailable(java.io.StreamTokenizer stok) Reports whether an integer is available to be read next from a stream tokenizer.
static boolean	isStringAvailable(java.io.StreamTokenizer stok) Reports whether a string is available to be read next from a stream tokenizer.
static CacheHandle	newCache(boolean deleteOnExit) Creates a new disk cache.
static java.io.FileInputStream	openCacheFile(CacheHandle cHandle, java.lang.String fileName) Opens a cache file in a specified cache.
static java.io.FileInputStream	openInputFile(java.lang.String fileName) Opens an abritrary file for reading.
static java.io.FileInputStream	openInputFile(java.lang.String fileName, java.lang.String tag) Opens a file in the Sofya database directory for reading.
static java.io.FileOutputStream	openOutputFile(java.lang.String fileName, boolean append) Opens an arbitrary file for writing.
static java.io.FileOutputStream	openOutputFile(java.lang.String fileName, java.lang.String tag, boolean append) Opens a file in the Sofya database directory for writing.
static org.apache.bcel.classfile.JavaClass	parseClass(java.lang.String className) Utility method to open a class file for handling in BCEL.
protected static void	prepareTokenizer(java.io.StreamTokenizer stok) Sets the syntax table of a stream tokenizer to a standard configuration useful for most handlers.
static int	readInt(java.io.StreamTokenizer stok) Reads an integer off of a stream tokenizer.
static int	readIntIgnoreEOL(java.io.StreamTokenizer stok)
static int	readJarClasses(java.lang.String jarName, java.util.List classList) Utility method extract a list of the class files contained in a jar file.
static java.lang.String	readNextLine(java.io.Reader reader) Reads the next non-blank, non-comment line from the stream wrapped by the given reader.
static int	readProgFile(java.lang.String fileName, java.lang.String tag, java.util.List unitList) Reads a "prog.lst" file.
static java.lang.String	readString(java.io.StreamTokenizer stok) Reads a string off of a stream tokenizer.
static java.lang.String	readStringIgnoreEOL(java.io.StreamTokenizer stok)
static boolean	readToEOL(java.io.StreamTokenizer stok) Advances a stream tokenizer through the next end-of-line token in the stream.
static boolean	readToNextDataLine(java.io.StreamTokenizer stok) Advances a stream tokenizer to point to the first token of the next data line in a database file.
protected static java.util.BitSet	toBinary(java.lang.String hexString) Converts a hexadecimal string to a bit vector representing its binary equivalent.
protected static java.lang.String	toHex(java.util.BitSet bv, int size) Converts a bit vector to a string containing its hexadecimal equivalent.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LINE_SEP

public static final java.lang.String LINE_SEP

Convenience string containing the system dependent newline character sequence.

HANDLER_EXTENSIONS

protected static final boolean HANDLER_EXTENSIONS

Compile flag controlling whether certain handler extensions are enabled. At this time, controls whether method signatures are written to certain database files.

See Also:

Constant Field Values

Constructor Detail

Handler

public Handler()

Method Detail

openInputFile

public static final java.io.FileInputStream openInputFile(java.lang.String fileName,
                                                          java.lang.String tag)
                                                   throws java.io.IOException

Opens a file in the Sofya database directory for reading.

Parameters:

fileName - Name of the file to be opened, without extension.

tag - Database tag to be associated with the file.

Returns:

A FileInputStream which can be used to read from the file.

Throws:

java.io.IOException - If there is error opening the file (such as a file not found exception).

openInputFile

public static final java.io.FileInputStream openInputFile(java.lang.String fileName)
                                                   throws java.io.IOException

Opens an abritrary file for reading.

Parameters:

fileName - Name of the file to be opened, including extension and any relative or absolute path required to locate the file.

Returns:

A FileInputStream which can be used to read from the file.

Throws:

java.io.IOException - If there is error opening the file (such as a file not found exception).

openOutputFile

public static final java.io.FileOutputStream openOutputFile(java.lang.String fileName,
                                                            java.lang.String tag,
                                                            boolean append)
                                                     throws java.io.IOException

Opens a file in the Sofya database directory for writing. The file will be created if necessary.

Parameters:

fileName - Name of the file to be opened, without extension.

tag - Database tag to be associated with the file.

append - If true, data will be appended to the end of the file, otherwise the existing contents of the file will be overwritten.

Returns:

A FileOutputStream which can be used to write to the file.

Throws:

java.io.IOException - If there is error creating the file.

openOutputFile

public static final java.io.FileOutputStream openOutputFile(java.lang.String fileName,
                                                            boolean append)
                                                     throws java.io.IOException

Opens an arbitrary file for writing. The file will be created if necessary.

Parameters:

fileName - Name of the file to be opened, including extension and any relative or absolute path required to locate the file.

append - If true, data will be appended to the end of the file, otherwise the existing contents of the file will be overwritten.

Returns:

A FileOutputStream which can be used to write to the file.

Throws:

java.io.IOException - If there is error creating the file.

newCache

public static final CacheHandle newCache(boolean deleteOnExit)
                                  throws CacheException

Creates a new disk cache.

Parameters:

deleteOnExit - Flag specifying whether the cache should be deleted on program exit. This is generally not useful except for debugging. Note also that the cache will not be removed if the contents of the cache are not cleared first.

Returns:

A cache handle which permits access to the cache.

Throws:

CacheException - If the cache cannot be created.

createCacheFile

public static final java.io.FileOutputStream createCacheFile(CacheHandle cHandle,
                                                             java.lang.String fileName,
                                                             boolean deleteOnExit)
                                                      throws java.io.IOException

Creates a new cache file in a specified cache.

Parameters:

cHandle - Cache handle, as returned by newCache(boolean), which identifies the cache in which the file is to be created.

fileName - Name of the cache file to be created.

deleteOnExit - Flag specifying whether the file should be deleted on program exit.

Returns:

A FileOutputStream which can be used to write to the new cache file.

Throws:

java.io.IOException - If the cache file cannot be created as requested.

openCacheFile

public static final java.io.FileInputStream openCacheFile(CacheHandle cHandle,
                                                          java.lang.String fileName)
                                                   throws java.io.IOException

Opens a cache file in a specified cache.

Parameters:

cHandle - Cache handle, as returned by newCache(boolean), which identifies the cache containing the file to be opened.

fileName - Name of the cache file to be opened.

Returns:

A FileInputStream which can be used to read from the cache file.

Throws:

java.io.IOException - If the cache file cannot be opened as requested.

readNextLine

public static final java.lang.String readNextLine(java.io.Reader reader)
                                           throws java.io.IOException

Reads the next non-blank, non-comment line from the stream wrapped by the given reader. A comment line is defined to be one which starts with the comment record character '0' (zero). A blank line is defined to be one which contains only the newline character sequence for the current platform.

Parameters:

reader - Reader from which the next line is to be read.

Returns:

The next non-blank, non-comment line available from the reader stream.

Throws:

java.io.EOFException - If the end of the underlying stream is reached.

java.io.IOException

readProgFile

public static final int readProgFile(java.lang.String fileName,
                                     java.lang.String tag,
                                     java.util.List unitList)
                              throws EmptyFileException,
                                     BadFileFormatException,
                                     java.io.FileNotFoundException,
                                     java.io.IOException

Reads a "prog.lst" file.

Parameters:

fileName - Name of the prog file to be loaded, including the ".prog" portion of the extension.

tag - Database tag associated with the prog file. May be null, in which case the handler will attempt to locate the file in the root database directory.

unitList - [out] List into which the classes specified by the prog file will be placed, as sets of classes associated with a location. Any existing contents of the list will be destroyed! The list elements will be instances of ProgramUnit.

Returns:

The number of classes read from the '.prog' file. (This is not the same as the number of elements added to classList.)

Throws:

EmptyFileException - If the prog file is empty.

BadFileFormatException - If there is a parse error reading the prog file.

java.io.FileNotFoundException - If the handler cannot locate a prog file by the given name.

java.io.IOException - On any other I/O error opening or reading the file.

readJarClasses

public static int readJarClasses(java.lang.String jarName,
                                 java.util.List classList)
                          throws java.io.IOException

Utility method extract a list of the class files contained in a jar file.

Parameters:

jarName - Name of the jar file.

classList - [out] List into which the classes contained in the jar file will be placed. Previous elements of the list will be preserved. The list elements will be Strings.

Returns:

The number of class files found in the jar file.

Throws:

java.io.IOException - On any I/O error opening or reading the specified jar file.

copyFile

public static final boolean copyFile(java.io.File source,
                                     java.io.File dest)

Utility method to copy a file.

Copies the specified source file to the specified destination. Paths may be specified.

Parameters:

source - File to be copied, including path if required.

dest - Name of copied file, including path if required.

Returns:

True if the copy was successful, false otherwise.

parseClass

public static final org.apache.bcel.classfile.JavaClass parseClass(java.lang.String className)
                                                            throws java.io.IOException,
                                                                   org.apache.bcel.classfile.ClassFormatException

Utility method to open a class file for handling in BCEL.

Parameters:

className - Name of the class to be parsed.

Returns:

The BCEL parsed representation of the class.

Throws:

java.io.IOException - If the class file does not exist or there is an an error reading the file.

org.apache.bcel.classfile.ClassFormatException - If the class file is malformed.

formatSignature

public static final java.lang.String formatSignature(java.lang.String fullClassName,
                                                     java.lang.String mSignature,
                                                     char classDelimiter)

Utility method to convert method signatures to a common format.

The class name is concatenated with the signature of the method, separated by a provided delimiter character. All spaces, tabs, and newlines in the resulting string are then converted to underscores. Sequences of underscores are reduced to a single underscore, except when an underscore is present in the method name itself.

Parameters:

fullClassName - Name of the class which will be inserted into the formatted string. This should be the fully package qualified name of the class to guarantee uniqueness.

mSignature - Signature of the method to be inserted into the formatted string, typically obtained using BCEL.

classDelimiter - Delimiter character that will be inserted between the class name and method signature.

Returns:

The concatenation of the class name, delimiter, and method signature with whitespace converted to underscores. This should be a universally unique identifier for the method, as long as the constraints on the parameters are met.

toHex

protected static java.lang.String toHex(java.util.BitSet bv,
                                        int size)

Converts a bit vector to a string containing its hexadecimal equivalent.

The bit vector will be end-padded to the nearest multiple of four and converted to a contiguous string of hexadecimal digits.

Parameters:

bv - Bit vector to be converted to a hexadecimal string.

size - Number of bits in the vector to be included in the conversion - any bits in the vector past this value are ignored.

Returns:

A string containing the hexadecimal equivalent of the given bit vector.

toBinary

protected static java.util.BitSet toBinary(java.lang.String hexString)

Converts a hexadecimal string to a bit vector representing its binary equivalent.

The hexadecimal string should be a contiguous string of hexadecimal digits with no special formatting.

Parameters:

hexString - String of hexadecimal characters encoding a bitset.

Returns:

A bit vector containing the binary equivalent of the given hexadecimal string.

ensureTagExists

public static void ensureTagExists(java.lang.String tag)
                            throws java.io.IOException

Checks whether a given tag exists and creates it if necessary.

Parameters:

tag - Name of the tag to be checked for existence and created if necessary.

Throws:

java.io.IOException - If there is an error creating the tag, when necessary.

prepareTokenizer

protected static void prepareTokenizer(java.io.StreamTokenizer stok)

Sets the syntax table of a stream tokenizer to a standard configuration useful for most handlers.

The tokenizer is configured as follows:

• All characters between ASCII 0 (\0) and ASCII 32 (' ') are considered whitespace (token delimiters).
• All other characters are considered word constituents.
• Numbers are parsed (numbers with no adjoining alpha characters will not be parsed as strings).
• Line terminators are returned as separate tokens (this assists in tracking position within the stream).

Parameters:

stok - Tokenizer to be configured.

disableParseNumbers

public static void disableParseNumbers(java.io.StreamTokenizer stok)

Modifies the syntax table of a stream tokenizer to disable parsing of numbers.

This method properly reverses the actions performed by StreamTokenizer.parseNumbers() since that class does not itself provide any method for accomplishing that task.

Parameters:

stok - Tokenizer to be configured.

readInt

public static int readInt(java.io.StreamTokenizer stok)
                   throws BadFileFormatException,
                          java.io.IOException

Reads an integer off of a stream tokenizer.

Parameters:

stok - Tokenizer from which an integer is to be read.

Returns:

An integer value from the stream being tokenized, if there is in fact a token available and it is a numeric token (floating point values will be truncated).

Throws:

EOLException - If the tokenizer is at the end of a line.

DatabaseEOFException - If the tokenizer reaches the end of the underlying database file.

DataTypeException - If the next token in the stream is not a number.

java.io.IOException - For any I/O error raised when attempting to read the underlying stream.

BadFileFormatException

readIntIgnoreEOL

public static int readIntIgnoreEOL(java.io.StreamTokenizer stok)
                            throws BadFileFormatException,
                                   java.io.IOException

Throws:

BadFileFormatException

java.io.IOException

readString

public static java.lang.String readString(java.io.StreamTokenizer stok)
                                   throws BadFileFormatException,
                                          java.io.IOException

Reads a string off of a stream tokenizer.

Parameters:

stok - Tokenizer from which a string is to be read.

Returns:

A string from the stream being tokenized, if there is in fact a token available and it is a word token.

Throws:

EOLException - If the tokenizer is at the end of a line.

DatabaseEOFException - If the tokenizer reaches the end of the underlying database file.

DataTypeException - If the next token in the stream is not a word/string.

java.io.IOException - For any I/O error raised when attempting to read the underlying stream.

BadFileFormatException

readStringIgnoreEOL

public static java.lang.String readStringIgnoreEOL(java.io.StreamTokenizer stok)
                                            throws BadFileFormatException,
                                                   java.io.IOException

Throws:

BadFileFormatException

java.io.IOException

isIntAvailable

public static boolean isIntAvailable(java.io.StreamTokenizer stok)
                              throws java.io.IOException

Reports whether an integer is available to be read next from a stream tokenizer. This method will not read through a line terminator.

Parameters:

stok - Tokenizer to check for the availability of an integer to be read.

Returns:

true if an integer is available as the next token to be read from the stream, false otherwise.

Throws:

java.io.IOException - For any I/O error raised when attempting to read the underlying stream.

isStringAvailable

public static boolean isStringAvailable(java.io.StreamTokenizer stok)
                                 throws java.io.IOException

Reports whether a string is available to be read next from a stream tokenizer. This method will not read through a line terminator.

Parameters:

stok - Tokenizer to check for the availability of a string to be read.

Returns:

true if a string is available as the next token to be read from the stream, false otherwise.

Throws:

java.io.IOException - For any I/O error raised when attempting to read the underlying stream.

readToEOL

public static boolean readToEOL(java.io.StreamTokenizer stok)
                         throws java.io.IOException

Advances a stream tokenizer through the next end-of-line token in the stream.

After calling this method, the token type of the tokenizer will be StreamTokenizer.TT_EOL, and the next call to nextToken() will return the first token on the next line.

Parameters:

stok - Tokenizer to be advanced to the end of the current line.

Returns:

true if the tokenizer was successfully advanced to the end of the line, false if the end of the underlying file was reached instead.

Throws:

java.io.IOException - For any I/O error raised when attempting to read the underlying stream.

readToNextDataLine

public static boolean readToNextDataLine(java.io.StreamTokenizer stok)
                                  throws BadFileFormatException,
                                         java.io.IOException

Advances a stream tokenizer to point to the first token of the next data line in a database file.

This method is the equivalent of readNextLine(Reader) for database files being read through a StreamTokenizer.

Parameters:

stok - Tokenizer to be advanced to the next data line.

Returns:

true if the tokenizer was successfully advanced to the next data line, false if the end of the underlying file was reached instead.

Throws:

BadFileFormatException - If a line is encountered in the underlying database file which does not begin with a line type indicator code.

java.io.IOException - For any I/O error raised when attempting to read the underlying stream.