Externalize Codelabs Code

PiperOrigin-RevId: 576710296

.bazelignore

@@ -0,0 +1 @@
+codelab

codelab/BUILD.bazel

@@ -0,0 +1,14 @@
+package(
+    default_applicable_licenses = ["//:license"],
+    default_visibility = ["//codelab:__subpackages__"],
+)
+
+java_library(
+    name = "codelab",
+    exports = ["//codelab/src/main/codelab"],
+)
+
+java_library(
+    name = "solutions",
+    exports = ["//codelab/src/main/codelab/solutions"],
+)

codelab/src/main/codelab/BUILD.bazel

@@ -0,0 +1,23 @@
+package(
+    default_applicable_licenses = [
+        "//:license",
+    ],
+    default_visibility = ["//codelab:__pkg__"],
+)
+
+java_library(
+    name = "codelab",
+    srcs = glob(["*.java"]),
+    deps = [
+        "@com_google_googleapis//google/rpc/context:attribute_context_java_proto",  # unuseddeps: keep
+        "@maven//:com_google_guava_guava",  # unuseddeps: keep
+        "//common",  # unuseddeps: keep
+        "//common:compiler_common",  # unuseddeps: keep
+        "//common/types",  # unuseddeps: keep
+        "//common/types:type_providers",  # unuseddeps: keep
+        "//compiler",  # unuseddeps: keep
+        "//compiler:compiler_builder",  # unuseddeps: keep
+        "//runtime",  # unuseddeps: keep
+        #
+    ],
+)

codelab/src/main/codelab/Exercise1.java

@@ -0,0 +1,46 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package codelab;
+
+import dev.cel.common.CelAbstractSyntaxTree;
+
+/**
+ * Exercise1 evaluates a simple literal expression: "Hello, World!"
+ *
+ * <p>Compile, eval, profit!
+ */
+final class Exercise1 {
+  /**
+   * Compile the input {@code expression} and produce an AST. This method parses and type-checks the
+   * given expression to validate the syntax and type-agreement of the expression.
+   *
+   * @throws IllegalArgumentException If the expression is malformed due to syntactic or semantic
+   *     errors.
+   */
+  @SuppressWarnings("DoNotCallSuggester")
+  CelAbstractSyntaxTree compile(String expression) {
+    throw new UnsupportedOperationException("To be implemented");
+  }
+
+  /**
+   * Evaluates the compiled AST.
+   *
+   * @throws IllegalArgumentException If the compiled expression in AST fails to evaluate.
+   */
+  @SuppressWarnings("DoNotCallSuggester")
+  Object eval(CelAbstractSyntaxTree ast) {
+    throw new UnsupportedOperationException("To be implemented");
+  }
+}

codelab/src/main/codelab/Exercise2.java

@@ -0,0 +1,52 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package codelab;
+
+import dev.cel.common.CelAbstractSyntaxTree;
+import dev.cel.common.types.CelType;
+import java.util.Map;
+
+/**
+ * Exercise2 shows how to declare and use variables in expressions through two examples:
+ *
+ * <ul>
+ *   <li>Given a user supplied integer value, test whether the value is negative
+ *   <li>Given a request of type {@link com.google.rpc.context.AttributeContext.Request} determine
+ *       whether a specific auth claim is set.
+ * </ul>
+ */
+final class Exercise2 {
+
+  /**
+   * Compiles the input expression with provided variable information.
+   *
+   * @throws IllegalArgumentException If the expression is malformed due to syntactic or semantic
+   *     errors.
+   */
+  @SuppressWarnings("DoNotCallSuggester")
+  CelAbstractSyntaxTree compile(String expression, String variableName, CelType variableType) {
+    throw new UnsupportedOperationException("To be implemented");
+  }
+
+  /**
+   * Evaluates the compiled AST with the user provided parameter values.
+   *
+   * @throws IllegalArgumentException If the compiled expression in AST fails to evaluate.
+   */
+  @SuppressWarnings("DoNotCallSuggester")
+  Object eval(CelAbstractSyntaxTree ast, Map<String, ?> parameterValues) {
+    throw new UnsupportedOperationException("To be implemented");
+  }
+}

