Initialize the Java API client
This is documentation for v3 of the Java API clients, which is not the latest version. To see the documentation for the latest version, see Java v4.
Before you can index your data or search your Algolia indices, you must initialize a search client with your application ID and API key. You can find both in your Algolia account.
Initialize the search client
The search client handles authentication and lets you manage your indices, for example, add data to them, or search them.
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 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 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 through the client
are:
Operations scoped to an index
are:
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, inject it into all client classes of the library. Your 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: 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 codeAlgoliaRetryException
: when the retry strategy failed to target all hostsAlgoliaRuntimeException
: when an error occurred during serialization/deserialization or data processingIllegalArgumentException
: when you provide invalid parametersNullPointerException
: 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.