Setup custom exceptions

To add documents to MeiliSearch the API requires a JSON object composed of an array of documents, either if you are sending one or multiple documents in the same request. In this case we need a method called addDocuments taking a list of documents as a parameter. This method can handle a single document in the exact same way. It would probably be better to replace the addDocument method

I run:

./gradlew test

and I got warnings

Placeholder search lets the user send a null query parameter in order to apply all the ranking rules to the documents in the index without matching them with a specific query, and return the results to the user. It is different to sending an empty string as a query, in which case you won't receive any results. This behavior should be explicitly tested in the SDK.

More info about Placeholder search here

UPDATE:

Placeholder works 👍

Placeholder Search can be used by:

• Using a null query: q=null
• Using an empty String: q=""

Tests are still missing (both options, null and empty String, should be tested).

Currently, it needs to generate json -> string for POST:

Indexes book = ms.getIndex("books");
        
JsonArray jsonArray = new JsonArray();
JsonObject jsonObject = new JsonObject();
jsonObject.addProperty("1111", "alice in wonderland");
jsonArray.add(jsonObject);

// add new document "[{"1111": "alice in wonderland"}]"
String response = book.addDocument(jsonObject.toString());

To make this simple:

1. Accept JSON modules(Gson, Jackson, ...) as input
2. Create custom input format(it will use JSON module internally to convert input into JSON format)

Currently, the push of this package is done manually and all the steps are described in this section of the CONTRIBUTING.md
We want to make it automatized for each release publishment.

Plus this should be taken into account -> https://jfrog.com/blog/into-the-sunset-bintray-jcenter-gocenter-and-chartcenter/

⚠️ Should be done by a MeiliSearch team member.

In the current implementation, getIndex() returns an Index instance, but createIndex() returns the response of the POST request for creating an index. This forces a usage that looks like this:

...
String i = ms.createIndex(indexUid);
Index index = ms.getIndex(indexUid);
index.addDocuments(...)
...

In case createIndex succeeds, it should return an Index instance which simplifies the usage to

...
Index index = ms.createIndex(indexUid);
index.addDocuments(...)
...

In case of error, this will be handled by #7

Create a nice welcoming file for new contributors, specifying every detail, and especially the developer workflow, and how to test, lint and release (whenever we have tests and linters etc...).

It can be inspired in our SDKs CONTRIBUTING.md files, such as this or this

meilisearch-java uses javadoc as a documentation generator, which is based on comments on the code. There are several classes, methods, and attributes that are very useful for developers who use our SDK that have no comment, and therefore no automated documentation.

Several warnings are shown when your build includes the task javadoc. It would be interesting to add some documentation to the most important classes and methods, and to suppress the warnings of those who do not need to be documented.

This is a good first issue to understand the project, and how it is plugged to MeiliSearch

Note: This doesn't need to be solved all in one single PR, any partial contribution would be appreciated.

I would say that the most important is to add the appropriate comments to the main classes: Client, Index, Search, SearchRequest and it's main methods with a short description of the method, params, return values and Exceptions

As an example:

/**
 * Wait for a pending update to be processed
 *
 * @param updateId ID of the index update
 * @param timeoutInMs number of milliseconds before throwing an Exception
 * @param intervalInMs number of milliseconds before requesting the status again
 * @throws Exception if timeout is reached
 */
public void waitForPendingUpdate(int updateId, int timeoutInMs, int intervalInMs) throws Exception {
	// ...
}

The HTTP API for indexing documents takes always a JSON array of documents as a parameter, either if you want to index a single document or a batch. In which case we should probably expose just a single method for both, and rename it in its plural way as addDocuments(...) :)

There are 3 main methods that are missing in this package. If I'm wrong, feel free to close this issue, but I don't find anything when I search for settings in this repository.

• getSettings that corresponds to this route: https://docs.meilisearch.com/references/settings.html#get-settings
• updateSettings that corresponds to this route: https://docs.meilisearch.com/references/settings.html#update-settings
• resetSettings that corresponds to this route: https://docs.meilisearch.com/references/settings.html#reset-settings

