Install

With Maven, add the following dependency to your pom.xml file:

<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch</artifactId>
  <version>[2,]</version>
</dependency>

Then, for the asynchronous version, use:

<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch-async</artifactId>
  <version>[2,]</version>
</dependency>

Or on Google AppEngine, use:

<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch-appengine</artifactId>
  <version>[2,]</version>
</dependency>

Supported platforms

This API client only supports Java 1.8 & Java 1.9 If you need support for an older version, please use this package.

Language-specific notes

WARNING: 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:

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

For debug purposes you can enable debug logging on the API client. It’s using slf4j so it should be compatible with most java logger. The logger is named algoliasearch.

Philosophy

Builder

The v2 of the api client uses a builder to create the APIClient object:

• on Google App Engine use the AppEngineAPIClientBuilder
  • if you fancy Future, use the AsyncHttpAPIClientBuilder
• on Android, use the Android API Client
• on a regular JVM, use the ApacheAPIClientBuilder

POJO, JSON & Jackson2

The Index (and AsyncIndex) classes are parametrized with a Java class. If you specify one it enables you to have type safe method results. This parametrized Java class is expected to follow the POJO convention:

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

Example:

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 is done with Jackson2. You can add your custom ObjectMapper with the method setObjectMapper of the builder. Changing it might produce unexpected results. You can find the one used in the interface com.algolia.search.Defaults.DEFAULT_OBJECT_MAPPER.

Async & Future

All methods of the AsyncAPIClient are exactly the same as the APIClient but returns CompletableFuture<?>. All other classes are prefixes with Async. You can also pass an optional ExecutorService to the build of the AsyncHttpAPIClientBuilder.

Init Index

To begin, you will need to initialize the client. In order to do this you will need your Application ID and API Key. You can find both on your Algolia account.

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

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

For the asynchronous version:

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

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

For Google AppEngine:

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

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

You need to replace your_index_name by the name of the index you want to use. If you want to target an existing index you can find the name from the dashboard. If the index does not exist you can choose any name and it will be created when you perform an add objects or a set settings operation.

If an api key is displayed in the previous snippet it is your ADMIN API Key. To maintain security, never use your ADMIN API Key on your frontend or share it with anyone. In your frontend, use the SEARCH ONLY API Key or any other key that has search only rights.

Make sure you don’t use any sensitive or personally identifiable information (PII) as your index name, including customer names, user IDs, or email addresses. Index names appear in network requests and should be considered publicly available.