sofya.ed.structural
Class ProgramEventDispatcher

java.lang.Object
  sofya.ed.structural.AbstractEventDispatcher
      sofya.ed.structural.ProgramEventDispatcher

public class ProgramEventDispatcher
extends AbstractEventDispatcher

A program event dispatcher is responsible for launching a subject program and dispatching an event stream of structural events observed during execution.

The program event dispatcher executes an instrumented subject in a separate Java virtual machine using a socket to receive the instrumentation probes. By implementing the event dispatcher in this manner, multi-threaded subjects can be monitored correctly (for coverage), subjects can be supplied specialized classpaths, and the event dispatcher can run other program event dispatchers as subjects.

The event dispatcher operates by creating a thread to receive and process instrumentation probes generated by the subject through a socket. The main thread then executes the subject in a separate JVM process and waits for it to terminate. It is considered paramount that a subject not be terminated unexpectedly so as to avoid an indeterminate or unstable system state. Therefore, termination of the subject is deferred as long as possible in the event of exceptions related to the event dispatcher. The socket connection to the subject is static and remains open until the subject terminates. This avoids severe performance degradation which is observed when transient socket connections are created for each trace message.

To support the static connection mechanism while preserving total self- traceability, a SocketProbe is used for all subjects. This class is packaged into a jar file that is added to the bootstrap classpath of the invoked subject; thus the static method calls to the SocketProbe resolve to the copy shared by the invoking event dispatcher, including when the subject is another event dispatcher, without introducing any ambiguities regarding the locations of subject classes in the classpath. A renamed copy of SocketProbe is also cloned into the jar file at runtime when it is desired to trace the execution of SocketProbe itself. If multiple event dispatchers are being chained together, the original clone is copied to each subsequent dispatcher. For additional details regarding how the instrumentation connection is made from the subject, see SocketProbe.

When an event dispatcher is running another event dispatcher as its subject, a situation arises in which the subject event dispatcher is running in one JVM process, and the subject event dispatcher's SocketProbe (logically considered a component of the subject event dispatcher) is running in another JVM process. Thus to perform a complete trace of a subject event dispatcher, it is necessary to receive socket connections for trace messages from two different processes. The invoking event dispatcher handles this situation by detecting that the subject is another event dispatcher (or being informed as such) and starting two processing threads executing a special synchronized version of the probe processing method. The subject event dispatcher will be instrumented to start its SocketProbe in a special mode that timestamps the trace messages. The synchronized threads then use the timestamps to preserve the order of the trace messages during processing. All of this special handling is internal - the resulting event stream appears no different than that generated for a regular subject.

For security and performance reasons, the event dispatcher socket only listens on the local loopback address (127.0.0.1). This address is normally a virtual address in software which is never visible external to the machine and should not require data to go through the network hardware.

Version:

06/12/2006

Author:

Alex Kinneer

See Also:

SocketProbe, Instrumentor, cfInstrumentor

Nested Class Summary

Nested classes/interfaces inherited from class sofya.ed.structural.AbstractEventDispatcher

AbstractEventDispatcher.CreateException, AbstractEventDispatcher.ExecException, AbstractEventDispatcher.SetupException, AbstractEventDispatcher.TraceFileException

Field Summary

protected static java.lang.String	className Name of the class currently set to be run by the dispatcher.
protected static java.lang.String	collectionsLib Location of the commons-collections library.
protected static EventDispatcherConfiguration	config The global configuration and resources for this event dispatcher.
protected static boolean	DEBUG Conditional compilation debug flag.
protected static char	fileSep Convenience variable to represent directory separation character.
static int	MAX_CONNECTIONS Maximum number of instrumentation connections that can be accepted by the server socket (simultaneously).
protected static java.lang.String	outputFile Name of output file to receive subject's output.
protected static char	pathSep Convenience variable to represent path separation character.
protected static boolean	pipeInput Flag to control whether stdin will be connected to the subject.
protected static int	port Port on which socket should be opened to receive trace statements.
protected SocketProcessingStrategy	processingStrategy The probe processing strategy that this dispatcher is configured to use.
protected sofya.ed.structural.ProgramEventDispatcher.ProcessorExecutor[]	processor Holder array for the probe processor runners, only one element is used unless the subject is another event dispatcher.
protected static java.lang.Thread[]	processorThread Holder array for the probe processing threads, only one element is used unless the subject is another event dispatcher.
protected static java.io.PrintStream	sbjout Stream to which subject's output should be written.
protected static java.net.ServerSocket	serverSocket Socket which accepts instrumentation connection(s).
protected static java.io.PrintStream	stderr Stream to which filter's error outputs should be written.
protected static java.io.PrintStream	stdout Stream to which filter's normal outputs should be written.
protected static java.lang.String[]	subjectArgs Set of arguments that will be passed to the subject.
protected static java.lang.String	subjectCP Java classpath that will be set for the subject when it is run.
protected static int	timeLimit Maximum time subject is allowed to run (0 equals no limit).

