org.apache.uima.util
Interface ProcessTrace

All Superinterfaces:

Serializable

public interface ProcessTrace
extends Serializable

A ProcessTrace object keeps a record of events that have occurred and information, such as timing, about those events.

Each event is represented by a ProcessTraceEvent object. Events may have sub-events, so a ProcessTrace is really a forest of events, which provides a useful description of where time is spent during a process involving several components.

Method Summary

void	addAll(List<ProcessTraceEvent> aEventList) Adds a list of completed event objects to this ProcessTrace.
void	addEvent(ProcessTraceEvent aEvent) Adds a completed event object to this ProcessTrace.
void	addEvent(String aResourceName, String aType, String aDescription, int aDuration, String aResultMsg) Adds an event with the specified parameters to this ProcessTrace.
void	aggregate(ProcessTrace aProcessTrace) Aggregates the information in another ProcessTrace with this one.
void	clear() Resets this ProcessTrace by removing all events.
void	endEvent(String aComponentName, String aEventType, String aResultMessage) Records the end of an event.
ProcessTraceEvent	getEvent(String aComponentName, String aType) Get a specified event.
List<ProcessTraceEvent>	getEvents() Gets a list of ProcessTraceEvents, in the order in which they were created.
List<ProcessTraceEvent>	getEventsByComponentName(String aComponentName, boolean aRecurseWithinMatch) Gets all events that have the given Component name.
List<ProcessTraceEvent>	getEventsByType(String aType, boolean aRecurseWithinMatch) Gets all events that have the given type
void	startEvent(String aComponentName, String aEventType, String aDescription) Records the start of an event.
String	toString() Generates a user-readable representation of all events in this ProcessTrace.

Method Detail

startEvent

void startEvent(String aComponentName,
                String aEventType,
                String aDescription)

Records the start of an event. The event will be ended when there is a corresponding call to endEvent(String,String,String) with the same component name and event type. The duration of the event will be automatically computed from the difference in time between the start and end.

Parameters:

aComponentName - name of the component generating the event

aEventType - type of the event. Standard types are defined as constants on the ProcessTraceEvent interface, but any string may be used.

aDescription - description of the event

endEvent

void endEvent(String aComponentName,
              String aEventType,
              String aResultMessage)

Records the end of an event. The event is identified by the component name and type. If there is no open event that matches those values, a UIMA_IllegalStateException will be thrown.

Parameters:

aComponentName - name of the component generating the event

aEventType - type of the event. Standard types are defined as constants on the ProcessTraceEvent interface, but any string may be used.

aResultMessage - describes the result of the event

Throws:

UIMA_IllegalStateException - if there is no open event matching the aComponentName and aEventType arguments.

addEvent

void addEvent(String aResourceName,
              String aType,
              String aDescription,
              int aDuration,
              String aResultMsg)

Adds an event with the specified parameters to this ProcessTrace.

Parameters:

aResourceName - name of the component generating the event

aType - type of the event. Standard types are defined as constants on the ProcessTraceEvent interface, but any string may be used.

aDescription - description of the event

aDuration - duration of the event in milliseconds

aResultMsg - result message of event

addEvent

void addEvent(ProcessTraceEvent aEvent)

Adds a completed event object to this ProcessTrace. This method is useful for copying events from one ProcessTrace into another.

Parameters:

aEvent - the event object to be added to this ProcessTrace

addAll

void addAll(List<ProcessTraceEvent> aEventList)

Adds a list of completed event objects to this ProcessTrace. This method is useful for copying events from one ProcessTrace into another.

Parameters:

aEventList - a List of event object to be added to this ProcessTrace

getEvents

List<ProcessTraceEvent> getEvents()

Gets a list of ProcessTraceEvents, in the order in which they were created. This is generally chronological order.

Returns:

an unmodifiable List of ProcessTraceEvents

getEventsByComponentName

List<ProcessTraceEvent> getEventsByComponentName(String aComponentName,
                                                 boolean aRecurseWithinMatch)

Gets all events that have the given Component name.

Parameters:

aComponentName - the component name to look for

aRecurseWithinMatch - if true, all events with the given component name will be returned. If false, this method will not recurse into the sub-events of a matching event.

Returns:

a List of ProcessTraceEvents having the given component name

getEventsByType

List<ProcessTraceEvent> getEventsByType(String aType,
                                        boolean aRecurseWithinMatch)

Gets all events that have the given type

Parameters:

aType - the type of event to look for

aRecurseWithinMatch - if true, all events with the given component name will be returned. If false, this method will not recurse into the sub-events of a matching event.

Returns:

a List of ProcessTraceEvents having the given type

getEvent

ProcessTraceEvent getEvent(String aComponentName,
                           String aType)

Get a specified event.

Parameters:

aComponentName - name of component producing desired event

aType - type of desired event

Returns:

the first ProcessTraceEvent matching the parameters, null if there is no such event.

clear

void clear()

Resets this ProcessTrace by removing all events.

aggregate

void aggregate(ProcessTrace aProcessTrace)

Aggregates the information in another ProcessTrace with this one. Events that exist in both ProcessTraces will have their durations added together. This method is useful for collecting aggregate performance statistics for collection processing.

Parameters:

aProcessTrace - the Process Trace object whose information will be combined with the information in this object

toString

String toString()

Generates a user-readable representation of all events in this ProcessTrace.

Overrides:

toString in class Object

Returns:

the String representation of all events in this ProcessTrace.