codelab/src/main/codelab/Exercise3.java

@@ -0,0 +1,53 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package codelab;
+
+import dev.cel.common.CelAbstractSyntaxTree;
+import dev.cel.common.CelValidationException;
+import dev.cel.common.types.SimpleType;
+import dev.cel.compiler.CelCompiler;
+import dev.cel.compiler.CelCompilerFactory;
+import dev.cel.runtime.CelEvaluationException;
+import dev.cel.runtime.CelRuntime;
+import dev.cel.runtime.CelRuntimeFactory;
+
+final class Exercise3 {
+
+  private static final CelCompiler CEL_COMPILER =
+      CelCompilerFactory.standardCelCompilerBuilder().setResultType(SimpleType.BOOL).build();
+  private static final CelRuntime CEL_RUNTIME =
+      CelRuntimeFactory.standardCelRuntimeBuilder().build();
+
+  /**
+   * Compiles the given expression and evaluates it.
+   *
+   * @throws IllegalArgumentException If the expression fails to compile or evaluate
+   */
+  Object compileAndEvaluate(String expression) {
+    CelAbstractSyntaxTree ast;
+    try {
+      ast = CEL_COMPILER.compile(expression).getAst();
+    } catch (CelValidationException e) {
+      throw new IllegalArgumentException("Failed to compile expression.", e);
+    }
+
+    try {
+      CelRuntime.Program program = CEL_RUNTIME.createProgram(ast);
+      return program.eval();
+    } catch (CelEvaluationException e) {
+      throw new IllegalArgumentException("Evaluation error has occurred.", e);
+    }
+  }
+}

codelab/src/main/codelab/Exercise4.java

@@ -0,0 +1,77 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package codelab;
+
+import com.google.rpc.context.AttributeContext.Request;
+import dev.cel.common.CelAbstractSyntaxTree;
+import dev.cel.common.CelValidationException;
+import dev.cel.common.types.SimpleType;
+import dev.cel.common.types.StructTypeReference;
+import dev.cel.compiler.CelCompiler;
+import dev.cel.compiler.CelCompilerFactory;
+import dev.cel.runtime.CelEvaluationException;
+import dev.cel.runtime.CelRuntime;
+import dev.cel.runtime.CelRuntimeFactory;
+import java.util.Map;
+
+/**
+ * Exercise4 demonstrates how to extend CEL with custom functions.
+ *
+ * <p>Declare a "contains" member function on map types that return a boolean indicating whether the
+ * map contains the key-value pair.
+ */
+final class Exercise4 {
+
+  /**
+   * Compiles the input expression.
+   *
+   * @throws IllegalArgumentException If the expression is malformed due to syntactic or semantic
+   *     errors.
+   */
+  CelAbstractSyntaxTree compile(String expression) {
+    CelCompiler celCompiler =
+        CelCompilerFactory.standardCelCompilerBuilder()
+            .addVar("request", StructTypeReference.create(Request.getDescriptor().getFullName()))
+            .addMessageTypes(Request.getDescriptor())
+            .setResultType(SimpleType.BOOL)
+            // Provide the custom `contains` function declaration here.
+            .build();
+
+    try {
+      return celCompiler.compile(expression).getAst();
+    } catch (CelValidationException e) {
+      throw new IllegalArgumentException("Failed to compile expression.", e);
+    }
+  }
+
+  /**
+   * Evaluates the compiled AST with the user provided parameter values.
+   *
+   * @throws IllegalArgumentException If the compiled expression in AST fails to evaluate.
+   */
+  Object eval(CelAbstractSyntaxTree ast, Map<String, ?> parameterValues) {
+    CelRuntime celRuntime =
+        CelRuntimeFactory.standardCelRuntimeBuilder()
+            // Provide the custom `contains` function implementation here.
+            .build();
+
+    try {
+      CelRuntime.Program program = celRuntime.createProgram(ast);
+      return program.eval(parameterValues);
+    } catch (CelEvaluationException e) {
+      throw new IllegalArgumentException("Evaluation error has occurred.", e);
+    }
+  }
+}