Fields inherited from class sofya.ed.structural.AbstractEventDispatcher

dispatcherReady, isInstrumented

Method Summary

protected void	checkRunning(java.lang.String msg) Checks whether the event dispatcher is currently running its subject and throws an exception if so.
java.util.List	configureDispatcher(java.util.List params) Configures this event dispatcher using the specified set of command line parameters.
java.util.List	configureDispatcher(java.lang.String[] params) Configures this event dispatcher using the specified set of command line parameters.
void	configureDispatcher(java.lang.String className, java.lang.String[] subjectArgs, java.lang.String subjectCP, int port, boolean pipeInput, int timeLimit, java.io.PrintStream sbjoutStream, java.io.PrintStream stdoutStream, java.io.PrintStream stderrStream) Configures the event dispatcher with a new set of parameters to run a subject class.
static ProgramEventDispatcher	createBlockCoverageTracer(java.lang.String[] argv, java.io.PrintStream sbjout, java.io.PrintStream stdout, java.io.PrintStream stderr) Constructs a ready to run event dispatcher to collect basic block coverage traces, equivalent to the old Sofya Filter class.
static ProgramEventDispatcher	createBlockSequenceTracer(java.lang.String[] argv, java.io.PrintStream sbjout, java.io.PrintStream stdout, java.io.PrintStream stderr) Constructs a ready to run event dispatcher to collect basic block sequence traces, equivalent to the old Sofya SequenceFilter class.
static ProgramEventDispatcher	createBranchCoverageTracer(java.lang.String[] argv, java.io.PrintStream sbjout, java.io.PrintStream stdout, java.io.PrintStream stderr) Constructs a ready to run event dispatcher to collect branch coverage traces, equivalent to the old Sofya BranchFilter class.
static ProgramEventDispatcher	createBranchSequenceTracer(java.lang.String[] argv, java.io.PrintStream sbjout, java.io.PrintStream stdout, java.io.PrintStream stderr) Constructs a ready to run event dispatcher to collect branch sequence traces, equivalent to the old Sofya BranchSequenceFilter class.
static ProgramEventDispatcher	createEventDispatcher(SocketProcessingStrategy strategy) Factory method that returns a singleton instance of the event dispatcher.
static ProgramEventDispatcher	createEventDispatcher(SocketProcessingStrategy processingStrategy, java.io.PrintStream sbjoutStream, java.io.PrintStream stdoutStream, java.io.PrintStream stderrStream) Factory method that returns a singleton instance of the event dispatcher.
static ProgramEventDispatcher	createEventDispatcher(SocketProcessingStrategy processingStrategy, java.lang.String className, java.lang.String[] subjectArgs, java.lang.String subjectCP, int port, boolean pipeInput, int timeLimit, java.io.PrintStream sbjoutStream, java.io.PrintStream stdoutStream, java.io.PrintStream stderrStream) Factory method that returns a singleton instance of the event dispatcher.
java.lang.String[]	getClassArguments() Gets the arguments to the subject class.
java.lang.String	getClassName() Gets the name of the subject class.
int	getPort() Gets the socket port on which the event dispatcher will listen for instrumentation from the subject.
SocketProcessingStrategy	getProcessingStrategy() Gets the probe processing strategy currently in use by the event dispatcher.
boolean	getRedirectInput() Reports whether the event dispatcher is set to redirect input on standard input to the subject's standard input stream.
java.lang.String	getSubjectClasspath() Gets the subject classpath.
java.lang.String	getSubjectOutputFile() Gets the name of the file to which subject output is redirected, if any.
int	getTimeLimit() Gets the maximum time in seconds that a subject is allowed to run before being forcibly terminated.
protected boolean	isReady() Reports whether the event dispatcher is ready to begin dispatching the event stream.
void	registerProcessor() Registers the probe processor and any attached components.
void	release() Releases this event dispatcher, its processing strategy, and any attached components.
void	reset() Resets the event dispatcher configuration; the event dispatcher must be reconfigured before it can be run again.
protected void	runSubject() Executes the subject, handling its inputs and outputs.
void	setClassArguments(java.lang.String[] arguments) Sets the arguments to the subject class.
void	setClassName(java.lang.String value) Sets the name of the subject class.
void	setPort(int port) Sets the socket port on which the event dispatcher will listen for instrumentation from the subject.
void	setProcessingStrategy(SocketProcessingStrategy processingStrategy) Sets the probe processing strategy to be used by the event dispatcher.
void	setRedirectInput(boolean enable) Sets whether the event dispatcher will redirect input on standard input to the subject's standard input stream.
void	setStandardErrorStream(java.io.OutputStream stderrStream) Sets the stream to which the event dispatcher error outputs will be written.
void	setStandardOutputStream(java.io.OutputStream stdoutStream) Sets the stream to which the event dispatcher standard outputs will be written.
void	setSubjectClasspath(java.lang.String cp) Sets the subject classpath.
void	setSubjectOutputFile(java.lang.String fileName) Sets the file to which the subject's outputs should be redirected.
void	setSubjectOutputStream(java.io.OutputStream sbjoutStream) Sets the stream to which subject outputs will be written.
void	setTimeLimit(int tl) Sets the maximum time in seconds that a subject is allowed to run before being forcibly terminated.
protected void	setup() Performs setup actions to prepare the event dispatcher and subject for execution.
void	startDispatcher() Performs setup and runs the processing threads threads and subject.
protected java.net.ServerSocket	startServer() Starts the server socket to receive the instrumentation connection(s).
protected void	startThreads() Creates and starts the trace statement processing thread(s).
protected void	stop() Signals the processing threads to stop.
protected void	stopServer() Stops the server socket, signalling the end of the event stream.
protected void	waitOnThreads() Waits for the probe processing threads to exit.

