Package ej.trace

Class 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.

    • 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.