[skywalking] 01/01: Add v2 plugin API doc.

[wu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wusheng pushed a commit to branch v2-doc
in repository https://gitbox.apache.org/repos/asf/skywalking.git

commit 0e22dacca4b11d0a23c468fa74c211c9b996b7d1
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Thu May 20 16:19:48 2021 +0800

    Add v2 plugin API doc.
---
 .../enhance/v2/MethodInvocationContext.java        | 20 ++++----
 docs/en/guides/Java-Plugin-Development-Guide.md    | 54 ++++++++++++++++++++++
 2 files changed, 64 insertions(+), 10 deletions(-)

diff --git a/apm-sniffer/apm-agent-core/src/main/java/org/apache/skywalking/apm/agent/core/plugin/interceptor/enhance/v2/MethodInvocationContext.java b/apm-sniffer/apm-agent-core/src/main/java/org/apache/skywalking/apm/agent/core/plugin/interceptor/enhance/v2/MethodInvocationContext.java
index 7916fb9..a638323 100644
--- a/apm-sniffer/apm-agent-core/src/main/java/org/apache/skywalking/apm/agent/core/plugin/interceptor/enhance/v2/MethodInvocationContext.java
+++ b/apm-sniffer/apm-agent-core/src/main/java/org/apache/skywalking/apm/agent/core/plugin/interceptor/enhance/v2/MethodInvocationContext.java
@@ -17,18 +17,18 @@
 
 package org.apache.skywalking.apm.agent.core.plugin.interceptor.enhance.v2;
 
+import lombok.Getter;
+import lombok.Setter;
 import org.apache.skywalking.apm.agent.core.plugin.interceptor.enhance.MethodInterceptResult;
 
+/**
+ * MethodInvocationContext holds the reference to propagate it between beforeMethod and afterMethod/handleMethodException
+ */
+@Setter
+@Getter
 public class MethodInvocationContext extends MethodInterceptResult {
-
+    /**
+     * A pointer for the propagating context
+     */
     private Object context;
-
-    public Object getContext() {
-        return context;
-    }
-
-    public void setContext(Object context) {
-        this.context = context;
-    }
-
 }
diff --git a/docs/en/guides/Java-Plugin-Development-Guide.md b/docs/en/guides/Java-Plugin-Development-Guide.md
index 0b60623..757b060 100644
--- a/docs/en/guides/Java-Plugin-Development-Guide.md
+++ b/docs/en/guides/Java-Plugin-Development-Guide.md
@@ -229,11 +229,22 @@ so you simply have to define the intercept point (a.k.a. aspect pointcut in Spri
 
 ### Intercept
 SkyWalking provides two common definitions to intercept constructor, instance method and class method.
+
+#### v1 APIs
 * Extend `ClassInstanceMethodsEnhancePluginDefine` to define `constructor` intercept points and `instance method` intercept points.
 * Extend `ClassStaticMethodsEnhancePluginDefine` to define `class method` intercept points.
 
 Of course, you can extend `ClassEnhancePluginDefine` to set all intercept points, although it is uncommon to do so.
 
+#### v2 APIs
+v2 APIs provide an enhanced interceptor, which could propagate context through MIC(MethodInvocationContext).
+
+* Extend `ClassInstanceMethodsEnhancePluginDefineV2` to define `constructor` intercept points and `instance method` intercept points.
+* Extend `ClassStaticMethodsEnhancePluginDefineV2` to define `class method` intercept points.
+
+Of course, you can extend `ClassEnhancePluginDefineV2` to set all intercept points, although it is uncommon to do so.
+
+
 ### Implement plugin
 See the following demonstration on how to implement a plugin by extending `ClassInstanceMethodsEnhancePluginDefine`.
 
@@ -359,6 +370,47 @@ public interface InstanceMethodsAroundInterceptor {
 ```
 Use the core APIs before and after calling the method, as well as during exception handling.
 
+
+#### V2 APIs
+The interceptor of V2 API uses `MethodInvocationContext context` to replace the `MethodInterceptResult result` in the `beforeMethod`,
+and be added as a new parameter in `afterMethod` and `handleMethodException`.
+
+`MethodInvocationContext context` is only shared in one time execution, and safe to use when face concurrency execution.
+
+```java
+/**
+ * A v2 interceptor, which intercept method's invocation. The target methods will be defined in {@link
+ * ClassEnhancePluginDefineV2}'s subclass, most likely in {@link ClassInstanceMethodsEnhancePluginDefine}
+ */
+public interface InstanceMethodsAroundInterceptorV2 {
+    /**
+     * called before target method invocation.
+     *
+     * @param context the method invocation context including result context.
+     */
+    void beforeMethod(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes,
+                      MethodInvocationContext context) throws Throwable;
+
+    /**
+     * called after target method invocation. Even method's invocation triggers an exception.
+     *
+     * @param ret the method's original return value. May be null if the method triggers an exception.
+     * @return the method's actual return value.
+     */
+    Object afterMethod(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes,
+                       Object ret, MethodInvocationContext context) throws Throwable;
+
+    /**
+     * called when occur exception.
+     *
+     * @param t the exception occur.
+     */
+    void handleMethodException(EnhancedInstance objInst, Method method, Object[] allArguments,
+                               Class<?>[] argumentsTypes, Throwable t, MethodInvocationContext context);
+
+}
+```
+
 ### Bootstrap class instrumentation.
 SkyWalking has packaged the bootstrap instrumentation in the agent core. You can easily implement it by declaring it in the instrumentation definition.
 
@@ -399,6 +451,8 @@ public class URLInstrumentation extends ClassEnhancePluginDefine {
 }
 ```
 
+`ClassEnhancePluginDefineV2` is provided in v2 APIs, `#isBootstrapInstrumentation` works too.
+
 **NOTE**: Bootstrap instrumentation should be used only where necessary. During its actual execution, it mostly affects the JRE core(rt.jar). Defining it other than where necessary could lead to unexpected results or side effects.
 
 ### Provide custom config for the plugin