[Backport 8.19] add Java language examples (#4580)

Makefile

@@ -74,6 +74,10 @@ generate-language-examples:
 	@node docs/examples/generate-language-examples.js
 	@npm run format:fix-examples --prefix compiler
 
+generate-language-examples-with-java:
+	@node docs/examples/generate-language-examples.js java
+	@npm run format:fix-examples --prefix compiler
+
 lint-docs: ## Lint the OpenAPI documents after overlays
 	@npx @redocly/cli lint "output/openapi/elasticsearch-*.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
 

docs/examples/generate-language-examples.js

@@ -21,6 +21,8 @@ const fs = require('fs');
 const path = require('path');
 const { parseDocument: yamlParseDocument } = require('yaml');
 const { convertRequests, loadSchema } = require('@elastic/request-converter');
+const {parseRequest} = require("@elastic/request-converter/dist/parse");
+const {JavaCaller} = require("java-caller");
 
 const LANGUAGES = ['Python', 'JavaScript', 'Ruby', 'PHP', 'curl'];
 
@@ -44,6 +46,50 @@ async function generateLanguages(example) {
     });
   }
   data.alternatives = alternatives.concat((data.alternatives ?? []).filter(pair => !LANGUAGES.includes(pair.language)));
+
+  // specific java example generator
+  if (process.argv[2] === "java") {
+    const partialRequest = await parseRequest(request);
+    const java = new JavaCaller({
+      minimumJavaVersion: 21,
+      jar: "path/to/converter/jar/java-es-request-converter-1.0-SNAPSHOT.jar",
+    });
+
+    let correctParams = getCodeGenParamNames(partialRequest.params, partialRequest.request);
+    let body = partialRequest.body;
+    if (!body) {
+      body = {}
+    }
+
+    let javaReqs = [];
+    const javaParsedRequest = {
+      api: partialRequest.api,
+      params: correctParams,
+      query: partialRequest.query,
+      body: body,
+    };
+    javaReqs.push(javaParsedRequest)
+
+    let args = [];
+    args.push(JSON.stringify(javaReqs));
+
+    const {status, stdout, stderr} = await java.run(args);
+    if (status) {
+      console.log(stderr);
+      console.log(JSON.stringify(javaReqs));
+    }
+    else {
+      const alternative_java = [];
+      alternative_java.push({
+        language: "Java",
+        code: stdout,
+      });
+      // replace old java examples
+      data.alternatives = data.alternatives.filter(pair => pair.language !== "Java");
+      data.alternatives = data.alternatives.concat(alternative_java);
+    }
+  }
+
   doc.delete('alternatives');
   doc.add(doc.createPair('alternatives', data.alternatives));
   await fs.promises.writeFile(example, doc.toString({lineWidth: 132}));
@@ -61,6 +107,23 @@ async function* walkExamples(dir) {
   }
 }
 
+function getCodeGenParamNames(
+    params,
+    request,
+){
+  for (const [key, value] of Object.entries(params)) {
+    if (request?.path) {
+      for (const prop of request.path) {
+        if (prop.name === key && prop.codegenName !== undefined) {
+          delete params[key];
+          params[prop.codegenName] = value;
+        }
+      }
+    }
+  }
+  return params;
+}
+
 async function main() {
   let count = 0;
   let errors = 0;

docs/examples/package.json

@@ -6,6 +6,7 @@
     "@elastic/request-converter": "^9.1.1",
     "@redocly/cli": "^1.34.3",
     "@stoplight/spectral-cli": "^6.14.2",
-    "yaml": "^2.8.0"
+    "yaml": "^2.8.0",
+    "java-caller": "^4.1.1"
   }
 }

specification/_global/clear_scroll/examples/request/ClearScrollRequestExample1.yaml

@@ -35,3 +35,8 @@ alternatives:
     code:
       'curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"scroll_id":"DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ=="}'' "$ELASTICSEARCH_URL/_search/scroll"'
+  - language: Java
+    code: |
+      client.clearScroll(c -> c
+          .scrollId("DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==")
+      );

specification/_global/close_point_in_time/examples/request/ClosePointInTimeRequestExample1.yaml

