sofya.ed.semantic
Class SemanticEventDispatcher

java.lang.Object
  extended by sofya.ed.semantic.SemanticEventDispatcher

public class SemanticEventDispatcher
extends java.lang.Object

Class which generates the stream of observable events occurring in a traced program. Events are dispatched to registered listeners, which can be used to set up a filtering chain and eventually reach an event target class which processes or stores the events in some way.

Version:
12/16/2005
Author:
Alex Kinneer

Nested Class Summary
 class SemanticEventDispatcher.InternalException
          Exception which indicates that an unexpected or internal configuration error occurred during startup or monitoring of the system.
 
Constructor Summary
SemanticEventDispatcher()
          Creates an uninitialized new event dispatcher.
SemanticEventDispatcher(SemanticEventData edData, java.lang.String mainClassName, java.lang.String[] args)
          Creates a ready to run event dispatcher.
 
Method Summary
 void addArgument(java.lang.String arg)
          Adds an argument to list of arguments to be passed to the system when launched.
 void addEventListener(EventListener listener)
          Registers a listener for observable events with the event dispatcher.
protected  void arrayElementAccessed(com.sun.jdi.ThreadReference t, com.sun.jdi.ArrayReference array, com.sun.jdi.Location loc)
          Internal handler for array element access events.
protected  void arrayElementWritten(com.sun.jdi.ThreadReference t, com.sun.jdi.ArrayReference array, com.sun.jdi.Location loc)
          Internal handler for array element write events.
protected  java.lang.String buildTargetInvocation()
          Sets the name of the main class to be used by the JDI launcher.
protected  void callReturned(com.sun.jdi.ThreadReference t, java.lang.String signature, com.sun.jdi.Location loc, int flagBits)
          Internal handler for method call return events.
protected  void classPrepared(com.sun.jdi.ThreadReference t, com.sun.jdi.ClassObjectReference cor)
          Internal handler for class prepare events.
 void clearArguments()
          Removes all arguments from the argument list.
protected  void constructorEntered(com.sun.jdi.ThreadReference t, com.sun.jdi.ObjectReference obj, java.lang.String signature)
          Internal handler for constructor entry events.
protected  void constructorExited(com.sun.jdi.ThreadReference t, com.sun.jdi.ObjectReference obj, java.lang.String signature)
          Internal handler for constructor exit events.
protected  void constructorInvoked(com.sun.jdi.ThreadReference t, java.lang.String signature, com.sun.jdi.Location loc)
          Internal handler for object construction events.
protected  void enteredUserCode()
          Internal handler for the start of user code execution event.
protected  void exceptionCaught(com.sun.jdi.ThreadReference t, com.sun.jdi.Type type, com.sun.jdi.Location loc)
          Internal handler for exception catch events.
protected  void exceptionThrown(com.sun.jdi.event.ExceptionEvent ee)
          Internal handler for exception throw events.
protected  void fieldAccessed(com.sun.jdi.event.AccessWatchpointEvent awe)
          Internal handler for field access events.
protected  void fieldWritten(com.sun.jdi.event.ModificationWatchpointEvent mwe)
          Internal handler for field write events.
 java.lang.String getArgument(int index)
          Gets an argument from the argument list.
 java.util.List getArguments()
          Gets the arguments to be passed to the system when launched.
 SemanticEventData getEDData()
          Gets the event dispatch data object which the event dispatcher is currently using.
 java.lang.String getMainClass()
          Gets the main class which this module tracer will use or has used to launch the system.
protected  void interceptorExecuted(com.sun.jdi.event.BreakpointEvent br)
          Internal handler that is triggered when a method call interceptor is invoked.
protected  void interfaceCall(com.sun.jdi.ThreadReference t, java.lang.String signature, com.sun.jdi.Location loc, int flagBits)
          Internal handler for interface call events.
protected  void monitorAcquire(com.sun.jdi.ThreadReference t, com.sun.jdi.ObjectReference obj, com.sun.jdi.Location loc)
          Internal handler for monitor acquisition events.
