Support string-like access to type-strings inside method and field descriptors while minimizing allocations

Author: mcculls

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

@@ -7,7 +7,6 @@
 package datadog.instrument.classmatch;
 
 import static datadog.instrument.classmatch.InternalMatchers.descriptor;
-import static datadog.instrument.classmatch.InternalMatchers.hasFieldType;
 
 import java.util.function.IntPredicate;
 import java.util.function.Predicate;
@@ -75,7 +74,11 @@ default FieldMatcher type(Class<?> type) {
    * @return matcher of fields with a matching type
    */
   default FieldMatcher type(TypeMatcher typeMatcher) {
-    return and(f -> hasFieldType(f, typeMatcher));
+    return and(
+        f -> {
+          TypeString fieldType = f.typeString();
+          return fieldType != null && typeMatcher.test(fieldType);
+        });
   }
 
   /**

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

@@ -6,6 +6,8 @@
 
 package datadog.instrument.classmatch;
 
+import javax.annotation.Nullable;
+
 /** Outlines a field; access modifiers, field name, descriptor. */
 public final class FieldOutline {
 
@@ -23,4 +25,25 @@ public final class FieldOutline {
     this.fieldName = fieldName;
     this.descriptor = descriptor;
   }
+
+  /** Lazy cache of the field's type-string hash. */
+  private int typeStringHash;
+
+  /**
+   * Provides a {@link TypeString} of the field type for hierarchy matching purposes.
+   *
+   * @return type-string; {@code null} if the field type is primitive or an array
+   */
+  @Nullable
+  TypeString typeString() {
+    if (descriptor.charAt(0) != 'L') {
+      return null; // don't create type-strings for primitive/array types
+    }
+    int start = 1;
+    int end = descriptor.length() - 1;
+    if (typeStringHash == 0) {
+      typeStringHash = TypeString.computeHash(descriptor, start, end);
+    }
+    return new TypeString(descriptor, start, end, typeStringHash);
+  }
 }

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

@@ -54,41 +54,6 @@ static boolean hasParamDescriptor(MethodOutline method, int paramIndex, String p
         && method.descriptor.startsWith(paramDescriptor, boundaries[paramIndex - 1]);
   }
 
-  /** Does the method's descriptor contain a matching parameter type at the given index? */
-  static boolean hasParamType(MethodOutline method, int paramIndex, TypeMatcher typeMatcher) {
-    // boundaries covers start of second parameter, to start of return descriptor
-    int[] boundaries = method.descriptorBoundaries();
-    if (paramIndex >= boundaries.length) { // ignore return descriptor boundary
-      return false;
-    }
-    // first parameter always starts at 1, for the rest check the boundary list
-    int from = paramIndex == 0 ? 1 : boundaries[paramIndex - 1];
-    String descriptor = method.descriptor;
-    // extract type from "L...;" descriptor string, ignore primitive/array types
-    return descriptor.charAt(from) == 'L'
-        && typeMatcher.test(descriptor.substring(from + 1, boundaries[paramIndex] - 1));
-  }
-
-  /** Does the method's descriptor contain a matching return type? */
-  static boolean hasReturnType(MethodOutline method, TypeMatcher typeMatcher) {
-    // boundaries covers start of second parameter, to start of return descriptor
-    int[] boundaries = method.descriptorBoundaries();
-    // return type starts at 2 if no parameters, otherwise check last boundary
-    int from = boundaries.length == 0 ? 2 : boundaries[boundaries.length - 1];
-    String descriptor = method.descriptor;
-    // extract type from "L...;" descriptor string, ignore primitive/array types
-    return descriptor.charAt(from) == 'L'
-        && typeMatcher.test(descriptor.substring(from + 1, descriptor.length() - 1));
-  }
-
-  /** Does the field's descriptor contain a matching type? */
-  static boolean hasFieldType(FieldOutline field, TypeMatcher typeMatcher) {
-    String descriptor = field.descriptor;
-    // extract type from "L...;" descriptor string, ignore primitive/array types
-    return descriptor.charAt(0) == 'L'
-        && typeMatcher.test(descriptor.substring(1, descriptor.length() - 1));
-  }
-
   /** Returns the descriptor for the given type. */
   static String descriptor(String type) {
     if (type.endsWith("[]")) {

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

@@ -13,8 +13,6 @@
 import static datadog.instrument.classmatch.InternalMatchers.declaresAnnotationOneOf;
 import static datadog.instrument.classmatch.InternalMatchers.descriptor;
 import static datadog.instrument.classmatch.InternalMatchers.hasParamDescriptor;
-import static datadog.instrument.classmatch.InternalMatchers.hasParamType;
-import static datadog.instrument.classmatch.InternalMatchers.hasReturnType;
 import static java.util.Arrays.asList;
 
 import java.util.Collection;
@@ -101,7 +99,7 @@ default MethodMatcher parameters(int paramCount) {
     if (paramCount == 0) {
       return noParameters();
     } else {
-      return and(m -> m.descriptorBoundaries().length == paramCount);
+      return and(m -> m.parameterCount() == paramCount);
     }
   }
 
@@ -175,7 +173,11 @@ default MethodMatcher parameter(int paramIndex, Class<?> paramType) {
    * @return matcher of methods with a matching parameter type
    */
   default MethodMatcher parameter(int paramIndex, TypeMatcher typeMatcher) {
-    return and(m -> hasParamType(m, paramIndex, typeMatcher));
+    return and(
+        m -> {
+          TypeString paramType = m.parameterTypeString(paramIndex);
+          return paramType != null && typeMatcher.test(paramType);
+        });
   }
 
   /**
@@ -207,7 +209,11 @@ default MethodMatcher returning(Class<?> returnType) {
    * @return matcher of methods with a matching return type
    */
   default MethodMatcher returning(TypeMatcher typeMatcher) {
-    return and(m -> hasReturnType(m, typeMatcher));
+    return and(
+        m -> {
+          TypeString returnType = m.returnTypeString();
+          return returnType != null && typeMatcher.test(returnType);
+        });
   }
 
   /**

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

@@ -10,6 +10,7 @@
 
 import java.util.BitSet;
 import java.util.List;
+import javax.annotation.Nullable;
 
 /** Outlines a method; access modifiers, method name, descriptor, annotations. */
 public final class MethodOutline {
@@ -26,9 +27,6 @@ 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;
-
   /**
    * @return internal names of annotations declared on this method
    */
@@ -43,8 +41,57 @@ public List<String> annotations() {
     this.annotations = annotations;
   }
 
+  /**
+   * @return number of method parameters
+   */
+  int parameterCount() {
+    return descriptorBoundaries().length;
+  }
+
+  /**
+   * Provides a {@link TypeString} of the indexed parameter type for hierarchy matching purposes.
+   *
+   * @param paramIndex the parameter index
+   * @return type-string; {@code null} if the parameter type is primitive, an array, or missing
+   */
+  @Nullable
+  TypeString parameterTypeString(int paramIndex) {
+    int[] boundaries = descriptorBoundaries();
+    if (paramIndex >= boundaries.length) {
+      return null; // method doesn't have enough parameters to match
+    }
+    // earliest potential param type can be found at index 2 "(L...;"
+    int start = paramIndex == 0 ? 2 : boundaries[paramIndex - 1] + 1;
+    if (descriptor.charAt(start - 1) != 'L') {
+      return null; // don't create type-strings for primitive/array types
+    }
+    int end = boundaries[paramIndex] - 1;
+    return new TypeString(descriptor, start, end, getHash(paramIndex, start, end));
+  }
+
+  /**
+   * Provides a {@link TypeString} of the return type for hierarchy matching purposes.
+   *
+   * @return type-string; {@code null} if the return type is primitive, an array, or missing
+   */
+  @Nullable
+  TypeString returnTypeString() {
+    int[] boundaries = descriptorBoundaries();
+    int returnIndex = boundaries.length;
+    // earliest potential return type can be found at index 3 "()L...;"
+    int start = returnIndex == 0 ? 3 : boundaries[returnIndex - 1] + 1;
+    if (descriptor.charAt(start - 1) != 'L') {
+      return null; // don't create type-strings for primitive/array/void types
+    }
+    int end = descriptor.length() - 1;
+    return new TypeString(descriptor, start, end, getHash(returnIndex, start, end));
+  }
+
   private static final int[] NO_BOUNDARIES = {};
 
+  /** Lazy cache of boundaries between each parameter/return descriptor. */
+  private int[] descriptorBoundaries;
+
   /**
    * Returns the boundaries between each parameter/return descriptor in the method descriptor.
    *
@@ -101,4 +148,20 @@ private static int[] parseBoundaries(String descriptor) {
     }
     return boundaries;
   }
+
+  /** Lazy cache of hashes for each parameter/return type-string. */
+  private int[] typeStringHashes;
+
+  /** Gets a previously cached {@link TypeString} hash; otherwise computes and caches a new hash. */
+  private int getHash(int typeStringIndex, int start, int end) {
+    if (typeStringHashes == null) {
+      // allow for one hash per parameter, plus one for return type
+      typeStringHashes = new int[descriptorBoundaries.length + 1];
+    }
+    int hash = typeStringHashes[typeStringIndex];
+    if (hash == 0) {
+      typeStringHashes[typeStringIndex] = hash = TypeString.computeHash(descriptor, start, end);
+    }
+    return hash;
+  }
 }

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

@@ -6,11 +6,35 @@
 
 package datadog.instrument.classmatch;
 
+import static datadog.instrument.classmatch.InternalMatchers.internalName;
+
 import java.util.function.Predicate;
 
 /** Fluent-API for building type hierarchy predicates. */
 public interface TypeMatcher extends Predicate<CharSequence> {
 
+  /**
+   * Matches when the type starts with the given prefix.
+   *
+   * @param prefix the expected prefix
+   * @return matcher of types starting with the prefix
+   */
+  static TypeMatcher typeStartsWith(String prefix) {
+    String internalPrefix = internalName(prefix);
+    return cs -> TypeString.startsWith(cs, internalPrefix);
+  }
+
+  /**
+   * Matches when the type ends with the given suffix.
+   *
+   * @param suffix the expected suffix
+   * @return matcher of types ending with the suffix
+   */
+  static TypeMatcher typeEndsWith(String suffix) {
+    String internalSuffix = internalName(suffix);
+    return cs -> TypeString.endsWith(cs, internalSuffix);
+  }
+
   /**
    * Conjunction of this matcher AND another.
    *

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

@@ -0,0 +1,114 @@
+/*
+ * Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2025-Present Datadog, Inc.
+ */
+
+package datadog.instrument.classmatch;
+
+/**
+ * Provides {@link String}-like access to type-strings inside method and field descriptors without
+ * allocating a completely separate {@link String}. Hashes are precomputed because type-strings are
+ * expected to be used as lookup keys; it also makes the hashes easier to cache and re-use.
+ */
+final class TypeString implements CharSequence {
+
+  private final String descriptor;
+  private final int offset;
+  private final int len;
+  private final int hash;
+
+  /**
+   * Computes the {@link String}-hash for part of the descriptor.
+   *
+   * @param descriptor the field/method descriptor
+   * @param start the start index
+   * @param end the end index
+   * @return string-hash for the selected range
+   */
+  static int computeHash(String descriptor, int start, int end) {
+    int h = 0;
+    for (int i = start; i < end; i++) {
+      h = 31 * h + descriptor.charAt(i);
+    }
+    return h;
+  }
+
+  /**
+   * Creates a {@link TypeString} window onto a field or method descriptor.
+   *
+   * @param descriptor the field/method descriptor
+   * @param start the start index
+   * @param end the end index
+   * @param hash the computed hash
+   */
+  TypeString(String descriptor, int start, int end, int hash) {
+    this.descriptor = descriptor;
+    this.offset = start;
+    this.len = end - start;
+    this.hash = hash;
+  }
+
+  @Override
+  public int length() {
+    return len;
+  }
+
+  @Override
+  public char charAt(int index) {
+    return descriptor.charAt(offset + index);
+  }
+
+  @Override
+  public CharSequence subSequence(int start, int end) {
+    throw new UnsupportedOperationException("Partial TypeStrings not allowed");
+  }
+
+  @Override
+  public int hashCode() {
+    return hash;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (o instanceof CharSequence) {
+      CharSequence cs = (CharSequence) o;
+      if (len != cs.length()) {
+        return false;
+      }
+      for (int i = offset, j = 0; j < len; i++, j++) {
+        if (descriptor.charAt(i) != cs.charAt(j)) {
+          return false;
+        }
+      }
+      return true;
+    } else {
+      return false;
+    }
+  }
+
+  @Override
+  public String toString() {
+    return descriptor.substring(offset, offset + len);
+  }
+
+  /** Avoids string allocation if the char sequence being tested is a {@link TypeString}. */
+  static boolean startsWith(CharSequence cs, String prefix) {
+    if (cs instanceof TypeString) {
+      TypeString ts = (TypeString) cs;
+      return ts.descriptor.startsWith(prefix, ts.offset);
+    } else {
+      return cs.toString().startsWith(prefix);
+    }
+  }
+
+  /** Avoids string allocation if the char sequence being tested is a {@link TypeString}. */
+  static boolean endsWith(CharSequence cs, String suffix) {
+    if (cs instanceof TypeString) {
+      TypeString ts = (TypeString) cs;
+      return ts.descriptor.startsWith(suffix, (ts.offset + ts.len) - suffix.length());
+    } else {
+      return cs.toString().endsWith(suffix);
+    }
+  }
+}