Add Javadoc and related settings

[lttng-ust-java-tests.git] / src / test / java / org / lttng / ust / agent / utils / LttngSession.java

diff --git a/src/test/java/org/lttng/ust/agent/utils/LttngSession.java b/src/test/java/org/lttng/ust/agent/utils/LttngSession.java
index 3a6a75196e5e1f80a5c705160db021b1493cb7ca..9c77f59b8395ca8e7bdd41d58aa1afa8daaa9302 100644 (file)
--- a/src/test/java/org/lttng/ust/agent/utils/LttngSession.java
+++ b/src/test/java/org/lttng/ust/agent/utils/LttngSession.java
@@ -1,3 +1,21 @@
+/*
+ * Copyright (C) 2015, EfficiOS Inc., Alexandre Montplaisir <alexmonthy@efficios.com>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program 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 General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
 package org.lttng.ust.agent.utils;
 
 import java.io.IOException;
@@ -13,10 +31,21 @@ import java.util.List;
 import java.util.UUID;
 import java.util.stream.Collectors;
 
+/**
+ * Java representation of a LTTng tracing session. It uses the command-line
+ * "lttng" tool to manipulate the session. Creating an instance will run
+ * "lttng create", close()'ing it will run "lttng destroy".
+ *
+ * @author Alexandre Montplaisir
+ */
 public class LttngSession implements AutoCloseable {
 
+    /**
+     * Tracing domains as they are defined by lttng-tools
+     */
     public enum Domain {
-        JUL("-j"),
+        /** The JUL (java.util.logging) domain */
+        JUL("-j"), /** The log4j (org.apache.log4j) domain */
         LOG4J("-l");
 
         private final String flag;
@@ -25,6 +54,10 @@ public class LttngSession implements AutoCloseable {
             this.flag = flag;
         }
 
+        /**
+         * @return The corresponding command-line flag to pass to options like
+         *         "lttng enable-event"
+         */
         public String flag() {
             return flag;
         }
@@ -35,6 +68,15 @@ public class LttngSession implements AutoCloseable {
 
     private volatile boolean channelCreated = false;
 
+    /**
+     * Constructor to create a new LTTng tracing session.
+     *
+     * @param sessionName
+     *            The name of the session to use. It can be null, in which case
+     *            we will provide a unique random name.
+     * @param domain
+     *            The tracing domain of this session
+     */
     public LttngSession(String sessionName, Domain domain) {
         if (sessionName != null) {
             this.sessionName = sessionName;
@@ -105,6 +147,11 @@ public class LttngSession implements AutoCloseable {
                 "-s", sessionName));
     }
 
+    /**
+     * Start tracing
+     *
+     * @return If the command executed successfully (return code = 0).
+     */
     public boolean start() {
         /*
          * We have to enable a channel for 'lttng start' to work. However, we
@@ -185,7 +232,11 @@ public class LttngSession implements AutoCloseable {
     }
 
     /**
-     * Just to test the environment / stdout are working correctly
+     * Simple command to test that the environment / stdout are working
+     * correctly.
+     *
+     * @param args
+     *            Command-line arguments
      */
     public static void main(String[] args) {
         List<String> command = Arrays.asList("ls", "-l");