Add comments on core interceptors. #78

skywalking-sniffer/skywalking-api/src/main/java/com/a/eye/skywalking/plugin/interceptor/EnhancedClassInstanceContext.java

@@ -8,7 +8,7 @@ import java.util.concurrent.ConcurrentHashMap;
  *
  * Any plugins({@link com.a.eye.skywalking.plugin.AbstractClassEnhancePluginDefine}'s subclass) override
  * {@link com.a.eye.skywalking.plugin.interceptor.enhance.ClassEnhancePluginDefine#getConstructorsInterceptPoints}
- * and
+ * or
  * {@link com.a.eye.skywalking.plugin.interceptor.enhance.ClassEnhancePluginDefine#getInstanceMethodsInterceptPoints}
  * will add a field with this type.
  * 

skywalking-sniffer/skywalking-api/src/main/java/com/a/eye/skywalking/plugin/interceptor/enhance/ClassConstructorInterceptor.java

@@ -9,33 +9,48 @@ import net.bytebuddy.implementation.bind.annotation.FieldProxy;
 import net.bytebuddy.implementation.bind.annotation.RuntimeType;
 import net.bytebuddy.implementation.bind.annotation.This;
 
+/**
+ * The actual byte-buddy's interceptor to intercept constructor methods.
+ * In this class, it provide a bridge between byte-buddy and sky-walking plugin.
+ *
+ * @author wusheng
+ */
 public class ClassConstructorInterceptor {
-	private static ILog logger = LogManager
-			.getLogger(ClassConstructorInterceptor.class);
+    private static ILog logger = LogManager.getLogger(ClassConstructorInterceptor.class);
 
-	private String instanceMethodsAroundInterceptorClassName;
+    /**
+     * A class full name, and instanceof {@link InstanceConstructorInterceptor}
+     * This name should only stay in {@link String}, the real {@link Class} type will trigger classloader failure.
+     * If you want to know more, please check on books about Classloader or Classloader appointment mechanism.
+     */
+    private String constructorInterceptorClassName;
 
-	public ClassConstructorInterceptor(String instanceMethodsAroundInterceptorClassName) {
-		this.instanceMethodsAroundInterceptorClassName = instanceMethodsAroundInterceptorClassName;
-	}
+    /**
+     * Set the name of {@link ClassConstructorInterceptor#constructorInterceptorClassName}
+     * @param constructorInterceptorClassName class full name.
+     */
+    public ClassConstructorInterceptor(String constructorInterceptorClassName) {
+        this.constructorInterceptorClassName = constructorInterceptorClassName;
+    }
 
-	@RuntimeType
-	public void intercept(
-			@This Object obj,
-			@FieldProxy(ClassEnhancePluginDefine.contextAttrName) FieldSetter accessor,
-			@AllArguments Object[] allArguments) {
-		try {
-			InstanceConstructorInterceptor interceptor = InterceptorInstanceLoader
-					.load(instanceMethodsAroundInterceptorClassName, obj.getClass().getClassLoader());
+    /**
+     * Intercept the target constructor.
+     * @param obj target class instance.
+     * @param accessor setter to the new added field of the target enhanced class.
+     * @param allArguments all constructor arguments
+     */
+    @RuntimeType
+    public void intercept(@This Object obj, @FieldProxy(ClassEnhancePluginDefine.contextAttrName) FieldSetter accessor, @AllArguments Object[] allArguments) {
+        try {
+            InstanceConstructorInterceptor interceptor = InterceptorInstanceLoader.load(constructorInterceptorClassName, obj.getClass().getClassLoader());
 
-			EnhancedClassInstanceContext context = new EnhancedClassInstanceContext();
-			accessor.setValue(context);
-			ConstructorInvokeContext interceptorContext = new ConstructorInvokeContext(obj,
-					allArguments);
-			interceptor.onConstruct(context, interceptorContext);
-		} catch (Throwable t) {
-			logger.error("ClassConstructorInterceptor failure.", t);
-		}
+            EnhancedClassInstanceContext context = new EnhancedClassInstanceContext();
+            accessor.setValue(context);
+            ConstructorInvokeContext interceptorContext = new ConstructorInvokeContext(obj, allArguments);
+            interceptor.onConstruct(context, interceptorContext);
+        } catch (Throwable t) {
+            logger.error("ClassConstructorInterceptor failure.", t);
+        }
 
-	}
+    }
 }

skywalking-sniffer/skywalking-api/src/main/java/com/a/eye/skywalking/plugin/interceptor/enhance/ClassInstanceMethodsInterceptor.java

@@ -10,19 +10,40 @@ import java.lang.reflect.Method;
 import java.util.concurrent.Callable;
 
 /**
- * 类方法拦截、控制器
+ * The actual byte-buddy's interceptor to intercept class instance methods.
+ * In this class, it provide a bridge between byte-buddy and sky-walking plugin.
  *
  * @author wusheng
  */
 public class ClassInstanceMethodsInterceptor {
     private static ILog logger = LogManager.getLogger(ClassInstanceMethodsInterceptor.class);
 
+    /**
+     * A class full name, and instanceof {@link InstanceMethodsAroundInterceptor}
+     * This name should only stay in {@link String}, the real {@link Class} type will trigger classloader failure.
+     * If you want to know more, please check on books about Classloader or Classloader appointment mechanism.
+     */
     private String instanceMethodsAroundInterceptorClassName;
 
+    /**
+     * Set the name of {@link ClassInstanceMethodsInterceptor#instanceMethodsAroundInterceptorClassName}
+     * @param instanceMethodsAroundInterceptorClassName class full name.
+     */
     public ClassInstanceMethodsInterceptor(String instanceMethodsAroundInterceptorClassName) {
         this.instanceMethodsAroundInterceptorClassName = instanceMethodsAroundInterceptorClassName;
     }
 
+    /**
+     * Intercept the target instance method.
+     * @param obj target class instance.
+     * @param allArguments all method arguments
+     * @param method method description.
+     * @param zuper the origin call ref.
+     * @param instanceContext the added field of enhanced class.
+     * @return the return value of target instance method.
+     * @throws Exception only throw exception because of zuper.call()
+     *          or unexpected exception in sky-walking ( This is a bug, if anything triggers this condition ).
+     */
     @RuntimeType
     public Object intercept(@This Object obj, @AllArguments Object[] allArguments, @Origin Method method, @SuperCall Callable<?> zuper,
             @FieldValue(ClassEnhancePluginDefine.contextAttrName) EnhancedClassInstanceContext instanceContext) throws Exception {

skywalking-sniffer/skywalking-api/src/main/java/com/a/eye/skywalking/plugin/interceptor/enhance/ClassStaticMethodsInterceptor.java

@@ -12,19 +12,39 @@ import java.lang.reflect.Method;
 import java.util.concurrent.Callable;
 
 /**
- * 类静态方法拦截、控制器
+ * The actual byte-buddy's interceptor to intercept class instance methods.
+ * In this class, it provide a bridge between byte-buddy and sky-walking plugin.
  *
  * @author wusheng
  */
 public class ClassStaticMethodsInterceptor {
     private static ILog logger = LogManager.getLogger(ClassStaticMethodsInterceptor.class);
 
+    /**
+     * A class full name, and instanceof {@link StaticMethodsAroundInterceptor}
+     * This name should only stay in {@link String}, the real {@link Class} type will trigger classloader failure.
+     * If you want to know more, please check on books about Classloader or Classloader appointment mechanism.
+     */
     private String staticMethodsAroundInterceptorClassName;
 
+    /**
+     * Set the name of {@link ClassStaticMethodsInterceptor#staticMethodsAroundInterceptorClassName}
+     * @param staticMethodsAroundInterceptorClassName class full name.
+     */
     public ClassStaticMethodsInterceptor(String staticMethodsAroundInterceptorClassName) {
         this.staticMethodsAroundInterceptorClassName = staticMethodsAroundInterceptorClassName;
     }
 
+    /**
+     * Intercept the target static method.
+     * @param clazz target class
+     * @param allArguments all method arguments
+     * @param method method description.
+     * @param zuper the origin call ref.
+     * @return the return value of target static method.
+     * @throws Exception only throw exception because of zuper.call()
+     *          or unexpected exception in sky-walking ( This is a bug, if anything triggers this condition ).
+     */
     @RuntimeType
     public Object intercept(@Origin Class<?> clazz, @AllArguments Object[] allArguments, @Origin Method method, @SuperCall Callable<?> zuper) throws Exception {
         StaticMethodsAroundInterceptor interceptor = InterceptorInstanceLoader