org.apache.uima.util

## Interface ProcessTrace

- All Superinterfaces:
    Serializable
  All Known Implementing Classes:
    ProcessTrace_impl

      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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 `ProcessTraceEvent`s, 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 `ProcessTraceEvent`s, in the order in which they were created. This is generally chronological order.
      Returns:
        an unmodifiable List of `ProcessTraceEvent`s

    - #### 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`.

Copyright © 2006–2022 The Apache Software Foundation. All rights reserved.