@@ -36,3 +36,8 @@ alternatives:
       "curl -X DELETE -H \"Authorization: ApiKey $ELASTIC_API_KEY\" -H \"Content-Type: application/json\" -d
       '{\"id\":\"46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAA\
       AAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==\"}' \"$ELASTICSEARCH_URL/_pit\""
+  - language: Java
+    code: >
+      client.closePointInTime(c -> c
+          .id("46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==")
+      );

specification/_global/count/examples/request/CountRequestExample1.yaml

@@ -59,3 +59,14 @@ alternatives:
     code:
       'curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"query":{"term":{"user.id":"kimchy"}}}'' "$ELASTICSEARCH_URL/my-index-000001/_count"'
+  - language: Java
+    code: |
+      client.count(c -> c
+          .index("my-index-000001")
+          .query(q -> q
+              .term(t -> t
+                  .field("user.id")
+                  .value(FieldValue.of("kimchy"))
+              )
+          )
+      );

specification/_global/create/examples/request/CreateRequestExample1.yaml

@@ -69,3 +69,10 @@ alternatives:
       'curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"@timestamp":"2099-11-15T13:12:00","message":"GET /search HTTP/1.1 200 1070000","user":{"id":"kimchy"}}''
       "$ELASTICSEARCH_URL/my-index-000001/_create/1"'
+  - language: Java
+    code: >
+      client.create(c -> c
+          .id("1")
+          .index("my-index-000001")
+          .document(JsonData.fromJson("{\"@timestamp\":\"2099-11-15T13:12:00\",\"message\":\"GET /search HTTP/1.1 200 1070000\",\"user\":{\"id\":\"kimchy\"}}"))
+      );

specification/_global/delete_by_query/examples/request/DeleteByQueryRequestExample1.yaml

@@ -49,3 +49,11 @@ alternatives:
     code:
       'curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"query":{"match_all":{}}}'' "$ELASTICSEARCH_URL/my-index-000001,my-index-000002/_delete_by_query"'
+  - language: Java
+    code: |
+      client.deleteByQuery(d -> d
+          .index(List.of("my-index-000001","my-index-000002"))
+          .query(q -> q
+              .matchAll(m -> m)
+          )
+      );

specification/_global/delete_by_query/examples/request/DeleteByQueryRequestExample2.yaml

@@ -64,3 +64,15 @@ alternatives:
     code:
       'curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"query":{"term":{"user.id":"kimchy"}},"max_docs":1}'' "$ELASTICSEARCH_URL/my-index-000001/_delete_by_query"'
+  - language: Java
+    code: |
+      client.deleteByQuery(d -> d
+          .index("my-index-000001")
+          .maxDocs(1L)
+          .query(q -> q
+              .term(t -> t
+                  .field("user.id")
+                  .value(FieldValue.of("kimchy"))
+              )
+          )
+      );

specification/_global/delete_by_query/examples/request/DeleteByQueryRequestExample3.yaml

@@ -91,3 +91,20 @@ alternatives:
       'curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"slice":{"id":0,"max":2},"query":{"range":{"http.response.bytes":{"lt":2000000}}}}''
       "$ELASTICSEARCH_URL/my-index-000001/_delete_by_query"'
+  - language: Java
+    code: |
+      client.deleteByQuery(d -> d
+          .index("my-index-000001")
+          .query(q -> q
+              .range(r -> r
+                  .untyped(u -> u
+                      .field("http.response.bytes")
+                      .lt(JsonData.fromJson("2000000"))
+                  )
+              )
+          )
+          .slice(s -> s
+              .id("0")
+              .max(2)
+          )
+      );

specification/_global/delete_by_query/examples/request/DeleteByQueryRequestExample4.yaml

@@ -80,3 +80,20 @@ alternatives:
       'curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"query":{"range":{"http.response.bytes":{"lt":2000000}}}}''
       "$ELASTICSEARCH_URL/my-index-000001/_delete_by_query?refresh&slices=5"'
+  - language: Java
+    code: |
+      client.deleteByQuery(d -> d
+          .index("my-index-000001")
+          .query(q -> q
+              .range(r -> r
+                  .untyped(u -> u
+                      .field("http.response.bytes")
+                      .lt(JsonData.fromJson("2000000"))
+                  )
+              )
+          )
+          .refresh(true)
+          .slices(s -> s
+              .value(5)
+          )
+      );

