elasticsearch/docs/reference/migration/migrate_5_0/java.asciidoc

[[breaking_50_java_api_changes]]
=== Java API changes

==== Transport client  has been moved

The Java transport client has been moved to its own module which can be referenced using:

[source,xml]
-----
<dependency>
    <groupId>org.elasticsearch.client</groupId>
    <artifactId>transport</artifactId>
    <version>5.0.0-alpha5</version>
</dependency>
-----

The transport client is now created using the following snippet:

[source,java]
-----
TransportClient client = new PreBuiltTransportClient(Settings.EMPTY)
        .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("host1"), 9300))
        .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("host2"), 9300));
-----

For more information please see the {javaclient}java-api.html[Java client documentation]

==== Count api has been removed

The deprecated count api has been removed from the Java api, use the search api instead and set size to 0.

The following call

[source,java]
-----
client.prepareCount(indices).setQuery(query).get();
-----

can be replaced with

[source,java]
-----
client.prepareSearch(indices).setSource(new SearchSourceBuilder().size(0).query(query)).get();
-----

==== Suggest api has been removed

The suggest api has been removed from the Java api, use the suggest option in search api, it has been optimized
for suggest-only request.

The following call

[source,java]
-----
client.prepareSuggest(indices).addSuggestion("foo", SuggestBuilders.completionSuggestion("field").text("s")).get();
-----

can be replaced with

[source,java]
-----
client.prepareSearch(indices).suggest(new SuggestBuilder().addSuggestion("foo", SuggestBuilders.completionSuggestion("field").text("s"))).get();
-----

==== Elasticsearch will no longer detect logging implementations

Elasticsearch now logs only to log4j 1.2. Previously if log4j wasn't on the
classpath it made some effort to degrade to slf4j or java.util.logging. Now it
will fail to work without the log4j 1.2 api. The log4j-over-slf4j bridge ought
to work when using the java client, as should log4j 2's log4j-1.2-api. The
Elasticsearch server now only supports log4j as configured by `logging.yml`
and will fail if log4j isn't present.

==== Groovy dependencies

In previous versions of Elasticsearch, the Groovy scripting capabilities
depended on the `org.codehaus.groovy:groovy-all` artifact.  In addition
to pulling in the Groovy language, this pulls in a very large set of
functionality, none of which is needed for scripting within
Elasticsearch. Aside from the inherent difficulties in managing such a
large set of dependencies, this also increases the surface area for
security issues. This dependency has been reduced to the core Groovy
language `org.codehaus.groovy:groovy` artifact.

==== DocumentAlreadyExistsException removed

`DocumentAlreadyExistsException` is removed and a `VersionConflictException` is thrown instead (with a better
error description). This will influence code that use the `IndexRequest.opType()` or `IndexRequest.create()`
to index a document only if it doesn't already exist.

==== writeConsistencyLevel removed on write requests

In previous versions of Elasticsearch, the various write requests had a
`setWriteConsistencyLevel` method to set the shard consistency level for
write operations. However, the semantics of write consistency were ambiguous 
as this is just a pre-operation check to ensure the specified number of
shards were available before the operation commenced. The write consistency
level did not guarantee that the data would be replicated to those number
of copies by the time the operation finished. The `setWriteConsistencyLevel`
method on these write requests has been changed to `setWaitForActiveShards`,
which can take a numerical value up to the total number of shard copies or 
`ActiveShardCount.ALL` for all shard copies. The default is to just wait
for the primary shard to be active before proceeding with the operation. 
See the section on <<index-wait-for-active-shards,wait for active shards>> 
for more details.

This change affects `IndexRequest`, `IndexRequestBuilder`, `BulkRequest`, 
`BulkRequestBuilder`, `UpdateRequest`, `UpdateRequestBuilder`, `DeleteRequest`, 
and `DeleteRequestBuilder`.

==== Changes to Query Builders

===== BoostingQueryBuilder

Removed setters for mandatory positive/negative query. Both arguments now have
to be supplied at construction time already and have to be non-null.

===== SpanContainingQueryBuilder

Removed setters for mandatory big/little inner span queries. Both arguments now have
to be supplied at construction time already and have to be non-null. Updated
static factory methods in QueryBuilders accordingly.

===== SpanOrQueryBuilder

