feat(java): add bridge to transformation on search (#4939)

shortcuts · web-flow · commit c8efa236ef86 · 2025-06-10T08:12:42.000Z
diff --git a/clients/algoliasearch-client-java/algoliasearch/src/main/java/com/algolia/ApiClient.java b/clients/algoliasearch-client-java/algoliasearch/src/main/java/com/algolia/ApiClient.java
@@ -28,7 +28,8 @@ public abstract class ApiClient implements Closeable {
 
   private final Requester requester;
   private final ExecutorService executor;
-  private AuthInterceptor authInterceptor;
+  public final ClientOptions clientOptions;
+  public AuthInterceptor authInterceptor;
 
   /** Constructs a new instance of the {@link ApiClient}. */
   protected ApiClient(
@@ -47,9 +48,9 @@ protected ApiClient(
     if (apiKey == null || apiKey.isEmpty()) {
       throw new AlgoliaRuntimeException("`apiKey` is missing.");
     }
-    final ClientOptions clientOptions = options != null ? options : new ClientOptions();
-    this.executor = clientOptions.getExecutor();
-    this.requester = clientOptions.getCustomRequester() != null
+    clientOptions = options != null ? options : new ClientOptions();
+    executor = clientOptions.getExecutor();
+    requester = clientOptions.getCustomRequester() != null
       ? clientOptions.getCustomRequester()
       : defaultRequester(appId, apiKey, clientName, clientOptions, defaultHosts, connectTimeout, readTimeout, writeTimeout);
   }
diff --git a/clients/algoliasearch-client-java/algoliasearch/src/main/java/com/algolia/internal/interceptors/AuthInterceptor.java b/clients/algoliasearch-client-java/algoliasearch/src/main/java/com/algolia/internal/interceptors/AuthInterceptor.java
@@ -23,6 +23,14 @@ public void setApiKey(String apiKey) {
     this.apiKey = apiKey;
   }
 
+  public String getApiKey() {
+    return this.apiKey;
+  }
+
+  public String getApplicationId() {
+    return this.applicationId;
+  }
+
   @Nonnull
   @Override
   public Response intercept(Chain chain) throws IOException {
diff --git a/scripts/cts/runCts.ts b/scripts/cts/runCts.ts
@@ -158,7 +158,7 @@ export async function runCts(
     assertValidReplaceAllObjectsFailed(languages.length - skip('dart'));
     assertValidReplaceAllObjectsScopes(languages.length - skip('dart'));
     assertValidWaitForApiKey(languages.length - skip('dart'));
-    assertPushMockValid(only('javascript') + only('go') + only('python'));
+    assertPushMockValid(only('javascript') + only('go') + only('python') + only('java'));
   }
   if (withBenchmarkServer) {
     printBenchmarkReport();
diff --git a/specs/search/helpers/partialUpdateObjectsWithTransformation.yml b/specs/search/helpers/partialUpdateObjectsWithTransformation.yml
@@ -5,6 +5,7 @@ method:
       - javascript
       - go
       - python
+      - java
     tags:
       - Records
     operationId: partialUpdateObjectsWithTransformation
diff --git a/specs/search/helpers/saveObjectsWithTransformation.yml b/specs/search/helpers/saveObjectsWithTransformation.yml
@@ -5,6 +5,7 @@ method:
       - javascript
       - go
       - python
+      - java
     tags:
       - Records
     operationId: saveObjectsWithTransformation
diff --git a/templates/java/api.mustache b/templates/java/api.mustache
@@ -6,6 +6,7 @@ import {{invokerPackage}}.ApiClient;
 import {{invokerPackage}}.config.ClientOptions;
 
 import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
 import javax.annotation.Nullable;
 
 import okhttp3.Call;
@@ -45,10 +46,21 @@ import java.util.Base64;
 import javax.annotation.Nonnull;
 import javax.crypto.Mac;
 import javax.crypto.spec.SecretKeySpec;
+import com.algolia.model.ingestion.PushTaskPayload;
+import com.algolia.model.ingestion.PushTaskRecords;
+import com.algolia.model.ingestion.WatchResponse;
 {{/isSearchClient}}
 
 {{#operations}}
 public class {{classname}} extends ApiClient {
+    {{#isSearchClient}}
+    private IngestionClient ingestionTransporter;
+
+    public void setTransformationRegion(String region) {
+      this.ingestionTransporter = new IngestionClient(this.authInterceptor.getApplicationId(), this.authInterceptor.getApiKey(), region, this.clientOptions);
+    }
+    {{/isSearchClient}}
+
     {{#hasRegionalHost}}
     private static final String[] allowedRegions = { {{#allowedRegions}}"{{.}}"{{^-last}},{{/-last}}{{/allowedRegions}} };
 
@@ -243,4 +255,4 @@ public class {{classname}} extends ApiClient {
 
   {{> api_helpers}}
 }
-{{/operations}}
+{{/operations}}
diff --git a/templates/java/api_helpers.mustache b/templates/java/api_helpers.mustache
@@ -653,6 +653,108 @@ public <T> List<BatchResponse> chunkedBatch(
   return chunkedBatch(indexName, objects, action, waitForTasks, 1000, requestOptions);
 }
 
+/**
+ * Helper: Similar to the `saveObjects` method but requires a Push connector
+ * (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push/)
+ * to be created first, in order to transform records before indexing them to Algolia. The
+ * `region` must have been passed to the client instantiation method.
+ *
+ * @param indexName The `indexName` to replace `objects` in.
+ * @param objects The array of `objects` to store in the given Algolia `indexName`.
+ * @throws AlgoliaRetryException When the retry has failed on all hosts
+ * @throws AlgoliaApiException When the API sends an http error code
+ * @throws AlgoliaRuntimeException When an error occurred during the serialization
+ */
+public <T> WatchResponse saveObjectsWithTransformation(String indexName, Iterable<T> objects) {
+  return saveObjectsWithTransformation(indexName, objects, null);
+}
+
+/**
+ * Helper: Similar to the `saveObjects` method but requires a Push connector
+ * (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push/)
+ * to be created first, in order to transform records before indexing them to Algolia. The
+ * `region` must have been passed to the client instantiation method.
+ *
+ * @param indexName The `indexName` to replace `objects` in.
+ * @param objects The array of `objects` to store in the given Algolia `indexName`.
+ * @param requestOptions The requestOptions to send along with the query, they will be merged with
+ *     the transporter requestOptions. (optional)
+ */
+public <T> WatchResponse saveObjectsWithTransformation(String indexName, Iterable<T> objects, RequestOptions requestOptions) {
+  return saveObjectsWithTransformation(indexName, objects, false, requestOptions);
+}
+
+/**
+ * Helper: Similar to the `saveObjects` method but requires a Push connector
+ * (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push/)
+ * to be created first, in order to transform records before indexing them to Algolia. The
+ * `region` must have been passed to the client instantiation method.
+ *
+ * @param indexName The `indexName` to replace `objects` in.
+ * @param objects The array of `objects` to store in the given Algolia `indexName`.
+ * @param waitForTasks - Whether or not we should wait until every `batch` tasks has been
+ *     processed, this operation may slow the total execution time of this method but is more
+ *     reliable.
+ * @param requestOptions The requestOptions to send along with the query, they will be merged with
+ *     the transporter requestOptions. (optional)
+ */
+public <T> WatchResponse saveObjectsWithTransformation(
+  String indexName,
+  Iterable<T> objects,
+  boolean waitForTasks,
+  RequestOptions requestOptions
+) {
+  return saveObjectsWithTransformation(indexName, objects, waitForTasks, 1000, requestOptions);
+}
+
+/**
+ * Helper: Similar to the `saveObjects` method but requires a Push connector
+ * (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push/)
+ * to be created first, in order to transform records before indexing them to Algolia. The
+ * `region` must have been passed to the client instantiation method.
+ *
+ * @param indexName The `indexName` to replace `objects` in.
+ * @param objects The array of `objects` to store in the given Algolia `indexName`.
+ * @param waitForTasks - Whether or not we should wait until every `batch` tasks has been
+ *     processed, this operation may slow the total execution time of this method but is more
+ *     reliable.
+ * @param batchSize The size of the chunk of `objects`. The number of `batch` calls will be equal
+ *     to `length(objects) / batchSize`.
+ * @param requestOptions The requestOptions to send along with the query, they will be merged with
+ *     the transporter requestOptions. (optional)
+ */
+public <T> WatchResponse saveObjectsWithTransformation(
+  String indexName,
+  Iterable<T> objects,
+  boolean waitForTasks,
+  int batchSize,
+  RequestOptions requestOptions
+) {
+  if (this.ingestionTransporter == null) {
+    throw new AlgoliaRuntimeException("`setTransformationRegion` must have been called before calling this method.");
+  }
+
+  return this.ingestionTransporter.push(
+      indexName,
+      new PushTaskPayload().setAction(com.algolia.model.ingestion.Action.ADD_OBJECT).setRecords(this.objectsToPushTaskRecords(objects)),
+      waitForTasks,
+      requestOptions
+    );
+}
+
+private <T> List<PushTaskRecords> objectsToPushTaskRecords(Iterable<T> objects) {
+    try {
+        ObjectMapper mapper = new ObjectMapper();
+        String json = mapper.writeValueAsString(objects);
+
+        return mapper.readValue(json, new TypeReference<List<PushTaskRecords>>() {});
+    } catch (Exception e) {
+      throw new AlgoliaRuntimeException(
+        "each object must have an `objectID` key in order to be used with the" + " WithTransformation methods"
+      );
+    }
+}
+
 /**
  * Helper: Saves the given array of objects in the given index. The `chunkedBatch` helper is used
  * under the hood, which creates a `batch` requests with at most 1000 objects in it.
@@ -777,6 +879,114 @@ public List<BatchResponse> deleteObjects(String indexName, List<String> objectID
   return chunkedBatch(indexName, objects, Action.DELETE_OBJECT, waitForTasks, batchSize, requestOptions);
 }
 
+/**
+ * Helper: Similar to the `partialUpdateObjects` method but requires a Push connector
+ * (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push/)
+ * to be created first, in order to transform records before indexing them to Algolia. The
+ * `region` must have been passed to the client instantiation method.
+ *
+ * @param indexName The `indexName` to update `objects` in.
+ * @param objects The array of `objects` to update in the given Algolia `indexName`.
+ * @param createIfNotExists To be provided if non-existing objects are passed, otherwise, the call
+ *     will fail.
+ */
+public <T> WatchResponse partialUpdateObjectsWithTransformation(String indexName, Iterable<T> objects, boolean createIfNotExists) {
+  return partialUpdateObjectsWithTransformation(indexName, objects, createIfNotExists, false, null);
+}
+
+/**
+ * Helper: Similar to the `partialUpdateObjects` method but requires a Push connector
+ * (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push/)
+ * to be created first, in order to transform records before indexing them to Algolia. The
+ * `region` must have been passed to the client instantiation method.
+ *
+ * @param indexName The `indexName` to update `objects` in.
+ * @param objects The array of `objects` to update in the given Algolia `indexName`.
+ * @param createIfNotExists To be provided if non-existing objects are passed, otherwise, the call
+ *     will fail.
+ * @param waitForTasks - Whether or not we should wait until every `batch` tasks has been
+ *     processed, this operation may slow the total execution time of this method but is more
+ *     reliable.
+ */
+public <T> WatchResponse partialUpdateObjectsWithTransformation(
+  String indexName,
+  Iterable<T> objects,
+  boolean createIfNotExists,
+  boolean waitForTasks
+) {
+  return partialUpdateObjectsWithTransformation(indexName, objects, createIfNotExists, waitForTasks, null);
+}
+
+/**
+ * Helper: Similar to the `partialUpdateObjects` method but requires a Push connector
+ * (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push/)
+ * to be created first, in order to transform records before indexing them to Algolia. The
+ * `region` must have been passed to the client instantiation method.
+ *
+ * @param indexName The `indexName` to update `objects` in.
+ * @param objects The array of `objects` to update in the given Algolia `indexName`.
+ * @param createIfNotExists To be provided if non-existing objects are passed, otherwise, the call
+ *     will fail.
+ * @param waitForTasks - Whether or not we should wait until every `batch` tasks has been
+ *     processed, this operation may slow the total execution time of this method but is more
+ *     reliable.
+ * @param requestOptions The requestOptions to send along with the query, they will be merged with
+ *     the transporter requestOptions. (optional)
+ */
+public <T> WatchResponse partialUpdateObjectsWithTransformation(
+  String indexName,
+  Iterable<T> objects,
+  boolean createIfNotExists,
+  boolean waitForTasks,
+  RequestOptions requestOptions
+) {
+  return partialUpdateObjectsWithTransformation(indexName, objects, createIfNotExists, waitForTasks, 1000, null);
+}
+
+/**
+ * Helper: Similar to the `partialUpdateObjects` method but requires a Push connector
+ * (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push/)
+ * to be created first, in order to transform records before indexing them to Algolia. The
+ * `region` must have been passed to the client instantiation method.
+ *
+ * @param indexName The `indexName` to update `objects` in.
+ * @param objects The array of `objects` to update in the given Algolia `indexName`.
+ * @param createIfNotExists To be provided if non-existing objects are passed, otherwise, the call
+ *     will fail.
+ * @param waitForTasks - Whether or not we should wait until every `batch` tasks has been
+ *     processed, this operation may slow the total execution time of this method but is more
+ *     reliable.
+ * @param batchSize The size of the chunk of `objects`. The number of `batch` calls will be equal
+ *     to `length(objects) / batchSize`.
+ * @param requestOptions The requestOptions to send along with the query, they will be merged with
+ *     the transporter requestOptions. (optional)
+ */
+public <T> WatchResponse partialUpdateObjectsWithTransformation(
+  String indexName,
+  Iterable<T> objects,
+  boolean createIfNotExists,
+  boolean waitForTasks,
+  int batchSize,
+  RequestOptions requestOptions
+) {
+  if (this.ingestionTransporter == null) {
+    throw new AlgoliaRuntimeException("`setTransformationRegion` must have been called before calling this method.");
+  }
+
+  return this.ingestionTransporter.push(
+      indexName,
+      new PushTaskPayload()
+        .setAction(
+          createIfNotExists
+            ? com.algolia.model.ingestion.Action.PARTIAL_UPDATE_OBJECT
+            : com.algolia.model.ingestion.Action.PARTIAL_UPDATE_OBJECT_NO_CREATE
+        )
+        .setRecords(this.objectsToPushTaskRecords(objects)),
+      waitForTasks,
+      requestOptions
+    );
+}
+
 /**
  * Helper: Replaces object content of all the given objects according to their respective
  * `objectID` field. The `chunkedBatch` helper is used under the hood, which creates a `batch`
diff --git a/templates/java/tests/client/client.mustache b/templates/java/tests/client/client.mustache
@@ -10,6 +10,9 @@ import com.algolia.EchoInterceptor;
 import com.algolia.EchoResponse;
 import com.algolia.api.{{client}};
 import com.algolia.model.{{import}}.*;
+{{#isSearchClient}}
+import com.algolia.model.ingestion.WatchResponse;
+{{/isSearchClient}}
 import com.algolia.config.*;
 import java.util.*;
 import java.time.Duration;
diff --git a/templates/java/tests/client/createClient.mustache b/templates/java/tests/client/createClient.mustache
@@ -1 +1,2 @@
-{{^autoCreateClient}}{{client}} client = {{/autoCreateClient}}new {{client}}("{{parametersWithDataTypeMap.appId.value}}","{{parametersWithDataTypeMap.apiKey.value}}"{{#hasRegionalHost}}{{#parametersWithDataTypeMap.region}},"{{parametersWithDataTypeMap.region.value}}"{{/parametersWithDataTypeMap.region}}{{/hasRegionalHost}}{{#useEchoRequester}},withEchoRequester(){{/useEchoRequester}}{{#hasCustomHosts}},withCustomHosts(Arrays.asList({{#customHosts}}new Host("true".equals(System.getenv("CI")) ? "localhost" : "host.docker.internal", EnumSet.of(CallType.READ, CallType.WRITE), "http", {{port}}){{^-last}},{{/-last}}{{/customHosts}}), {{gzipEncoding}}){{/hasCustomHosts}});
+{{^autoCreateClient}}{{client}} client = {{/autoCreateClient}}new {{client}}("{{parametersWithDataTypeMap.appId.value}}","{{parametersWithDataTypeMap.apiKey.value}}"{{#hasRegionalHost}}{{#parametersWithDataTypeMap.region}},"{{parametersWithDataTypeMap.region.value}}"{{/parametersWithDataTypeMap.region}}{{/hasRegionalHost}}{{#useEchoRequester}},withEchoRequester(){{/useEchoRequester}}{{#hasCustomHosts}},withCustomHosts(Arrays.asList({{#customHosts}}new Host("true".equals(System.getenv("CI")) ? "localhost" : "host.docker.internal", EnumSet.of(CallType.READ, CallType.WRITE), "http", {{port}}){{^-last}},{{/-last}}{{/customHosts}}), {{gzipEncoding}}){{/hasCustomHosts}});
+{{#hasTransformationRegion}}client.setTransformationRegion("{{{transformationRegion}}}");{{/hasTransformationRegion}}

Original file line number	Diff line number	Diff line change
`@@ -158,7 +158,7 @@ export async function runCts(`
`158`	`158`	`assertValidReplaceAllObjectsFailed(languages.length - skip('dart'));`
`159`	`159`	`assertValidReplaceAllObjectsScopes(languages.length - skip('dart'));`
`160`	`160`	`assertValidWaitForApiKey(languages.length - skip('dart'));`
`161`		`- assertPushMockValid(only('javascript') + only('go') + only('python'));`
	`161`	`+ assertPushMockValid(only('javascript') + only('go') + only('python') + only('java'));`
`162`	`162`	`}`
`163`	`163`	`if (withBenchmarkServer) {`
`164`	`164`	`printBenchmarkReport();`
Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
`1`		-{{^autoCreateClient}}{{client}} client = {{/autoCreateClient}}new {{client}}("{{parametersWithDataTypeMap.appId.value}}","{{parametersWithDataTypeMap.apiKey.value}}"{{#hasRegionalHost}}{{#parametersWithDataTypeMap.region}},"{{parametersWithDataTypeMap.region.value}}"{{/parametersWithDataTypeMap.region}}{{/hasRegionalHost}}{{#useEchoRequester}},withEchoRequester(){{/useEchoRequester}}{{#hasCustomHosts}},withCustomHosts(Arrays.asList({{#customHosts}}new Host("true".equals(System.getenv("CI")) ? "localhost" : "host.docker.internal", EnumSet.of(CallType.READ, CallType.WRITE), "http", {{port}}){{^-last}},{{/-last}}{{/customHosts}}), {{gzipEncoding}}){{/hasCustomHosts}});
	`1`	+{{^autoCreateClient}}{{client}} client = {{/autoCreateClient}}new {{client}}("{{parametersWithDataTypeMap.appId.value}}","{{parametersWithDataTypeMap.apiKey.value}}"{{#hasRegionalHost}}{{#parametersWithDataTypeMap.region}},"{{parametersWithDataTypeMap.region.value}}"{{/parametersWithDataTypeMap.region}}{{/hasRegionalHost}}{{#useEchoRequester}},withEchoRequester(){{/useEchoRequester}}{{#hasCustomHosts}},withCustomHosts(Arrays.asList({{#customHosts}}new Host("true".equals(System.getenv("CI")) ? "localhost" : "host.docker.internal", EnumSet.of(CallType.READ, CallType.WRITE), "http", {{port}}){{^-last}},{{/-last}}{{/customHosts}}), {{gzipEncoding}}){{/hasCustomHosts}});
	`2`	`+{{#hasTransformationRegion}}client.setTransformationRegion("{{{transformationRegion}}}");{{/hasTransformationRegion}}`