= Java API

include::../Versions.asciidoc[]

[[java-api]]
[preface]
== Preface

deprecated[7.0.0, The `TransportClient` is deprecated in favour of the {java-rest}/java-rest-high.html[Java High Level REST Client] and will be removed in Elasticsearch 8.0. The {java-rest}/java-rest-high-level-migration.html[migration guide] describes all the steps needed to migrate.]

This section describes the Java API that Elasticsearch provides. All
Elasticsearch operations are executed using a
<<client,Client>> object. All
operations are completely asynchronous in nature (either accepts a
listener, or returns a future).

Additionally, operations on a client may be accumulated and executed in
<<java-docs-bulk,Bulk>>.

Note, all the APIs are exposed through the
Java API (actually, the Java API is used internally to execute them).

== Javadoc

The javadoc for the transport client can be found at {transport-client-javadoc}/index.html.

== Maven Repository

Elasticsearch is hosted on
http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.elasticsearch.client%22[Maven
Central].

For example, you can define the latest version in your `pom.xml` file:

["source","xml",subs="attributes"]
--------------------------------------------------
<dependency>
    <groupId>org.elasticsearch.client</groupId>
    <artifactId>transport</artifactId>
    <version>{version}</version>
</dependency>
--------------------------------------------------

[[java-transport-usage-maven-lucene]]
=== Lucene Snapshot repository

The very first releases of any major version (like a beta), might have been built on top of a Lucene Snapshot version.
In such a case you will be unable to resolve the Lucene dependencies of the client.

For example, if you want to use the `6.0.0-beta1` version which depends on Lucene `7.0.0-snapshot-00142c9`, you must
define the following repository.

For Maven:

["source","xml",subs="attributes"]
--------------------------------------------------
<repository>
    <id>elastic-lucene-snapshots</id>
    <name>Elastic Lucene Snapshots</name>
    <url>https://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/00142c9</url>
    <releases><enabled>true</enabled></releases>
    <snapshots><enabled>false</enabled></snapshots>
</repository>
--------------------------------------------------

For Gradle:

["source","groovy",subs="attributes"]
--------------------------------------------------
maven {
    name "lucene-snapshots"
    url 'https://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/00142c9'
}
--------------------------------------------------

=== Log4j 2 Logger

You need to also include Log4j 2 dependencies:

["source","xml",subs="attributes"]
--------------------------------------------------
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-core</artifactId>
    <version>2.11.1</version>
</dependency>
--------------------------------------------------

And also provide a Log4j 2 configuration file in your classpath.
For example, you can add in your `src/main/resources` project dir a `log4j2.properties` file like:


["source","properties",subs="attributes"]
--------------------------------------------------
appender.console.type = Console
appender.console.name = console
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = [%d{ISO8601}][%-5p][%-25c] %marker%m%n

rootLogger.level = info
rootLogger.appenderRef.console.ref = console
--------------------------------------------------

=== Using another Logger

If you want to use another logger than Log4j 2, you can use http://www.slf4j.org/[SLF4J] bridge to do that:

["source","xml",subs="attributes"]
--------------------------------------------------
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-to-slf4j</artifactId>
    <version>2.11.1</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>1.7.24</version>
</dependency>
--------------------------------------------------

http://www.slf4j.org/manual.html[This page] lists implementations you can use. Pick your favorite logger
and add it as a dependency. As an example, we will use the `slf4j-simple` logger:

["source","xml",subs="attributes"]
--------------------------------------------------
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>1.7.21</version>
</dependency>
--------------------------------------------------

:client-tests: {docdir}/../../server/src/test/java/org/elasticsearch/client/documentation
:hlrc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client

:client-reindex-tests: {docdir}/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation

include::client.asciidoc[]

include::docs.asciidoc[]

include::search.asciidoc[]

include::aggs.asciidoc[]

include::query-dsl.asciidoc[]

include::admin/index.asciidoc[]