Added message parameter interpolation and documentation for logging.

git-svn-id: http://anonsvn.jboss.org/repos/weld/ri/trunk@1870 1c488680-804c-0410-94cd-c6b725194a0e

impl/src/main/java/org/jboss/webbeans/log/Log.java

@@ -17,8 +17,65 @@
 package org.jboss.webbeans.log;
 
 /**
+ * <p>A <code>Log</code> object is used by RI classes to log messages.
+ * They will be logged in any environment that has setup a logging service
+ * such as Log4J or the standard JDK logging facilities.  In fact, this
+ * logging interface is very similar to the other facilities with the
+ * difference that logging methods also take any number of optional
+ * parameters beyond the message object for later interpolation
+ * into the message.</p>
+ * 
+ * <p>The idea of using interpolation parameters is very important for
+ * performance reasons in production code.  Normally developers write
+ * logging messages similar to this one:
+ * <pre>
+ *    log.debug("Started processing of " + obj1 + " with action " + obj2);
+ * </pre>
+ * The problem that arises at runtime in production systems, is that DEBUG
+ * level logging may not be enabled.  And even if this logging is going to
+ * be a no-op call, Java must still build the string dynamically that is the
+ * argument to the call.  It is the building of this string that can be quite
+ * time consuming.  The more complex the objects being concatenated are, the
+ * worse the time penalty incurred is.  And this time is completely wasted
+ * since the string may never be used.</p>
+ * 
+ * <p>Normally to combat the problem of making this call and building the
+ * string dynamically, the developer uses a conditional statement to invoke
+ * the call only if the corresponding logging level is enabled.  So the above
+ * call may end up looking like:
+ * <pre>
+ *    if (log.isDebugEnabled())
+ *    {
+ *       log.debug("Started processing of " + obj1 + " with action " + obj2);
+ *    }
+ * </pre>
+ * Ideally, this structure should always be used to avoid the cost of building the
+ * dynamic string (concatenation) and making the unnecessary call.  The only 
+ * drawback to this is that code can become less readable.  In some cases, there
+ * might be more code devoted to logging than the actual behavior required by a
+ * method.</p>
+ * 
+ * <p>A cleaner way to do the logging is to use this interface where simple
+ * objects without any concatenation are passed as arguments.  Albeit the call
+ * itself may still be a no-op when the logging level is not enabled, this is
+ * still much smaller than the concatenation process with dynamic strings.  Each
+ * of the methods defined here will first check to see if the logging level is enabled,
+ * if that feature exists in the underlying logging system.  If and only if that logging
+ * level is enabled, will the implementation proceed with concatenation of the strings
+ * and objects passed.  So the above code using this interface becomes:
+ * <pre>
+ *    log.debug("Started processing of {0} with action {1}, obj1, obj2);
+ * </pre>
+ * </p>
+ * 
+ * <p>The interpolation of parameters into the message string are done using
+ * {@link java.text.MessageFormat}.  See the documentation on that class for
+ * more ideas of interpolation possibilities.  In the above code, <code>obj1</code>
+ * and <code>obj2</code> simply have their <code>toString()</code> methods invoked
+ * to produce a string which is then concatenated.</p>
  * 
  * @author Gavin King
+ * @author David Allen
  *
  */
 public interface Log

impl/src/main/java/org/jboss/webbeans/log/LogImpl.java

@@ -20,6 +20,7 @@
 import java.io.IOException;
 import java.io.ObjectInput;
 import java.io.ObjectOutput;
+import java.text.MessageFormat;
 
 /**
  * 
@@ -167,13 +168,14 @@ public void fatal(Object object, Throwable t, Object... params)
       }
    }
 
-   private Object interpolate(Object object, Object... params)
+   private Object interpolate(Object message, Object... params)
    {
+      Object interpolatedMessage = message;
       if (params.length > 0)
       {
-         throw new UnsupportedOperationException("Parameter interpolation not supported");
+         interpolatedMessage = MessageFormat.format(message.toString(), params);
       }
-      return object;
+      return interpolatedMessage;
    }
 
    public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException

impl/src/main/java/org/jboss/webbeans/mock/MockTransactionServices.java

@@ -32,18 +32,13 @@
 public class MockTransactionServices implements TransactionServices
 {
 
-   /* (non-Javadoc)
-    * @see org.jboss.webbeans.transaction.spi.TransactionServices#isTransactionActive()
-    */
    public boolean isTransactionActive()
    {
       return false;
    }
 
    public void registerSynchronization(Synchronization synchronizedObserver)
    {
-      // TODO Auto-generated method stub
-
    }
 
 }