Skip to content

Latest commit

 

History

History
129 lines (87 loc) · 4.73 KB

DEVELOPER_GUIDE.md

File metadata and controls

129 lines (87 loc) · 4.73 KB
Raw

Developer Guide

So you want to contribute code to the OpenSearch Java client? Excellent! We're glad you're here. Here's what you need to do.

Getting Started

Git Clone OpenSearch Repo

Fork opensearch-project/opensearch-java and clone locally, e.g. git clone https://github.com/[your username]/opensearch-java.git.

Install Prerequisites

To run the full suite of tests, download and install JDK 14. Any JDK >= 11 works.

Docker

Download and install Docker, required for running integration tests for the repo.

Build

To build the java-client:

./gradlew clean build -x test

Run Tests

Unit Tests

To run unit tests for the java-client:

./gradlew clean unitTest

Integration Tests

To run integration tests for the java-client, start an OpenSearch cluster using docker and pass the OpenSearch version:

docker-compose --project-directory .ci/opensearch build --build-arg OPENSEARCH_VERSION=1.3.0
docker-compose --project-directory .ci/opensearch up -d

Run integration tests after starting OpenSearch cluster:

./gradlew clean integrationTest

Using the Java Client

An example for using the java client in an application:

try (RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200)).build()) {
        String index = "test-index";

        // Create Client
        OpenSearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
        OpenSearchClient client = new OpenSearchClient(transport);

        // Create Index
        CreateIndexRequest createIndexRequest = new CreateIndexRequest.Builder().index(index).build();
        CreateIndexResponse createIndexResponse = client.indices().create(createIndexRequest);
        assert createIndexResponse.shardsAcknowledged();

        // Index Document
        AppData appData = new AppData(1337, "foo");

        IndexRequest<AppData> indexRequest = new IndexRequest.Builder<AppData>().index("index").id("1").document(appData).build();
        IndexResponse indexResponse = client.index(indexRequest);
        assertEquals(Result.Created, indexResponse.result());

        // Search Documents
        SearchResponse<AppData> search = client.search(b -> b.index(index), AppData.class);
        assertEquals(1, search.hits().total().value());

        // Delete Index
        DeleteIndexRequest deleteRequest = new DeleteIndexRequest.Builder().index(index).build();
        DeleteIndexResponse deleteResponse = client.indices().delete(deleteRequest);
        assert deleteResponse.shardsAcknowledged();
        }

Use an Editor

IntelliJ IDEA

When importing into IntelliJ you will need to define an appropriate JDK. The convention is that this SDK should be named "11", and the project import will detect it automatically. For more details on defining an SDK in IntelliJ please refer to this documentation. Note that SDK definitions are global, so you can add the JDK from any project, or after project import. Importing with a missing JDK will still work, IntelliJ will report a problem and will refuse to build until resolved.

You can import the opensearch-java project into IntelliJ IDEA as follows:

  1. Select File > Open
  2. In the subsequent dialog navigate to the root build.gradle.kts file
  3. In the subsequent dialog select Open as Project

Visual Studio Code

Follow links in the Java Tutorial to install the coding pack and extensions for Java, Gradle tasks, etc. Open the source code directory.

Java Language Formatting Guidelines

Java files in the opensearch-java codebase are formatted with the checkstyle plugin. This plugin is configured using checkstyle.xml. To run the formatting checks:

./gradlew checkstyleMain checkstyleTest

Submitting Changes

See CONTRIBUTING.