API Reference / API Methods / Upgrade guides for the API client
Jun. 10, 2019

Upgrade guides for the API client

Upgrade to v3

We entirely rewrote the Java client but we chose to keep a similar design to make it as easy as possible to upgrade.

There is still a client and an index class, but they have respectively been renamed SearchClient and SearchIndex. The method names remain the same. The asynchronous client was merged into SearchClient to have all the asynchronous and synchronous methods in the same place. We used the same design for the Analytics and Insights clients.

This new version is compatible with Java 8 and above.

Estimated upgrade time: 1 hour.

All deprecated methods and features from v2 have been removed.

Upgrading the Library

The library now comes in two parts.

  • algoliasearch-core which contains all the methods, the POJOs, 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.

With Maven

Add the following code in your pom.xml:

Copy
1
2
3
4
5
6
7
8
9
10
11

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

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

With Gradle

Add the following code in your build.gradle:

Copy
1
2

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

Client Instantiation

Replace the instantiation of the client as shown below.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// Before
APIClient client =
new ApacheAPIClientBuilder("YourApplicationID", "YourAdminAPIKey")
.build();

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

AsyncAPIClient client =
new AsyncHttpAPIClientBuilder("YourApplicationID", "YourAdminAPIKey")
.build();

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

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

SearchIndex<Contact> index = client.InitIndex("your_index_name", Contact.class);

Using configuration

All clients can be instantiated via 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:

Copy
1
2
3
4
5
6
7
8
9
10
11

SearchConfig config =
  new SearchConfig.Builder("YourApplicationID", "YourAdminAPIKey")
      .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.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// Before
APIClient client =
new ApacheAPIClientBuilder("YourApplicationID", "YourAdminAPIKey")
.build();

Analytics analytics = client.initAnalytics();

AsyncAPIClient client =
new AsyncHttpAPIClientBuilder("YourApplicationID", "YourAdminAPIKey")
.build();

AsyncAnalytics analytics = client.initAnalytics();

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

Insights Instantiation

Finally, you need to update the way you initialize the Insights client.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// Before
APIClient client =
new ApacheAPIClientBuilder("YourApplicationID", "YourAdminAPIKey")
.build();

SyncInsightsClient insights =
new SyncInsightsClient("YourApplicationID", "YourAdminAPIKey", client)

AsyncAPIClient client =
new AsyncHttpAPIClientBuilder("YourApplicationID", "YourAdminAPIKey")
.build();

AsyncInsightsClient insights =
new AsyncInsightsClient("YourApplicationID", "YourAdminAPIKey", client)

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

Breaking Changes

We kept most of the POJOs to facilitate the update. There are a few breaking changes you can find in the following table.

All methods marked as @Depracted have been removed.

Clients

Methods/Features in v2.x Breaking Change Methods/Features in v3.x
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 v2.x Breaking Change Methods/Features in v3.x
listKeys() Removed. Use listApiKeys() instead. listApiKeys()

Index/SearchIndex

Methods/Features in v2.x Breaking Change Methods/Features in v3.x
deleteByQuery(query) Removed. Use deleteBy() instead.deleteBy(query)
searchInFacetValues(facetName,facetQuery,query)Removed. Use searchForFacetValues() instead.searchForFacetValues(String, String, Query)
index.browse(Query) Breakingindex.browse(BrowseIndexQuery)
BrowseResult<T> BreakingBrowseIndexResponse<T>
IndexSetting.getAttributesToIndex() Removed. Use searchableAttributes instead.IndexSetting.getSearchableAttributes()
IndexSetting.setAttributesToIndex() Removed. Use searchableAttributes instead.IndexSetting.setSearchableAttributes()
Query.setFacetFilters(List<String>) BreakingQuery.setFacetFilters(List<List<String>>)
Query.setNumericFilters(List<String>) BreakingQuery.setNumericFilters(List<List<String>>)
Query.setTagFilters(List<String>) BreakingQuery.setTagFilters(List<List<String>>)
Query.setOptionalFilters(List<String>) BreakingQuery.setOptionalFilters(List<List<String>>)
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>>)

AnalyticsClient

Methods/Features in v2.x Breaking Change Methods/Features in v3.x
TaskABTest addABTest(ABTest abtest) BreakingAddABTestResponse 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)

Did you find this page helpful?

Java