-
Notifications
You must be signed in to change notification settings - Fork 242
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
- Loading branch information
Showing
40 changed files
with
1,383 additions
and
364 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
[[blocking-and-async]] | ||
=== Blocking and asynchronous clients | ||
|
||
API clients come in two flavors: blocking and asynchronous. All methods on | ||
asynchronous clients return a standard `CompletableFuture`. | ||
|
||
Both flavors can be used at the same time depending on your needs, sharing the | ||
same transport object: | ||
|
||
["source","java"] | ||
-------------------------------------------------- | ||
ElasticsearchTransport transport = ... | ||
include-tagged::{doc-tests-src}/api_conventions/ApiConventionsTest.java[blocking-and-async] | ||
-------------------------------------------------- | ||
|
||
Although we won't go in deeper details on asynchronous programming in Java, remember to handle failures of asynchronous tasks. It's easy to overlook them and have errors go unnoticed. | ||
|
||
{doc-tests-blurb} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,68 @@ | ||
[[building-objects]] | ||
=== Building API objects | ||
|
||
[discrete] | ||
==== Builder objects | ||
|
||
All data types in the {java-client} are immutable. Object creation uses the | ||
https://www.informit.com/articles/article.aspx?p=1216151&seqNum=2[builder pattern] | ||
that was popularized in *Effective Java* in 2008. | ||
|
||
["source","java"] | ||
-------------------------------------------------- | ||
ElasticsearchClient client = ... | ||
include-tagged::{doc-tests-src}/api_conventions/ApiConventionsTest.java[builders] | ||
-------------------------------------------------- | ||
|
||
Note that a builder should not be reused after its `build()` method has been | ||
called. | ||
|
||
[discrete] | ||
==== Builder lambda expressions | ||
|
||
Although this works nicely, having to instantiate builder classes and call the | ||
`build()` method is a bit verbose. So every property setter in the {java-client} also | ||
accepts a lambda expression that takes a newly created builder as a parameter | ||
and returns a populated builder. The snippet above can also be written as: | ||
|
||
["source","java"] | ||
-------------------------------------------------- | ||
ElasticsearchClient client = ... | ||
include-tagged::{doc-tests-src}/api_conventions/ApiConventionsTest.java[builder-lambdas] | ||
-------------------------------------------------- | ||
|
||
This approach allows for much more concise code, and also avoids importing | ||
classes (and even remembering their names) since types are inferred from the | ||
method parameter signature. | ||
|
||
Note in the above example that builder variables are only used to start a chain | ||
of property setters. The names of these variables are therefore unimportant and | ||
can be shortened to improve readability: | ||
|
||
["source","java"] | ||
-------------------------------------------------- | ||
ElasticsearchClient client = ... | ||
include-tagged::{doc-tests-src}/api_conventions/ApiConventionsTest.java[builder-lambdas-short] | ||
-------------------------------------------------- | ||
|
||
Builder lambdas become particularly useful with complex nested queries like the | ||
one below, taken from the | ||
{ref}/query-dsl-intervals-query.html[intervals query API documentation]. | ||
|
||
This example also highlights a useful naming convention for builder parameters in | ||
deeply nested structures. For lambda expressions with a single argument, Kotlin | ||
provides the implicit `it` parameter and Scala allows use of `_`. This can be approximated | ||
in Java by using an underscore or a single letter prefix followed by a number representing the depth | ||
level (i.e. `_0`, `_1`, or `b0`, `b1` and so on). Not only does this remove the need to create | ||
throw-away variable names, but it also improves code readability. Correct indentation | ||
also allows the structure of the query to stand out. | ||
|
||
["source","java"] | ||
-------------------------------------------------- | ||
ElasticsearchClient client = ... | ||
include-tagged::{doc-tests-src}/api_conventions/ApiConventionsTest.java[builder-intervals] | ||
-------------------------------------------------- | ||
<1> Search results will be mapped to `SomeApplicationData` instances to | ||
be readily available to the application. | ||
|
||
{doc-tests-blurb} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,15 @@ | ||
[[exceptions]] | ||
=== Exceptions | ||
|
||
Client methods can throw two kinds of exceptions: | ||
|
||
* Requests that were received by the {es} server but that were rejected | ||
(validation error, server internal timeout exceeded, etc) will produce an | ||
`ElasticsearchException`. This exception contains details about the error, | ||
provided by {es}. | ||
|
||
* Requests that failed to reach the server (network error, server unavailable, | ||
etc) will produce a `TransportException`. That exception's cause is the exception | ||
thrown by the lower-level implementation. In the case of the `RestClientTransport` | ||
it will be a `ResponseException` that contains the low level HTTP response. | ||
|
Oops, something went wrong.