javadoc

Author: mcculls

class-inject/src/main/java/datadog/instrument/classinject/ClassInjector.java

@@ -49,7 +49,7 @@ public static List<Class<?>> injectBootClasses(Map<String, byte[]> bytecode) {
   }
 
   /**
-   * Injects classes using the specified class-loader.
+   * Injects classes using the given class-loader.
    *
    * @param bytecode the named bytecode to inject
    * @param cl the class-loader to use

class-match/src/main/java/datadog/instrument/classmatch/ClassFile.java

@@ -301,6 +301,7 @@ private static String utf(byte[] bytecode, int utfOffset) {
     // most class-names will be ASCII, confirm with a quick scan
     for (int u = utfStart; u < utfEnd; u++) {
       if ((bytecode[u] & 0x80) != 0) {
+        // found non-ASCII byte, prepare char array for decoding
         chars = new char[utfLen];
         break;
       }

class-match/src/main/java/datadog/instrument/classmatch/ClassHeader.java

@@ -10,7 +10,7 @@
 
 import java.util.List;
 
-/** Minimal class header that describes its access flags and immediate class hierarchy. */
+/** Minimal class header that describes its access modifiers and immediate class hierarchy. */
 public class ClassHeader {
 
   /** Access modifiers for this class. */

class-match/src/main/java/datadog/instrument/classmatch/ClassMatcher.java

@@ -23,7 +23,7 @@ public interface ClassMatcher extends Predicate<ClassOutline> {
    * Matches classes that declare a field matching the given criteria.
    *
    * @param fieldMatcher the field matcher
-   * @return matcher of classes with a field matching tbe criteria
+   * @return matcher of classes with a matching field
    */
   static ClassMatcher declares(FieldMatcher fieldMatcher) {
     return c -> anyMatch(c.fields, fieldMatcher);
@@ -32,20 +32,20 @@ static ClassMatcher declares(FieldMatcher fieldMatcher) {
   /**
    * Matches classes that declare a field matching the given criteria.
    *
-   * @param accessMatcher the access flags matcher
+   * @param accessMatcher the access matcher
    * @param fieldMatcher the field matcher
-   * @return matcher of classes with a field matching tbe criteria
+   * @return matcher of classes with a matching field
    */
   static ClassMatcher declares(IntPredicate accessMatcher, FieldMatcher fieldMatcher) {
-    FieldMatcher combinedMatcher = fieldMatcher.withAccess(accessMatcher);
+    FieldMatcher combinedMatcher = fieldMatcher.access(accessMatcher);
     return c -> anyMatch(c.fields, combinedMatcher);
   }
 
   /**
    * Matches classes that declare a method matching the given criteria.
    *
    * @param methodMatcher the method matcher
-   * @return matcher of classes with a method matching tbe criteria
+   * @return matcher of classes with a matching method
    */
   static ClassMatcher declares(MethodMatcher methodMatcher) {
     return c -> anyMatch(c.methods, methodMatcher);
@@ -54,44 +54,44 @@ static ClassMatcher declares(MethodMatcher methodMatcher) {
   /**
    * Matches classes that declare a method matching the given criteria.
    *
-   * @param accessMatcher the access flags matcher
+   * @param accessMatcher the access matcher
    * @param methodMatcher the method matcher
-   * @return matcher of classes with a method matching tbe criteria
+   * @return matcher of classes with a matching method
    */
   static ClassMatcher declares(IntPredicate accessMatcher, MethodMatcher methodMatcher) {
-    MethodMatcher combinedMatcher = methodMatcher.withAccess(accessMatcher);
+    MethodMatcher combinedMatcher = methodMatcher.access(accessMatcher);
     return c -> anyMatch(c.methods, combinedMatcher);
   }
 
   /**
-   * Matches methods annotated with the given type.
+   * Matches classes annotated with the given type.
    *
-   * @param annotation the expected annotation type
-   * @return matcher of methods annotated with the same type
+   * @param annotationType the annotation type
+   * @return matcher of classes annotated with the type
    */
-  static ClassMatcher annotatedWith(String annotation) {
-    Predicate<String[]> annotationMatcher = declaresAnnotation(annotation);
+  static ClassMatcher annotatedWith(String annotationType) {
+    Predicate<String[]> annotationMatcher = declaresAnnotation(annotationType);
     return c -> annotationMatcher.test(c.annotations);
   }
 
   /**
    * Matches classes annotated with one of the given types.
    *
-   * @param annotations the expected annotation types
-   * @return matcher of methods annotated with one of the types
+   * @param annotationTypes the annotation types
+   * @return matcher of classes annotated with one of the types
    */
-  static ClassMatcher annotatedWith(String... annotations) {
-    return annotatedWith(asList(annotations));
+  static ClassMatcher annotatedWith(String... annotationTypes) {
+    return annotatedWith(asList(annotationTypes));
   }
 
   /**
    * Matches classes annotated with one of the given types.
    *
-   * @param annotations the expected annotation types
-   * @return matcher of methods annotated with one of the types
+   * @param annotationTypes the annotation types
+   * @return matcher of classes annotated with one of the types
    */
-  static ClassMatcher annotatedWith(Collection<String> annotations) {
-    Predicate<String[]> annotationMatcher = declaresAnnotationOneOf(annotations);
+  static ClassMatcher annotatedWith(Collection<String> annotationTypes) {
+    Predicate<String[]> annotationMatcher = declaresAnnotationOneOf(annotationTypes);
     return c -> annotationMatcher.test(c.annotations);
   }
 

class-match/src/main/java/datadog/instrument/classmatch/ClassOutline.java

@@ -10,7 +10,7 @@
 
 import java.util.List;
 
-/** Outlines a class; access flags, immediate class hierarchy, field, methods, annotations. */
+/** Outlines a class; access modifiers, immediate class hierarchy, field, methods, annotations. */
 public final class ClassOutline extends ClassHeader {
 
   /** Outlines of fields declared by this class. */

class-match/src/main/java/datadog/instrument/classmatch/FieldMatcher.java

@@ -18,8 +18,8 @@ public interface FieldMatcher extends Predicate<FieldOutline> {
   /**
    * Matches fields with the given name.
    *
-   * @param name the expected name
-   * @return matcher of fields that have the same name
+   * @param name the field name
+   * @return matcher of fields with the same name
    */
   static FieldMatcher field(String name) {
     return f -> name.equals(f.fieldName);
@@ -28,18 +28,18 @@ static FieldMatcher field(String name) {
   /**
    * Matches fields with names matching the given criteria.
    *
-   * @param nameMatcher the name matcher
-   * @return matcher of fields whose name matches tbe criteria
+   * @param nameMatcher the field name matcher
+   * @return matcher of fields with a matching name
    */
   static FieldMatcher field(Predicate<String> nameMatcher) {
     return f -> nameMatcher.test(f.fieldName);
   }
 
   /**
-   * Matches fields with access flags matching the given criteria.
+   * Matches fields with access modifiers matching the given criteria.
    *
-   * @param accessMatcher the access flag matcher
-   * @return matcher of fields whose access flags match tbe criteria
+   * @param accessMatcher the access matcher
+   * @return matcher of fields with matching access
    */
   default FieldMatcher withAccess(IntPredicate accessMatcher) {
     return and(f -> accessMatcher.test(f.access));
@@ -48,8 +48,8 @@ default FieldMatcher withAccess(IntPredicate accessMatcher) {
   /**
    * Matches fields of the given type.
    *
-   * @param type the type name
-   * @return matcher of fields of the same type
+   * @param type the field type
+   * @return matcher of fields with the same type
    */
   default FieldMatcher ofType(String type) {
     String descriptor = descriptor(type);
@@ -59,8 +59,8 @@ default FieldMatcher ofType(String type) {
   /**
    * Matches fields of the given type.
    *
-   * @param type the type name
-   * @return matcher of fields of the same type
+   * @param type the field type
+   * @return matcher of fields with the same type
    */
   default FieldMatcher ofType(Class<?> type) {
     String descriptor = descriptor(type);

class-match/src/main/java/datadog/instrument/classmatch/FieldOutline.java

@@ -6,7 +6,7 @@
 
 package datadog.instrument.classmatch;
 
-/** Outlines a field; access flags, field name, descriptor. */
+/** Outlines a field; access modifiers, field name, descriptor. */
 public final class FieldOutline {
 
   /** Access modifiers for this field. */

class-match/src/main/java/datadog/instrument/classmatch/InternalMatchers.java

@@ -22,6 +22,7 @@ private InternalMatchers() {}
   /** Matches when at least one annotation has the given name. */
   static Predicate<String[]> declaresAnnotation(String name) {
     String internalName = internalName(name);
+    // note this annotation is of interest when parsing
     ClassFile.annotationOfInterest(internalName);
     // performance tip: capture this method-ref outside the lambda
     Predicate<String> annotationNamed = internalName::equals;
@@ -31,6 +32,7 @@ static Predicate<String[]> declaresAnnotation(String name) {
   /** Matches when at least one annotation has one of the given names. */
   static Predicate<String[]> declaresAnnotationOneOf(Collection<String> names) {
     Set<String> internalNames = internalNames(names);
+    // note these annotations are of interest when parsing
     ClassFile.annotationsOfInterest(internalNames);
     // performance tip: capture this method-ref outside the lambda
     Predicate<String> annotationNamedOneOf = internalNames::contains;

class-match/src/main/java/datadog/instrument/classmatch/MethodMatcher.java

@@ -33,8 +33,8 @@ static MethodMatcher method() {
   /**
    * Matches methods with the given name.
    *
-   * @param name the expected name
-   * @return matcher of methods that have the same name
+   * @param name the method name
+   * @return matcher of methods with the same name
    */
   static MethodMatcher method(String name) {
     return m -> name.equals(m.methodName);
@@ -43,8 +43,8 @@ static MethodMatcher method(String name) {
   /**
    * Matches methods with names matching the given criteria.
    *
-   * @param nameMatcher the name matcher
-   * @return matcher of methods whose name matches tbe criteria
+   * @param nameMatcher the method name matcher
+   * @return matcher of methods with a matching name
    */
   static MethodMatcher method(Predicate<String> nameMatcher) {
     return m -> nameMatcher.test(m.methodName);
@@ -69,10 +69,10 @@ static MethodMatcher staticInitializer() {
   }
 
   /**
-   * Matches methods with access flags matching the given criteria.
+   * Matches methods with access modifiers matching the given criteria.
    *
-   * @param accessMatcher the access flag matcher
-   * @return matcher of methods whose access flags match tbe criteria
+   * @param accessMatcher the access matcher
+   * @return matcher of methods with matching access
    */
   default MethodMatcher withAccess(IntPredicate accessMatcher) {
     return and(m -> accessMatcher.test(m.access));
@@ -81,7 +81,7 @@ default MethodMatcher withAccess(IntPredicate accessMatcher) {
   /**
    * Matches methods with the given parameter count.
    *
-   * @param paramCount the expected parameter count
+   * @param paramCount the parameter count
    * @return matcher of methods with the same parameter count
    */
   default MethodMatcher withParameters(int paramCount) {
@@ -91,7 +91,7 @@ default MethodMatcher withParameters(int paramCount) {
   /**
    * Matches methods with the given parameter types.
    *
-   * @param paramTypes the expected parameter types
+   * @param paramTypes the parameter types
    * @return matcher of methods with the same parameter types
    */
   default MethodMatcher withParameters(String... paramTypes) {
@@ -106,7 +106,7 @@ default MethodMatcher withParameters(String... paramTypes) {
   /**
    * Matches methods with the given parameter types.
    *
-   * @param paramTypes the expected parameter types
+   * @param paramTypes the parameter types
    * @return matcher of methods with the same parameter types
    */
   default MethodMatcher withParameters(Class<?>... paramTypes) {
@@ -121,8 +121,8 @@ default MethodMatcher withParameters(Class<?>... paramTypes) {
   /**
    * Matches methods with the given parameter type at the given position.
    *
-   * @param paramIndex the expected parameter index
-   * @param paramType the expected parameter type
+   * @param paramIndex the parameter index
+   * @param paramType the parameter type
    * @return matcher of methods with the same parameter type at the same position
    */
   default MethodMatcher withParameter(int paramIndex, String paramType) {
@@ -133,8 +133,8 @@ default MethodMatcher withParameter(int paramIndex, String paramType) {
   /**
    * Matches methods with the given parameter type at the given position.
    *
-   * @param paramIndex the expected parameter index
-   * @param paramType the expected parameter type
+   * @param paramIndex the parameter index
+   * @param paramType the parameter type
    * @return matcher of methods with the same parameter type at the same position
    */
   default MethodMatcher withParameter(int paramIndex, Class<?> paramType) {
@@ -145,7 +145,7 @@ default MethodMatcher withParameter(int paramIndex, Class<?> paramType) {
   /**
    * Matches methods returning the given type.
    *
-   * @param returnType the expected return type
+   * @param returnType the return type
    * @return matcher of methods returning the same type
    */
   default MethodMatcher returning(String returnType) {
@@ -156,7 +156,7 @@ default MethodMatcher returning(String returnType) {
   /**
    * Matches methods returning the given type.
    *
-   * @param returnType the expected return type
+   * @param returnType the return type
    * @return matcher of methods returning the same type
    */
   default MethodMatcher returning(Class<?> returnType) {
@@ -167,32 +167,32 @@ default MethodMatcher returning(Class<?> returnType) {
   /**
    * Matches methods annotated with the given type.
    *
-   * @param annotation the expected annotation type
+   * @param annotationType the annotation type
    * @return matcher of methods annotated with the same type
    */
-  default MethodMatcher annotatedWith(String annotation) {
-    Predicate<String[]> annotationMatcher = declaresAnnotation(annotation);
+  default MethodMatcher annotatedWith(String annotationType) {
+    Predicate<String[]> annotationMatcher = declaresAnnotation(annotationType);
     return and(m -> annotationMatcher.test(m.annotations));
   }
 
   /**
    * Matches methods annotated with one of the given types.
    *
-   * @param annotations the expected annotation types
+   * @param annotationTypes the annotation types
    * @return matcher of methods annotated with one of the types
    */
-  default MethodMatcher annotatedWith(String... annotations) {
-    return annotatedWith(asList(annotations));
+  default MethodMatcher annotatedWith(String... annotationTypes) {
+    return annotatedWith(asList(annotationTypes));
   }
 
   /**
    * Matches methods annotated with one of the given types.
    *
-   * @param annotations the expected annotation types
+   * @param annotationTypes the annotation types
    * @return matcher of methods annotated with one of the types
    */
-  default MethodMatcher annotatedWith(Collection<String> annotations) {
-    Predicate<String[]> annotationMatcher = declaresAnnotationOneOf(annotations);
+  default MethodMatcher annotatedWith(Collection<String> annotationTypes) {
+    Predicate<String[]> annotationMatcher = declaresAnnotationOneOf(annotationTypes);
     return and(m -> annotationMatcher.test(m.annotations));
   }
 

class-match/src/main/java/datadog/instrument/classmatch/MethodOutline.java

@@ -11,7 +11,7 @@
 import java.util.BitSet;
 import java.util.List;
 
-/** Outlines a method; access flags, method name, descriptor, annotations. */
+/** Outlines a method; access modifiers, method name, descriptor, annotations. */
 public final class MethodOutline {
 
   /** Access modifiers for this method. */
@@ -26,6 +26,7 @@ public final class MethodOutline {
   /** Internal names of annotations declared on this method. */
   final String[] annotations;
 
+  /** Lazy cache of boundaries between each parameter/return descriptor. */
   private int[] descriptorBoundaries;
 
   /**
@@ -49,6 +50,8 @@ public List<String> annotations() {
    *
    * <p>The number of boundaries is the same as the number of parameters: there is no boundary
    * before the first parameter, and the return boundary is omitted if there are no parameters.
+   * (This is to save space - the first parameter always starts at index 1; and if there are no
+   * parameters then the return descriptor always starts at index 2.)
    */
   int[] descriptorBoundaries() {
     if (descriptorBoundaries == null) {