Making sure that query contains at least one clause by making initial clause mandatory
in constructor.
Renaming method to add clauses from `clause(SpanQueryBuilder)` to `addClause(SpanQueryBuilder)`.

===== SpanNearQueryBuilder

Removed setter for mandatory slop parameter, needs to be set in constructor now. Also
making sure that query contains at least one clause by making initial clause mandatory
in constructor. Updated the static factory methods in QueryBuilders accordingly.
Renaming method to add clauses from `clause(SpanQueryBuilder)` to `addClause(SpanQueryBuilder)`.

===== SpanNotQueryBuilder

Removed setter for mandatory include/exclude span query clause, needs to be set in constructor now.
Updated the static factory methods in QueryBuilders and tests accordingly.

===== SpanWithinQueryBuilder

Removed setters for mandatory big/little inner span queries. Both arguments now have
to be supplied at construction time already and have to be non-null. Updated
static factory methods in QueryBuilders accordingly.

===== WrapperQueryBuilder

Removed `wrapperQueryBuilder(byte[] source, int offset, int length)`. Instead simply
use  `wrapperQueryBuilder(byte[] source)`. Updated the static factory methods in
QueryBuilders accordingly.

===== QueryStringQueryBuilder

Removed ability to pass in boost value using `field(String field)` method in form e.g. `field^2`.
Use the `field(String, float)` method instead.

===== Operator

Removed the enums called `Operator` from `MatchQueryBuilder`, `QueryStringQueryBuilder`,
`SimpleQueryStringBuilder`, and `CommonTermsQueryBuilder` in favour of using the enum
defined in `org.elasticsearch.index.query.Operator` in an effort to consolidate the
codebase and avoid duplication.

===== queryName and boost support

Support for `queryName` and `boost` has been streamlined to all of the queries. That is
a breaking change till queries get sent over the network as serialized json rather
than in `Streamable` format. In fact whenever additional fields are added to the json
representation of the query, older nodes might throw error when they find unknown fields.

===== InnerHitsBuilder

InnerHitsBuilder now has a dedicated addParentChildInnerHits and addNestedInnerHits methods
to differentiate between inner hits for nested vs. parent / child documents. This change
makes the type / path parameter mandatory.

===== MatchQueryBuilder

Moving MatchQueryBuilder.Type and MatchQueryBuilder.ZeroTermsQuery enum to MatchQuery.Type.
Also reusing new Operator enum.

===== MoreLikeThisQueryBuilder

Removed `MoreLikeThisQueryBuilder.Item#id(String id)`, `Item#doc(BytesReference doc)`,
`Item#doc(XContentBuilder doc)`. Use provided constructors instead.

Removed `MoreLikeThisQueryBuilder#addLike` in favor of texts and/or items being provided
at construction time. Using arrays there instead of lists now.

Removed `MoreLikeThisQueryBuilder#addUnlike` in favor to using the `unlike` methods
which take arrays as arguments now rather than the lists used before.

The deprecated `docs(Item... docs)`, `ignoreLike(Item... docs)`,
`ignoreLike(String... likeText)`, `addItem(Item... likeItems)` have been removed.

===== GeoDistanceQueryBuilder

Removing individual setters for lon() and lat() values, both values should be set together
 using point(lon, lat).

===== GeoDistanceRangeQueryBuilder

Removing setters for to(Object ...) and from(Object ...) in favour of the only two allowed input
arguments (String, Number). Removing setter for center point (point(), geohash()) because parameter
is mandatory and should already be set in constructor.
Also removing setters for lt(), lte(), gt(), gte() since they can all be replaced by equivalent
calls to to/from() and inludeLower()/includeUpper().

===== GeoPolygonQueryBuilder

Require shell of polygon already to be specified in constructor instead of adding it pointwise.
This enables validation, but makes it necessary to remove the addPoint() methods.

===== MultiMatchQueryBuilder

Moving MultiMatchQueryBuilder.ZeroTermsQuery enum to MatchQuery.ZeroTermsQuery.
Also reusing new Operator enum.

Removed ability to pass in boost value using `field(String field)` method in form e.g. `field^2`.
Use the `field(String, float)` method instead.

===== MissingQueryBuilder