protected  void monitorContend(com.sun.jdi.ThreadReference t, com.sun.jdi.ObjectReference obj, com.sun.jdi.Location loc)
          Internal handler for monitor contention events.
protected  void monitorReleased(com.sun.jdi.ThreadReference t, com.sun.jdi.ObjectReference obj, com.sun.jdi.Location loc)
          Internal handler for monitor release events.
protected  void monitorReleasing(com.sun.jdi.ThreadReference t, com.sun.jdi.ObjectReference obj, com.sun.jdi.Location loc)
          Internal handler for monitor will be released events.
protected  void newAllocation(com.sun.jdi.ThreadReference t, java.lang.String className, com.sun.jdi.Location loc)
          Internal handler for new object allocation events.
protected  void processProbe(com.sun.jdi.event.ModificationWatchpointEvent mwe, java.lang.String name)
          Processes an event recorded by a probe.
 java.lang.String removeArgument(int index)
          Removes an argument from the argument list.
 boolean removeArgument(java.lang.String arg)
          Removes an argument from the argument list.
 void removeEventListener(EventListener listener)
          Unregisters a listener for observable events from the event dispatcher.
protected  void requestEvents()
          Issues universal event requests to the JDI which the module tracer needs to operate.
protected  void requestFieldEvents(com.sun.jdi.ReferenceType rType)
          Issues event requests to the JDI to monitor field observables in a prepared class.
protected  void requestInterceptorBreakpoints(com.sun.jdi.ReferenceType rType)
          Issues the breakpoint requests to the JDI for interceptor methods.
protected  void requestProbeEvents(com.sun.jdi.ReferenceType rType)
          Issues event requests to the JDI to monitor the probe fields.
 void setEDData(SemanticEventData edData)
          Sets the event dispatch data to be used by the event dispatcher.
 void setMainClass(java.lang.String mainClass)
          Sets the main class which will be used by the module tracer to launch the system.
 void startDispatcher()
          Launches the system, beginning the trace collection.
 void startDispatcher(long timeout)
          Launches the system, beginning the trace collection.
protected  void startIOThreads(java.lang.Process process)
          Starts the threads to redirect the system's stdin, stdout, and stderr streams.
protected  void staticCall(com.sun.jdi.ThreadReference t, java.lang.String signature, com.sun.jdi.Location loc, int flagBits)
          Internal handler for static call events.
protected  void staticInitializerEntered(com.sun.jdi.ThreadReference t, java.lang.String signature)
          Internal handler for static initializer entry events.
protected  void staticMethodEntered(com.sun.jdi.ThreadReference t, java.lang.String signature)
          Internal handler for static method entry events.
protected  void staticMethodExited(com.sun.jdi.ThreadReference t, java.lang.String signature)
          Internal handler for static method exit events.
protected  void threadDied(com.sun.jdi.event.ThreadDeathEvent tde)
          Internal handler for thread termination events.
protected  void threadStarted(com.sun.jdi.event.ThreadStartEvent tse)
          Internal handler for thread start events.
protected  void virtualCall(com.sun.jdi.ThreadReference t, java.lang.String signature, com.sun.jdi.Location loc, int flagBits)
          Internal handler for virtual call events.
protected  void virtualMethodEntered(com.sun.jdi.ThreadReference t, com.sun.jdi.ObjectReference obj, java.lang.String signature)
          Internal handler for virtual method entry events.
protected  void virtualMethodExited(com.sun.jdi.ThreadReference t, com.sun.jdi.ObjectReference obj, java.lang.String signature)
          Internal handler for virtual method exit events.
protected  void vmExited()
          Internal handler for the virtual machine death event.
protected  void vmStarted(com.sun.jdi.ThreadReference t)
          Internal handler for the virtual machine start event.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SemanticEventDispatcher

public SemanticEventDispatcher()
Creates an uninitialized new event dispatcher.

When using this constructor, at a minimum you must call setMainClass(java.lang.String) and setEDData(sofya.ed.semantic.SemanticEventData) before attempting to call startDispatcher().


SemanticEventDispatcher

public SemanticEventDispatcher(SemanticEventData edData,
                               java.lang.String mainClassName,
                               java.lang.String[] args)
