In this example, we shall demonstrate how to make use of Elasticsearch<\/a>, a distributed free-text search and analysis database engine based on Apache Lucene<\/a>\u00a0with a simple maven<\/a>-based Java client.<\/p>\n We will be using the latest version of Elasticsearch, which is ES v6.1.2\u00a0while writing this post.\u00a0For this example we use the following technologies:<\/p>\n Elasticsearch is very well known due to its capability of communication\u00a0over RESTful APIs. This means that we will be using APIs to interact with the database along with the HTTP methods like GET, POST, PUT and DELETE. It is a highly scalable\u00a0distributed\u00a0<\/span>database which provides an excellent implementation with Apache Lucene<\/a>. Some more features about Elasticsearch are:<\/p>\n Although\u00a0Elasticsearch is a great candidate when it comes to distributed free-text search and analysis engine, it might not be the best-suited database when it comes to doing some other operations like:<\/p>\n This means that\u00a0Elasticsearch is a highly use-case based database but is an excellent one when it comes to its own domains.<\/p>\n You must have installed Java on your computer in order to proceed because maven is a Java tool. You can download\u00a0Java\u00a0here<\/a>.<\/p>\n Once you have Java installed on your system, you must install maven. You can download Maven from\u00a0here<\/a>.<\/p>\n Finally, you need to install Elasticsearch. You can download it from here<\/a> and follow the steps for your OS. Note that we will be using v6.1.2 for this lesson. Other versions might now work exactly the same way. You can verify that ES is running by opening this URL in your browser:<\/p>\n You should get a response like:<\/p>\n Note that the We will be using one of the many Maven archetypes to create a sample project for our example.\u00a0To create the project execute the following command in a directory that you will use as workspace:<\/p>\n If you are running maven for the first time, it will take a few seconds to accomplish the generate command because maven has to download all the required plugins and artifacts in order to make the generation task.<\/p>\n Notice that now, you will have a new directory with the same name as the\u00a0 To start with, we need to add appropriate Maven dependencies to our project. We will add the following dependency to our pom.xml file:<\/p>\n pom.xml<\/em><\/span><\/p>\n Find the latest Elasticsearch dependency here<\/a>. Note that we used Jackson<\/a> only as the standard JSON library for Java in our code.<\/p>\n Now, we’re ready to start building our project and add more components to it.<\/p>\n We will start by adding a very simple model in our project, a Person. Its definition will be very standard, like:<\/p>\n Person.java<\/em><\/span><\/p>\n We omitted standard getters and setters for brevity but they are necessary to be made as Jackson uses them during Serialization<\/a> and Deserialization of an Object.<\/p>\n We will use default connection parameters for making a connection with Elasticsearch. By default, ES uses two ports: 9200 and 9201.<\/p>\n Connection Parameters<\/em><\/span><\/p>\n Apart from connection configuration params, we also defined the index params above to identify where our Person data is saved.<\/p>\n As mentioned in parameters above, Elasticsearch uses two ports, 9200 and 9201. The first port, 9200 is used by the Elasticsearch Query Server<\/strong> with which we can query the database directly through the RESTful APIs. The second port, 9201 is used by the REST server<\/strong> with which external clients can connect and perform operations.<\/p>\n We will make a method to establish the connection with the Elasticsearch Database. While making a connection to the Database, we must provide both the ports because only this way, our application will be able to connect to Elasticsearch server and we will be able to perform the database operations. Here is the code to make a connection:<\/p>\n Singleton method for getting Connection Object<\/em><\/span><\/p>\n Note that we have implemented Singleton Design pattern<\/a> here so that multiple connections aren’t made for ES which saves a lot of memory.<\/p>\n Due to the presence of RestHighLevelClient<\/a>, the connection to Elasticsearch is thread-safe. The best time to initialise this connection will be at application request or when the first request is made to the client. Once this connection client is initialised, it can be used to perform any supported APIs.<\/p>\n Just like in older versions of Elasticsearch, we used TransportClient and we closed it once we were done with our queries, it is also necessary to close a connection once the Database interaction is complete with RestHighLevelClient as well. Here is how this can be done:<\/p>\n Close Connection<\/em><\/span><\/p>\n We assigned null to RestHighLevelClient object as well so that Singleton pattern can stay consistent.<\/p>\n We can insert data into the\u00a0Database by converting the keys and values to a Hashmap<\/a>. ES\u00a0Database only accepts values in the form of a HashMap.\u00a0Let’s see the code snippet on how this can be achieved:<\/p>\n POST Query<\/em><\/span><\/p>\n Above, we used Java’s UUID<\/a> class to create a unique identifier of the object as well. This way, we can control how the identifiers of an object are made.<\/p>\n Once we are done with inserting data into the\u00a0Database, we can confirm the operation by making a GET request to the\u00a0Elasticsearch Database server. Let’s see the code snippet on how this can be done:<\/p>\n GET Query<\/em><\/span><\/p>\n In this query, we just provided the main information about the object with which it can be identified, i.e., the Index, the Type and its unique identifier. Also, what we get back is actually a Map of values, as expressed by this expression:<\/p>\n Getting Map<\/em><\/span><\/p>\n It is actually the Jackson’s objectMapper which is used to convert this Map to a POJO Object which can be easily used in our program and this way, we don’t have to each key form the Map, which will be a tedious process when you can simply have a POJO object.<\/p>\n We can make an Update request to\u00a0Elasticsearch easily by first identifying the resource with its Index, Type and unique identifier. Then we can use a new HashMap object to update any number of values in the Object. Here is an example code snippet:<\/p>\n PUT Query<\/em><\/span><\/p>\n Notice what we did above in the following statement:<\/p>\n PUT Query<\/em><\/span><\/p>\n Here, we didn’t passed any specific property of the object which needs to be updated, instead, we passed complete Object JSON which will replace every key present for that Object.<\/p>\n We also checked for any possible errors through the catch statements. In a real-world application, you will want to handle these errors gracefully and make documented logs.<\/p>\n Finally, we can delete data by simply identifying the resource with its Index, Type and unique identifier.\u00a0Let’s see the code snippet on how this can be done:<\/p>\n DELETE Query<\/em><\/span><\/p>\n Again, in the DELETE Query above, we just mentioned how we can identify an object. Let’s try our application by performing all the operations we mentioned above. As this is a plain Java application, we will call each of these methods and print the operation results:<\/p>\n main() method<\/em><\/span><\/p>\n Once we run this application with the code, we will get the following output:<\/p>\n Program Output<\/em><\/span><\/p>\n Of course, the IDs can vary. Note that we closed the connection after we are done with the queries. This helps JVM to claim back the memory which was held by the ES connection.<\/p>\n In this lesson, we studied how we can use Elasticsearch along with a plain Java client which uses a REST client<\/a>. Choosing to use the REST client for making it usable in a real-world application needs to be explored with a scalable example. It is a choice we need to make while we start architecting an application.<\/p>\n Explore much more about Elasticsearch in our Elasticsearch course<\/a>.<\/p>\n This was a tutorial on ElasticSearch REST client and queries with Java where we interacted with the\u00a0Elasticsearch Database via the RESTful operations.<\/p>\n\n
\n
\n
2. Prerequisites<\/h2>\n
localhost:9200\n<\/pre>\n
{\n \"name\": \"wKUxRAO\",\n \"cluster_name\": \"elasticsearch\",\n \"cluster_uuid\": \"gvBXz7xsS5W4zlZuiADelw\",\n \"version\": {\n \"number\": \"6.1.2\",\n \"build_hash\": \"5b1fea5\",\n \"build_date\": \"2018-01-10T02:35:59.208Z\",\n \"build_snapshot\": false,\n \"lucene_version\": \"7.1.0\",\n \"minimum_wire_compatibility_version\": \"5.6.0\",\n \"minimum_index_compatibility_version\": \"5.0.0\"\n },\n \"tagline\": \"You Know, for Search\"\n}\n<\/pre>\nelasticsearch<\/code> is the default cluster name in Elasticsearch.<\/p>\n3. Project Setup<\/h2>\n
mvn archetype:generate -DgroupId=com.javacodegeeks.example -DartifactId=jcg-elasticsearch-example -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false\n<\/pre>\n
artifactId<\/code>\u00a0inside the chosen directory. Now, feel free to open the project in your favourite IDE.<\/p>\n4. Maven Dependencies<\/h2>\n
<properties>\n <elasticsearch.version>6.1.2<\/elasticsearch.version>\n <jackson.version>2.9.4<\/jackson.version>\n <java.version>1.8<\/java.version>\n<\/properties>\n\n<dependencies>\n <dependency>\n <groupId>org.elasticsearch<\/groupId>\n <artifactId>elasticsearch<\/artifactId>\n <version>${elasticsearch.version}<\/version>\n <\/dependency>\n\n <dependency>\n <groupId>org.elasticsearch.client<\/groupId>\n <artifactId>elasticsearch-rest-high-level-client<\/artifactId>\n <version>${elasticsearch.version}<\/version>\n <\/dependency>\n\n <dependency>\n <groupId>com.fasterxml.jackson.core<\/groupId>\n <artifactId>jackson-databind<\/artifactId>\n <version>${jackson.version}<\/version>\n <\/dependency>\n\n <dependency>\n <groupId>com.fasterxml.jackson.core<\/groupId>\n <artifactId>jackson-core<\/artifactId>\n <version>${jackson.version}<\/version>\n <\/dependency>\n\n <dependency>\n <groupId>junit<\/groupId>\n <artifactId>junit<\/artifactId>\n <version>3.8.1<\/version>\n <scope>test<\/scope>\n <\/dependency>\n<\/dependencies>\n<\/pre>\n5. Making Database Queries<\/h2>\n
5.1 Making a Model<\/h3>\n
public class Person {\n\n private String personId;\n private String name;\n\n \/\/standard getters and setters\n\n @Override\n public String toString() {\n return String.format(\"Person{personId='%s', name='%s'}\", \n personId, name);\n }\n}<\/pre>\n5.2 Defining Connection parameters<\/h3>\n
\/\/The config parameters for the connection\nprivate static final String HOST = \"localhost\";\nprivate static final int PORT_ONE = 9200;\nprivate static final int PORT_TWO = 9201;\nprivate static final String SCHEME = \"http\";\n\nprivate static RestHighLevelClient restHighLevelClient;\nprivate static ObjectMapper objectMapper = new ObjectMapper();\n\nprivate static final String INDEX = \"persondata\";\nprivate static final String TYPE = \"person\";<\/pre>\n
5.3 Making a connection<\/h3>\n
\/**\n * Implemented Singleton pattern here\n * so that there is just one connection at a time.\n * @return RestHighLevelClient\n *\/\nprivate static synchronized RestHighLevelClient makeConnection() {\n\n if(restHighLevelClient == null) {\n restHighLevelClient = new RestHighLevelClient(\n RestClient.builder(\n new HttpHost(HOST, PORT_ONE, SCHEME),\n new HttpHost(HOST, PORT_TWO, SCHEME)));\n }\n\n return restHighLevelClient;\n}<\/pre>\n5.4 Closing a connection<\/h3>\n
private static synchronized void closeConnection() throws IOException {\n restHighLevelClient.close();\n restHighLevelClient = null;\n}<\/pre>\n5.5 Inserting Data<\/h3>\n
private static Person insertPerson(Person person){\n person.setPersonId(UUID.randomUUID().toString());\n Map<String, Object> dataMap = new HashMap<String, Object>();\n dataMap.put(\"personId\", person.getPersonId());\n dataMap.put(\"name\", person.getName());\n IndexRequest indexRequest = new IndexRequest(INDEX, TYPE, person.getPersonId())\n .source(dataMap);\n try {\n IndexResponse response = restHighLevelClient.index(indexRequest);\n } catch(ElasticsearchException e) {\n e.getDetailedMessage();\n } catch (java.io.IOException ex){\n ex.getLocalizedMessage();\n }\n return person;\n}<\/pre>\n5.6 Making a GET request<\/h3>\n
private static Person getPersonById(String id){\n GetRequest getPersonRequest = new GetRequest(INDEX, TYPE, id);\n GetResponse getResponse = null;\n try {\n getResponse = restHighLevelClient.get(getPersonRequest);\n } catch (java.io.IOException e){\n e.getLocalizedMessage();\n }\n return getResponse != null ?\n objectMapper.convertValue(getResponse.getSourceAsMap(), Person.class) : null;\n}<\/pre>\ngetResponse.getSourceAsMap()<\/pre>\n
5.7 Updating Data<\/h3>\n
private static Person updatePersonById(String id, Person person){\n UpdateRequest updateRequest = new UpdateRequest(INDEX, TYPE, id)\n .fetchSource(true); \/\/ Fetch Object after its update\n try {\n String personJson = objectMapper.writeValueAsString(person);\n updateRequest.doc(personJson, XContentType.JSON);\n UpdateResponse updateResponse = restHighLevelClient.update(updateRequest);\n return objectMapper.convertValue(updateResponse.getGetResult().sourceAsMap(), Person.class);\n }catch (JsonProcessingException e){\n e.getMessage();\n } catch (java.io.IOException e){\n e.getLocalizedMessage();\n }\n System.out.println(\"Unable to update person\");\n return null;\n}<\/pre>\nupdateRequest.doc(personJson, XContentType.JSON);<\/pre>\n
5.8 Deleting Data<\/h3>\n
private static void deletePersonById(String id) {\n DeleteRequest deleteRequest = new DeleteRequest(INDEX, TYPE, id);\n try {\n DeleteResponse deleteResponse = restHighLevelClient.delete(deleteRequest);\n } catch (java.io.IOException e){\n e.getLocalizedMessage();\n }\n}<\/pre>\n
\n[ulp id=’lFK4fMZhpULqeQUl’]
\n <\/p>\n5.9 Running the application<\/h3>\n
public static void main(String[] args) throws IOException {\n\n makeConnection();\n\n System.out.println(\"Inserting a new Person with name Shubham...\");\n Person person = new Person();\n person.setName(\"Shubham\");\n person = insertPerson(person);\n System.out.println(\"Person inserted --> \" + person);\n\n System.out.println(\"Changing name to `Shubham Aggarwal`...\");\n person.setName(\"Shubham Aggarwal\");\n updatePersonById(person.getPersonId(), person);\n System.out.println(\"Person updated --> \" + person);\n\n System.out.println(\"Getting Shubham...\");\n Person personFromDB = getPersonById(person.getPersonId());\n System.out.println(\"Person from DB --> \" + personFromDB);\n\n System.out.println(\"Deleting Shubham...\");\n deletePersonById(personFromDB.getPersonId());\n System.out.println(\"Person Deleted\");\n\n closeConnection();\n}<\/pre>\nInserting a new Person with name Shubham...\nPerson inserted --> Person{personId='bfc5ba80-832a-4925-9b8d-525a4e420cb0', name='Shubham'}\nChanging name to `Shubham Aggarwal`...\nUnable to update person\nPerson updated --> Person{personId='bfc5ba80-832a-4925-9b8d-525a4e420cb0', name='Shubham Aggarwal'}\nGetting Shubham...\nPerson from DB -->Person{personId='bfc5ba80-832a-4925-9b8d-525a4e420cb0', name='Shubham Aggarwal'}\nDeleting Shubham...\nPerson Deleted<\/pre>\n6. Conclusion<\/h2>\n
7. Download the Complete Source Code<\/h2>\n