sofya.ed.structural
Class SequenceTraceWriter

java.lang.Object
  sofya.ed.structural.SequenceTraceWriter

All Implemented Interfaces:

BlockEventListener, BranchEventListener, ActiveComponent

public final class SequenceTraceWriter
extends java.lang.Object
implements ActiveComponent, BlockEventListener, BranchEventListener

The sequence trace writer is responsible for generating basic block and branch edge sequence trace files from the event streams produced by a structural event dispatcher.

@author Alex Kinneer

@version 04/24/2006

Field Summary

static java.lang.String	relaySocketAddr Machine address to which the relay socket will attempt to connect.
static int	relaySocketPort Port to which the relay socket will attempt to connect.

Constructor Summary

SequenceTraceWriter()
Creates a new sequence trace writer using the default configuration.

SequenceTraceWriter(boolean toSocket, java.lang.String preData, java.lang.String postData, java.lang.String trName, boolean appendToTrace)
Creates a new sequence trace writer.

Method Summary

void	callBlockExecuteEvent(java.lang.String classAndSignature, int id) Notification that a call block was executed.
void	callBranchExecuteEvent(java.lang.String classAndSignature, int id) Notification that a call branch was executed.
void	codeBlockExecuteEvent(java.lang.String classAndSignature, int id) Notification that a general basic block was executed.
void	commitEventStream(int streamId) Notification that an event stream has completed.
java.util.List	configure(java.util.List params) Configures this component from command line parameters.
void	entryBlockExecuteEvent(java.lang.String classAndSignature, int id) Notification that an entry block was executed.
void	entryBranchExecuteEvent(java.lang.String classAndSignature, int id) Notification that an entry branch was executed.
void	exitBlockExecuteEvent(java.lang.String classAndSignature, int id) Notification that an exit block was executed.
java.lang.String	getPostData() Gets the data set to be inserted at the end of the trace.
java.lang.String	getPreData() Gets the data set to be inserted at the beginning of the trace.
java.lang.String	getTraceFileName() Gets the name of the trace file that will be written.
void	ifBranchExecuteEvent(java.lang.String classAndSignature, int id) Notification that an if branch was executed.
void	initialize() Initializes the event listener.
boolean	isAppending() Reports whether the trace writer is set to append the trace data for the current event stream to any existing trace file or whether it will overwrite it.
boolean	isForJUnit() Reports whether trace files are being generated from JUnit test cases.
boolean	isReady() Reports whether this component is ready for the event dispatcher to begin dispatching events.
void	methodEnterEvent(java.lang.String classAndSignature, int count) Notification that a new method has been entered.
void	newEventStream(int streamId) Notification that a new event stream is starting.
void	otherBranchExecuteEvent(java.lang.String classAndSignature, int id) Notification that a summary branch was executed.
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	returnBlockExecuteEvent(java.lang.String classAndSignature, int id) Notification that a return block was executed.
void	setAppending(boolean enable) Sets whether the trace writer will append the trace data for the current event stream to any existing trace file or whether it will overwrite it.
void	setForJUnit(boolean enable) Specifies whether trace files are being generated from JUnit test cases.
void	setPostData(java.lang.String data) Sets the data to be inserted at the end of the trace.
void	setPreData(java.lang.String data) Sets the data to be inserted at the beginning of the trace.
void	setTraceFileName(java.lang.String value) Sets the name of the trace file to be written.
void	switchBranchExecuteEvent(java.lang.String classAndSignature, int id) Notification that a switch branch was executed.
void	throwBranchExecuteEvent(java.lang.String classAndSignature, int id) Notification that a throws branch was executed.
void	useRelaySocket(boolean enable) Sets whether the trace writer is to relay trace information to a socket.
boolean	usingRelaySocket() Reports whether the trace writer will relay trace information to a socket.

Methods inherited from class java.lang.Object

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

Field Detail

relaySocketAddr

public static final java.lang.String relaySocketAddr

Machine address to which the relay socket will attempt to connect.

See Also:

Constant Field Values

relaySocketPort

public static final int relaySocketPort

Port to which the relay socket will attempt to connect.

See Also:

Constant Field Values

Constructor Detail

SequenceTraceWriter

public SequenceTraceWriter()

Creates a new sequence trace writer using the default configuration.

SequenceTraceWriter

public SequenceTraceWriter(boolean toSocket,
                           java.lang.String preData,
                           java.lang.String postData,
                           java.lang.String trName,
                           boolean appendToTrace)

Creates a new sequence trace writer.

Parameters:

toSocket - Flag to indicate whether trace information should be related to a socket.

preData - Data to be inserted at the beginning of each trace.

postData - Data to be appended at the end of each trace.

trName - Name of the trace file to be created.

appendToTrace - Flag specifying whether the trace writer should append current trace data to any existing trace file of the same name.

Method Detail

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.

initialize

public void initialize()

Description copied from interface: BlockEventListener

Initializes the event listener. Listeners that need to perform configuration or setup of state that will persist across multiple event streams should implement this method.

