From 9738b5c54b5ca1f7f78a0cb1bc1e540aaa462f2d Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Fri, 17 Sep 2021 17:18:46 -0700 Subject: [PATCH 1/8] Finally adding new OpenSearch java client --- _clients/java-rest-high-level.md | 6 +- _clients/java.md | 101 +++++++++++++++++++++++++++++++ 2 files changed, 104 insertions(+), 3 deletions(-) create mode 100644 _clients/java.md diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index a9ed5945..5d418d3b 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -1,10 +1,10 @@ --- layout: default -title: Java high-level REST client +title: Elasticsearch OSS Java high-level REST client nav_order: 97 --- -# Java high-level REST client +# Elasticsearch OSS Java high-level REST client The Elasticsearch OSS Java high-level REST client allows you to interact with your OpenSearch clusters and indices through Java methods and data structures rather than HTTP methods and JSON. @@ -22,7 +22,7 @@ To start using the Elasticsearch OSS Java high-level REST client, ensure that yo ``` -You can now start your OpenSearch cluster. The 7.10.2 high-level REST client works with the 1.x versions of OpenSearch. +You can now start your OpenSearch cluster. The 7.10.2 Elasticsearch OSS high-level REST client works with the 1.x versions of OpenSearch. ## Sample code diff --git a/_clients/java.md b/_clients/java.md new file mode 100644 index 00000000..9d49a279 --- /dev/null +++ b/_clients/java.md @@ -0,0 +1,101 @@ +--- +layout: default +title: OpenSearch Java client +nav_order: 65 +--- + +# Java client + +The OpenSearch Java client allows you to interact with your OpenSearch clusters through Java methods and data structures rather than HTTP methods and raw JSON. For example, you can submit requests to your cluster using objects to create indices, add data to documents, or complete some other operation using the client's built-in methods. + +## Setup + +To start using the OpenSearch Java client, ensure that you have the following dependency in your project's `pom.xml` file: + +``` + + + +``` + +You can now start your OpenSearch cluster. + +## Sample code + +```java +import org.apache.http.HttpHost; +import org.apache.http.auth.AuthScope; +import org.apache.http.auth.UsernamePasswordCredentials; +import org.apache.http.client.CredentialsProvider; +import org.apache.http.impl.client.BasicCredentialsProvider; +import org.apache.http.impl.nio.client.HttpAsyncClientBuilder; +import org.opensearch.client.RestClient; +import org.opensearch.client.RestClientBuilder; +import org.opensearch.clients.base.RestClientTransport; +import org.opensearch.clients.base.Transport; +import org.opensearch.clients.json.jackson.JacksonJsonpMapper; +import org.opensearch.clients.opensearch.OpenSearchClient; +import org.opensearch.clients.opensearch._global.IndexRequest; +import org.opensearch.clients.opensearch._global.IndexResponse; +import org.opensearch.clients.opensearch._global.SearchResponse; +import org.opensearch.clients.opensearch.indices.*; +import org.opensearch.clients.opensearch.indices.put_settings.IndexSettingsBody; + +import java.io.IOException; + + +public class Main { + public static void main(String[] args) throws IOException{ + System.setProperty("javax.net.ssl.trustStore", "/full/path/to/keystore"); + System.setProperty("javax.net.ssl.trustStorePassword", password-to-keystore); + + //Only for demo purposes. Don't specify your credentials in code. + final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); + credentialsProvider.setCredentials(AuthScope.ANY, + new UsernamePasswordCredentials("admin", "admin")); + + //Initialize the client with SSL and TLS enabled + RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200, "https")). + setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() { + @Override + public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) { + return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider); + } + }).build(); + Transport transport = new RestClientTransport(restClient, new JacksonJsonpMapper()); + OpenSearchClient client = new OpenSearchClient(transport); + + //Create the index + String index = "sample-index"; + CreateRequest createIndexRequest = new CreateRequest.Builder().index(index).build(); + client.indices().create(createIndexRequest); + + //Add some settings to the index + IndexSettings indexSettings = new IndexSettings.Builder().autoExpandReplicas("0-all").build(); + IndexSettingsBody settingsBody = new IndexSettingsBody.Builder().settings(indexSettings).build(); + PutSettingsRequest putSettingsRequest = new PutSettingsRequest.Builder().index(index).value(settingsBody).build(); + client.indices().putSettings(putSettingsRequest); + + //Index some data + IndexData indexData = new IndexData("first_name", "Bruce"); + IndexRequest indexRequest = new IndexRequest.Builder().index(index).id("1").value(indexData).build(); + client.index(indexRequest); + + //Search for the document + SearchResponse searchResponse = client.search(s -> s.index(index), IndexData.class); + for (int i = 0; i< searchResponse.hits().hits().size(); i++) { + System.out.println(searchResponse.hits().hits().get(i).source()); + } + + //Delete the document + client.delete(b -> b.index(index).id("1")); + + // Delete the index + DeleteRequest deleteRequest = new DeleteRequest.Builder().index(index).build(); + DeleteResponse deleteResponse = client.indices().delete(deleteRequest); + + restClient.close(); + } +} + +``` From 9861e07d7cc57ae241ac22165fa56a00d705eddc Mon Sep 17 00:00:00 2001 From: Keith Chan <12404772+keithhc2@users.noreply.github.com> Date: Mon, 20 Sep 2021 13:18:21 -0700 Subject: [PATCH 2/8] Added quotes around keystore password --- _clients/java.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/java.md b/_clients/java.md index 9d49a279..3823d0c4 100644 --- a/_clients/java.md +++ b/_clients/java.md @@ -47,7 +47,7 @@ import java.io.IOException; public class Main { public static void main(String[] args) throws IOException{ System.setProperty("javax.net.ssl.trustStore", "/full/path/to/keystore"); - System.setProperty("javax.net.ssl.trustStorePassword", password-to-keystore); + System.setProperty("javax.net.ssl.trustStorePassword", "password-to-keystore"); //Only for demo purposes. Don't specify your credentials in code. final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); From a0590a400c08fce0a8e485d7c888a6918edab944 Mon Sep 17 00:00:00 2001 From: Keith Chan <12404772+keithhc2@users.noreply.github.com> Date: Mon, 27 Sep 2021 10:09:34 -0700 Subject: [PATCH 3/8] Added maven repo --- _clients/java.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/_clients/java.md b/_clients/java.md index 3823d0c4..06a63692 100644 --- a/_clients/java.md +++ b/_clients/java.md @@ -14,7 +14,9 @@ To start using the OpenSearch Java client, ensure that you have the following de ``` - + org.opensearch.client + opensearch-rest-client + 1.0.0 ``` From e39f18da896232e4dcdbba82ee307b7a88f06f14 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Thu, 21 Oct 2021 15:57:33 -0700 Subject: [PATCH 4/8] Hopefully this resolves the conflict --- _clients/java-rest-high-level.md | 63 ++++++++++++++++++-------------- 1 file changed, 36 insertions(+), 27 deletions(-) diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index 5d418d3b..27c1283b 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -1,28 +1,28 @@ --- layout: default -title: Elasticsearch OSS Java high-level REST client -nav_order: 97 +title: OpenSearch Java high-level REST client +nav_order: 60 --- -# Elasticsearch OSS Java high-level REST client +# OpenSearch Java high-level REST client -The Elasticsearch OSS Java high-level REST client allows you to interact with your OpenSearch clusters and indices through Java methods and data structures rather than HTTP methods and JSON. +The OpenSearch Java high-level REST client allows you to interact with your OpenSearch clusters and indices through Java methods and data structures rather than HTTP methods and JSON. You submit requests to your cluster using request objects, which allows you to create indices, add data to documents, or complete other operations with your cluster. In return, you get back response objects that have all of the available information, such as the associated index or ID, from your cluster. ## Setup -To start using the Elasticsearch OSS Java high-level REST client, ensure that you have the following dependency in your project's `pom.xml` file: +To start using the OpenSearch Java high-level REST client, ensure that you have the following dependency in your project's `pom.xml` file: ``` - org.elasticsearch.client - elasticsearch-rest-high-level-client - 7.10.2 + org.opensearch.client + opensearch-rest-high-level-client + 1.1.0 ``` -You can now start your OpenSearch cluster. The 7.10.2 Elasticsearch OSS high-level REST client works with the 1.x versions of OpenSearch. +You can now start your OpenSearch cluster. The OpenSearch 1.x high-level REST client works with the 1.x versions of OpenSearch. ## Sample code @@ -33,22 +33,21 @@ import org.apache.http.auth.UsernamePasswordCredentials; import org.apache.http.client.CredentialsProvider; import org.apache.http.impl.client.BasicCredentialsProvider; import org.apache.http.impl.nio.client.HttpAsyncClientBuilder; -import org.elasticsearch.action.admin.indices.delete.DeleteIndexRequest; -import org.elasticsearch.action.delete.DeleteRequest; -import org.elasticsearch.action.delete.DeleteResponse; -import org.elasticsearch.action.get.GetRequest; -import org.elasticsearch.action.get.GetResponse; -import org.elasticsearch.action.index.IndexRequest; -import org.elasticsearch.action.index.IndexResponse; -import org.elasticsearch.action.support.master.AcknowledgedResponse; -import org.elasticsearch.client.RequestOptions; -import org.elasticsearch.client.RestClient; -import org.elasticsearch.client.RestClientBuilder; -import org.elasticsearch.client.RestHighLevelClient; -import org.elasticsearch.client.indices.CreateIndexRequest; -import org.elasticsearch.client.indices.CreateIndexResponse; -import org.elasticsearch.common.settings.Settings; -import org.elasticsearch.common.xcontent.XContentType; +import org.opensearch.action.admin.indices.delete.DeleteIndexRequest; +import org.opensearch.action.delete.DeleteRequest; +import org.opensearch.action.delete.DeleteResponse; +import org.opensearch.action.get.GetRequest; +import org.opensearch.action.get.GetResponse; +import org.opensearch.action.index.IndexRequest; +import org.opensearch.action.index.IndexResponse; +import org.opensearch.action.support.master.AcknowledgedResponse; +import org.opensearch.client.RequestOptions; +import org.opensearch.client.RestClient; +import org.opensearch.client.RestClientBuilder; +import org.opensearch.client.RestHighLevelClient; +import org.opensearch.client.indices.CreateIndexRequest; +import org.opensearch.client.indices.CreateIndexResponse; +import org.opensearch.common.settings.Settings; import java.io.IOException; import java.util.HashMap; @@ -59,7 +58,7 @@ public class RESTClientSample { //Point to keystore with appropriate certificates for security. System.setProperty("javax.net.ssl.trustStore", "/full/path/to/keystore"); - System.setProperty("javax.net.ssl.trustStorePassword", password-to-keystore); + System.setProperty("javax.net.ssl.trustStorePassword", "password-to-keystore"); //Establish credentials to use basic authentication. //Only for demo purposes. Do not specify your credentials in code. @@ -93,7 +92,7 @@ public class RESTClientSample { HashMap mapping = new HashMap(); mapping.put("properties", ageMapping); createIndexRequest.mapping(mapping); - CreateIndexResponse createIndexResponse = client.indices().create(createIndexRequest, RequestOptions.DEFAULT + CreateIndexResponse createIndexResponse = client.indices().create(createIndexRequest, RequestOptions.DEFAULT); //Adding data to the index. IndexRequest request = new IndexRequest("custom-index"); //Add a document to the custom-index we created. @@ -122,3 +121,13 @@ public class RESTClientSample { } } ``` + +## Elasticsearch OSS Java high-level REST client + +We recommend using the OpenSearch client to connect to OpenSearch clusters, but if you must use the Elasticsearch OSS Java high-level REST client, version 7.10.2 of the Elasticsearch OSS client also works with the 1.x versions of OpenSearch. + +### Migrating to the OpenSearch Java high-level REST client + +Migrating from the Elasticsearch OSS client to the OpenSearch high-level REST client is as simple as changing your Maven dependency to one that references [OpenSearch's dependency](#setup). + +Afterward, change all references of `org.elasticsearch` to `org.opensearch`, and you're ready to start submitting requests to your OpenSearch cluster. From 6a1cc2c2763ce2f1d198540ef1e8459f6c7276bb Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Thu, 21 Oct 2021 16:34:14 -0700 Subject: [PATCH 5/8] Added note recommending new client and changed POM dependency --- _clients/java-rest-high-level.md | 5 +++-- _clients/java.md | 8 +++++--- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index 27c1283b..896484a2 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -6,9 +6,10 @@ nav_order: 60 # OpenSearch Java high-level REST client -The OpenSearch Java high-level REST client allows you to interact with your OpenSearch clusters and indices through Java methods and data structures rather than HTTP methods and JSON. +Although the OpenSearch Java high-level REST client is still usable, we recommend that you use the [OpenSearch Java client]({{site.url}}{{site.baseurl}}/clients/java/), which replaces the existing Java high-level REST client. +{: .note} -You submit requests to your cluster using request objects, which allows you to create indices, add data to documents, or complete other operations with your cluster. In return, you get back response objects that have all of the available information, such as the associated index or ID, from your cluster. +The OpenSearch Java high-level REST client lets you interact with your OpenSearch clusters and indices through Java methods and data structures rather than HTTP methods and JSON. ## Setup diff --git a/_clients/java.md b/_clients/java.md index 06a63692..ac493b8f 100644 --- a/_clients/java.md +++ b/_clients/java.md @@ -6,7 +6,9 @@ nav_order: 65 # Java client -The OpenSearch Java client allows you to interact with your OpenSearch clusters through Java methods and data structures rather than HTTP methods and raw JSON. For example, you can submit requests to your cluster using objects to create indices, add data to documents, or complete some other operation using the client's built-in methods. +The OpenSearch Java client allows you to interact with your OpenSearch clusters through Java methods and data structures rather than HTTP methods and raw JSON. + +For example, you can submit requests to your cluster using objects to create indices, add data to documents, or complete some other operation using the client's built-in methods. ## Setup @@ -15,8 +17,8 @@ To start using the OpenSearch Java client, ensure that you have the following de ``` org.opensearch.client - opensearch-rest-client - 1.0.0 + opensearch-java + 0.1.0 ``` From 62d037ae632ff126ca9126442740785f452422a4 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Thu, 21 Oct 2021 17:37:52 -0700 Subject: [PATCH 6/8] Added versioning to high-level rest and tweaked some code --- _clients/java-rest-high-level.md | 2 +- _clients/java.md | 66 ++++++++++++++++++++++++++------ 2 files changed, 56 insertions(+), 12 deletions(-) diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index 896484a2..677ef280 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -19,7 +19,7 @@ To start using the OpenSearch Java high-level REST client, ensure that you have org.opensearch.client opensearch-rest-high-level-client - 1.1.0 + {{site.opensearch_version}} ``` diff --git a/_clients/java.md b/_clients/java.md index ac493b8f..c186d794 100644 --- a/_clients/java.md +++ b/_clients/java.md @@ -24,8 +24,49 @@ To start using the OpenSearch Java client, ensure that you have the following de You can now start your OpenSearch cluster. +The following example uses credentials that come with the default OpenSearch configuration. If you're using the OpenSearch Java client with your own OpenSearch cluster, be sure to change the code to use your own credentials. + ## Sample code +This section uses a class called `IndexData`, which is a simple Java class that stores basic data and methods. For your own OpenSearch cluster, you might find that you need a more robust class to store your data. + +### IndexData class + +```java +static class IndexData { + private String firstName; + private String lastName; + + public IndexData(String firstName, String lastName) { + this.firstName = firstName; + this.lastName = lastName; + } + + public String getFirstName() { + return firstName; + } + + public void setFirstName(String firstName) { + this.firstName = firstName; + } + + public String getLastName() { + return lastName; + } + + public void setLastName(String lastName) { + this.lastName = lastName; + } + + @Override + public String toString() { + return String.format("IndexData{first name='%s', last name='%s'}", firstName, lastName); + } +} +``` + +### OpenSearch client example + ```java import org.apache.http.HttpHost; import org.apache.http.auth.AuthScope; @@ -47,25 +88,25 @@ import org.opensearch.clients.opensearch.indices.put_settings.IndexSettingsBody; import java.io.IOException; - -public class Main { - public static void main(String[] args) throws IOException{ +public class OpenSearchClientExample { + public static void main(String[] args) { + try{ System.setProperty("javax.net.ssl.trustStore", "/full/path/to/keystore"); System.setProperty("javax.net.ssl.trustStorePassword", "password-to-keystore"); //Only for demo purposes. Don't specify your credentials in code. final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); credentialsProvider.setCredentials(AuthScope.ANY, - new UsernamePasswordCredentials("admin", "admin")); + new UsernamePasswordCredentials("admin", "admin")); //Initialize the client with SSL and TLS enabled RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200, "https")). - setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() { - @Override - public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) { - return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider); - } - }).build(); + setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() { + @Override + public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) { + return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider); + } + }).build(); Transport transport = new RestClientTransport(restClient, new JacksonJsonpMapper()); OpenSearchClient client = new OpenSearchClient(transport); @@ -99,7 +140,10 @@ public class Main { DeleteResponse deleteResponse = client.indices().delete(deleteRequest); restClient.close(); + } + catch (IOException e){ + System.out.println(e.toString()); + } } } - ``` From 0d78441e768a61c9553157b609676a2e975e607a Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Fri, 22 Oct 2021 11:48:16 -0700 Subject: [PATCH 7/8] Added finally block --- _clients/java.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/_clients/java.md b/_clients/java.md index c186d794..64d887dd 100644 --- a/_clients/java.md +++ b/_clients/java.md @@ -140,10 +140,17 @@ public class OpenSearchClientExample { DeleteResponse deleteResponse = client.indices().delete(deleteRequest); restClient.close(); - } - catch (IOException e){ + } catch (IOException e){ System.out.println(e.toString()); - } + } finally { + try { + if (client != null) { + client.close(); + } + } catch (IOException e) { + System.out.println(e.toString()); + } + } } } ``` From 9022db56eb3840d75f4feb0bd7ae7829cea30292 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Fri, 22 Oct 2021 11:57:44 -0700 Subject: [PATCH 8/8] Added Gradle dependency --- _clients/java.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/_clients/java.md b/_clients/java.md index 64d887dd..22c42bbe 100644 --- a/_clients/java.md +++ b/_clients/java.md @@ -22,6 +22,15 @@ To start using the OpenSearch Java client, ensure that you have the following de ``` +If you're using Gradle, add the following dependencies to your project. + +``` +dependencies { + implementation 'org.opensearch.client:opensearch-rest-client: {{site.opensearch_version}}' + implementation 'org.opensearch.client:opensearch-java:0.1.0' +} +``` + You can now start your OpenSearch cluster. The following example uses credentials that come with the default OpenSearch configuration. If you're using the OpenSearch Java client with your own OpenSearch cluster, be sure to change the code to use your own credentials.