Install the Java API Client

With Maven, add one of the following dependencies to your pom.xml file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
<!-- Algolia library with Apache HTTP requester (compatible with Java 8 and above) -->
<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch-core</artifactId>
  <version>3.10.0</version>
</dependency>
<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch-apache</artifactId>
  <version>3.10.0</version>
</dependency>

<!-- Algolia library with JDK 11 native HTTP client (compatible with Java 11 and above) -->
<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch-core</artifactId>
  <version>3.10.0</version>
</dependency>
<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch-java-net</artifactId>
  <version>3.10.0</version>
</dependency>

<!-- Algolia library with Apache HTTP requester bundled as a single uber JAR (compatible with Java 8 and above) -->
<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch-apache-uber</artifactId>
  <version>3.10.0</version>
</dependency>

Then run:

$
mvn compile

If you don’t use Maven, you can find all our module JARs available for download on Maven Central’s Sonatype servers:

• algoliasearch-core
• algoliasearch-apache
• algoliasearch-core-uber
• algoliasearch-apache-uber
• algoliasearch-java-net

OSGi platforms and Adobe Experience Manager (AEM)

If you’re using an OSGi platform such as Adobe Experience Manager (AEM), which requires a uber JAR as a dependency, you can use our algoliasearch-apache-uber which is compatible with those platforms.

Supported platforms

The API client supports Java 1.8 and above for all its modules except for the algoliasearch-java-net one. This module only works with Java 11 and above because it embeds the HTTP client from JDK 11 standard library.

Language-specific notes

The JVM has an infinite cache on successful DNS resolution. As our hostnames points to multiple IPs, the load could be not evenly spread among our machines, and you might also target a dead machine.

You should change this TTL by setting the property networkaddress.cache.ttl. For example to set the cache to 60 seconds:

1
java.security.Security.setProperty("networkaddress.cache.ttl", "60");

For debug purposes you can enable debug logging on the API client. It’s using java.util.logging. To enable it, add the following line in your logging.properties file.

1
com.algolia.search.HttpTransport=FINEST

Philosophy

Builder

The v3 of the API client 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.

You can instantiate a DefaultSearchClient with the two dependencies like this:

1
2
3
4
SearchClient client = 
DefaultSearchClient.create("YourApplicationID", "YourAdminAPIKey");

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

If you want to inject your own HttpClient you can inject it by constructor into all the clients classes of library. The latter has to implement the HttpRequester interface. In that case you don’t need algoliasearch-apache anymore as a dependency.

1
2
3
4
5
6
7
SearchConfig config =
new SearchConfig.Builder("YourApplicationID", "YourAdminAPIKey")
    .build();

HttpRequester myCustomRequester = new myCustomRequester();

SearchClient client = new SearchClient(config, myCustomRequester);

All clients are safe to use as a singleton. We recommend reusing client instances as much as possible to avoid socket exhaustion.

All clients implement the Closeable interface. You should close them when you’re done using them.

POJO, JSON & Jackson2

The SearchIndex class is parametrized with a Java class. If you specify one, it lets you have type safe method results.

This parametrized Java class should follow the POJO convention:

• A constructor without parameters
• Getters & setters for every field you want to (de)serialize

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
public class Contact {

  private String name;
  private int age;

  public Contact() {}

  public String getName() {
    return name;
  }

  public Contact setName(String name) {
    this.name = name;
    return this;
  }

  public int getAge() {
    return age;
  }

  public Contact setAge(int age) {
    this.age = age;
    return this;
  }
}

All the serialization/deserialization process is done with Jackson2. You can find the default ObjectMapper com.algolia.search.Defaults.DEFAULT_OBJECT_MAPPER.

Async & CompletableFuture

All asynchronous methods are suffixed with the Async keyword and are in the same classes as the synchronous one. All asynchronous methods return a CompletableFuture.

You can also pass a custom ExecutorService to the Configuration builder. If you don’t provide one the library will be using the ForkJoinPool.commonPool.

Multithreading

The client is designed to be thread-safe. You can use SearchClient, AnalyticsClient, and InsightsClient in a multithreaded environment.

Error handling

The library can throw three type of runtime exception for each methods:

• AlgoliaApiException When Algolia APIs send back an HTTP error code
• AlgoliaRetryException When the retry strategy failed targeting all hosts
• AlgoliaRuntimeException When an error occurred during serialization/deserialization or data processing
• IllegalArgumentException When unvalid parameters are provided
• NullPointerException When a null pointer is passed and not expected

Proxy

To run the API client behind a proxy, you can set the following properties at the JVM level:

1
2
3
4
5
6
7
8
9
10
System.setProperty("https.proxyHost", "https host");
System.setProperty("https.proxyPort", "https port");
System.setProperty("https.proxyUser", "https proxy login");
System.setProperty("https.proxyPassword", "https proxy password");

SearchConfig config = new SearchConfig.Builder("YourApplicationID", "YourAdminAPIKey")
    .setUseSystemProxy(true)
    .build();

SearchClient client = DefaultSearchClient.create(config);

You can find more information about JVM proxy settings on the Java documentation.