edu.buffalo.cse.jive.sequence
Interface SequenceModel

All Superinterfaces:

Iterable<EventOccurrence>

All Known Subinterfaces:

MultiThreadedSequenceModel

public interface SequenceModel
extends Iterable<EventOccurrence>

A representation of a program execution history. It can be thought of as a call tree, where each node of the tree is an ExecutionOccurrence in the program. Each execution occurrence contains a list of EventOccurrences in the sequence in which they arose within the containing execution occurrence.

A MessageSend is a type of event occurrence that resulted in another execution occurrence within the program. These message sends are what give rise to the model's tree structure. A depth-first traversal of the tree results in visiting the event and execution occurrences in the sequence in which they arose during the program execution.

This interface is designed to model programs having only a single thread of execution. For multi-threaded programs, the MultiThreadedSequenceModel interface should be used.

See Also:

ExecutionOccurrence, EventOccurrence, MessageSend, MultiThreadedSequenceModel

Nested Class Summary

static interface	SequenceModel.EventVisitor A visitor for the sequence model that visits EventOccurrences in the order in which they occurred within the program execution.
static interface	SequenceModel.ExecutionVisitor A visitor for the sequence model that visits ExecutionOccurrences in the order in which they occurred within the program execution.
static interface	SequenceModel.Listener A listener interface for the SequenceModel.

Method Summary

void	accept(SequenceModel.EventVisitor visitor) Processes an EventVisitor over the model in a depth-first order.
void	accept(SequenceModel.ExecutionVisitor visitor) Processes an ExecutionVisitor over the model in a depth-first order.
void	addListener(SequenceModel.Listener listener) Registers the supplied listener to be notified when the model has changed.
EventOccurrence	getEventOccurrence(long eventNumber)
ReentrantLock	getModelLock() Returns the lock object for synchronized reading and writing to the model.
ExecutionOccurrence	getRoot() Returns the root ExecutionOccurrence of the model.
ThreadID	getThread() Returns the ThreadID associated with the thread being modeled.
Iterator<EventOccurrence>	iterator() Returns an iterator which traverses the sequence model in a depth-first order.
Iterator<EventOccurrence>	iterator(ExecutionOccurrence root) Returns an iterator which traverses the sequence model in a depth-first order starting at the supplied ExecutionOccurrence.
long	lastEventNumber() Returns the event number of the last event in the model.
ContourID	objectContext(ExecutionOccurrence execution) Returns the object context of the given ExecutionOccurrence.
void	removeListener(SequenceModel.Listener listener) Unregisters the supplied listener from being notified when the model has changed.

Method Detail

accept

void accept(SequenceModel.EventVisitor visitor)

Processes an EventVisitor over the model in a depth-first order.

Parameters:

visitor - the event visitor

accept

void accept(SequenceModel.ExecutionVisitor visitor)

Processes an ExecutionVisitor over the model in a depth-first order.

Parameters:

visitor - the execution visitor

iterator

Iterator<EventOccurrence> iterator()

Returns an iterator which traverses the sequence model in a depth-first order.

Specified by:

iterator in interface Iterable<EventOccurrence>

Returns:

an iterator over the model

See Also:

Iterable.iterator()

iterator

Iterator<EventOccurrence> iterator(ExecutionOccurrence root)

Returns an iterator which traverses the sequence model in a depth-first order starting at the supplied ExecutionOccurrence. The iterator will be exhausted once all descendants of the root have been returned.

Parameters:

root - the starting point of the iterator

Returns:

an iterator over a sub-tree within the model

getModelLock

ReentrantLock getModelLock()

Returns the lock object for synchronized reading and writing to the model. Only the thread owning the lock (by calling ReentrantLock.lock()) may access the model.

The following is a typical example of using the lock to correctly access the model:

     SequenceModel model = ... ;
     ReentrantLock modelLock = model.getModelLock();
     modelLock.lock();
     try {
         ...
     }
     finally {
         modelLock.unlock();
     }
 

Returns:

the model's lock object

getThread

ThreadID getThread()

Returns the ThreadID associated with the thread being modeled.

Returns:

the thread of execution being modeled

getRoot

ExecutionOccurrence getRoot()

Returns the root ExecutionOccurrence of the model. That is, the execution occurrence that occurred first in the program execution history.

Returns:

the root execution occurrence

objectContext

ContourID objectContext(ExecutionOccurrence execution)

Returns the object context of the given ExecutionOccurrence. The object context is the ContourID of the inner-most contour of the object in which the method occurs (i.e., the non-virtual instance contour of the class that was instantiated). For static contexts, the execution's context is simply returned.

Parameters:

execution - the execution whose object context is returned

Returns:

the object context of the execution

See Also:

ExecutionOccurrence.context()

lastEventNumber

long lastEventNumber()

Returns the event number of the last event in the model.

Returns:

the event number of the last event

getEventOccurrence

EventOccurrence getEventOccurrence(long eventNumber)

addListener

void addListener(SequenceModel.Listener listener)

Registers the supplied listener to be notified when the model has changed.

Parameters:

listener - the listener to be notified

removeListener

void removeListener(SequenceModel.Listener listener)

Unregisters the supplied listener from being notified when the model has changed.

Parameters:

listener - the listener which no longer should be notified