specification/_global/explain/examples/request/ExplainRequestExample1.yaml

@@ -63,3 +63,15 @@ alternatives:
     code:
       'curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"query":{"match":{"message":"elasticsearch"}}}'' "$ELASTICSEARCH_URL/my-index-000001/_explain/0"'
+  - language: Java
+    code: |
+      client.explain(e -> e
+          .id("0")
+          .index("my-index-000001")
+          .query(q -> q
+              .match(m -> m
+                  .field("message")
+                  .query(FieldValue.of("elasticsearch"))
+              )
+          )
+      );

specification/_global/get_script_context/examples/request/GetScriptContextRequestExample1.yaml

@@ -10,3 +10,6 @@ alternatives:
     code: $resp = $client->getScriptContext();
   - language: curl
     code: 'curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_script_context"'
+  - language: Java
+    code: |
+      client.getScriptContext();

specification/_global/get_script_languages/examples/request/GetScriptLanguagesRequestExample1.yaml

@@ -10,3 +10,6 @@ alternatives:
     code: $resp = $client->getScriptLanguages();
   - language: curl
     code: 'curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_script_language"'
+  - language: Java
+    code: |
+      client.getScriptLanguages();

specification/_global/index/examples/request/IndexRequestExample1.yaml

@@ -66,3 +66,9 @@ alternatives:
       'curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"@timestamp":"2099-11-15T13:12:00","message":"GET /search HTTP/1.1 200 1070000","user":{"id":"kimchy"}}''
       "$ELASTICSEARCH_URL/my-index-000001/_doc/"'
+  - language: Java
+    code: >
+      client.index(i -> i
+          .index("my-index-000001")
+          .document(JsonData.fromJson("{\"@timestamp\":\"2099-11-15T13:12:00\",\"message\":\"GET /search HTTP/1.1 200 1070000\",\"user\":{\"id\":\"kimchy\"}}"))
+      );

specification/_global/index/examples/request/IndexRequestExample2.yaml

@@ -69,3 +69,10 @@ alternatives:
       'curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"@timestamp":"2099-11-15T13:12:00","message":"GET /search HTTP/1.1 200 1070000","user":{"id":"kimchy"}}''
       "$ELASTICSEARCH_URL/my-index-000001/_doc/1"'
+  - language: Java
+    code: >
+      client.index(i -> i
+          .id("1")
+          .index("my-index-000001")
+          .document(JsonData.fromJson("{\"@timestamp\":\"2099-11-15T13:12:00\",\"message\":\"GET /search HTTP/1.1 200 1070000\",\"user\":{\"id\":\"kimchy\"}}"))
+      );

specification/_global/info/examples/request/RootNodeInfoRequestExample1.yaml

@@ -10,3 +10,6 @@ alternatives:
     code: $resp = $client->info();
   - language: curl
     code: 'curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/"'
+  - language: Java
+    code: |
+      client.info();

specification/_global/mget/examples/request/MultiGetRequestExample1.yaml

@@ -76,3 +76,11 @@ alternatives:
     code:
       'curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"docs":[{"_id":"1"},{"_id":"2"}]}'' "$ELASTICSEARCH_URL/my-index-000001/_mget"'
+  - language: Java
+    code: |
+      client.mget(m -> m
+          .docs(List.of(MultiGetOperation.of(mu -> mu
+                  .id("1")),MultiGetOperation.of(mu -> mu
+                  .id("2"))))
+          .index("my-index-000001")
+      );

specification/_global/mget/examples/request/MultiGetRequestExample3.yaml

@@ -110,3 +110,14 @@ alternatives:
       "curl -X GET -H \"Authorization: ApiKey $ELASTIC_API_KEY\" -H \"Content-Type: application/json\" -d
       '{\"docs\":[{\"_index\":\"test\",\"_id\":\"1\",\"stored_fields\":[\"field1\",\"field2\"]},{\"_index\":\"test\",\"_id\":\"2\",\
       \"stored_fields\":[\"field3\",\"field4\"]}]}' \"$ELASTICSEARCH_URL/_mget\""
