liblttng-ust-java-agent/java/lttng-ust-agent-common/org/lttng/ust/agent/ILttngAgent.java

   1 /*
   2  * SPDX-License-Identifier: LGPL-2.1-only
   3  *
   4  * Copyright (C) 2015 EfficiOS Inc.
   5  * Copyright (C) 2015 Alexandre Montplaisir <alexmonthy@efficios.com>
   6  */
   7
   8 package org.lttng.ust.agent;
   9
  10 import java.util.Collection;
  11 import java.util.Map;
  12
  13 /**
  14  * Interface to define LTTng Java agents.
  15  *
  16  * An "agent" is a representative of an LTTng session daemon in the Java world.
  17  * It tracks the settings of a tracing session as they defined in the session
  18  * daemon.
  19  *
  20  * It also track the current logging handlers that are sending events to UST.
  21  *
  22  * @author Alexandre Montplaisir
  23  *
  24  * @param <T>
  25  *            The type of logging handler that should register to this agent
  26  */
  27 public interface ILttngAgent<T extends ILttngHandler> {
  28
  29         // ------------------------------------------------------------------------
  30         // Agent configuration elements
  31         // ------------------------------------------------------------------------
  32
  33         /**
  34          * Tracing domains. Corresponds to domains defined by LTTng Tools.
  35          */
  36         enum Domain {
  37                 JUL(3), LOG4J(4);
  38                 private int value;
  39
  40                 private Domain(int value) {
  41                         this.value = value;
  42                 }
  43
  44                 public int value() {
  45                         return value;
  46                 }
  47         }
  48
  49         /**
  50          * The tracing domain of this agent.
  51          *
  52          * @return The tracing domain.
  53          */
  54         Domain getDomain();
  55
  56         // ------------------------------------------------------------------------
  57         // Log handler registering
  58         // ------------------------------------------------------------------------
  59
  60         /**
  61          * Register a handler to this agent.
  62          *
  63          * @param handler
  64          *            The handler to register
  65          */
  66         void registerHandler(T handler);
  67
  68         /**
  69          * Deregister a handler from this agent.
  70          *
  71          * @param handler
  72          *            The handler to deregister.
  73          */
  74         void unregisterHandler(T handler);
  75
  76         // ------------------------------------------------------------------------
  77         // Tracing session parameters
  78         // ------------------------------------------------------------------------
  79
  80         /**
  81          * Query if a given event is currently enabled in a current tracing session,
  82          * meaning it should be sent to UST.
  83          *
  84          * @param eventName
  85          *            The name of the event to check.
  86          * @return True if the event is currently enabled, false if it is not.
  87          */
  88         boolean isEventEnabled(String eventName);
  89
  90         /**
  91          * Return the list of application contexts enabled in the tracing sessions.
  92          *
  93          * @return The application contexts, first indexed by retriever name, then
  94          *         by context name
  95          */
  96         Collection<Map.Entry<String, Map<String, Integer>>> getEnabledAppContexts();
  97 }