Add API stubs for the Java context info retrievers

A context info retriever will allow an application to define their own
context information, and have it available in the resulting UST traces.

Signed-off-by: Alexandre Montplaisir <alexmonthy@efficios.com>
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>

diff --git a/liblttng-ust-java-agent/java/lttng-ust-agent-common/Makefile.am b/liblttng-ust-java-agent/java/lttng-ust-agent-common/Makefile.am
index 67c3e1aa1337e53fff5ac81023bbbb9eddc59032..628aedb6c5cee305de35696054801657d6c2a73b 100644 (file)
--- a/liblttng-ust-java-agent/java/lttng-ust-agent-common/Makefile.am
+++ b/liblttng-ust-java-agent/java/lttng-ust-agent-common/Makefile.am
@@ -22,6 +22,8 @@ dist_noinst_JAVA = $(pkgpath)/AbstractLttngAgent.java \
                                   $(pkgpath)/client/SessiondDisableEventCommand.java \
                                   $(pkgpath)/client/SessiondEnableEventCommand.java \
                                   $(pkgpath)/client/SessiondListLoggersCommand.java \
+                                  $(pkgpath)/context/ContextInfoManager.java \
+                                  $(pkgpath)/context/IContextInfoRetriever.java \
                                   $(pkgpath)/filter/FilterChangeNotifier.java \
                                   $(pkgpath)/filter/IFilterChangeListener.java \
                                   $(pkgpath)/session/EventRule.java \
@@ -32,7 +34,7 @@ dist_noinst_DATA = $(jarfile_manifest)
 
 jar_DATA = $(jarfile)
 
-classes = $(pkgpath)/*.class $(pkgpath)/client/*.class $(pkgpath)/filter/*.class $(pkgpath)/session/*.class
+classes = $(pkgpath)/*.class $(pkgpath)/client/*.class $(pkgpath)/context/*.class $(pkgpath)/filter/*.class $(pkgpath)/session/*.class
 
 $(jarfile): classnoinst.stamp
        $(JAR) cfm $(JARFLAGS) $@ $(jarfile_manifest) $(classes) && rm -f $(jarfile_symlink) && $(LN_S) $@ $(jarfile_symlink)
@@ -45,4 +47,4 @@ install-data-hook:
 uninstall-hook:
        cd $(DESTDIR)/$(jardir) && rm -f $(jarfile_symlink)
 
-CLEANFILES = $(jarfile) $(pkgpath)/*.class $(pkgpath)/client/*.class $(pkgpath)/filter/*.class $(pkgpath)/session/*.class
+CLEANFILES = $(jarfile) $(pkgpath)/*.class $(pkgpath)/client/*.class $(pkgpath)/context/*.class $(pkgpath)/filter/*.class $(pkgpath)/session/*.class

diff --git a/liblttng-ust-java-agent/java/lttng-ust-agent-common/org/lttng/ust/agent/context/ContextInfoManager.java b/liblttng-ust-java-agent/java/lttng-ust-agent-common/org/lttng/ust/agent/context/ContextInfoManager.java
new file mode 100644 (file)
index 0000000..90a79ac
--- /dev/null
+++ b/liblttng-ust-java-agent/java/lttng-ust-agent-common/org/lttng/ust/agent/context/ContextInfoManager.java
@@ -0,0 +1,84 @@
+/*
+ * 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.context;
+
+import java.util.Set;
+import java.util.concurrent.CopyOnWriteArraySet;
+
+/**
+ * The singleton manager of {@link IContextInfoRetriever} objects.
+ *
+ * @author Alexandre Montplaisir
+ */
+public final class ContextInfoManager {
+
+       private static final ContextInfoManager INSTANCE = new ContextInfoManager();
+
+       private final Set<IContextInfoRetriever> cirs = new CopyOnWriteArraySet<IContextInfoRetriever>();
+
+       /** Singleton class, constructor should not be accessed directly */
+       private ContextInfoManager() {
+       }
+
+       /**
+        * Get the singleton instance.
+        *
+        * @return The singleton instance
+        * @deprecated The context-retrieving facilities are not yet implemented.
+        */
+       @Deprecated
+       public static ContextInfoManager getInstance() {
+               return INSTANCE;
+       }
+
+       /**
+        * Register a new context info retriever.
+        *
+        * This method has no effect if the exact same retriever is already
+        * registered.
+        *
+        * @param cir
+        *            The context info retriever to register
+        */
+       public void addContextInfoRetriever(IContextInfoRetriever cir) {
+               cirs.add(cir);
+       }
+
+       /**
+        * Unregister a previously added context info retriever.
+        *
+        * This method has no effect if the retriever was not already registered.
+        *
+        * @param cir
+        *            The context info retriever to unregister
+        */
+       public void removeContextInfoRetriever(IContextInfoRetriever cir) {
+               cirs.remove(cir);
+       }
+
+       /**
+        * Return a read-only view (does not support
+        * {@link java.util.Iterator#remove}) of the currently registered context
+        * info retrievers.
+        *
+        * @return The current context info retrievers
+        */
+       public Iterable<IContextInfoRetriever> getContextInfoRetrievers() {
+               return cirs;
+       }
+}

diff --git a/liblttng-ust-java-agent/java/lttng-ust-agent-common/org/lttng/ust/agent/context/IContextInfoRetriever.java b/liblttng-ust-java-agent/java/lttng-ust-agent-common/org/lttng/ust/agent/context/IContextInfoRetriever.java
new file mode 100644 (file)
index 0000000..6717b9e
--- /dev/null
+++ b/liblttng-ust-java-agent/java/lttng-ust-agent-common/org/lttng/ust/agent/context/IContextInfoRetriever.java
@@ -0,0 +1,41 @@
+/*
+ * 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.context;
+
+/**
+ * Context-retrieving object specified by the application to extract
+ * application-specific context information, which can then be passed on to the
+ * Java agents and saved to a trace.
+ *
+ * Retriever objects should be registered to the {@link ContextInfoManager} to
+ * make them available to the LTTng agents.
+ *
+ * @author Alexandre Montplaisir
+ */
+public interface IContextInfoRetriever {
+
+       /**
+        * Retrieve a piece of context information from the application, identified
+        * by a key.
+        *
+        * @param key
+        *            The key identifying the context information
+        * @return The context information.
+        */
+       Object retrieveContextInfo(String key);
+}