Implement Native Extensions

Future iterations may introduce an annotation based field mapping (ex: `@CelName('foo')`.

PiperOrigin-RevId: 904571869

Author: l46kok

common/internal/BUILD.bazel

@@ -147,3 +147,8 @@ cel_android_library(
     name = "date_time_helpers_android",
     exports = ["//common/src/main/java/dev/cel/common/internal:date_time_helpers_android"],
 )
+
+java_library(
+    name = "reflection_util",
+    exports = ["//common/src/main/java/dev/cel/common/internal:reflection_util"],
+)

common/src/main/java/dev/cel/common/internal/BUILD.bazel

@@ -398,6 +398,9 @@ java_library(
 java_library(
     name = "reflection_util",
     srcs = ["ReflectionUtil.java"],
+    tags = [
+        "alt_dep=//common/internal:reflection_util",
+    ],
     deps = [
         "//common/annotations",
     ],

common/src/main/java/dev/cel/common/internal/ReflectionUtil.java

@@ -17,6 +17,12 @@
 import dev.cel.common.annotations.Internal;
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.lang.reflect.WildcardType;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
 
 /**
  * Utility class for invoking Java reflection.
@@ -48,5 +54,68 @@ public static Object invoke(Method method, Object object, Object... params) {
     }
   }
 
+  /**
+   * Extracts the element type of a container type (List, Map, Optional, or Array). Returns the type
+   * itself if it's not a container or if generic type info is missing.
+   */
+  public static Class<?> getElementType(Class<?> type, Type genericType) {
+    if (type.isArray()) {
+      return type.getComponentType();
+    }
+
+    if (genericType instanceof ParameterizedType) {
+      Type[] args = ((ParameterizedType) genericType).getActualTypeArguments();
+      int argIndex = -1;
+
+      if (type == Optional.class || List.class.isAssignableFrom(type)) {
+        argIndex = 0;
+      } else if (Map.class.isAssignableFrom(type)) {
+        argIndex = 1;
+      }
+
+      if (argIndex >= 0 && args.length > argIndex && args[argIndex] instanceof Class<?>) {
+        return (Class<?>) args[argIndex];
+      }
+    }
+
+    return type;
+  }
+
+  /**
+   * Extracts the raw Class from a Type. Handles Class, ParameterizedType, and WildcardType (returns
+   * upper bound). Returns Object.class as fallback.
+   */
+  public static Class<?> getRawType(Type type) {
+    if (type instanceof Class<?>) {
+      return (Class<?>) type;
+    }
+    if (type instanceof ParameterizedType) {
+      return (Class<?>) ((ParameterizedType) type).getRawType();
+    }
+    if (type instanceof WildcardType) {
+      WildcardType wt = (WildcardType) type;
+      Type[] upperBounds = wt.getUpperBounds();
+      if (upperBounds.length > 0) {
+        return getRawType(upperBounds[0]);
+      }
+    }
+    return Object.class;
+  }
+
+  /**
+   * Extracts the actual type arguments from a ParameterizedType, if it has at least the expected
+   * minimum number of arguments. Returns Optional.empty() if the type is not parameterized or has
+   * fewer arguments than expected.
+   */
+  public static Optional<Type[]> getTypeArguments(Type type, int minArgs) {
+    if (type instanceof ParameterizedType) {
+      Type[] args = ((ParameterizedType) type).getActualTypeArguments();
+      if (args.length >= minArgs) {
+        return Optional.of(args);
+      }
+    }
+    return Optional.empty();
+  }
+
   private ReflectionUtil() {}
 }

extensions/BUILD.bazel

@@ -56,3 +56,8 @@ java_library(
     name = "comprehensions",
     exports = ["//extensions/src/main/java/dev/cel/extensions:comprehensions"],
 )
+
+java_library(
+    name = "native",
+    exports = ["//extensions/src/main/java/dev/cel/extensions:native"],
+)

extensions/src/main/java/dev/cel/extensions/BUILD.bazel

@@ -34,6 +34,7 @@ java_library(
         ":encoders",
         ":lists",
         ":math",
+        ":native",
         ":optional_library",
         ":protos",
         ":regex",
@@ -318,3 +319,25 @@ java_library(
         "@maven//:com_google_guava_guava",
     ],
 )
+
+java_library(
+    name = "native",
+    srcs = ["CelNativeTypesExtensions.java"],
+    tags = [
+    ],
+    deps = [
+        "//checker:checker_builder",
+        "//common/exceptions:attribute_not_found",
+        "//common/internal:reflection_util",
+        "//common/types",
+        "//common/types:type_providers",
+        "//common/values",
+        "//common/values:cel_byte_string",
+        "//common/values:cel_value",
+        "//common/values:cel_value_provider",
+        "//compiler:compiler_builder",
+        "//runtime",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+        "@maven//:com_google_guava_guava",
+    ],
+)

extensions/src/main/java/dev/cel/extensions/CelExtensions.java

@@ -15,13 +15,13 @@
 package dev.cel.extensions;
 
 import static com.google.common.collect.ImmutableSet.toImmutableSet;
-import static java.util.Arrays.stream;
 
 import com.google.common.collect.ImmutableSet;
 import com.google.common.collect.Streams;
 import com.google.errorprone.annotations.InlineMe;
 import dev.cel.common.CelOptions;
 import dev.cel.extensions.CelMathExtensions.Function;
+import java.util.EnumSet;
 import java.util.Set;
 
 /**
@@ -350,6 +350,18 @@ public static CelComprehensionsExtensions comprehensions() {
     return COMPREHENSIONS_EXTENSIONS;
   }
 
+  /**
+   * Extensions for supporting native Java types (POJOs) in CEL.
+   *
+   * <p>Refer to README.md for details on property discovery, type mapping, and limitations.
+   *
+   * <p>Note: Passing classes with unsupported types or anonymous/local classes will result in an
+   * {@link IllegalArgumentException} when the runtime is built.
+   */
+  public static CelNativeTypesExtensions nativeTypes(Class<?>... classes) {
+    return CelNativeTypesExtensions.nativeTypes(classes);
+  }
+
   /**
    * Retrieves all function names used by every extension libraries.
    *
@@ -359,18 +371,17 @@ public static CelComprehensionsExtensions comprehensions() {
    */
   public static ImmutableSet<String> getAllFunctionNames() {
     return Streams.concat(
-            stream(CelMathExtensions.Function.values())
-                .map(CelMathExtensions.Function::getFunction),
-            stream(CelStringExtensions.Function.values())
+            EnumSet.allOf(Function.class).stream().map(CelMathExtensions.Function::getFunction),
+            EnumSet.allOf(CelStringExtensions.Function.class).stream()
                 .map(CelStringExtensions.Function::getFunction),
-            stream(SetsFunction.values()).map(SetsFunction::getFunction),
-            stream(CelEncoderExtensions.Function.values())
+            EnumSet.allOf(SetsFunction.class).stream().map(SetsFunction::getFunction),
+            EnumSet.allOf(CelEncoderExtensions.Function.class).stream()
                 .map(CelEncoderExtensions.Function::getFunction),
-            stream(CelListsExtensions.Function.values())
+            EnumSet.allOf(CelListsExtensions.Function.class).stream()
                 .map(CelListsExtensions.Function::getFunction),
-            stream(CelRegexExtensions.Function.values())
+            EnumSet.allOf(CelRegexExtensions.Function.class).stream()
                 .map(CelRegexExtensions.Function::getFunction),
-            stream(CelComprehensionsExtensions.Function.values())
+            EnumSet.allOf(CelComprehensionsExtensions.Function.class).stream()
                 .map(CelComprehensionsExtensions.Function::getFunction))
         .collect(toImmutableSet());
   }