This method is called automatically by a JUnitEventDispatcher prior to beginning execution of test cases. It is the responsibility of the applications using other event dispatchers to call this method at the appropriate time.

Specified by:

initialize in interface BlockEventListener

Specified by:

initialize in interface BranchEventListener

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

isAppending

public boolean isAppending()

Reports whether the trace writer is set to append the trace data for the current event stream to any existing trace file or whether it will overwrite it.

Returns:

true if the trace writer will append the trace data for the current event stream to any existing trace file, false otherwise.

setAppending

public void setAppending(boolean enable)

Sets whether the trace writer will append the trace data for the current event stream to any existing trace file or whether it will overwrite it.

Parameters:

enable - true if the trace writer is to append the trace data for the current event stream to any existing trace file, false otherwise.

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.

usingRelaySocket

public boolean usingRelaySocket()

Reports whether the trace writer will relay trace information to a socket.

Returns:

true if trace information will be relayed to a socket, false otherwise.

useRelaySocket

public void useRelaySocket(boolean enable)
                    throws java.lang.IllegalStateException

Sets whether the trace writer is to relay trace information to a socket.

Parameters:

enable - true to specify that trace data should be sent to a socket, false to specify that trace data should be written to file.

Throws:

java.lang.IllegalStateException

getPreData

public java.lang.String getPreData()

Gets the data set to be inserted at the beginning of the trace.

Returns:

Data which will be inserted at the beginning of the trace.

setPreData

public void setPreData(java.lang.String data)
                throws java.lang.IllegalStateException

Sets the data to be inserted at the beginning of the trace.

Parameters:

data - Data which will be inserted at the beginning of the trace.

Throws:

java.lang.IllegalStateException

getPostData

public java.lang.String getPostData()

Gets the data set to be inserted at the end of the trace.

Returns:

Data which will be inserted at the end of the trace.

setPostData

public void setPostData(java.lang.String data)
                 throws java.lang.IllegalStateException

Sets the data to be inserted at the end of the trace.

Parameters:

data - Data which will be inserted at the end of the trace.

Throws:

java.lang.IllegalStateException

isForJUnit

public boolean isForJUnit()

Reports whether trace files are being generated from JUnit test cases.

Returns:

true if trace data is being generated from JUnit test cases, false otherwise.

setForJUnit

public void setForJUnit(boolean enable)

Specifies whether trace files are being generated from JUnit test cases.

Parameters:

enable - true if trace data is being generated from JUnit test cases, false otherwise.

newEventStream

public void newEventStream(int streamId)

Notification that a new event stream is starting.

Note that if the trace writer is generating trace files, this is the point at which a new trace file is opened for output. Any previous trace file must be moved or copied before this event is received unless the trace writer is configured to append to the existing trace. This is handled automatically by when the trace writer is being used by a JUnit SelectiveTestRunner and the '-o' option was passed to the test runner.

Specified by:

newEventStream in interface BlockEventListener

Specified by:

newEventStream in interface BranchEventListener

Parameters:

streamId - Identifier associated with the event stream, such as a test case number.

commitEventStream

public void commitEventStream(int streamId)

Notification that an event stream has completed.

Note that if the trace writer is generating trace files, this is the point at which the output stream to the trace file is closed.

Specified by:

commitEventStream in interface BlockEventListener

Specified by:

commitEventStream in interface BranchEventListener

Parameters:

streamId - Identifier associated with the finished event stream, such as a test case number.

methodEnterEvent

public void methodEnterEvent(java.lang.String classAndSignature,
                             int count)

Notification that a new method has been entered.

Specified by:

methodEnterEvent in interface BlockEventListener

Specified by:

methodEnterEvent in interface BranchEventListener

Parameters:

classAndSignature - Concatenation of the fully qualified class name, method name, and JNI signature of the method entered.

count - The number of structural entities in the method.

codeBlockExecuteEvent

public void codeBlockExecuteEvent(java.lang.String classAndSignature,
                                  int id)

Description copied from interface: BlockEventListener

Notification that a general basic block was executed.

Specified by:

codeBlockExecuteEvent in interface BlockEventListener

Parameters:

classAndSignature - Concatenation of the fully qualified class name, method name, and JNI signature of the method in which the basic block was executed.

id - Identifier of the basic block that was executed. Correlates to the basic block identifiers reported in a CFG.

callBlockExecuteEvent

public void callBlockExecuteEvent(java.lang.String classAndSignature,
                                  int id)

Description copied from interface: BlockEventListener

Notification that a call block was executed.

Specified by:

callBlockExecuteEvent in interface BlockEventListener

Parameters:

classAndSignature - Concatenation of the fully qualified class name, method name, and JNI signature of the method in which the basic block was executed.

id - Identifier of the basic block that was executed. Correlates to the basic block identifiers reported in a CFG.

returnBlockExecuteEvent

public void returnBlockExecuteEvent(java.lang.String classAndSignature,
                                    int id)

Description copied from interface: BlockEventListener

Notification that a return block was executed.

