Upgrading from 4.3.x to 4.4.x

This section describes breaking changes from version 4.3.x to 4.4.x and how removed features can be replaced by new introduced features.

Deprecations

org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations

The method <T> Publisher<T> execute(ClientCallback<Publisher<T>> callback) has been deprecated. As there now are multiple implementations using different client libraries the execute method is still available in the different implementations, but there is no more method in the interface, because there is no common callback interface for the different clients.

Breaking Changes

Removal of deprecated classes

org.springframework.data.elasticsearch.core.ElasticsearchTemplate has been removed

As of version 4.4 Spring Data Elasticsearch does not use the TransportClient from Elasticsearch anymore (which itself is deprecated since Elasticsearch 7.0). This means that the org.springframework.data.elasticsearch.core.ElasticsearchTemplate class which was deprecated since Spring Data Elasticsearch 4.0 has been removed. This was the implementation of the ElasticsearchOperations interface that was using the TransportClient. Connections to Elasticsearch must be made using either the imperative ElasticsearchRestTemplate or the reactive ReactiveElasticsearchTemplate.

Package changes

In 4.3 two classes (ElasticsearchAggregations and ElasticsearchAggregation) had been moved to the org.springframework.data.elasticsearch.core.clients.elasticsearch7 package in preparation for the integration of the new Elasticsearch client. The were moved back to the org.springframework.data.elasticsearch.core package as we keep the classes use the old Elasticsearch client where they were.

Behaviour change

The ReactiveElasticsearchTemplate, when created directly or by Spring Boot configuration had a default refresh policy of IMMEDIATE. This could cause performance issues on heavy indexing and was different than the default behaviour of Elasticsearch. This has been changed to that now the default refresh policy is NONE. When the ReactiveElasticsearchTemplate was provided by using the configuration like described in Reactive REST Client the default refresh policy already was set to NONE.

New Elasticsearch client

Elasticsearch has introduced it’s new ElasticsearchClient and has deprecated the previous RestHighLevelClient. Spring Data Elasticsearch 4.4 still uses the old client as the default client for the following reasons:

  • The new client forces applications to use the jakarta.json.spi.JsonProvider package whereas Spring Boot will stick to javax.json.spi.JsonProvider until version 3. So switching the default implementaiton in Spring Data Elasticsearch can only come with Spring Data Elasticsearch 5 (Spring Data 3, Spring 6).

  • There are still some bugs in the Elasticsearch client which need to be resolved

  • The implementation using the new client in Spring Data Elasticsearch is not yet complete, due to limited resources working on that - remember Spring Data Elasticsearch is a community driven project that lives from public contributions.

How to use the new client

The implementation using the new client is not complete, some operations will throw a java.lang.UnsupportedOperationException or might throw NPE (for example when the Elasticsearch cannot parse a response from the server, this still happens sometimes)
Use the new client to test the implementations but do not use it in productive code yet!

In order to try and use the new client the following steps are necessary:

Make sure not to configure the existing default client

If using Spring Boot, exclude Spring Data Elasticsearch from the autoconfiguration

@SpringBootApplication(exclude = ElasticsearchDataAutoConfiguration.class)
public class SpringdataElasticTestApplication {
	// ...
}

Remove Spring Data Elasticsearch related properties from your application configuration. If Spring Data Elasticsearch was configured using a programmatic configuration (see Elasticsearch Clients), remove these beans from the Spring application context.

Add dependencies

The dependencies for the new Elasticsearch client are still optional in Spring Data Elasticsearch so they need to be added explicitly:

<dependencies>
    <dependency>
        <groupId>co.elastic.clients</groupId>
        <artifactId>elasticsearch-java</artifactId>
        <version>7.17.3</version>
        <exclusions>
            <exclusion>
                <groupId>commons-logging</groupId>
                <artifactId>commons-logging</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>org.elasticsearch.client</groupId>
        <artifactId>elasticsearch-rest-client</artifactId> <!-- is Apache 2-->
        <version>7.17.3</version>
        <exclusions>
            <exclusion>
                <groupId>commons-logging</groupId>
                <artifactId>commons-logging</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
</dependencies>

When using Spring Boot, it is necessary to set the following property in the pom.xml.

<properties>
    <jakarta-json.version>2.0.1</jakarta-json.version>
</properties>

New configuration classes

Imperative style

In order configure Spring Data Elasticsearch to use the new client, it is necessary to create a configuration bean that derives from org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration:

@Configuration
public class NewRestClientConfig extends ElasticsearchConfiguration {

	@Override
	public ClientConfiguration clientConfiguration() {
		return ClientConfiguration.builder() //
			.connectedTo("localhost:9200") //
			.build();
	}
}

The configuration is done in the same way as with the old client, but it is not necessary anymore to create more than the configuration bean. With this configuration, the following beans will be available in the Spring application context:

  • a RestClient bean, that is the configured low level RestClient that is used by the Elasticsearch client

  • an ElasticsearchClient bean, this is the new client that uses the RestClient

  • an ElasticsearchOperations bean, available with the bean names elasticsearchOperations and elasticsearchTemplate, this uses the ElasticsearchClient

Reactive style

To use the new client in a reactive environment the only difference is the class from which to derive the configuration:

@Configuration
public class NewRestClientConfig extends ReactiveElasticsearchConfiguration {

	@Override
	public ClientConfiguration clientConfiguration() {
		return ClientConfiguration.builder() //
			.connectedTo("localhost:9200") //
			.build();
	}
}

With this configuration, the following beans will be available in the Spring application context:

  • a RestClient bean, that is the configured low level RestClient that is used by the Elasticsearch client

  • an ReactiveElasticsearchClient bean, this is the new reactive client that uses the RestClient

  • an ReactiveElasticsearchOperations bean, available with the bean names reactiveElasticsearchOperations and reactiveElasticsearchTemplate, this uses the ReactiveElasticsearchClient