TraceHandler (Sofya API Documentation)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

sofya.ed.structural
Class TraceHandler

java.lang.Object
  sofya.base.Handler
      sofya.ed.structural.TraceHandler

All Implemented Interfaces:: SConstants, CoverageListenerManager, ActiveComponent

public class TraceHandler
extends Handler
implements CoverageListenerManager, ActiveComponent, SConstants
extends Handler
implements CoverageListenerManager, ActiveComponent, SConstants

The trace handler provides routines to manipulate Sofya coverage trace (.tr) files and to create coverage trace objects.

Version:: 04/21/2006
Author:: Alex Kinneer
See Also:: CoverageTrace, TraceViewer

Nested Class Summary

Nested classes/interfaces inherited from interface sofya.base.SConstants
`SConstants.BlockLabel, SConstants.BlockObjectType, SConstants.BlockSubType, SConstants.BlockType, SConstants.BranchObjectType, SConstants.BranchType, SConstants.EDObjectType, SConstants.TraceObjectType`

Field Summary

Fields inherited from class sofya.base.Handler
`HANDLER_EXTENSIONS, LINE_SEP`

Fields inherited from interface sofya.base.SConstants
`DEFAULT_PORT, INST_COMPATIBLE, INST_OLD_UNSUPPORTED, INST_OPT_NORMAL, INST_OPT_SEQUENCE, SIG_CHKALIVE, SIG_ECHO`

Constructor Summary
`TraceHandler()` Creates a trace handler with no traces yet registered and the structural entity type set to basic blocks.
`TraceHandler(int typeFlags)` Creates a trace handler with the specified trace types active and the structural enetity type set to basic blocks.
`TraceHandler(int typeFlags, SConstants.TraceObjectType objectType)` Creates a trace handler with the specified trace types and structural entity type.