Creates a ready to run event dispatcher.

Parameters:
edData - Event dispatch data, as read from an event dispatch data file produced by the instrumentor.
mainClassName - Name of the main class from which the system is launched.
args - Arguments to be passed in when the system is launched (may be zero-length, but not null).
Method Detail

getEDData

public SemanticEventData getEDData()
Gets the event dispatch data object which the event dispatcher is currently using.

Returns:
The event dispatch data currently in use by the event dispatcher.

setEDData

public void setEDData(SemanticEventData edData)
Sets the event dispatch data to be used by the event dispatcher.

Parameters:
edData - Event dispatch data object, as read from an event dispatch data file produced by the instrumentor.

getMainClass

public java.lang.String getMainClass()
Gets the main class which this module tracer will use or has used to launch the system.

Returns:
The class which the module tracer has been instructed to use as the launching class of the system.

setMainClass

public void setMainClass(java.lang.String mainClass)
Sets the main class which will be used by the module tracer to launch the system.

Parameters:
mainClass - The class which the module tracer has been instructed to used as the launching class of the system.

getArguments

public java.util.List getArguments()
Gets the arguments to be passed to the system when launched.

Returns:
An unmodifiable list of the arguments which will be or have been passed to the system when launched.

getArgument

public java.lang.String getArgument(int index)
Gets an argument from the argument list.

Parameters:
index - Index of the argument to be retrieved.
Returns:
The argument at the given index in the arguments list.

addArgument

public void addArgument(java.lang.String arg)
Adds an argument to list of arguments to be passed to the system when launched.

Parameters:
arg - Argument to be added to the argument list.

removeArgument

public java.lang.String removeArgument(int index)
Removes an argument from the argument list.

Parameters:
index - Index of the argument to be removed from the arguments list.
Returns:
The argument at the given index in the arguments list.

removeArgument

public boolean removeArgument(java.lang.String arg)
Removes an argument from the argument list.

Parameters:
arg - Argument to be removed from the argument list.
Returns:
true if a matching argument was successfully removed from the arguments list.

clearArguments

public void clearArguments()
Removes all arguments from the argument list.


addEventListener

public void addEventListener(EventListener listener)
Registers a listener for observable events with the event dispatcher.

Parameters:
listener - Object that wishes to receive notifications of events related to observables in the system.

removeEventListener

public void removeEventListener(EventListener listener)
Unregisters a listener for observable events from the event dispatcher.

Parameters:
listener - Object that no longer wishes to receive notifications of events related to observables in the system.

vmStarted

protected void vmStarted(com.sun.jdi.ThreadReference t)
Internal handler for the virtual machine start event.


enteredUserCode

protected void enteredUserCode()
Internal handler for the start of user code execution event.


threadStarted

protected void threadStarted(com.sun.jdi.event.ThreadStartEvent tse)
Internal handler for thread start events.

Parameters:
tse - JDI event raised by the thread starting.

threadDied

protected void threadDied(com.sun.jdi.event.ThreadDeathEvent tde)
Internal handler for thread termination events.

Parameters:
tde - JDI event raised by the thread terminating.

classPrepared

protected void classPrepared(com.sun.jdi.ThreadReference t,
                             com.sun.jdi.ClassObjectReference cor)
                      throws SemanticEventDispatcher.InternalException
Internal handler for class prepare events.

Parameters:
t - JDI reference to the thread which caused the class prepare event.
cor - JDI reference to the class object for the prepared class.
Throws:
SemanticEventDispatcher.InternalException

monitorContend

protected void monitorContend(com.sun.jdi.ThreadReference t,
                              com.sun.jdi.ObjectReference obj,
                              com.sun.jdi.Location loc)
Internal handler for monitor contention events.

Parameters:
t - JDI reference to the thread which is contending for the monitor.
obj - Reference to the object which owns the monitor under contention.
loc - JDI location of the monitor contention event.

monitorAcquire

protected void monitorAcquire(com.sun.jdi.ThreadReference t,
                              com.sun.jdi.ObjectReference obj,
                              com.sun.jdi.Location loc)
