/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.uima.util;
import java.util.List;
import org.apache.uima.UIMA_IllegalStateException;
/**
* A <code>ProcessTrace</code> object keeps a record of events that have occurred and information,
* such as timing, about those events.
* <p>
* Each event is represented by a {@link 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.
*
*
*/
public interface ProcessTrace extends java.io.Serializable {
/**
* Records the start of an event. The event will be ended when there is a corresponding call to
* {@link #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.
*
* @param aComponentName
* name of the component generating the event
* @param aEventType
* type of the event. Standard types are defined as constants on the
* {@link ProcessTraceEvent} interface, but any string may be used.
* @param aDescription
* description of the event
*/
public void startEvent(String aComponentName, String aEventType, String aDescription);
/**
* 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 <code>UIMA_IllegalStateException</code> will be
* thrown.
*
* @param aComponentName
* name of the component generating the event
* @param aEventType
* type of the event. Standard types are defined as constants on the
* {@link ProcessTraceEvent} interface, but any string may be used.
* @param aResultMessage
* describes the result of the event
*
* @throws UIMA_IllegalStateException
* if there is no open event matching the <code>aComponentName</code> and
* <code>aEventType</code> arguments.
*/
public void endEvent(String aComponentName, String aEventType, String aResultMessage);
/**
* Adds an event with the specified parameters to this <code>ProcessTrace</code>.
*
* @param aResourceName
* name of the component generating the event
* @param aType
* type of the event. Standard types are defined as constants on the
* {@link ProcessTraceEvent} interface, but any string may be used.
* @param aDescription
* description of the event
* @param aDuration
* duration of the event in milliseconds
* @param aResultMsg
* result message of event
*/
public void addEvent(String aResourceName, String aType, String aDescription, int aDuration,
String aResultMsg);
/**
* Adds a completed event object to this <code>ProcessTrace</code>. This method is useful for
* copying events from one ProcessTrace into another.
*
* @param aEvent
* the event object to be added to this <code>ProcessTrace</code>
*/
public void addEvent(ProcessTraceEvent aEvent);
/**
* Adds a list of completed event objects to this <code>ProcessTrace</code>. This method is
* useful for copying events from one ProcessTrace into another.
*
* @param aEventList
* a List of event object to be added to this <code>ProcessTrace</code>
*/
public void addAll(List<ProcessTraceEvent> aEventList);
/**
* Gets a list of {@link ProcessTraceEvent}s, in the order in which they were created. This is
* generally chronological order.
*
* @return an unmodifiable List of {@link ProcessTraceEvent}s
*/
public List<ProcessTraceEvent> getEvents();
/**
* Gets all events that have the given Component name.
*
* @param aComponentName
* the component name to look for
* @param 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.
*
* @return a List of ProcessTraceEvents having the given component name
*/
public List<ProcessTraceEvent> getEventsByComponentName(String aComponentName, boolean aRecurseWithinMatch);
/**
* Gets all events that have the given type
*
* @param aType
* the type of event to look for
* @param 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.
*
* @return a List of ProcessTraceEvents having the given type
*/
public List<ProcessTraceEvent> getEventsByType(String aType, boolean aRecurseWithinMatch);
/**
* Get a specified event.
*
* @param aComponentName
* name of component producing desired event
* @param aType
* type of desired event
*
* @return the first ProcessTraceEvent matching the parameters, <code>null</code> if there is no
* such event.
*/
public ProcessTraceEvent getEvent(String aComponentName, String aType);
/**
* Resets this <code>ProcessTrace</code> by removing all events.
*/
public void clear();
/**
* Aggregates the information in another <code>ProcessTrace</code> 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.
*
* @param aProcessTrace
* the Process Trace object whose information will be combined with the information in
* this object
*/
public void aggregate(ProcessTrace aProcessTrace);
/**
* Generates a user-readable representation of all events in this <code>ProcessTrace</code>.
*
* @return the String representation of all events in this <code>ProcessTrace</code>.
*/
public String toString();
}