Java high-level REST client
DEPRECATED
The Lucenia Java high-level REST client is deprecated. Support will be removed in Lucenia version 1.0.0. We recommend switching to the Java client instead.
The Lucenia Java high-level REST client lets you interact with your Lucenia clusters and indexes through Java methods and data structures rather than HTTP methods and JSON.
Setup
To start using the Lucenia Java high-level REST client, ensure that you have the following dependency in your project’s pom.xml
file:
<dependency>
<groupId>io.lucenia.client</groupId>
<artifactId>lucenia-rest-high-level-client</artifactId>
<version></version>
</dependency>
You can now start your Lucenia cluster. The Lucenia 0.x high-level REST client works with the 0.x versions of Lucenia.
Security
Before using the REST client in your Java application, you must configure the application’s truststore to connect to the Security plugin. If you are using self-signed certificates or demo configurations, you can use the following command to create a custom truststore and add in root authority certificates.
If you’re using certificates from a trusted Certificate Authority (CA), you don’t need to configure the truststore.
keytool -import <path-to-cert> -alias <alias-to-call-cert> -keystore <truststore-name>
You can now point your Java client to the truststore and set basic authentication credentials that can access a secure cluster (refer to the sample code below on how to do so).
If you run into issues when configuring security, see common issues and troubleshoot TLS.
Sample program
This code example uses basic credentials that come with the default Lucenia configuration. If you’re using the Lucenia Java high-level REST client with your own Lucenia cluster, be sure to change the code to use your own credentials.
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 io.lucenia.action.admin.indices.delete.DeleteIndexRequest;
import io.lucenia.action.delete.DeleteRequest;
import io.lucenia.action.delete.DeleteResponse;
import io.lucenia.action.get.GetRequest;
import io.lucenia.action.get.GetResponse;
import io.lucenia.action.index.IndexRequest;
import io.lucenia.action.index.IndexResponse;
import io.lucenia.action.support.master.AcknowledgedResponse;
import io.lucenia.client.RequestOptions;
import io.lucenia.client.RestClient;
import io.lucenia.client.RestClientBuilder;
import io.lucenia.client.RestHighLevelClient;
import io.lucenia.client.indices.CreateIndexRequest;
import io.lucenia.client.indices.CreateIndexResponse;
import io.lucenia.common.settings.Settings;
import java.io.IOException;
import java.util.HashMap;
public class RESTClientSample {
public static void main(String[] args) throws IOException {
//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");
//Establish credentials to use basic authentication.
//Only for demo purposes. Don't specify your credentials in code.
final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY,
new UsernamePasswordCredentials("admin", "admin"));
//Create a client.
RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "https"))
.setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
@Override
public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider);
}
});
RestHighLevelClient client = new RestHighLevelClient(builder);
//Create a non-default index with custom settings and mappings.
CreateIndexRequest createIndexRequest = new CreateIndexRequest("custom-index");
createIndexRequest.settings(Settings.builder() //Specify in the settings how many shards you want in the index.
.put("index.number_of_shards", 4)
.put("index.number_of_replicas", 3)
);
//Create a set of maps for the index's mappings.
HashMap<String, String> typeMapping = new HashMap<String,String>();
typeMapping.put("type", "integer");
HashMap<String, Object> ageMapping = new HashMap<String, Object>();
ageMapping.put("age", typeMapping);
HashMap<String, Object> mapping = new HashMap<String, Object>();
mapping.put("properties", ageMapping);
createIndexRequest.mapping(mapping);
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.
request.id("1"); //Assign an ID to the document.
HashMap<String, String> stringMapping = new HashMap<String, String>();
stringMapping.put("message:", "Testing Java REST client");
request.source(stringMapping); //Place your content into the index's source.
IndexResponse indexResponse = client.index(request, RequestOptions.DEFAULT);
//Getting back the document
GetRequest getRequest = new GetRequest("custom-index", "1");
GetResponse response = client.get(getRequest, RequestOptions.DEFAULT);
System.out.println(response.getSourceAsString());
//Delete the document
DeleteRequest deleteDocumentRequest = new DeleteRequest("custom-index", "1"); //Index name followed by the ID.
DeleteResponse deleteResponse = client.delete(deleteDocumentRequest, RequestOptions.DEFAULT);
//Delete the index
DeleteIndexRequest deleteIndexRequest = new DeleteIndexRequest("custom-index"); //Index name.
AcknowledgedResponse deleteIndexResponse = client.indices().delete(deleteIndexRequest, RequestOptions.DEFAULT);
client.close();
}
}
Elasticsearch OSS Java high-level REST client
We recommend using the Lucenia client to connect to Lucenia 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 Lucenia.
Migrating to the Lucenia Java high-level REST client
Migrating from the Elasticsearch OSS client to the Lucenia high-level REST client is as simple as changing your Maven dependency to one that references Lucenia’s dependency.
Afterward, change all references of org.elasticsearch
or org.opensearch
to io.lucenia
, and you’re ready to start submitting requests to your Lucenia cluster.