[lttng-dev] [PATCH lttng-ust] Update Java agent documentation

[Christian Babeux]

Signed-off-by: Christian Babeux <christian.babeux at efficios.com>
---
 doc/Makefile.am           |  2 +-
 doc/java-agent.txt        | 51 +++++++++++++++++++++++++++++++++++++++++++++++
 doc/java-util-logging.txt | 41 -------------------------------------
 3 files changed, 52 insertions(+), 42 deletions(-)
 create mode 100644 doc/java-agent.txt
 delete mode 100644 doc/java-util-logging.txt

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 72dcde2..ba21e9f 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -5,4 +5,4 @@ dist_man_MANS = man/lttng-gen-tp.1 \
 	man/lttng-ust-dl.3 \
 	man/lttng-ust-cyg-profile.3
 
-dist_doc_DATA = java-util-logging.txt
+dist_doc_DATA = java-agent.txt
diff --git a/doc/java-agent.txt b/doc/java-agent.txt
new file mode 100644
index 0000000..51b0e8c
--- /dev/null
+++ b/doc/java-agent.txt
@@ -0,0 +1,51 @@
+The agent can now be built in three different configurations:
+
+1) Java agent with JUL support:
+
+$ ./configure --enable-java-agent-jul
+
+2) Java agent with Log4j support:
+
+$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
+$ ./configure --enable-java-agent-log4j
+
+3) Java agent with JUL + Log4j support
+
+$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
+$ ./configure --enable-java-agent-all
+
+To build the agent with log4j support, make sure that the log4j jar
+is in your Java classpath.
+
+The configure script will automatically detect the appropriate Java
+binaries to use in order to build the Java agent.
+
+The name of the agent jar file is now "liblttng-ust-agent.jar".
+It will be installed in the arch-agnostic "$prefix/share/java" path
+e.g: "/usr/share/java".
+
+In order to support older applications using the "org.lttng.ust.jul"
+package, a transitional package is built with the same name.
+
+All applications should move to use the "org.lttng.ust.agent" package.
+
+After building, you can use the "liblttng-ust-agent.jar" file in a
+Java project.  Depending on your configuration, the agent will
+requires shared objects (e.g: "liblttng-ust-jul.so") which is installed
+by the build system when doing "make install". Make sure that your
+Java application can find this shared object with the
+"java.library.path".
+
+In order to enable the agent in your Java application, you simply have to add
+this as early as you can in the runtime process.
+
+import org.lttng.ust.agent.LTTngAgent;
+[...]
+	private static LTTngAgent lttngAgent;
+	[...]
+	lttngAgent = LTTngAgent.getLTTngAgent();
+
+This will initialize automatically the singleton LTTngAgent, and will
+return when the session daemon registration is done. If no session daemon is
+available, the execution will continue and the agent will retry every
+3 seconds.
diff --git a/doc/java-util-logging.txt b/doc/java-util-logging.txt
deleted file mode 100644
index 9f827e6..0000000
--- a/doc/java-util-logging.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-The support for JUL needs to be explicitly enabled when lttng-ust is
-configured, e.g.:
-
-dependency: openjdk-7-jdk
-    ./configure --with-java-jdk=/usr/lib/jvm/java-7-openjdk --with-jni-interface
-
-On Debian system for instance you can simply use the "default-java" path:
-
-    ./configure --with-java-jdk=/usr/lib/jvm/default-java --with-jni-interface
-
-Note that the OpenJDK 7 is used for development and continuous integration thus
-we directly support that version for this library. However, it has been tested
-with OpenJDK 6 also. Please let us know if other Java version (commercial or
-not) work with this library.
-
-The LTTng Java Agent for JUL support is typically installed here:
-
-/usr/local/lib/lttng/java/liblttng-ust-jul.jar
-
-After building, you can use the "liblttng-ust-jul.jar" file in a Java project.
-It requires "liblttng-ust-jul.so" which is installed by the build system when
-doing "make install". Make sure that your Java application can find this shared
-object with the "java.library.path".
-
-In order to enable the agent in your Java application, you simply have to add
-this as early as you can in the runtime process.
-
-import org.lttng.ust.jul.LTTngAgent;
-[...]
-	private static LTTngAgent lttngAgent;
-	[...]
-	lttngAgent = LTTngAgent.getLTTngAgent();
-
-This will initialize automatically the singleton LTTngAgent, and will
-return when session daemon registration is done. If no session daemon is
-available, the execution will continue and the agent will retry every
-3 seconds.
-
-Once registered, it is adds a thread inside your Java application and will be
-able to automatically use every Logger object and map them to the jul_event
-tracepoint of the JNI interface.
-- 
2.1.1