svn commit: r801571 - /qpid/trunk/qpid/java/broker/src/main/java/org/apache/qpid/server/logging/actors/CurrentActor.java

[ri...@apache.org]

Author: ritchiem
Date: Thu Aug  6 09:38:14 2009
New Revision: 801571

URL: http://svn.apache.org/viewvc?rev=801571&view=rev
Log:
QPID-2002 : Javadoc'd CurrentActor

Modified:
    qpid/trunk/qpid/java/broker/src/main/java/org/apache/qpid/server/logging/actors/CurrentActor.java

Modified: qpid/trunk/qpid/java/broker/src/main/java/org/apache/qpid/server/logging/actors/CurrentActor.java
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/java/broker/src/main/java/org/apache/qpid/server/logging/actors/CurrentActor.java?rev=801571&r1=801570&r2=801571&view=diff
==============================================================================
--- qpid/trunk/qpid/java/broker/src/main/java/org/apache/qpid/server/logging/actors/CurrentActor.java (original)
+++ qpid/trunk/qpid/java/broker/src/main/java/org/apache/qpid/server/logging/actors/CurrentActor.java Thu Aug  6 09:38:14 2009
@@ -25,28 +25,82 @@
 import java.util.LinkedList;
 import java.util.Deque;
 
+/**
+ * The CurrentActor is a ThreadLocal wrapper that allows threads in the broker
+ * to retrieve an actor to perform logging. This approach is used so for two
+ * reasons:
+ * 1) We do not have to pass a logging actor around the system
+ * 2) We can set new actors at the point we have enough information. i.e.
+ *  - Set a low level ConnectionActor when processing bytes from the wire.
+ *  - Set a ChannelActor when we are processing the frame
+ *  - Set a SubscriptionActor when we are handling the subscription.
+ *
+ * The code performing the logging need not worry about what type of actor is
+ * currently set so can perform its logging. The resulting log entry though will
+ * contain customised details from the the currently set Actor.
+ *
+ * The Actor model also allows the pre-creation of fixed messages so the
+ * performance impact of the additional logging data is minimised.
+ *
+ * This class does not perform any checks to ensure that there is an Actor set
+ * when calling remove or get. As a result the application developer must ensure
+ * that they have called set before they attempt to use the actor via get or
+ * remove the set actor.
+ *
+ * The checking of the return via get should not be done as the logging is
+ * desired. It is preferable to cause the NullPointerException to highlight the
+ * programming error rather than miss a log message.
+ *
+ * The same is true for the remove. A NPE will occur if no set has been called
+ * highlighting the programming error.
+ * 
+ */
 public class CurrentActor
 {
+    /**
+     * The ThreadLocal variable with initialiser
+     */
     private static final ThreadLocal<Deque<LogActor>> _currentActor = new ThreadLocal<Deque<LogActor>>()
     {
+        // Initialise the CurrentActor to be an empty List
         protected Deque<LogActor> initialValue()
         {
             return new LinkedList<LogActor>();
         }
     };
 
+    /**
+     * Set a new LogActor to be the Current Actor
+     *
+     * This pushes the Actor in to the LIFO Queue
+     *
+     * @param actor The new LogActor
+     */
     public static void set(LogActor actor)
     {
         Deque<LogActor> stack = _currentActor.get();
         stack.addFirst(actor);
     }
 
+    /**
+     * Remove the current LogActor.
+     *
+     * Calling remove without calling set will result in a NoSuchElementException.
+     *
+     */
     public static void remove()
     {
         Deque<LogActor> stack = _currentActor.get();
-        stack.remove();
+        stack.removeFirst();
     }
 
+    /**
+     * Return the current head of the list of LogActors.
+     *
+     * If there has been no set call then this will return Null.
+     *
+     * @return Current LogActor
+     */
     public static LogActor get()
     {
         return _currentActor.get().peek();



---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org