Extend prepare API/docs across bindings

Agent-Logs-Url: https://github.com/microsoft/regorus/sessions/49ba4462-95d3-42c0-a302-db1b81df4f65

Co-authored-by: anakrish <35780660+anakrish@users.noreply.github.com>

bindings/java/com_microsoft_regorus_Engine.h

@@ -23,6 +23,14 @@ JNIEXPORT jlong JNICALL Java_com_microsoft_regorus_Engine_nativeNewEngine
 JNIEXPORT jlong JNICALL Java_com_microsoft_regorus_Engine_nativeClone
   (JNIEnv *, jclass, jlong);
 
+/*
+ * Class:     com_microsoft_regorus_Engine
+ * Method:    nativePrepare
+ * Signature: (J)V
+ */
+JNIEXPORT void JNICALL Java_com_microsoft_regorus_Engine_nativePrepare
+  (JNIEnv *, jclass, jlong);
+
 /*
  * Class:     com_microsoft_regorus_Engine
  * Method:    nativeAddPolicy

bindings/java/src/lib.rs

@@ -36,6 +36,19 @@ pub extern "system" fn Java_com_microsoft_regorus_Engine_nativeClone(
     Box::into_raw(Box::new(c)) as jlong
 }
 
+#[no_mangle]
+pub extern "system" fn Java_com_microsoft_regorus_Engine_nativePrepare(
+    env: EnvUnowned,
+    _class: JClass,
+    engine_ptr: jlong,
+) {
+    let _ = throw_err(env, |_env| {
+        let engine = unsafe { &mut *(engine_ptr as *mut Engine) };
+        engine.prepare()?;
+        Ok(())
+    });
+}
+
 #[no_mangle]
 pub extern "system" fn Java_com_microsoft_regorus_Engine_nativeSetRegoV0(
     env: EnvUnowned,

bindings/java/src/main/java/com/microsoft/regorus/Engine.java

@@ -21,6 +21,7 @@ public class Engine implements AutoCloseable, Cloneable {
     // if you update the native API.
     private static native long nativeNewEngine();
     private static native long nativeClone(long enginePtr);
+    private static native void nativePrepare(long enginePtr);
     private static native void nativeSetRegoV0(long enginePtr, boolean enable);
     private static native String nativeAddPolicy(long enginePtr, String path, String rego);
     private static native String nativeAddPolicyFromFile(long enginePtr, String path);
@@ -65,6 +66,14 @@ public class Engine implements AutoCloseable, Cloneable {
     public Engine clone() {
 	return new Engine(nativeClone(enginePtr));
     }
+
+    /**
+     * Prepares internal evaluation structures without executing a query.
+     * Optional: if skipped, first evaluation performs the same setup.
+     */
+    public void prepare() {
+        nativePrepare(enginePtr);
+    }
     
      /**
      * Enable/disable Rego v0.

bindings/java/src/test/java/com/microsoft/regorus/EngineTest.java

@@ -22,6 +22,9 @@ public class EngineTest extends TestCase
                 "package test\nmessage = concat(\", \", [input.message, data.message])"
             );
             engine.addDataJson("{\"message\":\"World!\"}");
+            engine.prepare();
+            Engine template = engine.clone();
+            template.close();
             engine.setInputJson("{\"message\":\"Hello\"}");
             resJson = engine.evalQuery("data.test.message");
         }