249 lines
8.4 KiB
Plaintext
249 lines
8.4 KiB
Plaintext
[[java-api]]
|
|
= Java API
|
|
|
|
include::../Versions.asciidoc[]
|
|
|
|
[preface]
|
|
== Preface
|
|
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).
|
|
|
|
WARNING: Starting from version 5.6.0, a new Java client has been
|
|
released: the {java-rest}/java-rest-high.html[Java High Level REST Client].
|
|
This new client is designed to replace the `TransportClient` in Java
|
|
applications which will be deprecated in future versions of Elasticsearch.
|
|
|
|
== 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%7Ca%3A%22elasticsearch%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>http://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 {
|
|
url 'http://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.8.2</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.8.2</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>
|
|
--------------------------------------------------
|
|
|
|
|
|
== Dealing with JAR dependency conflicts
|
|
|
|
If you want to use Elasticsearch in your Java application, you may have to deal with version conflicts with third party
|
|
dependencies like Guava and Joda. For instance, perhaps Elasticsearch uses Joda 2.8, while your code uses Joda 2.1.
|
|
|
|
You have two choices:
|
|
|
|
* The simplest solution is to upgrade. Newer module versions are likely to have fixed old bugs.
|
|
The further behind you fall, the harder it will be to upgrade later. Of course, it is possible that you are using a
|
|
third party dependency that in turn depends on an outdated version of a package, which prevents you from upgrading.
|
|
|
|
* The second option is to relocate the troublesome dependencies and to shade them either with your own application
|
|
or with Elasticsearch and any plugins needed by the Elasticsearch client.
|
|
|
|
The https://www.elastic.co/blog/to-shade-or-not-to-shade["To shade or not to shade" blog post] describes
|
|
all the steps for doing so.
|
|
|
|
== Embedding jar with dependencies
|
|
|
|
If you want to create a single jar containing your application and all dependencies, you should not
|
|
use `maven-assembly-plugin` for that because it can not deal with `META-INF/services` structure which is
|
|
required by Lucene jars.
|
|
|
|
Instead, you can use `maven-shade-plugin` and configure it as follow:
|
|
|
|
[source,xml]
|
|
--------------------------------------------------
|
|
<plugin>
|
|
<groupId>org.apache.maven.plugins</groupId>
|
|
<artifactId>maven-shade-plugin</artifactId>
|
|
<version>2.4.1</version>
|
|
<executions>
|
|
<execution>
|
|
<phase>package</phase>
|
|
<goals><goal>shade</goal></goals>
|
|
<configuration>
|
|
<transformers>
|
|
<transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
|
|
</transformers>
|
|
</configuration>
|
|
</execution>
|
|
</executions>
|
|
</plugin>
|
|
--------------------------------------------------
|
|
|
|
Note that if you have a `main` class you want to automatically call when running `java -jar yourjar.jar`, just add
|
|
it to the `transformers`:
|
|
|
|
[source,xml]
|
|
--------------------------------------------------
|
|
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
|
|
<mainClass>org.elasticsearch.demo.Generate</mainClass>
|
|
</transformer>
|
|
--------------------------------------------------
|
|
|
|
|
|
== Deploying in JBoss EAP6 module
|
|
|
|
Elasticsearch and Lucene classes need to be in the same JBoss module.
|
|
|
|
You should define a `module.xml` file like this:
|
|
|
|
[source,xml]
|
|
--------------------------------------------------
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<module xmlns="urn:jboss:module:1.1" name="org.elasticsearch">
|
|
<resources>
|
|
<!-- Elasticsearch -->
|
|
<resource-root path="elasticsearch-2.0.0.jar"/>
|
|
<!-- Lucene -->
|
|
<resource-root path="lucene-core-5.1.0.jar"/>
|
|
<resource-root path="lucene-analyzers-common-5.1.0.jar"/>
|
|
<resource-root path="lucene-queries-5.1.0.jar"/>
|
|
<resource-root path="lucene-memory-5.1.0.jar"/>
|
|
<resource-root path="lucene-highlighter-5.1.0.jar"/>
|
|
<resource-root path="lucene-queryparser-5.1.0.jar"/>
|
|
<resource-root path="lucene-sandbox-5.1.0.jar"/>
|
|
<resource-root path="lucene-suggest-5.1.0.jar"/>
|
|
<resource-root path="lucene-misc-5.1.0.jar"/>
|
|
<resource-root path="lucene-join-5.1.0.jar"/>
|
|
<resource-root path="lucene-grouping-5.1.0.jar"/>
|
|
<resource-root path="lucene-spatial-5.1.0.jar"/>
|
|
<resource-root path="lucene-expressions-5.1.0.jar"/>
|
|
<!-- Insert other resources here -->
|
|
</resources>
|
|
|
|
<dependencies>
|
|
<module name="sun.jdk" export="true" >
|
|
<imports>
|
|
<include path="sun/misc/Unsafe" />
|
|
</imports>
|
|
</module>
|
|
<module name="org.apache.log4j"/>
|
|
<module name="org.apache.commons.logging"/>
|
|
<module name="javax.api"/>
|
|
</dependencies>
|
|
</module>
|
|
--------------------------------------------------
|
|
|
|
|
|
include::client.asciidoc[]
|
|
|
|
include::docs.asciidoc[]
|
|
|
|
include::search.asciidoc[]
|
|
|
|
include::aggs.asciidoc[]
|
|
|
|
include::query-dsl.asciidoc[]
|
|
|
|
include::indexed-scripts.asciidoc[]
|
|
|
|
include::admin/index.asciidoc[]
|