Methods inherited from class java.lang.Object

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

Field Detail

processingStrategy

protected SocketProcessingStrategy processingStrategy

The probe processing strategy that this dispatcher is configured to use.

processor

protected sofya.ed.structural.ProgramEventDispatcher.ProcessorExecutor[] processor

Holder array for the probe processor runners, only one element is used unless the subject is another event dispatcher.

processorThread

protected static java.lang.Thread[] processorThread

Holder array for the probe processing threads, only one element is used unless the subject is another event dispatcher.

DEBUG

protected static final boolean DEBUG

Conditional compilation debug flag. Set to false to ensure the compiler will optimize away all print statements guarded by this flag. When set to true, it may be convenient to remove the final qualifier and uncomment the -d parameter detection in main, so that this flag can be activated at the command line.

See Also:

Constant Field Values

config

protected static EventDispatcherConfiguration config

The global configuration and resources for this event dispatcher.

className

protected static java.lang.String className

Name of the class currently set to be run by the dispatcher.

subjectArgs

protected static java.lang.String[] subjectArgs

Set of arguments that will be passed to the subject.

subjectCP

protected static java.lang.String subjectCP

Java classpath that will be set for the subject when it is run.

port

protected static int port

Port on which socket should be opened to receive trace statements.

pipeInput

protected static boolean pipeInput

Flag to control whether stdin will be connected to the subject. Set to true when the -i option is used. This is false by default since it introduces the overhead of another thread and is not consistent with the objectives of automated regression testing.

timeLimit

protected static int timeLimit

Maximum time subject is allowed to run (0 equals no limit). Set using -tl option.

outputFile

protected static java.lang.String outputFile

Name of output file to receive subject's output. This takes precedence over sbjout.

sbjout

protected static java.io.PrintStream sbjout

Stream to which subject's output should be written.

stdout

protected static java.io.PrintStream stdout

Stream to which filter's normal outputs should be written.

stderr

protected static java.io.PrintStream stderr

Stream to which filter's error outputs should be written.

serverSocket

