/*
 * Java
 *
 * Copyright 2017-2021 MicroEJ Corp. All rights reserved.
 * MicroEJ Corp. PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */
package ej.trace;

import ej.bon.Constants;

/**
 * A {@link Tracer} object is used to trace events for debug or monitoring. {@link Tracer} are named and can produce a
 * limited number of different event types.
 * <p>
 * The following example uses a {@link Tracer} object to trace the execution of a method: <blockquote>
 *
 * <pre>
 * 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;
 * }
 * </pre>
 *
 * </blockquote>
 */
public class Tracer {

    /**
     * The value of this boolean constant property is {@code true} when the traces are enabled in the system and
     * {@code false} otherwise (see {@link Constants}).
     * <p>
     * It can be used to prevent unnecessary code to be embedded and executed when the traces are disabled: <blockquote>
     *
     * <pre>
     * if (Constants.getBoolean(Tracer.TRACE_ENABLED_CONSTANT_PROPERTY)) {
     * 	int myEventValue = getMyEventValue();
     * 	mytracer.recordEvent(myEvent, myEventValue);
     * }
     * </pre>
     *
     * </blockquote>
     */
    public static final String TRACE_ENABLED_CONSTANT_PROPERTY = "core.trace.enabled";

    /**
     * Starts to record the events.
     * <p>
     * By default, the trace system is stopped.
     */
    public static void startTrace() {
        throw new RuntimeException();
    }

    /**
     * Stops to record the events. When the record system is stopped, any call to the {@link #recordEvent(int)} methods
     * will not record any events.
     * <p>
     * By default, the trace system is stopped.
     */
    public static void stopTrace() {
        throw new RuntimeException();
    }

    /**
     * Tests whether the trace system is started or not.
     *
     * @return <code>true</code> if the trace system is started, <code>false</code> otherwise.
     */
    public static boolean isTraceStarted() {
        throw new RuntimeException();
    }

    /**
     * Creates a new tracer with the given name. The created {@link Tracer} defines <code>nbEventTypes</code> types of
     * events. The event IDs available for this group are from 0 to <code>nbEventTypes</code>-1.
     *
     * @param name
     *            name that identifies the group. Must not be <code>null</code>.
     *
     * @param nbEventTypes
     *            maximum number of event types available for the group.
     *
     * @throws InternalError
     *             if the tracer cannot be created.
     */
    public Tracer(String name, int nbEventTypes) throws InternalError {
        throw new RuntimeException();
    }

    /**
     * Gets the group identifier. This identifier is unique for each {@link Tracer} instance.
     *
     * @return the group unique identifier.
     */
    public int getGroupID() {
        throw new RuntimeException();
    }

    /**
     * Record an event for this {@link Tracer}. The given event ID must be valid for this {@link Tracer} (i.e. between 0
     * and <code>nbEventTypes</code>-1 included where <code>nbEventTypes</code> is the value given to the
     * {@link #Tracer(String, int)} constructor).
     * <p>
     * The record is done only if the trace system is started (see <code>{@link #startTrace()}</code>).
     *
     * @param eventId
     *            ID of the event.
     */
    public void recordEvent(int eventId) {
        throw new RuntimeException();
    }

    /**
     * Record an event for this {@link Tracer}. The given event ID must be valid for this {@link Tracer} (i.e. between 0
     * and <code>nbEventTypes</code>-1 included where <code>nbEventTypes</code> is the value given to the
     * {@link #Tracer(String, int)} constructor).
     * <p>
     * The record is done only if the trace system is started (see <code>{@link #startTrace()}</code>).
     *
     * @param eventId
     *            ID of the event.
     *
     * @param value1
     *            custom value for the event.
     */
    public void recordEvent(int eventId, int value1) {
        throw new RuntimeException();
    }

    /**
     * Record an event for this {@link Tracer}. The given event ID must be valid for this {@link Tracer} (i.e. between 0
     * and <code>nbEventTypes</code>-1 included where <code>nbEventTypes</code> is the value given to the
     * {@link #Tracer(String, int)} constructor).
     * <p>
     * The record is done only if the trace system is started (see <code>{@link #startTrace()}</code>).
     *
     * @param eventId
     *            ID of the event.
     *
     * @param value1
     *            custom value for the event.
     *
     * @param value2
     *            custom value for the event.
     */
    public void recordEvent(int eventId, int value1, int value2) {
        throw new RuntimeException();
    }

