Java API Client v3 is released 🎉


Hi Everyone! :wave:

Today we are happy to announce that the v3.0.0 of the Java client is now out :rocket: It implements our common specs and it’s coming with a lot of sweet additions :candy:

Check them out!

:coffee: Support for Java from 8 to 12

In the API client squad, we want our libraries to be compatible with the lower LTS version of the targeted platform, so that they can be used by the largest possible audience. That’s why the v3 was designed to be compatible from Java 8 to 12.

:floppy_disk: Minimal dependency set

The v3 has less dependencies than the v2: we went from 15 to 9! Having a reduced the dependency set makes the final package smaller, and more importantly makes our library easier to port to higher JDK version.

:syringe: Injectable HttpClient

The library comes in two flavors, to be selected depending on the needs:

  • algoliasearch-core: which contains the models, the retry-strategy, the serializer and all the API methods.
  • algoliasearch-apache: which is our default HTTP client implementation based on Apache

If you don’t want to use the default Apache HTTP client-based implementation we provide - because they don’t want to pay the extra cost of a dependency they don’t use, they can use the algoliasearch-core package and instead of the algoliasearch-apache one. In this case, you have to implement the HttpRequester interface to inject their HTTP Client in algoliasearch-core. Good news is, even with an injected HTTP client our users can still leverage all the features of our library: the retry-strategy, the models, the serializer, etc.

:package: Dependency-conflict-free packages

You probably already faced dependencies versions clashes when adding popular libraries such as Jackson or Guava in your projects. Lots of our users are having issues of this kind while leveraging the v2, and contact us for support. Helping them solve this is generally tricky, and can end up in us tweaking the building of their products. Documenting the workaround is an imperfect solution - getting rid of the issue entirely is better. This is where the über-jar kicks in!

An über-jar is a package embedding all its dependencies, in such a way that they are hidden to the exterior. The package obtained is bigger, but cannot induce version-conflicts.

We distribute the Java API Client v3 as über-jars too. This is a huge win for our users who don’t want to solve conflicts on dependencies versions and don’t mind the slight increase in size. For users preferring to deal with version conflicts, they can still leverage the “standard” jars which we continue to provide.

:electric_plug: New design for asynchronous methods

Before, asynchronous and synchronous methods were split into two different classes. Now, they are in the same class! All asynchronous methods are suffixed with the async word and return a CompletableFuture.

:gear: Thread-safe clients

Every Client class in the library, such as SearchClient, AnalyticsClient, and InsightsClient can be used in a multi-threaded environment. This is a huge improvement for our users willing to use our library in multi threaded batches or web applications such as Java Spring.

:running_man:Test 60 times faster

As the client is thread safe, we are now able to run our common test suite in parallel. As a result, the common test suite - consisting in 30 end-to-end tests is now running in less than 30 seconds, while it used to run in 28 minutes!

:bug: Tracing feature

The library comes with a logger which, if enabled, logs all the requests and responses going through the library. Good news is that even if you change the default HTTP client the logger will still be there because it’s agnostic of any HTTP client implementations!

:stopwatch: Homogeneous way to wait for operations completions

It is now as easy as:

You can wait not only for operations that return a taskId (such as indexing objects), but also for operations that don’t (like operations on keys). You can wait on every class that implements the AlgoliaWaitableResponse interface. For example:

Read the full list of supported operations

:robot: Hassle free batching for indexing

When given an iterator, indexing methods automatically create batches to optimise the amount of network calls. The batch size can be adjusted, but for common use cases, our users don’t have to even think about batching.

:vulcan_salute: Specific client classes

Our API Clients aren’t handling only search methods anymore but also analytics or insights ones. We separated them into dedicated clients to make clear what to use and when.

:confused: No more confusion between add and save.

We dropped the verb add. Now, all save methods mean either you add something new or replace it completely if it was already existing. Also, if you decide to save objects that don’t have any objectIds, the method will fail except if you explicitly say that you want Algolia to generate them for you. This feature is helpful only for particular use cases and shouldn’t be the default option.

:checkered_flag: Where should I start?

We no have a repository with playgrounds for most of our clients.

The Java playground comes with several examples - notably, how to perform a basic indexing/searching or how to inject another Http Client than the default one in the library. Check it out!

:raised_hands: Call for feedback

If you are already an Algolia user or if you plan to be, please share any feedback you may have via:

GitHub issues or Pull Requests

1 Like