sofya.graphs.cfg
Class MapHandler

java.lang.Object
  extended by sofya.base.Handler
      extended by sofya.graphs.cfg.MapHandler

public class MapHandler
extends Handler

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

Version:
11/04/2004
Author:
Alex Kinneer
See Also:
CFG, CFHandler, MapViewer

Field Summary
 
Fields inherited from class sofya.base.Handler
HANDLER_EXTENSIONS, LINE_SEP
 
Constructor Summary
MapHandler()
          Default constructor, initalizes internal CFG hashmap.
MapHandler(CFGCache sharedCache)
          Creates a handler which is backed by the given CFG cache.
 
Method Summary
 void addCFG(CFG cfg)
          Adds CFG to the current .map 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 method names 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 map 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 MapHandler.
 void readMapFile(java.lang.String fileName, java.lang.String tag)
          Reads map information from a .map file.
 void setClearOnLoad(boolean enabled)
          Specifies whether previously cached control flow graphs should be cleared whenever a new map 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 writeMapFile(java.lang.String fileName)
          Writes current map information to .map file.
 void writeMapFile(java.lang.String className, java.lang.String fileName, java.lang.String tag)
          Writes current map information to .map 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

MapHandler

public MapHandler()
Default constructor, initalizes internal CFG hashmap.


MapHandler

public MapHandler(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

writeMapFile

public void writeMapFile(java.lang.String fileName)
                  throws java.io.FileNotFoundException,
                         java.io.IOException
Writes current map information to .map file.

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

Parameters:
fileName - Name of the map (.map) 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 .map file.

writeMapFile

public void writeMapFile(java.lang.String className,
                         java.lang.String fileName,
                         java.lang.String tag)
                  throws java.io.FileNotFoundException,
                         java.io.IOException
Writes current map information to .map file.

The map information for control flow graphs currently registered with the handler are written to a .map 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 map information is to be written to file.
fileName - Name of the map (.map) 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 .map file.

readMapFile

public void readMapFile(java.lang.String fileName,
                        java.lang.String tag)
                 throws java.io.FileNotFoundException,
                        EmptyFileException,
                        BadFileFormatException,
                        java.io.IOException
Reads map information from a .map file.

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

Parameters:
fileName - Name of the map 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 .map file or is otherwise malformed or corrupted.
java.io.IOException - If there is an error reading from the .map file.

addCFG

public void addCFG(CFG cfg)
Adds CFG to the current .map file, using the method name or signature associated with the given CFG object.

Parameters:
cfg - CFG to be added to the map information in the currently opened .map 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 method names 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 map 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 map 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 map file is read, false to permit the handler to cache control flow graphs from multiple map files.

isClearedOnLoad

public boolean isClearedOnLoad()
Gets whether the handler clears existing control flow graphs from its cache when a new map file is read.

Returns:
true if existing control flow graphs are cleared whenever a new map file is read, false if the handler will retain control flow graphs from multiple map 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 MapHandler.