mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-06 04:58:50 +00:00
1708f1773b
The Log4j dependency is separated into two artifacts, the API and the core implementation. This is to enable replacing Log4j on the backend through the SLF4J bridge with another logging implementation. For this reason, the dependencies are marked as optional. This causes confusion amongst users as to use the bridge, the API should be non-optional since it is needed for the bridge to function correctly. While they could pull it into their application directly, it would be clearer if we simply marked this depdendency as non-optional. Note that this does not mean that users have to use Log4j for logging in their application, so we are not marking core as required, it only clarifies what they need to be able to plug in a different logging implementation. Relates #25136
210 lines
6.9 KiB
Plaintext
210 lines
6.9 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).
|
|
|
|
|
|
== 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>
|
|
--------------------------------------------------
|
|
|
|
=== 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[]
|