The MissingQueryBuilder which was deprecated in 2.2.0 is removed. As a replacement use ExistsQueryBuilder
inside a mustNot() clause. So instead of using `new ExistsQueryBuilder(name)` now use
`new BoolQueryBuilder().mustNot(new ExistsQueryBuilder(name))`.

===== NotQueryBuilder

The NotQueryBuilder which was deprecated in 2.1.0 is removed. As a replacement use BoolQueryBuilder
with added mustNot() clause. So instead of using `new NotQueryBuilder(filter)` now use
`new BoolQueryBuilder().mustNot(filter)`.

===== TermsQueryBuilder

Remove the setter for `termsLookup()`, making it only possible to either use a TermsLookup object or
individual values at construction time. Also moving individual settings for the TermsLookup (lookupIndex,
lookupType, lookupId, lookupPath) to the separate TermsLookup class, using constructor only and moving
checks for validation there. Removed `TermsLookupQueryBuilder` in favour of `TermsQueryBuilder`.

===== FunctionScoreQueryBuilder

`add` methods have been removed, all filters and functions must be provided as constructor arguments by
creating an array of `FunctionScoreQueryBuilder.FilterFunctionBuilder` objects, containing one element
for each filter/function pair.

`scoreMode` and `boostMode` can only be provided using corresponding enum members instead
of string values: see `FilterFunctionScoreQuery.ScoreMode` and `CombineFunction`.

`CombineFunction.MULT` has been renamed to `MULTIPLY`.

===== IdsQueryBuilder

For simplicity, only one way of adding the ids to the existing list (empty by default)  is left: `addIds(String...)`

===== ShapeBuilders

`InternalLineStringBuilder` is removed in favour of `LineStringBuilder`, `InternalPolygonBuilder` in favour of PolygonBuilder` and `Ring` has been replaced with `LineStringBuilder`. Also the abstract base classes `BaseLineStringBuilder` and `BasePolygonBuilder` haven been merged with their corresponding implementations.

===== RescoreBuilder

`RecoreBuilder.Rescorer` was merged with `RescoreBuilder`, which now is an abstract superclass. QueryRescoreBuilder currently is its only implementation.

===== PhraseSuggestionBuilder

The inner DirectCandidateGenerator class has been moved out to its own class called DirectCandidateGeneratorBuilder.

===== SortBuilders

The `sortMode` setter in `FieldSortBuilder`, `GeoDistanceSortBuilder` and `ScriptSortBuilder` now
accept a `SortMode` enum instead of a String constant. Also the getter returns the same enum type.

===== SuggestBuilder

The `setText` method has been changed to `setGlobalText` to make the intent more clear, and a `getGlobalText` method has been added.

The `addSuggestion` method now required the user specified suggestion name, previously used in the ctor of each suggestion.

===== SuggestionBuilder

The `field` setter has been deleted. Instead the field name needs to be specified as constructor argument.

==== SearchSourceBuilder

All methods which take an `XContentBuilder`, `BytesReference` `Map<String, Object>` or `bytes[]` have been removed in favor of providing the
relevant builder object for that feature (e.g. `HighlightBuilder`, `AggregationBuilder`, `SuggestBuilder`) . This means that all search requests
can now be validated at call time which results in much clearer errors.

The `defaultResourceWindowSize(int)` method has been removed. The window size should be set explicitly on all `RescoreBuilder` objects.

==== SearchRequestBuilder

All methods which take an `XContentBuilder`, `BytesReference` `Map<String, Object>` or `bytes[]` have been removed in favor of providing the
relevant builder object for that feature (e.g. `HighlightBuilder`, `AggregationBuilder`, `SuggestBuilder`) . This means that all search requests
can now be validated at call time which results in much clearer errors.

All highlighter methods have been removed in favor of a single `highlighter(HighlightBuilder)` method.

The `setExtraSource(SearchSourceBuilder)` method has been removed.

The `setTemplateSource(String)` and `setTemplateSource(BytesReference)` methods have been removed. Use `setTemplate(Template)` instead.

`setRescorer(Rescorer)` and `setRescorer(Rescorer, int)` have been removed infavor of `setRescorer(RescoreBuilder)` and `setRescorer(RescoreBuilder, int)`

==== SearchRequest

All `source` methods have been removed in favor of a single `source(SearchSourceBuilder)` method. This means that all search requests can now be validated
at call time which results in much clearer errors.

All `extraSource` methods have been removed.

All `template` methods have been removed in favor of a new Search Template API. A new `SearchTemplateRequest` now accepts a template and
a `SearchRequest` and must be executed using the new `SearchTemplateAction` action.

==== SearchResponse

Sort values for `string` fields are now return as `java.lang.String` objects rather than `org.elasticsearch.common.text.Text`.

==== AggregationBuilder

All methods which take an `XContentBuilder`, `BytesReference` `Map<String, Object>` or `bytes[]` have been removed in favor of providing the
relevant builder object (i.e. `subAggregation(AggregationBuilder)` or `subAggregation(PipelineAggregationBuilder)`). This means that all
requests can now be validated at call time which results in much clearer errors.

==== ValidateQueryRequest

`source(QuerySourceBuilder)`, `source(Map)`, `source(XContentBuilder)`, `source(String)`, `source(byte[])`, `source(byte[], int, int)`,
`source(BytesReference)` and `source()` have been removed in favor of using `query(QueryBuilder)` and `query()`

==== ValidateQueryRequestBuilder

`setSource()` methods have been removed in favor of using `setQuery(QueryBuilder)`

==== ExplainRequest

`source(QuerySourceBuilder)`, `source(Map)`, `source(BytesReference)` and `source()` have been removed in favor of using
`query(QueryBuilder)` and `query()`

==== ExplainRequestBuilder

The `setQuery(BytesReference)` method have been removed in favor of using `setQuery(QueryBuilder)`

==== ClusterStatsResponse

Removed the `getMemoryAvailable` method from `OsStats`, which could be previously accessed calling
`clusterStatsResponse.getNodesStats().getOs().getMemoryAvailable()`.

==== setRefresh(boolean) has been removed

`setRefresh(boolean)` has been removed in favor of `setRefreshPolicy(RefreshPolicy)` because there
are now three options (NONE, IMMEDIATE, and WAIT_FOR). `setRefresh(IMMEDIATE)` has the same behavior
as `setRefresh(true)` used to have. See `setRefreshPolicy`'s javadoc for more.

==== Remove properties support

Some Java APIs (e.g., `IndicesAdminClient#setSettings`) would support Java properties syntax
(line-delimited key=value pairs). This support has been removed.