    /**
     * Record an event for this {@link Tracer}. The given event ID must be valid for this {@link Tracer} (i.e. between 0
     * and <code>nbEventTypes</code>-1 included where <code>nbEventTypes</code> is the value given to the
     * {@link #Tracer(String, int)} constructor).
     * <p>
     * The record is done only if the trace system is started (see <code>{@link #startTrace()}</code>).
     *
     * @param eventId
     *            ID of the event.
     *
     * @param value1
     *            custom value for the event.
     *
     * @param value2
     *            custom value for the event.
     *
     * @param value3
     *            custom value for the event.
     */
    public void recordEvent(int eventId, int value1, int value2, int value3) {
        throw new RuntimeException();
    }

    /**
     * Record an event for this {@link Tracer}. The given event ID must be valid for this {@link Tracer} (i.e. between 0
     * and <code>nbEventTypes</code>-1 included where <code>nbEventTypes</code> is the value given to the
     * {@link #Tracer(String, int)} constructor).
     * <p>
     * The record is done only if the trace system is started (see <code>{@link #startTrace()}</code>).
     *
     * @param eventId
     *            ID of the event.
     *
     * @param value1
     *            custom value for the event.
     *
     * @param value2
     *            custom value for the event.
     *
     * @param value3
     *            custom value for the event.
     *
     * @param value4
     *            custom value for the event.
     */
    public void recordEvent(int eventId, int value1, int value2, int value3, int value4) {
        throw new RuntimeException();
    }

    /**
     * Record an event for this {@link Tracer}. The given event ID must be valid for this {@link Tracer} (i.e. between 0
     * and <code>nbEventTypes</code>-1 included where <code>nbEventTypes</code> is the value given to the
     * {@link #Tracer(String, int)} constructor).
     * <p>
     * The record is done only if the trace system is started (see <code>{@link #startTrace()}</code>).
     *
     * @param eventId
     *            ID of the event.
     *
     * @param value1
     *            custom value for the event.
     *
     * @param value2
     *            custom value for the event.
     *
     * @param value3
     *            custom value for the event.
     *
     * @param value4
     *            custom value for the event.
     *
     * @param value5
     *            custom value for the event.
     */
    public void recordEvent(int eventId, int value1, int value2, int value3, int value4, int value5) {
        throw new RuntimeException();
    }

    /**
     * Record an event for this {@link Tracer}. The given event ID must be valid for this {@link Tracer} (i.e. between 0
     * and <code>nbEventTypes</code>-1 included where <code>nbEventTypes</code> is the value given to the
     * {@link #Tracer(String, int)} constructor).
     * <p>
     * The record is done only if the trace system is started (see <code>{@link #startTrace()}</code>).
     *
     * @param eventId
     *            ID of the event.
     *
     * @param value1
     *            custom value for the event.
     *
     * @param value2
     *            custom value for the event.
     *
     * @param value3
     *            custom value for the event.
     *
     * @param value4
     *            custom value for the event.
     *
     * @param value5
     *            custom value for the event.
     *
     * @param value6
     *            custom value for the event.
     */
    public void recordEvent(int eventId, int value1, int value2, int value3, int value4, int value5, int value6) {
        throw new RuntimeException();
    }

    /**
     * Record an event for this {@link Tracer}. The given event ID must be valid for this {@link Tracer} (i.e. between 0
     * and <code>nbEventTypes</code>-1 included where <code>nbEventTypes</code> is the value given to the
     * {@link #Tracer(String, int)} constructor).
     * <p>
     * The record is done only if the trace system is started (see <code>{@link #startTrace()}</code>).
     *
     * @param eventId
     *            ID of the event.
     *
     * @param value1
     *            custom value for the event.
     *
     * @param value2
     *            custom value for the event.
     *
     * @param value3
     *            custom value for the event.
     *
     * @param value4
     *            custom value for the event.
     *
     * @param value5
     *            custom value for the event.
     *
     * @param value6
     *            custom value for the event.
     *
     * @param value7
     *            custom value for the event.
     */
    public void recordEvent(int eventId, int value1, int value2, int value3, int value4, int value5, int value6, int value7) {
        throw new RuntimeException();
    }

