Upgrade the Java API client to version 3

The Java API client follows semantic versioning.

Upgrade to version 3

The client and index class have been renamed SearchClient and SearchIndex. The method names remain the same. To have all the asynchronous and synchronous methods in the same place, the asynchronous client is now part of the SearchClient. The Analytics and Insights clients use the same API design. This version is compatible with Java 8 and later.

This version removes all deprecated methods and features from version 2.

Upgrade the library

The library now comes in two parts.

algoliasearch-core which holds all the methods, the plain old Java object (POJO), the transport layer and the retry strategy. This JAR is agnostic of any HTTP client implementation.
algoliasearch-apache which is the default HTTP client implementation for the core library.

Upgrade with maven

Add the following code in your pom.xml:

pom.xml

<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch-core</artifactId>
  <version>3.6.1</version>
</dependency>

<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch-apache</artifactId>
  <version>3.6.1</version>
</dependency>

Upgrade with Gradle

Add the following code in your build.gradle:

build.gradle

compile 'com.algolia:algoliasearch-core:3.+'
compile 'com.algolia:algoliasearch-apache:3.+'

Client instantiation

Replace the instantiation of the client as shown below.

Java

// Before
APIClient client = 
new ApacheAPIClientBuilder("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
.build();

Index<Contact> index = client.initIndex("INDEX_NAME", Contact.class);

AsyncAPIClient client =
new AsyncHttpAPIClientBuilder("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
.build();

AsyncIndex<Contact> index = client.initIndex("INDEX_NAME", Contact.class);

// After
// It's the same class for async and sync methods!
SearchClient client =
DefaultSearchClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

SearchIndex<Contact> index = client.initIndex("INDEX_NAME", Contact.class);

Instantiate with configuration

You can instantiate all clients with a configuration builder. This is useful to affect the way a client behaves. You can configure :

DefaultHeaders: to set HTTP headers for every request
BatchSize: to customize the chunk size of batches for save methods
Hosts: to set custom hosts to target
Timeouts : to set timeout such as the read timeout, the write timeout, and the connect timeout
ExecutorService: to set your own ExecutorService

Example:

Java

SearchConfig config =
  new SearchConfig.Builder("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
      .setHosts(...)
      .setReadTimeOut(...)
      .setWriteTimeOut(...)
      .setConnectTimeOut(...)
      .setBatchSize(...)
      .setExecutorService(...)
      .build();

SearchClient client = DefaultSearchClient.create(config);

Analytics instantiation

Similarly, you need to update the way you initialize the Analytics client.

Java

// Before
APIClient client =
new ApacheAPIClientBuilder("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
.build();

Analytics analytics = client.initAnalytics();

AsyncAPIClient client =
new AsyncHttpAPIClientBuilder("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
.build();

AsyncAnalytics analytics = client.initAnalytics();

// After
// It's the same class for async and sync methods!
AnalyticsClient analytics =
DefaultAnalyticsClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

Insights instantiation

You need to update the way you initialize the Insights client:

Java

// Before
APIClient client =
new ApacheAPIClientBuilder("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
.build();

SyncInsightsClient insights =
new SyncInsightsClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", client)

AsyncAPIClient client =
new AsyncHttpAPIClientBuilder("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
.build();

AsyncInsightsClient insights =
new AsyncInsightsClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", client)

// After
// It's the same class for async and sync methods!
InsightsClient insights =
DefaultInsightsClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

Review breaking changes

To ease the update, most of the plain old java objects (POJO) didn’t change. You can find some breaking changes in the following table. All methods marked as @Depracted are removed.

Clients

Methods/Features in version 2	Breaking Change	Methods/Features in version 3
`APIClient`	Removed. Use `SearchClient` `AnalyticsClient` `InsightsClient` instead.	`DefaultSearchClient.create(..)` `DefaultAnalyticsClient.create(..)` `DefaultInsightsClient.create(..)`
`AsyncAPIClient`	Removed. Use `SearchClient` `AnalyticsClient` `InsightsClient` instead.	`DefaultSearchClient.create(..)` `DefaultAnalyticsClient.create(..)` `DefaultInsightsClient.create(..)`

`SearchClient`

Methods/Features in version 2	Breaking Change	Methods/Features in version 3
`listKeys()`	Removed. Use `listApiKeys()` instead.	`listApiKeys()`

`Index/SearchIndex`

Methods/Features in version 2	Breaking Change	Methods/Features in version 3
`deleteByQuery(query)`	Removed. Use `deleteBy()` instead.	`deleteBy(query)`
`searchInFacetValues(facetName,facetQuery,query)`	Removed. Use `searchForFacetValues()` instead.	`searchForFacetValues(String, String, Query)`
`index.browse(Query)`	Breaking	`index.browseObjects(BrowseIndexQuery)`
`BrowseResult<T>`	Breaking	`BrowseIndexResponse<T>`
`IndexSetting.getAttributesToIndex()`	Removed. Use `searchableAttributes` instead.	`IndexSetting.getSearchableAttributes()`
`IndexSetting.setAttributesToIndex()`	Removed. Use `searchableAttributes` instead.	`IndexSetting.setSearchableAttributes()`
`Query.setFacetFilters(List<String>)`	Breaking	`Query.setFacetFilters(List)`
`Query.setNumericFilters(List<String>)`	Breaking	`Query.setNumericFilters(List)`
`Query.setTagFilters(List<String>)`	Breaking	`Query.setTagFilters(List)`
`Query.setOptionalFilters(List<String>)`	Breaking	`Query.setOptionalFilters(List)`
`AbstractSynonym`	Removed. Use `Synonym` instead.	`Synonym`
`ConsequenceQueryObject`	Removed. Use `ConsequenceQuery` instead.	`ConsequenceQuery`
`ConsequenceQueryObject.setRemove(List<String>)`	Removed. Use `ConsequenceQuery.setEdits()` instead.	`ConsequenceQuery.setEdits(List<Edits>>)`
`Index<T>.addObject(T object)`	Removed. Use `SearchIndex<T>.saveObject(T data)` instead.	`SearchIndex<T>.saveObject(T data)`

`AnalyticsClient`

Methods/Features in version 2	Breaking Change	Methods/Features in version 3
`TaskABTest addABTest(ABTest abtest)`	Breaking	`AddABTestResponse addABTest(ABTest abTest)`
`TaskABTest stopABTest(long id)`	Breaking	`StopAbTestResponse stopABTest(long id)`
`TaskABTest deleteABTest(long id)`	Breaking	`DeleteAbTestResponse deleteABTest(long id)`
`ABTest getABTest(long id)`	Breaking	`ABTestResponse getABTest(long id)`

​Upgrade to version 3

​Upgrade the library

​Upgrade with maven

​Upgrade with Gradle

​Client instantiation

​Instantiate with configuration

​Analytics instantiation

​Insights instantiation

​Review breaking changes

​Clients

​SearchClient

​Index/SearchIndex

​AnalyticsClient

Upgrade to version 3

Upgrade the library

Upgrade with maven

Upgrade with Gradle

Client instantiation

Instantiate with configuration

Analytics instantiation

Insights instantiation

Review breaking changes

Clients

`SearchClient`

`Index/SearchIndex`

`AnalyticsClient`