diff --git a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Name.java b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Name.java index 9d3f21b39..17c159e30 100644 --- a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Name.java +++ b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Name.java @@ -20,6 +20,10 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** + * Provides name of auto binded parameter. + * + * Some auto binded parameter types should be identified by name. + * * @author Jongho Moon * */ diff --git a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/ProfilerPlugin.java b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/ProfilerPlugin.java index d30c9865a..a0a3d8545 100644 --- a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/ProfilerPlugin.java +++ b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/ProfilerPlugin.java @@ -17,7 +17,14 @@ package com.navercorp.pinpoint.bootstrap.plugin; - +/** + * Pinpoint profiler plugin should implement this interface. + * + * When Pinpoint agent initialize, plugins are loaded by the agent, and then their {@link #setup(ProfilerPluginSetupContext)} methods are invoked. + * + * @author Jongho Moon + * + */ public interface ProfilerPlugin { void setup(ProfilerPluginSetupContext context); } diff --git a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/ProfilerPluginContext.java b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/ProfilerPluginContext.java index 8e5c48860..60536d98b 100644 --- a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/ProfilerPluginContext.java +++ b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/ProfilerPluginContext.java @@ -20,16 +20,60 @@ import com.navercorp.pinpoint.bootstrap.context.TraceContext; import com.navercorp.pinpoint.bootstrap.instrument.ByteCodeInstrumentor; /** + * Provides attributes and objects to interceptors. + * + * Only interceptors can acquire an instance of this class as a constructor argument. + * * @author Jongho Moon * */ public interface ProfilerPluginContext { - public Object setAttribute(String key, Object value); - public Object getAttribute(String key); - - public MetadataAccessor getMetadataAccessor(String name); - public FieldAccessor getFieldSnooper(String name); + /** + * Set an attribute. Only objects within same plug-in can see this attribute. + * + * @param name attribute name + * @param value attribute value + * @return Previous value if the name was associated with other value. null otherwise. + */ + public Object setAttribute(String name, Object value); + /** + * Get an attribute set within a plug-in. + * + * You can get attributes set by {@link ProfilerPluginSetupContext#setAttribute(String, Object)} too. + * + * @param name attribute name + * @return value value associated with given name. null if no value is set. + */ + public Object getAttribute(String name); + + /** + * Get the {@link MetadataAccessor} with given name. + * + * @param name + * @return {@link MetadataAccessor} with given name. null if there is no {@link MetadataAccessor} with the name. + */ + public MetadataAccessor getMetadataAccessor(String name); + + /** + * Get the {@link MetadataAccessor} with given name. + * + * @param name + * @return {@link MetadataAccessor} with given name. null if there is no {@link MetadataAccessor} with the name. + */ + public FieldAccessor getFieldAccessor(String name); + + /** + * Get {@link TraceContext} + * + * @return {@link TraceContext} of current transction + */ public TraceContext getTraceContext(); + + /** + * Get {@link ByteCodeInstrumentor} + * + * @return {@link ByteCodeInstrumentor} + */ public ByteCodeInstrumentor getByteCodeInstrumentor(); } diff --git a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/ProfilerPluginSetupContext.java b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/ProfilerPluginSetupContext.java index 129e435eb..ec52995bf 100644 --- a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/ProfilerPluginSetupContext.java +++ b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/ProfilerPluginSetupContext.java @@ -19,17 +19,61 @@ import com.navercorp.pinpoint.bootstrap.plugin.editor.ClassEditor; import com.navercorp.pinpoint.bootstrap.plugin.editor.ClassEditorBuilder; /** + * {@link ProfilerPlugin} uses this class to setup itself. + * + * * @author Jongho Moon - * */ public interface ProfilerPluginSetupContext { + /** + * Get the {@link ProfilerConfig} + * + * @return {@link ProfilerConfig} + */ public ProfilerConfig getConfig(); - public Object setAttribute(String key, Object value); - public Object getAttribute(String key); + /** + * Set an attribute. + * + * Interceptors of same plug-in can get attributes set by this method by {@link ProfilerPluginContext#getAttribute(String)} + * + * @param name attribute name + * @param value attribute value + * + * @return Previous value if the key was associated with other value. null otherwise. + */ + public Object setAttribute(String name, Object value); + + /** + * Get an attribute value with given name. + * + * @param name attribute name + * @return value value associated with given name. null if no value is set. + */ + public Object getAttribute(String name); + /** + * Get a {@link ClassEditorBuilder}. + * + * By using returned {@link ClassEditorBuilder} you can create a {@link ClassEditor} easily. + * You have to register resulting {@link ClasEditor} by {@link #addClassEditor(ClassEditor)} to make it works. + * + * @param targetClassName target class name + * @return {@link ClassEditorBuilder} + */ public ClassEditorBuilder getClassEditorBuilder(String targetClassName); + /** + * Add a {@link ClassEditor} to Pinpoint agent. + * + * @param classEditor + */ public void addClassEditor(ClassEditor classEditor); + + /** + * Add a {@link ApplicationTypeDetector} to Pinpoint agent. + * + * @param detectors + */ public void addApplicationTypeDetector(ApplicationTypeDetector... detectors); } diff --git a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Scope.java b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Scope.java index 67accb685..2da920f45 100644 --- a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Scope.java +++ b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Scope.java @@ -20,11 +20,27 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** + * Indicates that the annotated {@link Interceptor} should in a scope. + * + * Scope is used to prevent handling same task twice. + * + * Once a transaction entered a scope S by entering a method m() which is intercepted by an interceptor I scoped by S, + * the interceptor I's before() is executed normally but all the other interceptors encounterd afterward within the same scope S are skipped + * until the interceptor I's after() is executed. + * + * For example, if an interceptor I intecept method a() which invokes itself recusively, + * interceptor I will be executed every time a() is invoked. + * To prevent this, you can put I in a scope S. + * Then I will be invoked the first time a() is invoked only. + * * @author Jongho Moon * */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface Scope { + /** + * scope name + */ public String value(); } diff --git a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Singleton.java b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Singleton.java index 0f2ad3360..9c1493510 100644 --- a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Singleton.java +++ b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Singleton.java @@ -19,12 +19,20 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +import com.navercorp.pinpoint.bootstrap.plugin.editor.ClassEditorBuilder; + /** + * Indicates that the annotated interceptor have to be singleton. + * + * For now, this annotation is applied only when a interceptor is injected by {@link com.navercorp.pinpoint.bootstrap.plugin.editor.MethodEditorBuilder MethodEditorBuilder} returned from {@link com.navercorp.pinpoint.bootstrap.plugin.editor.ClassEditorBuilder#editMethods(com.navercorp.pinpoint.bootstrap.instrument.MethodFilter) ClassEditorBuilder#editMethods(MethodFilter)}. + * If so, only one instance of the interceptor is created and that instance is injected to all the target methods of the {@link com.navercorp.pinpoint.bootstrap.plugin.editor.MethodEditorBuilder MethodEditorBuilder}. + * + * If you inject an interceptor with this annotation by other ways, every injection will create a new instance. + * * @author Jongho Moon * */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface Singleton { - public String value(); } diff --git a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/TargetConstructor.java b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/TargetConstructor.java index 6998c889c..7cbeaf038 100644 --- a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/TargetConstructor.java +++ b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/TargetConstructor.java @@ -20,11 +20,18 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** + * Specify the target constructor of the annotated interceptor. + * * @author Jongho Moon * */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface TargetConstructor { + /** + * Target constructor's parameter types. + * + * @return + */ public String[] value() default {}; } diff --git a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/TargetFilter.java b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/TargetFilter.java index bca63dbef..405d14e86 100644 --- a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/TargetFilter.java +++ b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/TargetFilter.java @@ -22,13 +22,26 @@ import java.lang.annotation.Target; import com.navercorp.pinpoint.bootstrap.instrument.MethodFilter; /** + * Specify the {@link MethodFilter} which will be used to filter the annotated interceptor's target methods. + * * @author Jongho Moon * */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface TargetFilter { + /** + * Filter type + */ public Class value(); + + /** + * Filter type + */ public Class type(); + + /** + * Arguments for specified {@link MethodFilter}'s constructor. + */ public String[] constructorArguments(); } diff --git a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/TargetMethod.java b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/TargetMethod.java index ba647151c..7965975aa 100644 --- a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/TargetMethod.java +++ b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/TargetMethod.java @@ -20,12 +20,20 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** + * Specify the target method of the annotated interceptor. * @author Jongho Moon * */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface TargetMethod { + /** + * target method name + */ String name(); + + /** + * target method parameter types + */ String[] paramTypes() default {}; } diff --git a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Targets.java b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Targets.java index bcc4741c4..4654e2dbb 100644 --- a/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Targets.java +++ b/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/plugin/Targets.java @@ -20,13 +20,26 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** + * Specify multiple targets of the annotated interceptor. + * * @author Jongho Moon * */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface Targets { + /** + * target methods + */ TargetMethod[] methods() default {}; + + /** + * target constructors + */ TargetConstructor[] constructors() default {}; + + /** + * target method filters + */ TargetFilter[] filters() default {}; } diff --git a/profiler/src/main/java/com/navercorp/pinpoint/profiler/plugin/DefaultProfilerPluginContext.java b/profiler/src/main/java/com/navercorp/pinpoint/profiler/plugin/DefaultProfilerPluginContext.java index 4afface7b..9a1185d82 100644 --- a/profiler/src/main/java/com/navercorp/pinpoint/profiler/plugin/DefaultProfilerPluginContext.java +++ b/profiler/src/main/java/com/navercorp/pinpoint/profiler/plugin/DefaultProfilerPluginContext.java @@ -122,7 +122,7 @@ public class DefaultProfilerPluginContext implements ProfilerPluginSetupContext, } @Override - public FieldAccessor getFieldSnooper(String name) { + public FieldAccessor getFieldAccessor(String name) { return fieldSnooperMap.get(name); }