==== Render Search Template Java API has been removed

The Render Search Template Java API including `RenderSearchTemplateAction`, `RenderSearchTemplateRequest` and
`RenderSearchTemplateResponse` has been removed in favor of a new `simulate` option in the Search Template Java API.
 This Search Template API is now included in the `lang-mustache` module and the `simulate` flag must be set on the
 `SearchTemplateRequest` object.

==== AnalyzeRequest

The `tokenFilters(String...)` and `charFilters(String...)` methods have been removed
in favor of using `addTokenFilter(String)`/`addTokenFilter(Map)` and `addCharFilter(String)`/`addCharFilter(Map)` each filters

==== AnalyzeRequestBuilder

The `setTokenFilters(String...)` and `setCharFilters(String...)` methods have been removed
in favor of using `addTokenFilter(String)`/`addTokenFilter(Map)` and `addCharFilter(String)`/`addCharFilter(Map)` each filters

==== BlobContainer Interface for Snapshot/Restore

Some methods have been removed from the `BlobContainer` interface for Snapshot/Restore repositories.  In particular,
the following three methods have been removed:

 1. `deleteBlobs(Collection<String>)` (use `deleteBlob(String)` instead)
 2. `deleteBlobsByPrefix(String)` (use `deleteBlob(String)` instead)
 3. `writeBlob(String, BytesReference)` (use `writeBlob(String, InputStream, long)` instead)

The `deleteBlob` methods that took multiple blobs as arguments were deleted because no atomic guarantees can be made about either deleting all blobs or deleting none of them, and exception handling in such a situation is ambiguous and best left to the caller. Hence, all delete blob calls use the singular `deleteBlob(String)` method. 

The extra `writeBlob` method offered no real advantage to the interface and all calls to `writeBlob(blobName, bytesRef)` can be replaced with:

[source,java]
-----
try (InputStream stream = bytesRef.streamInput()) {
    blobContainer.writeBlob(blobName, stream, bytesRef.length());
}
-----

For any custom implementation of the `BlobContainer` interface, these three methods must be removed.