Internal handler for monitor acquisition events.

Parameters:
t - JDI reference to the thread which acquired the monitor.
obj - Reference to the object which owns the acquired monitor.
loc - JDI location of the monitor acquisition event.

monitorReleasing

protected void monitorReleasing(com.sun.jdi.ThreadReference t,
                                com.sun.jdi.ObjectReference obj,
                                com.sun.jdi.Location loc)
Internal handler for monitor will be released events.

Parameters:
t - JDI reference to the thread which is about to release a monitor.
obj - Reference to the object which owns the monitor about to be released.
loc - JDI location of the monitor releasing event.

monitorReleased

protected void monitorReleased(com.sun.jdi.ThreadReference t,
                               com.sun.jdi.ObjectReference obj,
                               com.sun.jdi.Location loc)
Internal handler for monitor release events.

Parameters:
t - JDI reference to the thread which is has released the monitor.
obj - Reference to the object which owns the monitor that was released.
loc - JDI location of the monitor release event.

newAllocation

protected void newAllocation(com.sun.jdi.ThreadReference t,
                             java.lang.String className,
                             com.sun.jdi.Location loc)
Internal handler for new object allocation events.

Parameters:
t - JDI reference to the thread in which the new object allocation occurred.
className - Name of the class of the newly allocated object.
loc - JDI location of the new object allocation event.

constructorInvoked

protected void constructorInvoked(com.sun.jdi.ThreadReference t,
                                  java.lang.String signature,
                                  com.sun.jdi.Location loc)
Internal handler for object construction events.

Parameters:
t - JDI reference to the thread in which the object construction occurred.
signature - Parsable signature of the constructor which was invoked.
loc - JDI location of the constructor invocation.

constructorEntered

protected void constructorEntered(com.sun.jdi.ThreadReference t,
                                  com.sun.jdi.ObjectReference obj,
                                  java.lang.String signature)
Internal handler for constructor entry events.

Parameters:
t - JDI reference to the thread which entered the constructor.
obj - JDI reference to the object for which the constructor was invoked.
signature - Parsable signature of the entered constructor.

constructorExited

protected void constructorExited(com.sun.jdi.ThreadReference t,
                                 com.sun.jdi.ObjectReference obj,
                                 java.lang.String signature)
Internal handler for constructor exit events.

Parameters:
t - JDI reference to the thread which exited the constructor.
obj - JDI reference to the object for which the constructor was invoked.
signature - Parsable signature of the exited constructor.

fieldAccessed

protected void fieldAccessed(com.sun.jdi.event.AccessWatchpointEvent awe)
Internal handler for field access events.

Parameters:
awe - JDI event raised by the field access.

arrayElementAccessed

protected void arrayElementAccessed(com.sun.jdi.ThreadReference t,
                                    com.sun.jdi.ArrayReference array,
                                    com.sun.jdi.Location loc)
Internal handler for array element access events.

The default implementation dispatches array element access events as regular field access events. Technically, these are more like pseudo-events, where the field information corresponds to the individual element of the array in question. The field name is taken to be the name of the field holding the array reference, annoted by the index of the element. The effect is that array elements are transparently treated as individual fields accessible at the same scope as the field holding the array reference, which is of course the semantics of arrays in Java. This makes the treatment of array elements transparent to analyses that are, strictly speaking, only interested in memory locations (which is true of most analyses). Note that the access to the field holding the array reference will be dispatched as a field access event prior to events corresponding to individual elements of the array.

Parameters:
t - JDI reference to the thread that read from the array.
array - Reference to the array that is being accessed.
loc - JDI location of the array element access event.

fieldWritten

protected void fieldWritten(com.sun.jdi.event.ModificationWatchpointEvent mwe)
Internal handler for field write events.

Parameters:
mwe - JDI event raised for the field write.

arrayElementWritten

protected void arrayElementWritten(com.sun.jdi.ThreadReference t,
                                   com.sun.jdi.ArrayReference array,
                                   com.sun.jdi.Location loc)
Internal handler for array element write events.

