Package ej.trace

## Class Tracer

- java.lang.Object
- - ej.trace.Tracer

-     public class Tracer
      extends Object

  A `Tracer` object is used to trace events for debug or monitoring. `Tracer` are named and can produce a limited number of different event types.

  The following example uses a `Tracer` object to trace the execution of a method:

  >      static final int EVT_FOO = 0;

  >      Trace myTracer = new Tracer("MyTracer", 1);

  >      int foo(int x, int y) {
  >             myTracer.recordEvent(EVT_FOO, x, y);
  >             ...
  >             myTracer.recordEventEnd(EVT_FOO, z);
  >             return z;
  >      }

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String` | `TRACE_ENABLED_CONSTANT_PROPERTY` | The value of this boolean constant property is `true` when the traces are enabled in the system and `false` otherwise (see `Constants`).

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Tracer​(String name, int nbEventTypes)` | Creates a new tracer with the given name.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `int` | `getGroupID()` | Gets the group identifier.
    `static boolean` | `isTraceStarted()` | Tests whether the trace system is started or not.
    `void` | `recordEvent​(int eventId)` | Record an event for this `Tracer`.
    `void` | `recordEvent​(int eventId, int value1)` | Record an event for this `Tracer`.
    `void` | `recordEvent​(int eventId, int value1, int value2)` | Record an event for this `Tracer`.
    `void` | `recordEvent​(int eventId, int value1, int value2, int value3)` | Record an event for this `Tracer`.
    `void` | `recordEvent​(int eventId, int value1, int value2, int value3, int value4)` | Record an event for this `Tracer`.
    `void` | `recordEvent​(int eventId, int value1, int value2, int value3, int value4, int value5)` | Record an event for this `Tracer`.
    `void` | `recordEvent​(int eventId, int value1, int value2, int value3, int value4, int value5, int value6)` | Record an event for this `Tracer`.
    `void` | `recordEvent​(int eventId, int value1, int value2, int value3, int value4, int value5, int value6, int value7)` | Record an event for this `Tracer`.
    `void` | `recordEvent​(int eventId, int value1, int value2, int value3, int value4, int value5, int value6, int value7, int value8)` | Record an event for this `Tracer`.
    `void` | `recordEvent​(int eventId, int value1, int value2, int value3, int value4, int value5, int value6, int value7, int value8, int value9)` | Record an event for this `Tracer`.
    `void` | `recordEvent​(int eventId, int value1, int value2, int value3, int value4, int value5, int value6, int value7, int value8, int value9, int value10)` | Record an event for this `Tracer`.
    `void` | `recordEventEnd​(int eventId)` | Record the end of the execution of an event for this `Tracer`.
    `void` | `recordEventEnd​(int eventId, int value1)` | Record the end of the execution of an event for this `Tracer`.
    `static void` | `startTrace()` | Starts to record the events.
    `static void` | `stopTrace()` | Stops to record the events.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### TRACE_ENABLED_CONSTANT_PROPERTY

          public static final String TRACE_ENABLED_CONSTANT_PROPERTY

      The value of this boolean constant property is `true` when the traces are enabled in the system and `false` otherwise (see `Constants`).

      It can be used to prevent unnecessary code to be embedded and executed when the traces are disabled:

      >      if (Constants.getBoolean(Tracer.TRACE_ENABLED_CONSTANT_PROPERTY)) {
      >             int myEventValue = getMyEventValue();
      >             mytracer.recordEvent(myEvent, myEventValue);
      >      }

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Tracer

          public Tracer​(String name,
                        int nbEventTypes)
                 throws InternalError

      Creates a new tracer with the given name. The created `Tracer` defines `nbEventTypes` types of events. The event IDs available for this group are from 0 to `nbEventTypes`-1.
      Parameters:
        `name` - name that identifies the group. Must not be `null`.
        `nbEventTypes` - maximum number of event types available for the group.
      Throws:
        `InternalError` - if the tracer cannot be created.

  - ### Method Detail

    - #### startTrace

          public static void startTrace()

      Starts to record the events.

      By default, the trace system is stopped.

    - #### stopTrace

          public static void stopTrace()

      Stops to record the events. When the record system is stopped, any call to the `recordEvent(int)` methods will not record any events.

      By default, the trace system is stopped.

    - #### isTraceStarted

          public static boolean isTraceStarted()

      Tests whether the trace system is started or not.
      Returns:
        `true` if the trace system is started, `false` otherwise.

    - #### getGroupID

          public int getGroupID()

      Gets the group identifier. This identifier is unique for each `Tracer` instance.
      Returns:
        the group unique identifier.

    - #### recordEvent

          public void recordEvent​(int eventId)

      Record an event for this `Tracer`. The given event ID must be valid for this `Tracer` (i.e. between 0 and `nbEventTypes`-1 included where `nbEventTypes` is the value given to the `Tracer(String, int)` constructor).

      The record is done only if the trace system is started (see ``startTrace()``).

      Parameters:
        `eventId` - ID of the event.

    - #### recordEvent

          public void recordEvent​(int eventId,
                                  int value1)

      Record an event for this `Tracer`. The given event ID must be valid for this `Tracer` (i.e. between 0 and `nbEventTypes`-1 included where `nbEventTypes` is the value given to the `Tracer(String, int)` constructor).

      The record is done only if the trace system is started (see ``startTrace()``).

      Parameters:
        `eventId` - ID of the event.
        `value1` - custom value for the event.

    - #### recordEvent

          public void recordEvent​(int eventId,
                                  int value1,
                                  int value2)

      Record an event for this `Tracer`. The given event ID must be valid for this `Tracer` (i.e. between 0 and `nbEventTypes`-1 included where `nbEventTypes` is the value given to the `Tracer(String, int)` constructor).

      The record is done only if the trace system is started (see ``startTrace()``).

      Parameters:
        `eventId` - ID of the event.
        `value1` - custom value for the event.
        `value2` - custom value for the event.

    - #### recordEvent

          public void recordEvent​(int eventId,
                                  int value1,
                                  int value2,
                                  int value3)

      Record an event for this `Tracer`. The given event ID must be valid for this `Tracer` (i.e. between 0 and `nbEventTypes`-1 included where `nbEventTypes` is the value given to the `Tracer(String, int)` constructor).

      The record is done only if the trace system is started (see ``startTrace()``).

      Parameters:
        `eventId` - ID of the event.
        `value1` - custom value for the event.
        `value2` - custom value for the event.
        `value3` - custom value for the event.

    - #### recordEvent

          public void recordEvent​(int eventId,
                                  int value1,
                                  int value2,
                                  int value3,
                                  int value4)

      Record an event for this `Tracer`. The given event ID must be valid for this `Tracer` (i.e. between 0 and `nbEventTypes`-1 included where `nbEventTypes` is the value given to the `Tracer(String, int)` constructor).

      The record is done only if the trace system is started (see ``startTrace()``).

      Parameters:
        `eventId` - ID of the event.
        `value1` - custom value for the event.
        `value2` - custom value for the event.
        `value3` - custom value for the event.
        `value4` - custom value for the event.

    - #### recordEvent

          public void recordEvent​(int eventId,
                                  int value1,
                                  int value2,
                                  int value3,
                                  int value4,
                                  int value5)

      Record an event for this `Tracer`. The given event ID must be valid for this `Tracer` (i.e. between 0 and `nbEventTypes`-1 included where `nbEventTypes` is the value given to the `Tracer(String, int)` constructor).

      The record is done only if the trace system is started (see ``startTrace()``).

      Parameters:
        `eventId` - ID of the event.
        `value1` - custom value for the event.
        `value2` - custom value for the event.
        `value3` - custom value for the event.
        `value4` - custom value for the event.
        `value5` - custom value for the event.

    - #### recordEvent

          public void recordEvent​(int eventId,
                                  int value1,
                                  int value2,
                                  int value3,
                                  int value4,
                                  int value5,
                                  int value6)

      Record an event for this `Tracer`. The given event ID must be valid for this `Tracer` (i.e. between 0 and `nbEventTypes`-1 included where `nbEventTypes` is the value given to the `Tracer(String, int)` constructor).

      The record is done only if the trace system is started (see ``startTrace()``).

      Parameters:
        `eventId` - ID of the event.
        `value1` - custom value for the event.
        `value2` - custom value for the event.
        `value3` - custom value for the event.
        `value4` - custom value for the event.
        `value5` - custom value for the event.
        `value6` - custom value for the event.

    - #### recordEvent

          public void recordEvent​(int eventId,
                                  int value1,
                                  int value2,
                                  int value3,
                                  int value4,
                                  int value5,
                                  int value6,
                                  int value7)

      Record an event for this `Tracer`. The given event ID must be valid for this `Tracer` (i.e. between 0 and `nbEventTypes`-1 included where `nbEventTypes` is the value given to the `Tracer(String, int)` constructor).

      The record is done only if the trace system is started (see ``startTrace()``).

      Parameters:
        `eventId` - ID of the event.
        `value1` - custom value for the event.
        `value2` - custom value for the event.
        `value3` - custom value for the event.
        `value4` - custom value for the event.
        `value5` - custom value for the event.
        `value6` - custom value for the event.
        `value7` - custom value for the event.

    - #### recordEvent

          public void recordEvent​(int eventId,
                                  int value1,
                                  int value2,
                                  int value3,
                                  int value4,
                                  int value5,
                                  int value6,
                                  int value7,
                                  int value8)

      Record an event for this `Tracer`. The given event ID must be valid for this `Tracer` (i.e. between 0 and `nbEventTypes`-1 included where `nbEventTypes` is the value given to the `Tracer(String, int)` constructor).

      The record is done only if the trace system is started (see ``startTrace()``).

      Parameters:
        `eventId` - ID of the event.
        `value1` - custom value for the event.
        `value2` - custom value for the event.
        `value3` - custom value for the event.
        `value4` - custom value for the event.
        `value5` - custom value for the event.
        `value6` - custom value for the event.
        `value7` - custom value for the event.
        `value8` - custom value for the event.

    - #### recordEvent

          public void recordEvent​(int eventId,
                                  int value1,
                                  int value2,
                                  int value3,
                                  int value4,
                                  int value5,
                                  int value6,
                                  int value7,
                                  int value8,
                                  int value9)

      Record an event for this `Tracer`. The given event ID must be valid for this `Tracer` (i.e. between 0 and `nbEventTypes`-1 included where `nbEventTypes` is the value given to the `Tracer(String, int)` constructor).

      The record is done only if the trace system is started (see ``startTrace()``).

      Parameters:
        `eventId` - ID of the event.
        `value1` - custom value for the event.
        `value2` - custom value for the event.
        `value3` - custom value for the event.
        `value4` - custom value for the event.
        `value5` - custom value for the event.
        `value6` - custom value for the event.
        `value7` - custom value for the event.
        `value8` - custom value for the event.
        `value9` - custom value for the event.

    - #### recordEvent

          public void recordEvent​(int eventId,
                                  int value1,
                                  int value2,
                                  int value3,
                                  int value4,
                                  int value5,
                                  int value6,
                                  int value7,
                                  int value8,
                                  int value9,
                                  int value10)

      Record an event for this `Tracer`. The given event ID must be valid for this `Tracer` (i.e. between 0 and `nbEventTypes`-1 included where `nbEventTypes` is the value given to the `Tracer(String, int)` constructor).

      The record is done only if the trace system is started (see ``startTrace()``).

      Parameters:
        `eventId` - ID of the event.
        `value1` - custom value for the event.
        `value2` - custom value for the event.
        `value3` - custom value for the event.
        `value4` - custom value for the event.
        `value5` - custom value for the event.
        `value6` - custom value for the event.
        `value7` - custom value for the event.
        `value8` - custom value for the event.
        `value9` - custom value for the event.
        `value10` - custom value for the event.

    - #### recordEventEnd

          public void recordEventEnd​(int eventId)

      Record the end of the execution of an event for this `Tracer`. Call this method to trace the duration of an event previously record with one of the `recordEvent(int)` methods. This method should not be called for event that has no duration.

      For example, if you want to trace the execution of a method, you can call `recordEvent(int)` at the beginning of the function and `recordEventEnd(int)` at the end of the function.

      The record is done only if the trace system is started (see `startTrace()`).

      Parameters:
        `eventId` - ID of the event.

    - #### recordEventEnd

          public void recordEventEnd​(int eventId,
                                     int value1)

      Record the end of the execution of an event for this `Tracer`. Call this method to trace the duration of an event previously record with one of the `recordEvent(int)` methods. This method should not be called for event that has no duration.

      For example, if you want to trace the execution of a method, you can call `recordEvent(int)` at the beginning of the function and `recordEventEnd(int, int)` at the end of the function.

      The record is done only if the trace system is started (see `startTrace()`).

      Parameters:
        `eventId` - ID of the event.
        `value1` - custom value for the event end.