sofya.graphs.cfg
Class CFHandler

java.lang.Object
  sofya.base.Handler
      sofya.graphs.cfg.CFHandler

public class CFHandler
extends Handler

The CFHandler provides routines to manipulate Sofya control flow (.cf) files and to form control flow graph (CFG) objects.

Version:

02/23/2005

Author:

Alex Kinneer

See Also:

CFG, MapHandler, CFViewer

Field Summary

Fields inherited from class sofya.base.Handler

HANDLER_EXTENSIONS, LINE_SEP

Constructor Summary

CFHandler()
Default constructor, creates a handler with a new cache for CFG storage.

CFHandler(CFGCache sharedCache)
Creates a handler which is backed by the given CFG cache.

Method Summary

void	addCFG(CFG cfg) Adds CFG to the current .cf file, using the method name or signature associated with the given CFG object.
boolean	containsCFG(MethodSignature signature) Queries whether a CFG exists for a given method.
boolean	containsCFG(java.lang.String methodName) Queries whether a CFG exists for a given method.
CFG	getCFG(MethodSignature signature) Gets CFG for a method.
CFG	getCFG(java.lang.String methodName) Gets CFG for a method.
java.lang.String	getClassName() Gets the name of the class which the handler believes is currently loaded, which is set only when a CF file has been loaded by the handler.
java.lang.String[]	getMethodList() Gets the list of pretty-printed methods associated with control flow graphs registered with the handler.
MethodSignature[]	getSignatureList() Gets the list of method signatures for control flow graphs registered with the handler.
MethodSignature[]	getSignatureList(java.lang.String className) Gets the list of method signatures for control flow graphs from a specific class which are registered with the handler.
boolean	isClearedOnLoad() Gets whether the handler clears existing control flow graphs from its cache when a new control flow file is read.
java.util.Iterator	iterator() Gets an iterator over all of the control flow graphs currently registered with the handler.
static void	main(java.lang.String[] argv) Test driver for CFHandler.
void	readCFFile(java.lang.String fileName, java.lang.String tag) Reads control flow information from a .cf file.
void	setClearOnLoad(boolean enabled) Specifies whether previously cached control flow graphs should be cleared whenever a new control flow file is read.
void	setLegacySort(boolean enabled) Specifies whether the control flow graphs should be written to file using the same sorting criterion applied up through v3.3.0 of Galileo.
java.util.Iterator	sortedIterator() Gets a sorted iterator over all of the control flow graphs currently registered with the handler.
boolean	usingLegacySort() Gets whether the control flow graphs are to be written to file using the same sorting criterion applied up through v3.3.0 of Galileo.
void	writeCFFile(java.lang.String fileName) Writes current control flow information to .cf file.
void	writeCFFile(java.lang.String className, java.lang.String fileName, java.lang.String tag) Writes current control flow information to .cf file.

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

CFHandler

public CFHandler()

Default constructor, creates a handler with a new cache for CFG storage.

CFHandler

public CFHandler(CFGCache sharedCache)

Creates a handler which is backed by the given CFG cache.

Parameters:

sharedCache - CFG cache from which the handler will retrieve CFGs for writing to file.

Method Detail

writeCFFile

public void writeCFFile(java.lang.String fileName)
                 throws java.io.FileNotFoundException,
                        java.io.IOException

Writes current control flow information to .cf file.

The control flow graphs currently registered with the handler are written to a .cf file. If necessary (and permitted), the file is created and placed in the Sofya database directory automatically.

Parameters:

fileName - Name of the control flow (.cf) file to be written.

Throws:

java.io.FileNotFoundException - If the specified file doesn't exist and can't be created.

java.io.IOException - If there is an error writing to the .cf file.

writeCFFile

public void writeCFFile(java.lang.String className,
                        java.lang.String fileName,
                        java.lang.String tag)
                 throws java.io.FileNotFoundException,
                        java.io.IOException

Writes current control flow information to .cf file.

The CFGs found in the cache for a specified class are written to a .cf file. If necessary (and permitted), the file is created and placed in the Sofya database directory automatically.

Parameters:

className - Name of the class for which control flow graphs are to be written to file.

fileName - Name of the control flow (.cf) file to be written.

tag - Database tag to be associated with the file.

Throws:

java.io.FileNotFoundException - If the specified file doesn't exist and can't be created.

java.io.IOException - If there is an error writing to the .cf file.

readCFFile

public void readCFFile(java.lang.String fileName,
                       java.lang.String tag)
                throws java.io.FileNotFoundException,
                       EmptyFileException,
                       BadFileFormatException,
                       java.io.IOException

Reads control flow information from a .cf file.