codelab/src/main/codelab/solutions/BUILD.bazel

@@ -0,0 +1,22 @@
+package(
+    default_applicable_licenses = [
+        "//:license",
+    ],
+    default_visibility = ["//codelab:__pkg__"],
+)
+
+java_library(
+    name = "solutions",
+    srcs = glob(["*.java"]),
+    deps = [
+        "//common",
+        "//common:compiler_common",
+        "//common/types",
+        "//common/types:type_providers",
+        "//compiler",
+        "//compiler:compiler_builder",
+        "//runtime",
+        "@com_google_googleapis//google/rpc/context:attribute_context_java_proto",
+        "@maven//:com_google_guava_guava",
+    ],
+)

codelab/src/main/codelab/solutions/Exercise1.java

@@ -0,0 +1,90 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package codelab.solutions;
+
+import dev.cel.common.CelAbstractSyntaxTree;
+import dev.cel.common.CelValidationException;
+import dev.cel.common.types.SimpleType;
+import dev.cel.compiler.CelCompiler;
+import dev.cel.compiler.CelCompilerFactory;
+import dev.cel.runtime.CelEvaluationException;
+import dev.cel.runtime.CelRuntime;
+import dev.cel.runtime.CelRuntimeFactory;
+
+/**
+ * Exercise1 evaluates a simple literal expression: "Hello, World!"
+ *
+ * <p>Compile, eval, profit!
+ */
+final class Exercise1 {
+  /**
+   * Compile the input {@code expression} and produce an AST. This method parses and type-checks the
+   * given expression to validate the syntax and type-agreement of the expression.
+   *
+   * @throws IllegalArgumentException If the expression is malformed due to syntactic or semantic
+   *     errors.
+   */
+  CelAbstractSyntaxTree compile(String expression) {
+    // Construct a CelCompiler instance.
+    // "String" is the expected output type for the type-checked expression
+    // CelCompiler is immutable and when statically configured can be moved to a static final
+    // member.
+    CelCompiler celCompiler =
+        CelCompilerFactory.standardCelCompilerBuilder().setResultType(SimpleType.STRING).build();
+
+    CelAbstractSyntaxTree ast;
+    try {
+      // Parse the expression
+      ast = celCompiler.parse(expression).getAst();
+    } catch (CelValidationException e) {
+      // Report syntactic errors, if present
+      throw new IllegalArgumentException(
+          "Failed to parse expression. Reason: " + e.getMessage(), e);
+    }
+
+    try {
+      // Type-check the expression for correctness
+      ast = celCompiler.check(ast).getAst();
+    } catch (CelValidationException e) {
+      // Report semantic errors, if present.
+      throw new IllegalArgumentException(
+          "Failed to type-check expression. Reason: " + e.getMessage(), e);
+    }
+    return ast;
+  }
+
+  /**
+   * Evaluates the compiled AST.
+   *
+   * @throws IllegalArgumentException If the compiled expression in AST fails to evaluate.
+   */
+  Object eval(CelAbstractSyntaxTree ast) {
+    // Construct a CelRuntime instance
+    // CelRuntime is immutable just like the compiler and can be moved to a static final member.
+    CelRuntime celRuntime = CelRuntimeFactory.standardCelRuntimeBuilder().build();
+
+    try {
+      // Plan the program
+      CelRuntime.Program program = celRuntime.createProgram(ast);
+
+      // Evaluate the program without any additional arguments.
+      return program.eval();
+    } catch (CelEvaluationException e) {
+      // Report any evaluation errors, if present
+      throw new IllegalArgumentException(
+          "Evaluation error has occurred. Reason: " + e.getMessage(), e);
+    }
+  }
+}