+  - language: Java
+    code: |
+      client.mget(m -> m
+          .docs(List.of(MultiGetOperation.of(mu -> mu
+                  .id("1")
+                  .index("test")
+                  .storedFields(List.of("field1","field2"))),MultiGetOperation.of(mu -> mu
+                  .id("2")
+                  .index("test")
+                  .storedFields(List.of("field3","field4")))))
+      );

specification/_global/mget/examples/request/MultiGetRequestExample4.yaml

@@ -93,3 +93,14 @@ alternatives:
       'curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"docs":[{"_index":"test","_id":"1","routing":"key2"},{"_index":"test","_id":"2"}]}''
       "$ELASTICSEARCH_URL/_mget?routing=key1"'
+  - language: Java
+    code: |
+      client.mget(m -> m
+          .docs(List.of(MultiGetOperation.of(mu -> mu
+                  .id("1")
+                  .index("test")
+                  .routing("key2")),MultiGetOperation.of(mu -> mu
+                  .id("2")
+                  .index("test"))))
+          .routing("key1")
+      );

specification/_global/mtermvectors/examples/request/MultiTermVectorsRequestExample1.yaml

@@ -95,3 +95,13 @@ alternatives:
       'curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"docs":[{"_id":"2","fields":["message"],"term_statistics":true},{"_id":"1"}]}''
       "$ELASTICSEARCH_URL/my-index-000001/_mtermvectors"'
+  - language: Java
+    code: |
+      client.mtermvectors(m -> m
+          .docs(List.of(MultiTermVectorsOperation.of(mu -> mu
+                  .id("2")
+                  .fields("message")
+                  .termStatistics(true)),MultiTermVectorsOperation.of(mu -> mu
+                  .id("1"))))
+          .index("my-index-000001")
+      );

specification/_global/mtermvectors/examples/request/MultiTermVectorsRequestExample2.yaml

@@ -69,3 +69,9 @@ alternatives:
       'curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"ids":["1","2"],"fields":["message"],"term_statistics":true}''
       "$ELASTICSEARCH_URL/my-index-000001/_mtermvectors"'
+  - language: Java
+    code: |
+      client.mtermvectors(m -> m
+          .ids(List.of("1","2"))
+          .index("my-index-000001")
+      );

specification/_global/mtermvectors/examples/request/MultiTermVectorsRequestExample3.yaml

@@ -103,3 +103,12 @@ alternatives:
       'curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"docs":[{"_index":"my-index-000001","doc":{"message":"test test
       test"}},{"_index":"my-index-000001","doc":{"message":"Another test ..."}}]}'' "$ELASTICSEARCH_URL/_mtermvectors"'
+  - language: Java
+    code: |
+      client.mtermvectors(m -> m
+          .docs(List.of(MultiTermVectorsOperation.of(mu -> mu
+                  .index("my-index-000001")
+                  .doc(JsonData.fromJson("{\"message\":\"test test test\"}"))),MultiTermVectorsOperation.of(mu -> mu
+                  .index("my-index-000001")
+                  .doc(JsonData.fromJson("{\"message\":\"Another test ...\"}")))))
+      );

specification/_global/open_point_in_time/examples/request/OpenPointInTimeRequestExample1.yaml

@@ -31,3 +31,12 @@ alternatives:
   - language: curl
     code: 'curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY"
       "$ELASTICSEARCH_URL/my-index-000001/_pit?keep_alive=1m&allow_partial_search_results=true"'
+  - language: Java
+    code: |
+      client.openPointInTime(o -> o
+          .allowPartialSearchResults(true)
+          .index("my-index-000001")
+          .keepAlive(k -> k
+              .offset(1)
+          )
+      );

specification/_global/put_script/examples/request/PutScriptRequestExample2.yaml

@@ -56,3 +56,12 @@ alternatives:
       'curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d
       ''{"script":{"lang":"painless","source":"Math.log(_score * 2) + params[''"''"''my_modifier''"''"'']"}}''
       "$ELASTICSEARCH_URL/_scripts/my-stored-script"'
+  - language: Java
+    code: |
+      client.putScript(p -> p
+          .id("my-stored-script")
+          .script(s -> s
+              .lang("painless")
+              .source("Math.log(_score * 2) + params['my_modifier']")
+          )
+      );