The control flow information is read from the file and stored to internal data structures. This data can then be retrieved via other accessor functions in this class, such as getCFG(sofya.base.MethodSignature). The .cf file is assumed to be located in the Sofya database directory.

Parameters:

fileName - Name of the control flow file to be read.

tag - Database tag associated with the file.

Throws:

java.io.FileNotFoundException - If the specified file doesn't exist.

EmptyFileException - If the specified file contains no data.

BadFileFormatException - If the specified file is not a .cf file or is otherwise malformed or corrupted.

java.io.IOException - If there is an error reading from the .cf file.

addCFG

public void addCFG(CFG cfg)

Adds CFG to the current .cf file, using the method name or signature associated with the given CFG object.

Parameters:

cfg - CFG to be added to the control flow information in the currently opened .cf file.

containsCFG

public boolean containsCFG(MethodSignature signature)

Queries whether a CFG exists for a given method.

Parameters:

signature - Signature of the method which the handler should query for a CFG.

Returns:

true if a CFG is available for the given method, false otherwise.

containsCFG

public boolean containsCFG(java.lang.String methodName)

Queries whether a CFG exists for a given method.

Parameters:

methodName - Name of the method which the handler should query for a CFG.

Returns:

true if a CFG is available for the given method, false otherwise.

getCFG

public CFG getCFG(MethodSignature signature)
           throws MethodNotFoundException

Gets CFG for a method.

Parameters:

signature - Signature of the method whose CFG is to be retrieved.

Returns:

CFG constructed for the specified method.

Throws:

MethodNotFoundException - If the handler has no CFG associated with a method with the specified signature.

getCFG

public CFG getCFG(java.lang.String methodName)
           throws MethodNotFoundException

Gets CFG for a method.

Parameters:

methodName - Name of the method whose CFG is to be retrieved.

Returns:

CFG constructed for the specified method.

Throws:

MethodNotFoundException - If the handler has no CFG associated with a method of the specified name.

getMethodList

public java.lang.String[] getMethodList()

Gets the list of pretty-printed methods associated with control flow graphs registered with the handler.

Returns:

List of names of the methods the handler knows about.

getSignatureList

public MethodSignature[] getSignatureList()

Gets the list of method signatures for control flow graphs registered with the handler.

Returns:

List of names of the methods the handler knows about.

getSignatureList

public MethodSignature[] getSignatureList(java.lang.String className)

Gets the list of method signatures for control flow graphs from a specific class which are registered with the handler.

Parameters:

className - Name of the class for which associated method signatures are to be retrieved.

Returns:

List of names of the methods the handler knows about.

iterator

public java.util.Iterator iterator()

Gets an iterator over all of the control flow graphs currently registered with the handler.

Returns:

An iterator over the control flow graphs currently registered with the handler.

sortedIterator

public java.util.Iterator sortedIterator()

Gets a sorted iterator over all of the control flow graphs currently registered with the handler.

The order of iteration is consistent with the lexical ordering of the names of the methods with which the graphs are associated.

Returns:

An iterator over the graphs in the cache, which iterates over the graphs in the order determined by a lexical sorting of the names of the methods with which the graphs are associated.

See Also:

MethodSignature.NameComparator

setLegacySort

public void setLegacySort(boolean enabled)

Specifies whether the control flow graphs should be written to file using the same sorting criterion applied up through v3.3.0 of Galileo.

Parameters:

enabled - true to enable legacy sorting, false otherwise.

usingLegacySort

public boolean usingLegacySort()

Gets whether the control flow graphs are to be written to file using the same sorting criterion applied up through v3.3.0 of Galileo.

Returns:

true if legacy sorting is enabled, false otherwise.

setClearOnLoad

public void setClearOnLoad(boolean enabled)

Specifies whether previously cached control flow graphs should be cleared whenever a new control flow file is read. This is true by default.

Normally it is the contract of the handler to only retain graphs from the most recently loaded control flow file. This may be disabled under certain special circumstances for performance reasons.

Parameters:

enabled - true to have existing control flow graphs removed from the cache whenever a new control flow file is read, false to permit the handler to cache control flow graphs from multiple control flow files.

isClearedOnLoad

public boolean isClearedOnLoad()

Gets whether the handler clears existing control flow graphs from its cache when a new control flow file is read.

Returns:

true if existing control flow graphs are cleared whenever a new control flow file is read, false if the handler will retain control flow graphs from multiple control flow files in its cache.

getClassName

public java.lang.String getClassName()

Gets the name of the class which the handler believes is currently loaded, which is set only when a CF file has been loaded by the handler.

Returns:

The name of the class for which control flow information was loaded from file.

main

public static void main(java.lang.String[] argv)

Test driver for CFHandler.