The updateSettings route should be able to work even if all the settings (rankingRules, distinctAttribute, synonyms...) are not all passed. A similar implementation to the SearchRequest class with all the setXXX methods for the Settings class could be useful: https://github.com/meilisearch/meilisearch-java/blob/2b042ada803cd207730b85db4e10157a9ed3d923/src/main/java/com/meilisearch/sdk/SearchRequest.java.

Steps:

• Add the Settings class with all the needed methods
• Add the 3 settings methods (get, update, reset)
• Add tests

Feel free to ask any question if something is not clear to you 🙂

Description
Add facetsDistribution as query parameter in SearchRequest.

Basic example

SearchRequest searchRequest = new SearchRequest("knight")
	.setFacetsDistribution(new String[]{"*"});

new SearchRequest("prince", 200, 900, new String[]{"bubble"}, new String[]{"crop"}, 900, new String[]{"highlight"}, "tag='romance'", true, new String[]{"title"});

JacksonJsonHandlerTest.java and GsonJsonHandlerTest.java generate varargs warnings

#92 Introduces the ServiceTemplate, which makes the API implementation independent from the HTTP Client and JSON handler. This level of abstraction is not yet used by the SDK and will probably introduce breaking changes.

Document this implementation

Code Samples for MeiliSearch documentation

Introduction

As MeiliSearch grows so does its SDK's. More and more SDK's rises from the ground and they all deserve to be as well documented as the core engine itself.

The most common way for a user to understand MeiliSearch is to go to its official documentation. As of yesterday all examples in the documentation were made with cURL. Unfortunately, most of our users do not communicate with MeiliSearch directly with cURL. Which forces them to search for the specific references somewhere else (in the readme's, in the sdk's code itself,..). This makes for unnecessary friction.

Goal

We want our documentation to include all SDK's

As a first step we want all examples to be made using the most possible SDK's. As did Stripe and Algolia.

examples with curl, javascript and soon enough this SDK too!

To achieve this it is expected from this SDK to create a sample file containing all the code samples needed by the documentation.

These are the steps to follow:

• Create your sample file
• Fill your sample file
• Add your samples to the documentation

Create your sample file

The sample file is a yaml file added at the root of each MeiliSearch SDK.
Sample files are created based on the sample-template.yaml file.

sample-template file:

get_one_index_1: |-
list_all_indexes_1: |-
create_an_index_1: |-
...

This template is accessible publicly here or in the public directory : .vuepress/public/sample-template.yaml of the documentation.

The name of the file should be .code-samples.meilisearch.yaml

Fill your sample file

After creating the sample file with the content of the sample template you should have a file containing all the sampleId's.

get_one_index_1: |-
list_all_indexes_1: |-
create_an_index_1: |-
...

By the name of the different sampleId you should know where that code sample will be added to the documentation.

For example, create_an_index_1 is the first example in the API References of the index creation.

Using the already existing cURL example in the documentation you should see what is expected from that sample. It is very important that you look at the already existing samples in the documentation as it gives you the parameters to use in your sample to match with the rest of the documentation.

Good sample based on documentation:

create_an_index_1: |-
  client.createIndex({ uid: 'movies' })

Bad sample that does not match with the response.

create_an_index_1: |-
  client.createIndex({ uid: 'otherName' })

Each sample is expected to be written in the respective SDK language.

Javascript example:

get_one_index_1: |-
  client.getIndex('movies').show()
list_all_indexes_1: |-
  client.listIndexes()
create_an_index_1: |-
  client.createIndex({ uid: 'movies' })
  ...

The complete cURL sample file is available at the root of the documentation repository.
Every other SDK sample file should be available at the root of their respective repository.

Formatting Exception

There is one exception to the formatting rule.
When the sampleId finishes with _md it means it is expected to be written in markdown format.

JavaScript sample id with _md extension:

Add your samples to the documentation

Once your sample file is filled with the code samples, you will need to create a pull request on the documentation repository.

Open the following file in your IDE:
.vuepress/code-samples/sdks.json

And add your sample file to the list:

