Initialize the Java API client

Before you can interact with Algolia’s APIs, for example, to index your data or search your indices, you need to authenticate with Algolia with your Application ID and API key by initializing a client. You can find both in your Algolia account.

We released a new version of the Java API client in public beta. Read the beta documentation for more information.

Initialize the search client

The search client lets you manage your indices, add data to your indices, and search your indices.

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

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

Replace your_index_name with the name of the index you want to use. You can find your existing indices in the Algolia dashboard, or by using the listIndices method. If the index doesn’t exist, a new, empty index is created locally. It’s created on Algolia’s servers only if you add records to the index.

Don’t use any sensitive or personally identifiable information as your index name, including usernames, IDs, or email addresses. Index names are publicly shared.

Operations, that are scoped to your Algolia application via the client are:

• Manage indices
• Manage dictionaries
• Manage API keys

Operations scoped to an index are:

• Search
• Indexing
• Set and get settings
• Define synonyms
• Define Rules

The Recommend, Personalization, Insights, and A/B testing APIs come with their own clients.

Usage notes

JVM DNS caching

By default, the JVM caches DNS resolutions infinitely. Since Algolia uses multiple IP addresses for load balancing, you should reduce the time to live (TTL) of the cache.

For example, to set the cache to 60 seconds:

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

Debug logging

To enable debug logging in the API client, add the following line to your logging.properties file:

1
com.algolia.search.HttpTransport=FINEST

Builder

The Java API client comes in two packages:

• algoliasearch-core which implements the API methods, Java objects, transport layer, and retry strategy. This package is HTTP client agnostic.
• algoliasearch-apache, algoliasearch-jvm-net are HTTP client implementations of the core library.

If you want to use your own HTTP client, you can inject it into all client classes of library. You custom HTTP client must implement the HttpRequester interface.

If you’re using a custom HTTP client, you don’t need to use algoliasearch-apache or algoliasearch-jvm-net as a dependency.

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

HttpRequester myCustomRequester = new myCustomRequester();

SearchClient client = new SearchClient(config, myCustomRequester);

All clients are safe to use as a singleton. You should reuse client instances as much as possible to avoid exhausting the number of available sockets. All clients implement the Closeable interface. You should close them when you’re done using them.

Serialization

You can parametrize the SearchIndex class with a Java class which lets you use type-safe method results.

The parametrized Java classes should follow the POJO convention:

• A constructor without parameters
• Getters and 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;
  }
}

The Java API client uses Jackson2 for serialization and deserialization. The default object mapper is set in: com.algolia.search.Defaults.DEFAULT_OBJECT_MAPPER.

Asynchronous methods and completable futures

All asynchronous have the suffix Async and are defined in the same classes as their synchronous counterparts. All asynchronous methods return a CompletableFuture.

You can also pass a custom ExecutorService to the Configuration builder. By default, the API client uses ForkJoinPool.commonPool.

Thread safety

The Java API client is thread-safe. You can use SearchClient, AnalyticsClient, and InsightsClient in a multi-threaded environment.

Handling exceptions

The Java API clients can throw three types of runtime exceptions:

• 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 you provide invalid parameters
• NullPointerException: when you pass a null pointer

Use the Java API client with a 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", "YourWriteAPIKey")
    .setUseSystemProxy(true)
    .build();

SearchClient client = DefaultSearchClient.create(config);

For more information about JVM proxy settings, see the Java documentation.