A return block is a virtual block that does not correlate to any code in the executing program. It serves only as a marker that execution has returned to a caller following execution of a call block.

Specified by:

returnBlockExecuteEvent in interface BlockEventListener

Parameters:

classAndSignature - Concatenation of the fully qualified class name, method name, and JNI signature of the method in which the basic block was executed.

id - Identifier of the basic block that was executed. Correlates to the basic block identifiers reported in a CFG.

entryBlockExecuteEvent

public void entryBlockExecuteEvent(java.lang.String classAndSignature,
                                   int id)

Description copied from interface: BlockEventListener

Notification that an entry block was executed.

An entry block is a virtual block that does not correlate to any code in the executing program. It serves only as a marker that execution has entered a new method.

Specified by:

entryBlockExecuteEvent in interface BlockEventListener

Parameters:

classAndSignature - Concatenation of the fully qualified class name, method name, and JNI signature of the method in which the basic block was executed.

id - Identifier of the basic block that was executed. Correlates to the basic block identifiers reported in a CFG.

exitBlockExecuteEvent

public void exitBlockExecuteEvent(java.lang.String classAndSignature,
                                  int id)

Description copied from interface: BlockEventListener

Notification that an exit block was executed.

An exit block is a virtual block that does not correlate to any code in the executing program. It serves only as a marker that execution has exited a method.

There is only one normal exit block in a method, but there may be multiple exceptional exit blocks in a method.

Specified by:

exitBlockExecuteEvent in interface BlockEventListener

Parameters:

classAndSignature - Concatenation of the fully qualified class name, method name, and JNI signature of the method in which the basic block was executed.

id - Identifier of the basic block that was executed. Correlates to the basic block identifiers reported in a CFG.

ifBranchExecuteEvent

public void ifBranchExecuteEvent(java.lang.String classAndSignature,
                                 int id)

Description copied from interface: BranchEventListener

Notification that an if branch was executed.

Specified by:

ifBranchExecuteEvent in interface BranchEventListener

Parameters:

classAndSignature - Concatenation of the fully qualified class name, method name, and JNI signature of the method in which the branch was executed.

id - Identifier of the branch that was executed. Correlates to the branch identifiers reported in a CFG.

switchBranchExecuteEvent

public void switchBranchExecuteEvent(java.lang.String classAndSignature,
                                     int id)

Description copied from interface: BranchEventListener

Notification that a switch branch was executed.

Specified by:

switchBranchExecuteEvent in interface BranchEventListener

Parameters:

classAndSignature - Concatenation of the fully qualified class name, method name, and JNI signature of the method in which the branch was executed.

id - Identifier of the branch that was executed. Correlates to the branch identifiers reported in a CFG.

throwBranchExecuteEvent

public void throwBranchExecuteEvent(java.lang.String classAndSignature,
                                    int id)

Description copied from interface: BranchEventListener

Notification that a throws branch was executed.

Note that a particular throws statement is not considered a branch if the control flow graph builder determines that only one type of exception can ever be thrown.

Specified by:

throwBranchExecuteEvent in interface BranchEventListener

Parameters:

classAndSignature - Concatenation of the fully qualified class name, method name, and JNI signature of the method in which the branch was executed.

id - Identifier of the branch that was executed. Correlates to the branch identifiers reported in a CFG.

callBranchExecuteEvent

public void callBranchExecuteEvent(java.lang.String classAndSignature,
                                   int id)

Description copied from interface: BranchEventListener

Notification that a call branch was executed.

Specified by:

callBranchExecuteEvent in interface BranchEventListener

Parameters:

classAndSignature - Concatenation of the fully qualified class name, method name, and JNI signature of the method in which the branch was executed.

id - Identifier of the branch that was executed. Correlates to the branch identifiers reported in a CFG.

entryBranchExecuteEvent

public void entryBranchExecuteEvent(java.lang.String classAndSignature,
                                    int id)

Description copied from interface: BranchEventListener

Notification that an entry branch was executed.

Method entry is not actually a branch, however, this event is provided for the benefit of analyses that may wish to have information about method entry inlined in the event stream as a type-compatible entity.

Specified by:

entryBranchExecuteEvent in interface BranchEventListener

Parameters:

classAndSignature - Concatenation of the fully qualified class name, method name, and JNI signature of the method in which the branch was executed.

id - Identifier of the branch that was executed. Correlates to the branch identifiers reported in a CFG.

otherBranchExecuteEvent

public void otherBranchExecuteEvent(java.lang.String classAndSignature,
                                    int id)

Description copied from interface: BranchEventListener

Notification that a summary branch was executed.

A summary branch is used to capture any branching of execution that causes exit from the currently executing method. This is normally associated with asynchronous exceptions and runtime exceptions that can potentially be raised at too many locations to be practically encoded in a control flow representation.

Specified by:

otherBranchExecuteEvent in interface BranchEventListener

Parameters:

classAndSignature - Concatenation of the fully qualified class name, method name, and JNI signature of the method in which the branch was executed.

id - Identifier of the branch that was executed. Correlates to the branch identifiers reported in a CFG.