Migration guide to version 3.x

Overview

Version 3 brought a few incompatible changes to the Android client's public interface. This guide will help you adapt your code to work with the new version.

This guide only focuses on incompatible changes. For a complete list of all changes, please refer to ChangeLog.md at the root of the repository.

Changes

Client class

• The APIClient class is now called Client.

• If you used to specify the enableDsn and/or dsnHost when constructing an APIClient, remove those parameters as they are no longer supported.

• If you used to specify hosts when constructing an APIClient:

  1. First consider whether you really need to do so. The default hosts leverage our fault-tolerant DNS and are highly recommended in most use cases.
  2. If you really need to specify hosts, use an array (String[]) instead of a list (List<String>).

Asynchronous methods

• Methods have been renamed to use an Async suffix (note the lowercase S) instead of ASync.

• All asynchronous methods now use a new, unique listener called CompletionHandler. Its interface contains a single method used for both success and error cases. In addition to simplifying the code and aligning the Android client with other languages, this makes it possible to use Java 8 lambda expressions. You will have to rewrite all your listeners accordingly.

Query parameters

Overview

First of all, the Query class now provides low-level methods to access any parameter (even not implemented yet) in an untyped fashion: use the get(String)/set(String, String) methods. You should therefore no longer be blocked by missing parameters.

The class has undergone quite a few changes, with the following goals:

1. Bring it in line with the REST API. This implies renaming parameters, adding missing parameters or (in some rare cases) removing them.

2. Honor the essentially optional nature of all query parameters. A null value is acceptable and is the default for all parameters, including primitive types, which are now represented by the corresponding boxed type (e.g. Integer for int).

3. Provide adequate types:

   • For parameters taking a list of strings, arrays (String[]) are now used instead of lists (List<String>), making it possible to leverage variable arguments.

   • Enum values have been renamed to better match those in the REST API.

4. Consistent naming convention: accessors to parameter fooBar are now named getFooBar() and setFooBar().

Detailed changes

• analyticsTags is now typed String[] (variable arguments allowed).
• aroundLatitudeLongitude() has been renamed to setAroundLatLng() and is now typed LatLng. Also, the overloaded flavors accepting a radius and a precision have been removed; use the individual setters instead.
• aroundLatitudeLongitudeViaIP() has been renamed to setAroundLatLngViaIP(). Also, the overloaded flavors accepting a radius and a precision have been removed; use the individual setters instead.
• attributesToHighlight is now exclusively typed String[] (variable arguments allowed).
• attributesToRetrieve is now exclusively typed String[] (variable arguments allowed).
• attributesToSnippet is now exclusively typed String[] (variable arguments allowed).
• enableAvancedSyntax() has been renamed to setAdvancedSyntax().
• enableAnalytics() has been renamed to setAnalytics().
• enableDistinct() has been renamed to setDistinct() and is now exclusively typed Integer.
• enableRemoveStopWords() has been renamed to setRemoveStopWords().
• enableReplaceSynonymsInHighlight() has been renamed to setReplaceSynonymsInHighlight().
• enableSynonyms() has been renamed to setSynonyms().
• enableTyposOnNumericTokens() has been renamed to setAllowTyposOnNumericTokens().
• enableTypoTolerance() has been renamed to setTypoTolerance() and is now enum-typed.
• getRankingInfo() has been renamed to setGetRankingInfo().
• ignorePlural() has been renamed to setIgnorePlurals().
• insideBoundingBox() has been renamed to setInsideBoundingBox() and is now typed GeoRect[] (variable arguments allowed).
• insidePolygon() has been renamed to setInsidePolygon() and is now typed LatLng[] (variable arguments allowed).
• removeWordsIfNoResult() has been renamed setRemoveWordsIfNoResult().
• restrictSearchableAttributes() has been renamed to setRestrictSearchableAttributes().
• restrictSearchableAttributes is now typed String[] (variable arguments allowed).
• setFacets() is now exclusively typed String[] (variable arguments allowed).
• setFacetFilters() is now exclusively typed JSONArray, using the same JSON notation as the REST API.
• setMaxNumberOfFacets() has been renamed to setMaxValuesPerFacet().
• setHighlightingTags() has been removed. Use the individual setters instead.
• setMinWordSizeToAllowOneTypo() has been renamed to setMinWordSizefor1Typo().
• setMinWordSizeToAllowTwoTypos() has been renamed to setMinWordSizefor2Typos().
• setNbHitsPerPage() has been removed. Use setHitsPerPage() instead.
• setNumericFilters() is now typed JSONArray, using the same JSON notation as the REST API.
• setOptionalWords() is now exclusively typed String[] (variable arguments allowed).
• setQueryString() has been renamed to setQuery().
• setSimilarQueryString() has been removed.
• setTagFilters() is now typed JSONArray, using the same JSON notation as the REST API.

Miscellaneous

• Accessors to obsolete security HTTP headers have been removed (APIClient.setSecurityTags(), APIClient.setUserToken()). If you need them:

  1. First please consider migrating to secured API keys, which are now the preferred way to deal with per-user authorization.
  2. If you really need the legacy headers, you may set them via Client.setHeaders().

• Operations requiring an admin API key have been removed. For obvious security reasons, the admin key should never be used on the client side. There is no plan to reintegrate those features.

• @NonNull annotations are consistently used throughout the API wherever a parameter is mandatory. Please respect them, otherwise your code is likely to crash!