[
  ...
  {
    "language": "sdk-language",
    "label": "sdk-label",
    "url": "url to yaml file"
  }
]

The language key expect a supported language for the code highlight.

The label key is the name of the tab. While label and language could have been the same, it created some conflict (i.e: bash and cURL).

The url is the raw link to access your sample file. It should look like this:
https://raw.githubusercontent.com/[PROJECT]/[REPO]/.code-samples.meilisearch.yaml

Rename Class MeiliSearchIndex to Index

It will be accessed from external projects as meilisearch.Index

Make a basic set of tests for the main classes and methods, and run a GitHub action on PR to have a CI workflow

I'll create a GitHub action for next years.

The MeiliSearch documentation describes the way to get a list of documents using 3 optional parameters: limit, offset, and/or attributesToRetrieve. The current implementation of the SDK only enables the user to profit from the limit parameter. offset and attributesToRetrieve should be supported.

Since v0.15.0, MeiliSearch exposes a new functionality: dumps

This feature should be implemented in this SDK following this specificacions

• Implement dump creation route
• Implement get dump status route
• Add tests
• Add code samples

• Choose a well maintained and known Linter for Java
• Run the linter for the whole SDK code and make a Pull Request
• Add a task in the CI [GitHub Actions] that runs automatically the linter (Lint will be required for any merge/contribution afterwards)

Do not hesitate to contact us if you have any doubts or questions!

Include a copy if the MIT License in the root of the repo

With our current code base, this upgrade would break the tests: https://github.com/meilisearch/meilisearch-java/pull/57/checks?check_run_id=1458442839

See the PR opened by dependabot: #57

We should make meilisearch-java works with the latest version of each dependency 👍

Currently, the trigger for the publish workflow is based on the name of the tag on push.
We want to trigger the workflow on release, irrespective of the tag.

⚠️ Should be done by a MeiliSearch team member.

Code Samples for MeiliSearch documentation

Introduction

As MeiliSearch grows so does its SDK's. More and more SDK's rises from the ground and they all deserve to be as well documented as the core engine itself.

The most common way for a user to understand MeiliSearch is to go to its official documentation. As of yesterday all examples in the documentation were made with cURL. Unfortunately, most of our users do not communicate with MeiliSearch directly with cURL. Which forces them to search for the specific references somewhere else (in the readme's, in the sdk's code itself,..). This makes for unnecessary friction.

Goal

We want our documentation to include all SDK's

As a first step we want all examples to be made using the most possible SDK's. As did Stripe and Algolia.

examples with curl, javascript and soon enough this SDK too!

To achieve this it is expected from this SDK to create a sample file containing all the code samples needed by the documentation.

These are the steps to follow:

• Create your sample file
• Fill your sample file
• Add your samples to the documentation

Create your sample file

The sample file is a yaml file added at the root of each MeiliSearch SDK.
Sample files are created based on the sample-template.yaml file.

sample-template file:

get_one_index_1: |-
list_all_indexes_1: |-
create_an_index_1: |-
...

This template is accessible publicly here or in the public directory : .vuepress/public/sample-template.yaml of the documentation.

The name of the file should be .code-samples.meilisearch.yaml

Fill your sample file

After creating the sample file with the content of the sample template you should have a file containing all the sampleId's.

get_one_index_1: |-
list_all_indexes_1: |-
create_an_index_1: |-
...

By the name of the different sampleId you should know where that code sample will be added to the documentation.

For example, create_an_index_1 is the first example in the API References of the index creation.

Using the already existing cURL example in the documentation you should see what is expected from that sample. It is very important that you look at the already existing samples in the documentation as it gives you the parameters to use in your sample to match with the rest of the documentation.

Good sample based on documentation:

create_an_index_1: |-
  client.createIndex({ uid: 'movies' })

Bad sample that does not match with the response.

create_an_index_1: |-
  client.createIndex({ uid: 'otherName' })

Each sample is expected to be written in the respective SDK language.

Javascript example:

get_one_index_1: |-
  client.getIndex('movies').show()
list_all_indexes_1: |-
  client.listIndexes()