Method Summary
`void`	`clear()` Removes all of the method traces.
`void`	`commitCoverageResults(int streamId)` Notification that an event stream has completed.
`java.util.List`	`configure(java.util.List params)` Configures this component from command line parameters.
`boolean`	`containsTrace(java.lang.String methodName)` Reports whether the handler contains a trace for the given method.
`BlockCoverageListener`	`getBlockCoverageListener(java.lang.String classAndSignature)` Gets the basic block listener for a particular method.
`BranchCoverageListener`	`getBranchCoverageListener(java.lang.String classAndSignature)` Gets the branch listener for a particular method.
`java.lang.String[]`	`getMethodList()` Gets the list of methods names for which traces are currently registered with the handler.
`SConstants.TraceObjectType`	`getObjectType()` Gets the type code for the trace entities recorded in the traces being managed by the handler.
`CoverageTrace`	`getTrace(java.lang.String methodName)` Gets the trace associated with a given method.
`java.lang.String`	`getTraceFileName()` Gets the name of the trace file that will be written.
`int`	`getTypeFlags()` Gets the bit mask indicating what types of objects are marked by the traces being managed by the handler.
`java.lang.String`	`getTypesString()` Gets a string listing the types of objects marked by the traces being managed by the handler.
`void`	`initialize()` Initializes the coverage listener manager.
`void`	`initializeBlockListener(java.lang.String classAndSignature, int blockCount)` Notification to initialize a basic block listener for a method.
`void`	`initializeBranchListener(java.lang.String classAndSignature, int branchCount)` Notification to initialize a branch listener for a method.
`boolean`	`isAppending()` Reports whether the trace handler will merge any new coverage information into any existing trace file of the same name.
`boolean`	`isReady()` Reports whether this component is ready for the event dispatcher to begin dispatching events.
`static void`	`main(java.lang.String[] argv)` Provides a function to merge two trace files, if given the argument '`-merge`' with appropriate values.
`void`	`mergeTraceFile(java.lang.String fileName)` Merges another trace file with the currently loaded trace file.
`void`	`newEventStream(int streamId)` Notification that a new event stream is starting.
`void`	`readTraceFile(java.lang.String fileName)` Reads a trace file, making the information available for request from the handler.
`void`	`readTraceFile(java.lang.String fileName, boolean safe)` Reads a trace file, making the information available for request from the handler.
`void`	`register(EventDispatcherConfiguration edConfig)` Registers this component with the event dispatcher.
`void`	`release()` Notifies this component that its current lifecycle has expired and that it should commit any stored state and release resources.
`void`	`reset()` Notifies this component to clear its configuration and reset any internal state.
`void`	`setAppending(boolean enable)` Sets whether the trace handler will merge any new coverage information into any existing trace file of the same name.
`void`	`setObjectType(SConstants.TraceObjectType type)` Sets the type code for the trace entities recorded in the traces being managed by the handler.
`void`	`setTrace(java.lang.String methodName, CoverageTrace trace)` Sets the trace associated with a given method.
`void`	`setTraceFileName(java.lang.String value)` Sets the name of the trace file to be written.
`void`	`setTypeFlags(int typeFlags)` Sets the bit mask indicating what types of objects are marked by the traces being managed by the handler.
`protected static java.util.BitSet`	`toBinary(java.lang.String hexString)`
`protected static java.lang.String`	`toHex(java.util.BitSet bv, int size)`
`void`	`writeTraceFile(java.lang.String fileName, boolean append)` Writes a trace file to the Sofya database using the trace information currently registered with the handler.

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`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

TraceHandler

public TraceHandler()

Creates a trace handler with no traces yet registered and the structural entity type set to basic blocks.

Note: You must call setTypeFlags(int) before attempting to save a trace file or an IllegalArgumentException will be thrown.

TraceHandler

public TraceHandler(int typeFlags)

Creates a trace handler with the specified trace types active and the structural enetity type set to basic blocks.

Parameters:

typeFlags - Bit mask representing the types of blocks that are marked in the traces managed by the handler. Can be any bitwise combination of the following (See SConstants):

SConstants.BlockType.MASK_BASIC
SConstants.BlockType.MASK_ENTRY
SConstants.BlockType.MASK_EXIT
SConstants.BlockType.MASK_CALL

Throws:

java.lang.IllegalArgumentException - If the bit vector doesn't have a bit set which corresponds to a valid block type.

TraceHandler

public TraceHandler(int typeFlags,
                    SConstants.TraceObjectType objectType)

Creates a trace handler with the specified trace types and structural entity type.

Parameters:: typeFlags - Bit mask representing the types of objects that are marked in the traces managed by the handler. The meaning of the bits in the vector is determined by objectType.; objectType - Code specifying the type of trace entities recorded by the traces managed by the handler.

Method Detail

isAppending

public boolean isAppending()

Reports whether the trace handler will merge any new coverage information into any existing trace file of the same name.

Returns:: true if the trace handler will merge current coverage information with the information contained in any existing trace file with the same name.

setAppending

public void setAppending(boolean enable)

Sets whether the trace handler will merge any new coverage information into any existing trace file of the same name.

Parameters:: enable - true to instruct the trace handler to merge current coverage information with the information contained in any existing trace file with the same name.

getTraceFileName

public java.lang.String getTraceFileName()

Gets the name of the trace file that will be written.

Returns:: The name of the trace file.

setTraceFileName

public void setTraceFileName(java.lang.String value)

Sets the name of the trace file to be written.

Parameters:: value - The name of the trace file to be written.

register

public void register(EventDispatcherConfiguration edConfig)

Description copied from interface: ActiveComponent

Registers this component with the event dispatcher.

This method is called each time an event dispatcher prepares to initiate a new event stream, caused by a call to ProgramEventDispatcher.startDispatcher().

Specified by:: register in interface ActiveComponent

Parameters:: edConfig - The current configuration of system global resources and settings that the component may (and should) use as appropriate.

configure

public java.util.List configure(java.util.List params)

Description copied from interface: ActiveComponent

Configures this component from command line parameters.

This method provides a component the opportunity to define and process command line parameters required to configure itself. Components participate in a processing chain, initiated in Sofya-provided event dispatchers by calling this method on the processing strategy. The processing strategies provided by Sofya in turn invoke this method on any listeners implementing this interface.

Specified by:: configure in interface ActiveComponent

Parameters:: params - A list of command line tokens that have not yet been processed by any previous components.
Returns:: The list of parameters, with any recognized parameters and associated values removed. This enables the chaining of parameter processing.

reset

public void reset()

Description copied from interface: ActiveComponent

Notifies this component to clear its configuration and reset any internal state.

Calls to this method are chained similary to the ActiveComponent.configure(java.util.List) method. This method is invoked by the event dispatcher prior to reconfiguration. Normally it should be used to clear any configuration state to avoid using stale values.

Specified by:: reset in interface ActiveComponent

isReady

public boolean isReady()

Description copied from interface: ActiveComponent

Reports whether this component is ready for the event dispatcher to begin dispatching events.

Calls to this method are chained similarly to the ActiveComponent.configure(java.util.List) method. The event dispatcher will fail with an error if a client invokes ProgramEventDispatcher.startDispatcher() when any attached component returns false from this method.

Specified by:: isReady in interface ActiveComponent

Returns:: true if this component is ready for the event dispatcher to begin dispatching events, false otherwise.

release

public void release()

Description copied from interface: ActiveComponent

Notifies this component that its current lifecycle has expired and that it should commit any stored state and release resources.

Calls to this method are chained similary to the ActiveComponent.configure(java.util.List) method. This method is invoked directly by a client of the event dispatcher. Normally, it should be used to release any resources that were required to persist over multiple runs of the event dispatcher.

Specified by:: release in interface ActiveComponent