[slf4j-dev] svn commit: r1215 - in slf4j/trunk/slf4j-ext/src/main/java/org/slf4j: agent instrumentation

[ravn at slf4j.org]

Author: ravn
Date: Sat Oct 25 16:39:44 2008
New Revision: 1215

Modified:
   slf4j/trunk/slf4j-ext/src/main/java/org/slf4j/agent/AgentPremain.java
   slf4j/trunk/slf4j-ext/src/main/java/org/slf4j/instrumentation/JavassistHelper.java
   slf4j/trunk/slf4j-ext/src/main/java/org/slf4j/instrumentation/LogTransformer.java

Log:
added javadoc

Modified: slf4j/trunk/slf4j-ext/src/main/java/org/slf4j/agent/AgentPremain.java
==============================================================================
--- slf4j/trunk/slf4j-ext/src/main/java/org/slf4j/agent/AgentPremain.java	(original)
+++ slf4j/trunk/slf4j-ext/src/main/java/org/slf4j/agent/AgentPremain.java	Sat Oct 25 16:39:44 2008
@@ -17,11 +17,14 @@
 
   /**
    * JavaAgent premain entry point as specified in the MANIFEST.MF file. See
-   * {@link http://java.sun.com/javase/6/docs/api/java/lang/instrument/package-summary.html} for details.
+   * {@link http
+   * ://java.sun.com/javase/6/docs/api/java/lang/instrument/package-summary
+   * .html} for details.
    * 
    * @param agentArgument
    *          string provided after "=" up to first space
    * @param instrumentation
+   *          instrumentation environment provided by the JVM
    */
   public static void premain(String agentArgument,
       Instrumentation instrumentation) {

Modified: slf4j/trunk/slf4j-ext/src/main/java/org/slf4j/instrumentation/JavassistHelper.java
==============================================================================
--- slf4j/trunk/slf4j-ext/src/main/java/org/slf4j/instrumentation/JavassistHelper.java	(original)
+++ slf4j/trunk/slf4j-ext/src/main/java/org/slf4j/instrumentation/JavassistHelper.java	Sat Oct 25 16:39:44 2008
@@ -10,6 +10,16 @@
 
 public class JavassistHelper {
 
+  /**
+   * Create a javaassist source snippet which either is empty (for anything
+   * which does not return a value) or a explanatory text around the $_
+   * javaassist return value variable.
+   * 
+   * @param method
+   *          descriptor of method
+   * @return source snippet
+   * @throws NotFoundException
+   */
   public static String returnValue(CtBehavior method) throws NotFoundException {
 
     String returnValue = "";
@@ -19,6 +29,14 @@
     return returnValue;
   }
 
+  /**
+   * determine if the given method returns a value, and return true if so. false
+   * otherwise.
+   * 
+   * @param method
+   * @return
+   * @throws NotFoundException
+   */
   private static boolean methodReturnsValue(CtBehavior method)
       throws NotFoundException {
 
@@ -35,6 +53,15 @@
     return methodReturnsValue;
   }
 
+  /**
+   * Return javaassist source snippet which lists all the parameters and their
+   * values. If available the source names are extracted from the debug
+   * information and used, otherwise just a number is shown.
+   * 
+   * @param method
+   * @return
+   * @throws NotFoundException
+   */
   public static String getSignature(CtBehavior method) throws NotFoundException {
 
     CtClass parameterTypes[] = method.getParameterTypes();
@@ -82,6 +109,15 @@
     return signature;
   }
 
+  /**
+   * Determine the name of parameter with index i in the given method. Use the
+   * locals attributes about local variables from the classfile.
+   * 
+   * @param method
+   * @param locals
+   * @param i
+   * @return
+   */
   static String parameterNameFor(CtBehavior method,
       LocalVariableAttribute locals, int i) {
     if (locals == null) {

Modified: slf4j/trunk/slf4j-ext/src/main/java/org/slf4j/instrumentation/LogTransformer.java
==============================================================================
--- slf4j/trunk/slf4j-ext/src/main/java/org/slf4j/instrumentation/LogTransformer.java	(original)
+++ slf4j/trunk/slf4j-ext/src/main/java/org/slf4j/instrumentation/LogTransformer.java	Sat Oct 25 16:39:44 2008
@@ -157,16 +157,11 @@
   }
 
   /**
-   * The transform(...) method calls doClass(...) if the class name does not
-   * start with any of the prefixes it has been told to ignore.
-   * 
-   * doClass() first creates a class description from the byte codes. If it is a
-   * class (i.e. not an interface) the methods defined have bodies, and a static
-   * final logger object is added with the name of this class as an argument,
-   * and each method then gets processed with doMethod(...) to have logger calls
-   * added.
-   * 
-   * 
+   * doClass() process a single class by first creates a class description from
+   * the byte codes. If it is a class (i.e. not an interface) the methods
+   * defined have bodies, and a static final logger object is added with the
+   * name of this class as an argument, and each method then gets processed with
+   * doMethod(...) to have logger calls added.
    * 
    * @param name
    *          class name (slashes separate, not dots)
@@ -181,16 +176,20 @@
       cl = pool.makeClass(new ByteArrayInputStream(b));
       if (cl.isInterface() == false) {
 
+        // We have to define the log variable.
         String pattern1 = "private static org.slf4j.Logger {};";
         String loggerDefinition = format(pattern1, _LOG);
         CtField field = CtField.make(loggerDefinition, cl);
 
+        // and assign it the appropriate value.
         String pattern2 = "org.slf4j.LoggerFactory.getLogger({}.class);";
         String replace = name.replace('/', '.');
         String getLogger = format(pattern2, replace);
 
         cl.addField(field, getLogger);
-        // System.out.println(getLogger);
+
+        // then check every behaviour (which includes methods). We are only
+        // interested in non-empty ones, as they have code.
 
         CtBehavior[] methods = cl.getDeclaredBehaviors();
         for (int i = 0; i < methods.length; i++) {
@@ -212,6 +211,14 @@
     return b;
   }
 
+  /**
+   * process a single method - this means add entry/exit logging if requested.
+   * It is only called for methods with a body.
+   * 
+   * @param method method to work on
+   * @throws NotFoundException
+   * @throws CannotCompileException
+   */
   private void doMethod(CtBehavior method) throws NotFoundException,
       CannotCompileException {