Install the Java API client
Install
If you’re using Maven
, add the following dependency to your pom.xml
file:
<dependency>
<groupId>com.algolia</groupId>
<artifactId>algoliasearch</artifactId>
<version>[2,]</version>
</dependency>
For the asynchronous version use:
<dependency>
<groupId>com.algolia</groupId>
<artifactId>algoliasearch-async</artifactId>
<version>[2,]</version>
</dependency>
On Google AppEngine
use this:
<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:
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 theAppEngineAPIClientBuilder
- if you fancy
Future
, use theAsyncHttpAPIClientBuilder
- if you fancy
- on
Android
, use theAndroid
API Client - on a regular
JVM
, use theApacheAPIClientBuilder
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.
Did you find this page helpful?
We're always looking for advice to help improve our documentation!
Please let us know what's working (or what's not!).
We're constantly iterating thanks to the feedback we receive.