    /**
     * Record an event for this {@link Tracer}. The given event ID must be valid for this {@link Tracer} (i.e. between 0
     * and <code>nbEventTypes</code>-1 included where <code>nbEventTypes</code> is the value given to the
     * {@link #Tracer(String, int)} constructor).
     * <p>
     * The record is done only if the trace system is started (see <code>{@link #startTrace()}</code>).
     *
     * @param eventId
     *            ID of the event.
     *
     * @param value1
     *            custom value for the event.
     *
     * @param value2
     *            custom value for the event.
     *
     * @param value3
     *            custom value for the event.
     *
     * @param value4
     *            custom value for the event.
     *
     * @param value5
     *            custom value for the event.
     *
     * @param value6
     *            custom value for the event.
     *
     * @param value7
     *            custom value for the event.
     *
     * @param value8
     *            custom value for the event.
     */
    public void recordEvent(int eventId, int value1, int value2, int value3, int value4, int value5, int value6, int value7, int value8) {
        throw new RuntimeException();
    }

    /**
     * Record an event for this {@link Tracer}. The given event ID must be valid for this {@link Tracer} (i.e. between 0
     * and <code>nbEventTypes</code>-1 included where <code>nbEventTypes</code> is the value given to the
     * {@link #Tracer(String, int)} constructor).
     * <p>
     * The record is done only if the trace system is started (see <code>{@link #startTrace()}</code>).
     *
     * @param eventId
     *            ID of the event.
     *
     * @param value1
     *            custom value for the event.
     *
     * @param value2
     *            custom value for the event.
     *
     * @param value3
     *            custom value for the event.
     *
     * @param value4
     *            custom value for the event.
     *
     * @param value5
     *            custom value for the event.
     *
     * @param value6
     *            custom value for the event.
     *
     * @param value7
     *            custom value for the event.
     *
     * @param value8
     *            custom value for the event.
     *
     * @param value9
     *            custom value for the event.
     */
    public void recordEvent(int eventId, int value1, int value2, int value3, int value4, int value5, int value6, int value7, int value8, int value9) {
        throw new RuntimeException();
    }

    /**
     * Record an event for this {@link Tracer}. The given event ID must be valid for this {@link Tracer} (i.e. between 0
     * and <code>nbEventTypes</code>-1 included where <code>nbEventTypes</code> is the value given to the
     * {@link #Tracer(String, int)} constructor).
     * <p>
     * The record is done only if the trace system is started (see <code>{@link #startTrace()}</code>).
     *
     * @param eventId
     *            ID of the event.
     *
     * @param value1
     *            custom value for the event.
     *
     * @param value2
     *            custom value for the event.
     *
     * @param value3
     *            custom value for the event.
     *
     * @param value4
     *            custom value for the event.
     *
     * @param value5
     *            custom value for the event.
     *
     * @param value6
     *            custom value for the event.
     *
     * @param value7
     *            custom value for the event.
     *
     * @param value8
     *            custom value for the event.
     *
     * @param value9
     *            custom value for the event.
     *
     * @param value10
     *            custom value for the event.
     */
    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) {
        throw new RuntimeException();
    }

    /**
     * Record the end of the execution of an event for this {@link Tracer}. Call this method to trace the duration of an
     * event previously record with one of the {@link #recordEvent(int)} methods. This method should not be called for
     * event that has no duration.
     * <p>
     * For example, if you want to trace the execution of a method, you can call {@link #recordEvent(int)} at the
     * beginning of the function and {@link #recordEventEnd(int)} at the end of the function.
     * <p>
     * The record is done only if the trace system is started (see {@link #startTrace()}).
     *
     * @param eventId
     *            ID of the event.
     */
    public void recordEventEnd(int eventId) {
        throw new RuntimeException();
    }

    /**
     * Record the end of the execution of an event for this {@link Tracer}. Call this method to trace the duration of an
     * event previously record with one of the {@link #recordEvent(int)} methods. This method should not be called for
     * event that has no duration.
     * <p>
     * For example, if you want to trace the execution of a method, you can call {@link #recordEvent(int)} at the
     * beginning of the function and {@link #recordEventEnd(int, int)} at the end of the function.
     * <p>
     * The record is done only if the trace system is started (see {@link #startTrace()}).
     *
     * @param eventId
     *            ID of the event.
     *
     * @param value1
     *            custom value for the event end.
     */
    public void recordEventEnd(int eventId, int value1) {
        throw new RuntimeException();
    }
}