The default implementation dispatches array element write events as regular field write events. Technically, these are more like pseudo- events, where the field information corresponds to the individual element of the array affected. The field name is taken to be the name of the field holding the array reference, annoted by the index of the element. The effect is that array elements are transparently treated as individual fields accessible at the same scope as the field holding the array reference, which is of course the semantics of arrays in Java. This makes the treatment of array elements transparent to analyses that are, strictly speaking, only interested in memory locations (which is true of most analyses). Note that the access to the field holding the array reference will be dispatched as a field access event prior to events corresponding to individual elements of the array.

Parameters:
t - JDI reference to the thread that wrote to the array.
array - Reference to the array that is being written.
loc - JDI location of the array element write event.

staticCall

protected void staticCall(com.sun.jdi.ThreadReference t,
                          java.lang.String signature,
                          com.sun.jdi.Location loc,
                          int flagBits)
                   throws SemanticEventDispatcher.InternalException
Internal handler for static call events.

Parameters:
t - JDI reference to the thread in which the static call occurred.
signature - Parsable signature of the called method.
loc - JDI location of the method call.
flagBits - Flag bitmask extracted from the probe.
Throws:
SemanticEventDispatcher.InternalException

virtualCall

protected void virtualCall(com.sun.jdi.ThreadReference t,
                           java.lang.String signature,
                           com.sun.jdi.Location loc,
                           int flagBits)
                    throws SemanticEventDispatcher.InternalException
Internal handler for virtual call events.

Parameters:
t - JDI reference to the thread in which the virtual call occurred.
signature - Parsable signature of the called method.
loc - JDI location of the method call.
flagBits - Flag bitmask extracted from the probe.
Throws:
SemanticEventDispatcher.InternalException

interfaceCall

protected void interfaceCall(com.sun.jdi.ThreadReference t,
                             java.lang.String signature,
                             com.sun.jdi.Location loc,
                             int flagBits)
                      throws SemanticEventDispatcher.InternalException
Internal handler for interface call events.

Parameters:
t - JDI reference to the thread in which the interface call occurred.
signature - Parsable signature of the called method.
loc - JDI location of the method call.
flagBits - Flag bitmask extracted from the probe.
Throws:
SemanticEventDispatcher.InternalException

callReturned

protected void callReturned(com.sun.jdi.ThreadReference t,
                            java.lang.String signature,
                            com.sun.jdi.Location loc,
                            int flagBits)
Internal handler for method call return events.

Parameters:
t - JDI reference to the thread in which the call return occurred.
signature - Parsable signature of the method from which the return occurred.
loc - JDI location of the method call from which the return occurred.
flagBits - Flag bitmask extracted from the probe.

virtualMethodEntered

protected void virtualMethodEntered(com.sun.jdi.ThreadReference t,
                                    com.sun.jdi.ObjectReference obj,
                                    java.lang.String signature)
Internal handler for virtual method entry events.

Parameters:
t - JDI reference to the thread which entered the virtual method.
obj - JDI reference to the object on which the virtual method was invoked.
signature - Parsable signature of the entered method.

virtualMethodExited

protected void virtualMethodExited(com.sun.jdi.ThreadReference t,
                                   com.sun.jdi.ObjectReference obj,
                                   java.lang.String signature)
Internal handler for virtual method exit events.

Parameters:
t - JDI reference to the thread which exited the virtual method.
obj - JDI reference to the object on which the virtual method was invoked.
signature - Parsable signature of the exited method.

staticMethodEntered

protected void staticMethodEntered(com.sun.jdi.ThreadReference t,
                                   java.lang.String signature)
Internal handler for static method entry events.

Parameters:
t - JDI reference to the thread which entered the static method.
signature - Parsable signature of the entered method.

staticMethodExited

protected void staticMethodExited(com.sun.jdi.ThreadReference t,
                                  java.lang.String signature)
Internal handler for static method exit events.

Parameters:
t - JDI reference to the thread which exited the static method.
signature - Parsable signature of the exited method.

exceptionThrown

protected void exceptionThrown(com.sun.jdi.event.ExceptionEvent ee)
Internal handler for exception throw events.