protected static volatile java.net.ServerSocket serverSocket

Socket which accepts instrumentation connection(s).

collectionsLib

protected static java.lang.String collectionsLib

Location of the commons-collections library. This is determined in the static initializer by searching the classpath for a directory containing the appropriate jar file.

fileSep

protected static final char fileSep

Convenience variable to represent directory separation character.

pathSep

protected static final char pathSep

Convenience variable to represent path separation character.

MAX_CONNECTIONS

public static final int MAX_CONNECTIONS

Maximum number of instrumentation connections that can be accepted by the server socket (simultaneously). Should not need to be greater than two (one connection for subject filter and one connection for subject filter's SocketProbe).

See Also:

Constant Field Values

Method Detail

createEventDispatcher

public static ProgramEventDispatcher createEventDispatcher(SocketProcessingStrategy strategy)
                                                    throws AbstractEventDispatcher.CreateException

Factory method that returns a singleton instance of the event dispatcher.

A singleton strategy is enforced because important parts of the class data are static. This is necessary to enable the multi-threaded probe processing strategy used when another event dispatcher is the subject, and for efficiency.

Parameters:

strategy - Processing strategy to be used to process probes received from the instrumentation.

Returns:

A new event dispatcher, or a reference to the existing singleton instance. An existing instance can be reconfigured, enabling dispatch of multiple event streams.

Throws:

CreateException - If the commons-collections library could not be found by the static initializer.

AbstractEventDispatcher.CreateException

createEventDispatcher

public static ProgramEventDispatcher createEventDispatcher(SocketProcessingStrategy processingStrategy,
                                                           java.io.PrintStream sbjoutStream,
                                                           java.io.PrintStream stdoutStream,
                                                           java.io.PrintStream stderrStream)
                                                    throws AbstractEventDispatcher.CreateException

Factory method that returns a singleton instance of the event dispatcher.

A singleton strategy is enforced because important parts of the class data are static. This is necessary to enable the multi-threaded probe processing strategy used when another event dispatcher is the subject, and for efficiency.

Parameters:

processingStrategy - Processing strategy to be used to process probes received from the instrumentation.

sbjoutStream - Output stream to which subject's outputs are to be written. If null, System.out is used by default.

stdoutStream - Output stream to which the event dispatcher's normal outputs are to be written. If null, System.out is used by default. When the dispatcher is compiled in DEBUG mode, debug information is also printed to this stream.

stderrStream - Output stream to which the event dispatcher's error outputs are to be written. If null, System.err is used by default.

Returns:

A new event dispatcher, or a reference to the existing singleton instance. An existing instance can be reconfigured, enabling dispatch of multiple event streams.

Throws:

CreateException - If the commons-collections library could not be found by the static initializer.

AbstractEventDispatcher.CreateException

createEventDispatcher

public static ProgramEventDispatcher createEventDispatcher(SocketProcessingStrategy processingStrategy,
                                                           java.lang.String className,
                                                           java.lang.String[] subjectArgs,
                                                           java.lang.String subjectCP,
                                                           int port,
                                                           boolean pipeInput,
                                                           int timeLimit,
                                                           java.io.PrintStream sbjoutStream,
                                                           java.io.PrintStream stdoutStream,
                                                           java.io.PrintStream stderrStream)
                                                    throws java.lang.IllegalArgumentException,
                                                           AbstractEventDispatcher.CreateException

Factory method that returns a singleton instance of the event dispatcher.

A singleton strategy is enforced because important parts of the class data are static. This is necessary to enable the multi-threaded probe processing strategy used when another event dispatcher is the subject, and for efficiency.

Parameters:

className - Name of the subject class which is to be executed.

subjectArgs - Set of arguments to be passed to the subject class.

subjectCP - Java classpath that will be set for the subject when it is executed.

port - The port number on which event dispatcher should listen for incoming instrumentation messages from the subject. The valid range is 1024 to 65535. An exception is the value -1, which instructs it to select the default port.

pipeInput - If true, the event dispatcher will redirect input on the standard input stream to the subject's standard input stream.

timeLimit - The length of time in seconds that the subject is allowed to run before being killed.

sbjoutStream - Output stream to which subject's outputs are to be written. If null, System.out is used by default.

stdoutStream - Output stream to which the event dispatcher's normal outputs are to be written. If null, System.out is used by default. When the dispatcher is compiled in DEBUG mode, debug information is also printed to this stream.

stderrStream - Output stream to which the event dispatcher's error outputs are to be written. If null, System.err is used by default.

Returns:

A new event dispatcher, or a reference to the existing singleton instance. An existing instance can be reconfigured, enabling dispatch of multiple event streams.

Throws:

CreateException - If the commons-collections library could not be found by the static initializer.

java.lang.IllegalArgumentException - If required parameters are missing, invalid parameters are encountered, or data required for optional parameters is missing.

AbstractEventDispatcher.CreateException

stop

protected void stop()

Signals the processing threads to stop.

This method signals the processing threads to forcibly terminate. The socket connection will be closed and any necessary standard cleanup is performed. Use with caution; this will result in incomplete traces and inconsistent behavior in the subject.

getProcessingStrategy

public SocketProcessingStrategy getProcessingStrategy()

Gets the probe processing strategy currently in use by the event dispatcher.

Returns:

The processing strategy being used by the event dispatcher to receive probes.

setProcessingStrategy

public void setProcessingStrategy(SocketProcessingStrategy processingStrategy)

Sets the probe processing strategy to be used by the event dispatcher.

Parameters:

processingStrategy - The processing strategy to be used by the event dispatcher to receive probes.

reset

public void reset()

Resets the event dispatcher configuration; the event dispatcher must be reconfigured before it can be run again.

isReady

protected boolean isReady()

Reports whether the event dispatcher is ready to begin dispatching the event stream.

Returns:

true if the event dispatcher and all attached components indicate that they are ready to being dispatching the event stream.

release

public void release()

Releases this event dispatcher, its processing strategy, and any attached components.

After release, attached components may have to be replaced or fully reinitialized.

registerProcessor

public void registerProcessor()

Registers the probe processor and any attached components.

startServer

protected java.net.ServerSocket startServer()
                                     throws AbstractEventDispatcher.ExecException

Starts the server socket to receive the instrumentation connection(s).

Throws:

AbstractEventDispatcher.ExecException - If there is an error binding the server socket.

stopServer

protected void stopServer()

Stops the server socket, signalling the end of the event stream.

startDispatcher

public void startDispatcher()
                     throws AbstractEventDispatcher.SetupException,
                            AbstractEventDispatcher.ExecException

Performs setup and runs the processing threads threads and subject. This is the main driving method for the event dispatcher.

Specified by:

startDispatcher in class AbstractEventDispatcher

Throws:

SetupException - If there is an error attempting to set up the event dispatcher to run the subject.

AbstractEventDispatcher.ExecException - If an error occurs executing the subject. This does not include exceptions thrown by the subject itself, only errors in the event dispatcher while attempting to interface with the subject.

AbstractEventDispatcher.SetupException

setup

protected void setup()
              throws AbstractEventDispatcher.SetupException

Performs setup actions to prepare the event dispatcher and subject for execution.

This method is responsible for relocating the SocketProbe, patching the subject's classpath, and creating SocketProbeAlt.

Throws:

SetupException - If there is an error performing any of the aforementioned tasks.

AbstractEventDispatcher.SetupException

startThreads

protected void startThreads()
                     throws AbstractEventDispatcher.ExecException

Creates and starts the trace statement processing thread(s).

Starts the thread(s) to process incoming instrumentation messages.

Throws:

AbstractEventDispatcher.ExecException - If there is an error binding the server socket to listen for incoming instrumentation messages.

waitOnThreads

protected void waitOnThreads()
                      throws AbstractEventDispatcher.ExecException

Waits for the probe processing threads to exit.

This method is used to ensure orderly termination of the threads, regardless of the circumstances under which the event dispatcher exits. If the subject was not found to be instrumented, this method will itself stop the processing threads.

Throws:

AbstractEventDispatcher.ExecException - If an exception occurs while waiting for the threads to exit.

runSubject

protected void runSubject()
                   throws AbstractEventDispatcher.ExecException

Executes the subject, handling its inputs and outputs.

The subject process is executed, and a thread is created to pipe outputs from the subject. If piping of input to the subject and/or a time limit has been imposed on the subject, those threads are created here also. Upon completion of the subject's execution (or forcible termination), the method waits for the processing threads to finish.

Throws:

AbstractEventDispatcher.ExecException

checkRunning

protected void checkRunning(java.lang.String msg)
                     throws java.lang.IllegalStateException

Checks whether the event dispatcher is currently running its subject and throws an exception if so.

This method can be used to guard operations that should not be performed while the event dispatcher is actively running a subject.

Parameters:

msg - Message to be assigned to the exception.

Throws:

java.lang.IllegalStateException - If the event dispatcher is currently running its subject.

configureDispatcher

public void configureDispatcher(java.lang.String className,
                                java.lang.String[] subjectArgs,
                                java.lang.String subjectCP,
                                int port,
                                boolean pipeInput,
                                int timeLimit,
                                java.io.PrintStream sbjoutStream,
                                java.io.PrintStream stdoutStream,
                                java.io.PrintStream stderrStream)
                         throws java.lang.IllegalArgumentException,
                                java.lang.IllegalStateException

Configures the event dispatcher with a new set of parameters to run a subject class.

Parameters:

className - Name of the subject class which is to be executed.

subjectArgs - Set of arguments to be passed to the subject class.

subjectCP - Java classpath that will be set for the subject when it is executed.

port - The port number on which event dispatcher should listen for incoming instrumentation messages from the subject. The valid range is 1024 to 65535. An exception is the value -1, which instructs it to select the default port.

pipeInput - If true, the event dispatcher will redirect input on the standard input stream to the subject's standard input stream.

timeLimit - The length of time in seconds that the subject is allowed to run before being killed.

sbjoutStream - Output stream to which subject's outputs are to be written. If null, System.out is used by default.

stdoutStream - Output stream to which the event dispatcher's normal outputs are to be written. If null, System.out is used by default. When the dispatcher is compiled in DEBUG mode, debug information is also printed to this stream.

stderrStream - Output stream to which the event dispatcher's error outputs are to be written. If null, System.err is used by default.

Throws:

java.lang.IllegalArgumentException - If required parameters are missing, invalid parameters are encountered, or data required for optional parameters is missing.

java.lang.IllegalStateException - If called while the event dispatcher is running.

configureDispatcher

public java.util.List configureDispatcher(java.lang.String[] params)
                                   throws java.lang.IllegalArgumentException,
                                          java.lang.IllegalStateException

Configures this event dispatcher using the specified set of command line parameters.

Parameters:

params - Array of command line parameters.

Returns:

A list of parameters that were unrecognized. If the method does not throw an exception, the event dispatcher will have been configured to a runnable state, thus it is at the discretion of the caller whether or not to do anything with this list.

Throws:

java.lang.IllegalArgumentException - If required parameters are missing or data required for optional parameters is missing.

java.lang.IllegalStateException - If called while the event dispatcher is running.

configureDispatcher

public java.util.List configureDispatcher(java.util.List params)
                                   throws java.lang.IllegalArgumentException,
                                          java.lang.IllegalStateException

Configures this event dispatcher using the specified set of command line parameters.

The public method first ensures that all state variables are cleared before calling this method. It is expected that implementations will remove from the list those parameters which it has successfully processed. This creates an extensible model that permits new parameters to be defined by attached classes implementing ActiveComponent. Such a component can process all the parameters that it recognizes and then pass the remainder of the list back to be provided to other components for processing or returned to the caller.

Parameters:

params - List of strings containing the command line parameters.

Returns:

A list of parameters that were unrecognized. Other components may attempt to process these parameters, or they can be returned back to the caller for handling (usually to report as an error).

Throws:

java.lang.IllegalArgumentException - If required parameters are missing or data required for optional parameters is missing.

java.lang.IllegalStateException - If called while the event dispatcher is running.

getClassName

public java.lang.String getClassName()

Gets the name of the subject class.

Returns:

The name of the subject class being executed by the event dispatcher.

setClassName

public void setClassName(java.lang.String value)
                  throws java.lang.IllegalStateException

Sets the name of the subject class.

Parameters:

value - The name of the subject class to be executed by the event dispatcher.

Throws:

java.lang.IllegalStateException

getClassArguments

public java.lang.String[] getClassArguments()

Gets the arguments to the subject class.

Returns:

The arguments that will be passed to the subject when it is run by the event dispatcher.

setClassArguments

public void setClassArguments(java.lang.String[] arguments)
                       throws java.lang.IllegalStateException

Sets the arguments to the subject class.

Parameters:

arguments - The arguments that should be passed to the subject when it is run by the event dispatcher.

Throws:

java.lang.IllegalStateException

getSubjectClasspath

public java.lang.String getSubjectClasspath()

Gets the subject classpath.

Returns:

The classpath that will be set for the subject when it is run by the event dispatcher.

setSubjectClasspath

public void setSubjectClasspath(java.lang.String cp)
                         throws java.lang.IllegalStateException

Sets the subject classpath.

Parameters:

cp - The classpath that should be set for the subject when it is run by the event dispatcher.

Throws:

java.lang.IllegalStateException

getSubjectOutputFile

public java.lang.String getSubjectOutputFile()

Gets the name of the file to which subject output is redirected, if any.

Note: Even if the subject's output is not being directed to a file, it may still be redirected to an output stream. However, file redirection takes precedence over any specified stream.

Returns:

The name of the file, including path, to which subject output will be redirected, null if output is not being redirected to file.

setSubjectOutputFile

public void setSubjectOutputFile(java.lang.String fileName)
                          throws java.lang.IllegalStateException

Sets the file to which the subject's outputs should be redirected.

Specifying a file for redirection in this manner takes precedence over any requests to redirect output to a stream. You can pass null to this method to cause the event dispatcher to revert to the last stream specified for redirection.

Parameters:

fileName - Name of the file to which output should be redirected, including path if desired. If null, disables redirection to file and causes the event dispatcher to default to the last specified stream (stdout if none has been specified).

Throws:

java.lang.IllegalStateException

getPort

public int getPort()

Gets the socket port on which the event dispatcher will listen for instrumentation from the subject.

Returns:

The port number on which the event dispatcher will connect the socket to listen for incoming instrumentation messages from the subject.

setPort

public void setPort(int port)
             throws java.lang.IllegalStateException

Sets the socket port on which the event dispatcher will listen for instrumentation from the subject.

Parameters:

port - The port number on which the event dispatcher should listen for incoming instrumentation messages from the subject. The valid range is 1024 to 65535. An exception is the value -1, which instructs it to select the default port.

Throws:

java.lang.IllegalStateException

getTimeLimit

public int getTimeLimit()

Gets the maximum time in seconds that a subject is allowed to run before being forcibly terminated.

Returns:

The length of time in seconds that a subject can run before being killed. 0 (zero) signifies that a subject is permitted to run indefinitely.

setTimeLimit

public void setTimeLimit(int tl)
                  throws java.lang.IllegalStateException

Sets the maximum time in seconds that a subject is allowed to run before being forcibly terminated.

Parameters:

tl - The length of time in seconds that the subject can run before being killed. 0 (zero) signifies that a subject is permitted to run indefinitely.

Throws:

java.lang.IllegalStateException

getRedirectInput

public boolean getRedirectInput()

Reports whether the event dispatcher is set to redirect input on standard input to the subject's standard input stream.

Returns:

true if the event dispatcher is to redirect input on stdin to the subject, false otherwise.

setRedirectInput

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

Sets whether the event dispatcher will redirect input on standard input to the subject's standard input stream.

Parameters:

enable - true to enable redirection, false to disable.

Throws:

java.lang.IllegalStateException

setSubjectOutputStream

public void setSubjectOutputStream(java.io.OutputStream sbjoutStream)

Sets the stream to which subject outputs will be written.

Parameters:

sbjoutStream - Output stream to which subject outputs are to be written.

setStandardOutputStream

public void setStandardOutputStream(java.io.OutputStream stdoutStream)

Sets the stream to which the event dispatcher standard outputs will be written.

Parameters:

stdoutStream - Output stream to which the event dispatcher standard outputs are to be written.

setStandardErrorStream

public void setStandardErrorStream(java.io.OutputStream stderrStream)

Sets the stream to which the event dispatcher error outputs will be written.

Parameters:

stderrStream - Output stream to which the event dispatcher error outputs are to be written.

createBlockCoverageTracer

public static ProgramEventDispatcher createBlockCoverageTracer(java.lang.String[] argv,
                                                               java.io.PrintStream sbjout,
                                                               java.io.PrintStream stdout,
                                                               java.io.PrintStream stderr)
                                                        throws AbstractEventDispatcher.CreateException

Constructs a ready to run event dispatcher to collect basic block coverage traces, equivalent to the old Sofya Filter class.

Parameters:

argv - Array of command line parameters.

sbjout - Output stream to which subject's outputs are to be written. If null, System.out is used by default.

stdout - Output stream to which the event dispatcher's normal outputs are to be written. If null, System.out is used by default. When the dispatcher is compiled in DEBUG mode, debug information is also printed to this stream.

stderr - Output stream to which the event dispatcher's error outputs are to be written. If null, System.err is used by default.

Returns:

A new event dispatcher, or a reference to the existing singleton instance. An existing instance can be reconfigured, enabling dispatch of multiple event streams.

Throws:

CreateException - If the commons-collections library could not be found by the static initializer.

AbstractEventDispatcher.CreateException

createBlockSequenceTracer

public static ProgramEventDispatcher createBlockSequenceTracer(java.lang.String[] argv,
                                                               java.io.PrintStream sbjout,
                                                               java.io.PrintStream stdout,
                                                               java.io.PrintStream stderr)
                                                        throws AbstractEventDispatcher.CreateException

Constructs a ready to run event dispatcher to collect basic block sequence traces, equivalent to the old Sofya SequenceFilter class.

Parameters:

argv - Array of command line parameters.

sbjout - Output stream to which subject's outputs are to be written. If null, System.out is used by default.

stdout - Output stream to which the event dispatcher's normal outputs are to be written. If null, System.out is used by default. When the dispatcher is compiled in DEBUG mode, debug information is also printed to this stream.

stderr - Output stream to which the event dispatcher's error outputs are to be written. If null, System.err is used by default.

Returns:

A new event dispatcher, or a reference to the existing singleton instance. An existing instance can be reconfigured, enabling dispatch of multiple event streams.

Throws:

CreateException - If the commons-collections library could not be found by the static initializer.

AbstractEventDispatcher.CreateException

createBranchCoverageTracer

public static ProgramEventDispatcher createBranchCoverageTracer(java.lang.String[] argv,
                                                                java.io.PrintStream sbjout,
                                                                java.io.PrintStream stdout,
                                                                java.io.PrintStream stderr)
                                                         throws AbstractEventDispatcher.CreateException

Constructs a ready to run event dispatcher to collect branch coverage traces, equivalent to the old Sofya BranchFilter class.

Parameters:

argv - Array of command line parameters.

sbjout - Output stream to which subject's outputs are to be written. If null, System.out is used by default.

stdout - Output stream to which the event dispatcher's normal outputs are to be written. If null, System.out is used by default. When the dispatcher is compiled in DEBUG mode, debug information is also printed to this stream.

stderr - Output stream to which the event dispatcher's error outputs are to be written. If null, System.err is used by default.

Returns:

A new event dispatcher, or a reference to the existing singleton instance. An existing instance can be reconfigured, enabling dispatch of multiple event streams.

Throws:

CreateException - If the commons-collections library could not be found by the static initializer.

AbstractEventDispatcher.CreateException

createBranchSequenceTracer

public static ProgramEventDispatcher createBranchSequenceTracer(java.lang.String[] argv,
                                                                java.io.PrintStream sbjout,
                                                                java.io.PrintStream stdout,
                                                                java.io.PrintStream stderr)
                                                         throws AbstractEventDispatcher.CreateException

Constructs a ready to run event dispatcher to collect branch sequence traces, equivalent to the old Sofya BranchSequenceFilter class.

Parameters:

argv - Array of command line parameters.

sbjout - Output stream to which subject's outputs are to be written. If null, System.out is used by default.

stdout - Output stream to which the event dispatcher's normal outputs are to be written. If null, System.out is used by default. When the dispatcher is compiled in DEBUG mode, debug information is also printed to this stream.

stderr - Output stream to which the event dispatcher's error outputs are to be written. If null, System.err is used by default.

Returns:

A new event dispatcher, or a reference to the existing singleton instance. An existing instance can be reconfigured, enabling dispatch of multiple event streams.

Throws:

CreateException - If the commons-collections library could not be found by the static initializer.

AbstractEventDispatcher.CreateException