[jboss-svn-commits] JBoss Common SVN: r3184 - jboss-logmanager/trunk/src/main/java/org/jboss/logmanager.

[jboss-svn-commits at lists.jboss.org]

Author: david.lloyd at jboss.com
Date: 2009-05-20 17:29:16 -0400 (Wed, 20 May 2009)
New Revision: 3184

Modified:
   jboss-logmanager/trunk/src/main/java/org/jboss/logmanager/MDC.java
   jboss-logmanager/trunk/src/main/java/org/jboss/logmanager/NDC.java
Log:
javadocs

Modified: jboss-logmanager/trunk/src/main/java/org/jboss/logmanager/MDC.java
===================================================================
--- jboss-logmanager/trunk/src/main/java/org/jboss/logmanager/MDC.java	2009-05-20 21:11:43 UTC (rev 3183)
+++ jboss-logmanager/trunk/src/main/java/org/jboss/logmanager/MDC.java	2009-05-20 21:29:16 UTC (rev 3184)
@@ -26,7 +26,7 @@
 import java.util.HashMap;
 
 /**
- *
+ * Mapped diagnostic context.  This is a thread-local map used to hold loggable information.
  */
 public final class MDC {
 
@@ -34,10 +34,23 @@
 
     private static final Holder mdc = new Holder();
 
+    /**
+     * Get the value for a key, or {@code null} if there is no mapping.
+     *
+     * @param key the key
+     * @return the value
+     */
     public static String get(String key) {
         return mdc.get().get(key);
     }
 
+    /**
+     * Set the value of a key, returning the old value (if any) or {@code null} if there was none.
+     *
+     * @param key the key
+     * @param value the new value
+     * @return the old value or {@code null} if there was none
+     */
     public static String put(String key, String value) {
         if (key == null) {
             throw new NullPointerException("key is null");
@@ -48,14 +61,28 @@
         return mdc.get().put(key, value);
     }
 
+    /**
+     * Remove a key.
+     *
+     * @param key the key
+     * @return the old value or {@code null} if there was none
+     */
     public static String remove(String key) {
         return mdc.get().remove(key);
     }
 
+    /**
+     * Get a copy of the MDC map.  This is a relatively expensive operation.
+     *
+     * @return a copy of the map
+     */
     public static Map<String, String> copy() {
         return new HashMap<String, String>(mdc.get());
     }
 
+    /**
+     * Clear the current MDC map.
+     */
     public static void clear() {
         mdc.get().clear();
     }

Modified: jboss-logmanager/trunk/src/main/java/org/jboss/logmanager/NDC.java
===================================================================
--- jboss-logmanager/trunk/src/main/java/org/jboss/logmanager/NDC.java	2009-05-20 21:11:43 UTC (rev 3183)
+++ jboss-logmanager/trunk/src/main/java/org/jboss/logmanager/NDC.java	2009-05-20 21:29:16 UTC (rev 3184)
@@ -25,7 +25,8 @@
 import java.util.Arrays;
 
 /**
- *
+ * Nested diagnostic context.  This is basically a thread-local stack that holds a string which can be included
+ * in a log message.
  */
 public final class NDC {
 
@@ -33,6 +34,12 @@
 
     private static final Holder ndc = new Holder();
 
+    /**
+     * Push a value on to the NDC stack, returning the new stack depth which should later be used to restore the stack.
+     *
+     * @param context the new value
+     * @return the new stack depth
+     */
     public static int push(String context) {
         final Stack<String> stack = ndc.get();
         try {
@@ -42,6 +49,11 @@
         }
     }
 
+    /**
+     * Pop the topmost value from the NDC stack and return it.
+     *
+     * @return the old topmost value
+     */
     public static String pop() {
         final Stack<String> stack = ndc.get();
         if (stack.isEmpty()) {
@@ -51,18 +63,37 @@
         }
     }
 
+    /**
+     * Clear the thread's NDC stack.
+     */
     public static void clear() {
         ndc.get().trimTo(0);
     }
 
+    /**
+     * Trim the thread NDC stack down to no larger than the given size.  Used to restore the stack to the depth returned
+     * by a {@code push()}.
+     *
+     * @param size the new size
+     */
     public static void trimTo(int size) {
         ndc.get().trimTo(size);
     }
 
+    /**
+     * Get the current NDC stack depth.
+     *
+     * @return the stack depth
+     */
     public static int getDepth() {
         return ndc.get().depth();
     }
 
+    /**
+     * Get the current NDC value.
+     *
+     * @return the current NDC value, or {@code ""} if there is none
+     */
     public static String get() {
         final Stack<String> stack = ndc.get();
         if (stack.isEmpty()) {