Parameters:
ee - JDI event raised by the exception throw.

exceptionCaught

protected void exceptionCaught(com.sun.jdi.ThreadReference t,
                               com.sun.jdi.Type type,
                               com.sun.jdi.Location loc)
Internal handler for exception catch events.

Parameters:
t - JDI reference to the thread in which the exception catch occurred.
type - Type of the caught exception.
loc - JDI location of the caught exception.

staticInitializerEntered

protected void staticInitializerEntered(com.sun.jdi.ThreadReference t,
                                        java.lang.String signature)
Internal handler for static initializer entry events.

Parameters:
t - JDI reference to the thread in which has entered the static initializer.
signature - Parsable signature of the entered method (useful for determining which class initializer is being run).

interceptorExecuted

protected void interceptorExecuted(com.sun.jdi.event.BreakpointEvent br)
                            throws SemanticEventDispatcher.InternalException
Internal handler that is triggered when a method call interceptor is invoked.

Due to a bug in the JDI, a modification watchpoint event does not always result in the thread being properly suspended at the location of the field access. Therefore, the call probe in an interceptor may be processed after the thread has exited the interceptor, in which case the stack frame for the interceptor method is no longer available. In that situation, we cannot retrieve the values of arguments from the stack frame as desired. Thus, a breakpoint is set at the entry to all interceptor methods, which appears to always properly suspend the thread in the interceptor method stack frame.

Parameters:
br - JDI breakpoint event indicating that an interceptor has been invoked.
Throws:
SemanticEventDispatcher.InternalException

vmExited

protected void vmExited()
Internal handler for the virtual machine death event.


processProbe

protected void processProbe(com.sun.jdi.event.ModificationWatchpointEvent mwe,
                            java.lang.String name)
                     throws SemanticEventDispatcher.InternalException
Processes an event recorded by a probe.

Parameters:
mwe - JDI event raised when a probe writes to a probe field.
name - Name of the probe field to which a probe event was written.
Throws:
SemanticEventDispatcher.InternalException - If the probe code received is unrecognized.

buildTargetInvocation

protected java.lang.String buildTargetInvocation()
Sets the name of the main class to be used by the JDI launcher.


requestEvents

protected void requestEvents()
Issues universal event requests to the JDI which the module tracer needs to operate.


requestProbeEvents

protected void requestProbeEvents(com.sun.jdi.ReferenceType rType)
Issues event requests to the JDI to monitor the probe fields.

Parameters:
rType - JDI handle to the reference type of the probe class.

requestFieldEvents

protected void requestFieldEvents(com.sun.jdi.ReferenceType rType)
Issues event requests to the JDI to monitor field observables in a prepared class.

Parameters:
rType - JDI reference type of the class that was prepared. The list of fields declared by the prepared class is scanned to request events for those fields marked as observables in the module description.

requestInterceptorBreakpoints

protected void requestInterceptorBreakpoints(com.sun.jdi.ReferenceType rType)
                                      throws SemanticEventDispatcher.InternalException
Issues the breakpoint requests to the JDI for interceptor methods.

Parameters:
rType - Type of the loaded class for which interceptor breakpoints are to be set.
Throws:
SemanticEventDispatcher.InternalException

startIOThreads

protected void startIOThreads(java.lang.Process process)
Starts the threads to redirect the system's stdin, stdout, and stderr streams.

Parameters:
process - Process object associated with the launched system.

startDispatcher

public void startDispatcher()
                     throws SemanticEventDispatcher.InternalException
Launches the system, beginning the trace collection.

Throws:
SemanticEventDispatcher.InternalException - If an unexpected error occurs during the launch process or in the event dispatch queue.

startDispatcher

public void startDispatcher(long timeout)
                     throws SemanticEventDispatcher.InternalException
Launches the system, beginning the trace collection.

Parameters:
timeout - Amount of time, in milliseconds, after which to forcibly terminate the subject system. If zero or negative, no timeout is enforced.
Throws:
SemanticEventDispatcher.InternalException - If an unexpected error occurs during the launch process or in the event dispatch queue.