create_an_index_1: |-
  client.createIndex({ uid: 'movies' })
  ...

The complete cURL sample file is available at the root of the documentation repository.
Every other SDK sample file should be available at the root of their respective repository.

Formatting Exception

There is one exception to the formatting rule.
When the sampleId finishes with _md it means it is expected to be written in markdown format.

JavaScript sample id with _md extension:

Add your samples to the documentation

Once your sample file is filled with the code samples, you will need to create a pull request on the documentation repository.

Open the following file in your IDE:
.vuepress/code-samples/sdks.json

And add your sample file to the list:

[
  ...
  {
    "language": "sdk-language",
    "label": "sdk-label",
    "url": "url to yaml file"
  }
]

The language key expect a supported language for the code highlight.

The label key is the name of the tab. While label and language could have been the same, it created some conflict (i.e: bash and cURL).

The url is the raw link to access your sample file. It should look like this:
https://raw.githubusercontent.com/[PROJECT]/[REPO]/.code-samples.meilisearch.yaml

The addDocument and updateDocuments methods do not take any primary key as parameter, but they should.
Related docs:

• https://docs.meilisearch.com/references/documents.html#add-or-replace-documents
• https://docs.meilisearch.com/references/documents.html#add-or-update-documents

⚠️ The primary key parameter should be optional!

• add in the code base
• add tests

In the current state of the Java SDK, the return value of the search method is a String, which needs to be deserialized by the user after performing a search.

This SDK should provide a generic class capable of deserializing MeiliSearch results. Search method should return an instance of this object, with MeiliSearch's results already deserialized.

Following this discussion, the waitForPendingUpdate() method should wait until the asynchronous update was processed by MeiliSearch. This should have a customizable timeout and interval.

• Implement the method
• Add tests

The wrapper lacks genericity a lot: for the moment each data it returns is a string and must be parsed by the program using the wrapper.
We should implement generic methods allowing to retrieve dynamically mapped types rather than simply strings.

Hello,
I'm facing an issue here, i have meilisearch running in a docker container (last image)
I use meilisearch-java 0.2.0.

I have a doc.json encoded in UTF-8 that contains © and … "spécial" characters.
[{"id":1,"content":"© hop"},{"id":2,"content":"… hop"}]

The following command line is working perfectly as expected.

$ curl  -H "X-Meili-API-Key: masterKey" -X POST 'http://127.0.0.1:7700/indexes/kiki/documents'   --data @doc.json
{"updateId":0}

The following line using meilisearch-java is returning an error:
index.addDocuments("[{\"id\":1,\"content\":\"© hopaaa\"},{\"id\":2,\"content\":\"… hop\"}]")
Invalid JSON: invalid unicode code point at line 1 column 29

I have this problem with all the UTF8 html file i'm trying to index... and it's driving me a bit crazy.
What am i missing? Could this be a bug ?

Serach should use the POST /indexes/:uid/search route instead of GET /indexes/:uid/search

See meilisearch/integration-guides#37

This issue is ready to be implemented, if you need any precision or help, do not hesitate to contact me! :)

With our current code base, this upgrade would break the tests: https://github.com/meilisearch/meilisearch-java/actions/runs/385051667

See the PR opened by dependabot: #59

We should make meilisearch-java works with the latest version of each dependency 👍

Following the new guidelines for Hacktoberfest, we should add the hacktoberfest topic to the repository.

An update status contains, in case of failure, relevant information about the error (message, code and a link to the description of the error in the docs) that should be added to the UpdateStatus for further usage in this SDK and for users!

Example of a failed update:

{
"status":"failed",
"updateId":1,
"type": {
  "name":"DocumentsAddition",
  "number":2
},
"duration":2.55E-5,
"enqueuedAt":"2020-09-28T20:17:27.005486800Z",
"processedAt":"2020-09-28T20:17:27.016900700Z",
"errorCode":"missing_document_id",
"errorType":"invalid_request_error",
"errorLink":"https://docs.meilisearch.com/errors#missing_document_id"
}

All of our SDK's follow a main layout/structure. Of course, this one won't be an exception 🎉

