/*
 * Copyright (C) 2015 - EfficiOS Inc., Alexandre Montplaisir <alexmonthy@efficios.com>
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License, version 2.1 only,
 * as published by the Free Software Foundation.
 *
 * This library is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

package org.lttng.ust.agent;

import java.util.Collection;
import java.util.Map;

/**
 * Interface to define LTTng Java agents.
 *
 * An "agent" is a representative of an LTTng session daemon in the Java world.
 * It tracks the settings of a tracing session as they defined in the session
 * daemon.
 *
 * It also track the current logging handlers that are sending events to UST.
 *
 * @author Alexandre Montplaisir
 *
 * @param <T>
 *            The type of logging handler that should register to this agent
 */
public interface ILttngAgent<T extends ILttngHandler> {

	// ------------------------------------------------------------------------
	// Agent configuration elements
	// ------------------------------------------------------------------------

	/**
	 * Tracing domains. Corresponds to domains defined by LTTng Tools.
	 */
	enum Domain {
		JUL(3), LOG4J(4);
		private int value;

		private Domain(int value) {
			this.value = value;
		}

		public int value() {
			return value;
		}
	}

	/**
	 * The tracing domain of this agent.
	 *
	 * @return The tracing domain.
	 */
	Domain getDomain();

	// ------------------------------------------------------------------------
	// Log handler registering
	// ------------------------------------------------------------------------

	/**
	 * Register a handler to this agent.
	 *
	 * @param handler
	 *            The handler to register
	 */
	void registerHandler(T handler);

	/**
	 * Deregister a handler from this agent.
	 *
	 * @param handler
	 *            The handler to deregister.
	 */
	void unregisterHandler(T handler);

	// ------------------------------------------------------------------------
	// Tracing session parameters
	// ------------------------------------------------------------------------

	/**
	 * Query if a given event is currently enabled in a current tracing session,
	 * meaning it should be sent to UST.
	 *
	 * @param eventName
	 *            The name of the event to check.
	 * @return True if the event is currently enabled, false if it is not.
	 */
	boolean isEventEnabled(String eventName);

	/**
	 * Return the list of application contexts enabled in the tracing sessions.
	 *
	 * @return The application contexts, first indexed by retriever name, then
	 *         by context name
	 */
	Collection<Map.Entry<String, Map<String, Integer>>> getEnabledAppContexts();
}