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

   1 /*
   2  * Copyright (C) 2015 - EfficiOS Inc., Alexandre Montplaisir <alexmonthy@efficios.com>
   3  *
   4  * This library is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU Lesser General Public License, version 2.1 only,
   6  * as published by the Free Software Foundation.
   7  *
   8  * This library is distributed in the hope that it will be useful, but WITHOUT
   9  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
  11  * for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public License
  14  * along with this library; if not, write to the Free Software Foundation,
  15  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  16  */
  17
  18 package org.lttng.ust.agent;
  19
  20 import java.util.Collection;
  21 import java.util.Map;
  22
  23 /**
  24  * Interface to define LTTng Java agents.
  25  *
  26  * An "agent" is a representative of an LTTng session daemon in the Java world.
  27  * It tracks the settings of a tracing session as they defined in the session
  28  * daemon.
  29  *
  30  * It also track the current logging handlers that are sending events to UST.
  31  *
  32  * @author Alexandre Montplaisir
  33  *
  34  * @param <T>
  35  *            The type of logging handler that should register to this agent
  36  */
  37 public interface ILttngAgent<T extends ILttngHandler> {
  38
  39         // ------------------------------------------------------------------------
  40         // Agent configuration elements
  41         // ------------------------------------------------------------------------
  42
  43         /**
  44          * Tracing domains. Corresponds to domains defined by LTTng Tools.
  45          */
  46         enum Domain {
  47                 JUL(3), LOG4J(4);
  48                 private int value;
  49
  50                 private Domain(int value) {
  51                         this.value = value;
  52                 }
  53
  54                 public int value() {
  55                         return value;
  56                 }
  57         }
  58
  59         /**
  60          * The tracing domain of this agent.
  61          *
  62          * @return The tracing domain.
  63          */
  64         Domain getDomain();
  65
  66         // ------------------------------------------------------------------------
  67         // Log handler registering
  68         // ------------------------------------------------------------------------
  69
  70         /**
  71          * Register a handler to this agent.
  72          *
  73          * @param handler
  74          *            The handler to register
  75          */
  76         void registerHandler(T handler);
  77
  78         /**
  79          * Deregister a handler from this agent.
  80          *
  81          * @param handler
  82          *            The handler to deregister.
  83          */
  84         void unregisterHandler(T handler);
  85
  86         // ------------------------------------------------------------------------
  87         // Tracing session parameters
  88         // ------------------------------------------------------------------------
  89
  90         /**
  91          * Query if a given event is currently enabled in a current tracing session,
  92          * meaning it should be sent to UST.
  93          *
  94          * @param eventName
  95          *            The name of the event to check.
  96          * @return True if the event is currently enabled, false if it is not.
  97          */
  98         boolean isEventEnabled(String eventName);
  99
 100         /**
 101          * Return the list of application contexts enabled in the tracing sessions.
 102          *
 103          * @return The application contexts, first indexed by retriever name, then
 104          *         by context name
 105          */
 106         Collection<Map.Entry<String, Map<String, Integer>>> getEnabledAppContexts();
 107 }