• Quickstart
• API table
• Installation guide
• Description

Concern of supporting Java version 8 or more

• For using various features in Java 8 (stream, optional...)

Related to meilisearch/integration-guides#48

• Change the Getting Started as described in the main issue.
• get_index() does an HTTP call and is not the main method to use anymore.
• Add the index() method
• Add tests for index() method
• Update get_or_create_index with the new way of using index()
• Add a fetchPrimaryKey() method to Index class. The attribute primaryKey is not updated when using the index() method: the method does not do any HTTP call. Refer to the limitation section in the main issue.

Is there any way to update setting through Java SDK?

Like for the curl request below:
$ curl
-X POST 'http://localhost:7700/indexes/movies/settings'
--data '{
"displayedAttributes": [
"title",
"description",
"poster",
"release_date",
"rank"
]
}'

Gets the index instance or creates a new one if it does not exist

• Implement getOrCreate method
• Add tests

Follows this discussion

The implementation for this route letting the user delete a batch of documents by providing a list of document ids is missing from the SDK.

Method names should be explicit, for making the difference obvious, like deleteAllDocuments() and deleteDocuments([...]) (these are the method names used in other MeiliSearch SDKs)

• Implement the method for deleting a batch of documents as deleteDocuments([...])
• Rename the deleteDocuments method (which currently deletes all documents) to deleteAllDocuments()
• Add tests for deleteDocuments()

Currently, there is no check that the version of the package that will be published match the release tag.
We want to implement the check when the publish workflow is triggered (ossrh-publish.yml)

⚠️ Should be done by a MeiliSearch team member.

If I understand well, this library provides default usage but also provides abstractions to choose and customize:

• the JSON library
• the Client
• the HTTP requests

It would be nice to add a section in the README to show with simple lines of code how to customize all of these points 🙂

Due to the changes made to the build.gradle (updating to maven-publish), the build and publish tasks don't create the javadoc and sources anymore.

This is needed by the Central Repository to publish a package.

There is no method to update documents in this package.
Here are the docs about PUT /indexes/:uid/documents: https://docs.meilisearch.com/references/documents.html#add-or-update-documents

• Add it in the code. You can be inspired by addDocuments method. But not completely because there is a missing parameter until this issue is fixed (#78). updateDocuments should also have this optional paramter.
• Add tests.

Inspired on our PHP SDK's search wiki, this document can specify features about search as the different methods exposed to the user (search() and rawSearch(), different constructors for this methods etc...

The repo's README can have a link to this WIKI in the Custom Search section as in this PHP README example

To be consistent with createIndex and getIndex, the method updateIndex should return an Index instance. This method should update the primaryKey attribute of the Index instance with the information returned by MeiliSearch.

• Update the code base
• Add tests

EDIT: this PR (#74) should have been merged before.

Let's be allies and make this change that means a lot.

Here is a blog post that explain a little more why it's important, and how to easily do it. It will be a bit more complicated with automation, but we still should do it!

Currently, here is the way to add documents we show in the first Getting Started example:

final String documents = "["
	+ "{\"book_id\": 123, \"title\": \"Pride and Prejudice\"},"
	+ "{\"book_id\": 456, \"title\": \"Le Petit Prince\"},"
	+ "{\"book_id\": 1, \"title\": \"Alice In Wonderland\"},"
	+ "{\"book_id\": 1344, \"title\": \"The Hobbit\"},"
	+ "{\"book_id\": 4, \"title\": \"Harry Potter and the Half-Blood Prince\"},"
	+ "{\"book_id\": 2, \"title\": \"The Hitchhiker\'s Guide to the Galaxy\"}"
	+ "]";

We would like to use, if it exists, a more friendly way to add documents that we can introduce into our Getting Started, instead of escaping double-quotes.

Maybe we could be inspired by the Stripe Java client and the HashMap solution, but it might also involve lots of lines, and this solution might be "heavy" too.
https://github.com/stripe/stripe-java#usage

What do you think?
Does someone know a way to make the Getting Started example more friendly? 😄