Migration guide from 1.x to 2.x

AlgoliaSearch Java client v2 was introduced to improve type safety, testability, and uses new features in Java 1.8. So the v2, drops support for Java 1.6 & 1.7. With all those improvements come some incompatible changes with the first version of the client. This document is intended to the users of the v1.x of the client who choose to migrate their code from version 1.x to 2.x.

Non-backward compatible changes are affecting all the existing functions from the APIClient and Index classes. They now provide typed results based on your POJO.

The serialization/deserialization of JSON is made with Jackson2.

If you have any issue, please contact our team at [email protected].

Table of contents

1. Migrate your code to v2
2. Initialization
3. Other breaking changes
4. New features
5. Fixes
6. Misc
7. Can I still use v1?

Migrate your code to v2

Initialization

v1

APIClient client = new APIClient("YourApplicationID", "YourAPIKey");

v2

APIClient client = new ApacheAPIClientBuilder("YourApplicationID", "YourAPIKey").build();

The initialization is now done with a builder, on which you can change the default values.

Removed setters in APIClient

All the parameters of the class APIClient are now passed to the builder

See the options in the APIClientBuilder class.

Changed function signatures

To standardise methods signatures, to add type safety and to uses java 1.8 features, some methods have changed their signature.

Index class

• All methods returning JSONObject now returns real types. You can still use JSONObject by using the jackson-datatype-json-org library
• All methods on UserKey are now just named Key (eg: listUserKeys => listKeys)
• searchDisjunctiveFaceting was removed
• addObject(obj, objectId) has its parameters swapped index.addObject(objectId, obj)
• waitTask was moved to the Task class
• All getXXX methods now returns an Optional<T>

APIClient class

• All methods returning JSONObject now returns real types. You can still use JSONObject by using the jackson-datatype-json-org library
• listIndexes was renamed listIndices
• getLogs(int offset, int length) was removed, use getLogs(offset, length, LOG_ALL)
• getLogs(int offset, int length, boolean onlyErrors) was removed, use getLogs(offset, length, LOG_ERROR)
• client.copyIndex was moved to index.copyTo(dst)
• client.moveIndex was moved to index.moveTo(dst)
• Move all setters to the builder
• Remove enableRateLimitForward

Query class

• renamed attributes to attributesToRetrieve
• renamed numerics numericFilters
• renamed tags to tagsFilters
• renamed maxNumberOfFacets to maxValuesPerFacet
• renamed aroundLatLong to aroundLatLng
• renamed aroundLatLongViaIP to aroundLatLngViaIP
• removed noTypoToleranceOn, similarQuery and referers

Other breaking changes

• package com.algolia.search.saas was renamed com.algolia.search
• APIClient.IndexQuery was moved to its own file IndexQuery
• Index.IndexBrowser was deleted and replaced by IndexIterable<T>. It is now an Iterable. To get an iterator call the iterator() method

New features

• The Index class can now be parametrized with a concrete type. Use client.initIndex("myIndex", MyPojo.class)
• Each method of the Index class now returns specific types based on the concrete type passed at creation time.
• All serialization/deserialization is made with Jackson2, you can pass your own ObjectMapper to the builder. It's overriden with specific configuration, you can find the overrides in com.algolia.search.Defaults.DEFAULT_OBJECT_MAPPER.
• Each method parameter that must not be null is now annotated with the annotation @Nonnull
• A stream() method is available to IndexIterable
• In the Query class
  • add setAroundRadiusAll()
  • add setRemoveStopWords(List<String> isoCode)

Can I still use v1?

Yes. If you are using the v1 of our Java client and do not want to upgrade then you can stick to v1.

Warning New features of the v2 (async, type safety, etc.) won't be back-ported to the v1.