Merge pull request #518 from meilisearch/documents_changes

Update documents API for Meilisearch v.28

src/main/java/com/meilisearch/sdk/Documents.java

@@ -1,8 +1,9 @@
 package com.meilisearch.sdk;
 
-import static java.util.Collections.singletonList;
-
 import com.meilisearch.sdk.exceptions.MeilisearchException;
+import com.meilisearch.sdk.http.URLBuilder;
+import com.meilisearch.sdk.model.DocumentsQuery;
+import com.meilisearch.sdk.model.Results;
 import com.meilisearch.sdk.model.TaskInfo;
 import java.util.List;
 
@@ -19,85 +20,111 @@ protected Documents(Config config) {
     }
 
     /**
-     * Retrieves the document at the specified index uid with the specified identifier
+     * Retrieves the document from the specified index uid with the specified identifier
      *
+     * @param <T> Type of the document returned
      * @param uid Partial index identifier for the requested documents
      * @param identifier ID of the document
-     * @return String containing the requested document
+     * @param targetClass Class of the document returned
+     * @return Object containing the requested document
+     * @throws MeilisearchException if the client request causes an error
+     */
+    <T> T getDocument(String uid, String identifier, Class<T> targetClass)
+            throws MeilisearchException {
+        return httpClient.<T>get(new DocumentsQuery().toQuery(uid, identifier), targetClass);
+    }
+
+    /**
+     * Retrieves the document from the specified index uid with the specified identifier
+     *
+     * @param uid Partial index identifier for the requested documents
+     * @param identifier ID of the document
+     * @param param accepted by the get document route
+     * @param targetClass Class of the document returned
+     * @return Object containing the requested document
      * @throws MeilisearchException if client request causes an error
      */
-    String getDocument(String uid, String identifier) throws MeilisearchException {
-        String urlPath = "/indexes/" + uid + "/documents/" + identifier;
-        return httpClient.get(urlPath, String.class);
+    <T> T getDocument(String uid, String identifier, DocumentsQuery param, Class<T> targetClass)
+            throws MeilisearchException {
+        return httpClient.<T>get(param.toQuery(uid, identifier, param), targetClass);
     }
 
     /**
-     * Retrieves the document at the specified index
+     * Retrieves the document from the specified index uid with the specified identifier
      *
      * @param uid Partial index identifier for the requested documents
+     * @param identifier ID of the document
      * @return String containing the requested document
-     * @throws MeilisearchException if the client request causes an error
+     * @throws MeilisearchException if client request causes an error
      */
-    String getDocuments(String uid) throws MeilisearchException {
-        String urlPath = "/indexes/" + uid + "/documents";
-        return httpClient.get(urlPath, String.class);
+    String getRawDocument(String uid, String identifier) throws MeilisearchException {
+        return httpClient.<String>get(new DocumentsQuery().toQuery(uid, identifier), String.class);
     }
 
     /**
-     * Retrieves the document at the specified index
+     * Retrieves the document from the specified index uid with the specified identifier
      *
      * @param uid Partial index identifier for the requested documents
-     * @param limit Limit on the requested documents to be returned
+     * @param identifier ID of the document
+     * @param param accept by the documents route
      * @return String containing the requested document
-     * @throws MeilisearchException if the client request causes an error
+     * @throws MeilisearchException if client request causes an error
      */
-    String getDocuments(String uid, int limit) throws MeilisearchException {
-        String urlQuery = "/indexes/" + uid + "/documents?limit=" + limit;
-        return httpClient.get(urlQuery, String.class);
+    String getRawDocument(String uid, String identifier, DocumentsQuery param)
+            throws MeilisearchException {
+        return httpClient.<String>get(param.toQuery(uid, identifier, param), String.class);
     }
 
     /**
-     * Retrieves the document at the specified index
+     * Retrieves the document from the specified index
      *
+     * @param <T> Type of documents returned
      * @param uid Partial index identifier for the requested documents
-     * @param limit Limit on the requested documents to be returned
-     * @param offset Specify the offset of the first hit to return
-     * @return String containing the requested document
+     * @param targetClass Class of documents returned
+     * @return Results containing a list of Object containing the requested document
      * @throws MeilisearchException if the client request causes an error
      */
-    String getDocuments(String uid, int limit, int offset) throws MeilisearchException {
-        String urlQuery = "/indexes/" + uid + "/documents?limit=" + limit + "&offset=" + offset;
-        return httpClient.get(urlQuery, String.class);
+    <T> Results<T> getDocuments(String uid, Class<T> targetClass) throws MeilisearchException {
+        return httpClient.<Results>get(
+                new DocumentsQuery().toQuery(uid), Results.class, targetClass);
     }
 
     /**
-     * Retrieves the document at the specified index
+     * Retrieves the document from the specified index
      *
+     * @param <T> Type of documents returned
      * @param uid Partial index identifier for the requested documents
-     * @param limit Limit on the requested documents to be returned
-     * @param offset Specify the offset of the first hit to return
-     * @param attributesToRetrieve Document attributes to show
-     * @return String containing the requested document
+     * @param param accepted by the get documents route
+     * @param targetClass Class of documents returned
+     * @return Results containing a list of Object containing the requested document
      * @throws MeilisearchException if the client request causes an error
      */
-    String getDocuments(String uid, int limit, int offset, List<String> attributesToRetrieve)
+    <T> Results<T> getDocuments(String uid, DocumentsQuery param, Class<T> targetClass)
             throws MeilisearchException {
-        if (attributesToRetrieve == null || attributesToRetrieve.size() == 0) {
-            attributesToRetrieve = singletonList("*");
-        }
+        return httpClient.<Results>get(param.toQuery(uid, param), Results.class, targetClass);
+    }
+
+    /**
+     * Retrieves the document as a string from the specified index
+     *
+     * @param uid Partial index identifier for the requested documents
+     * @return Meilisearch API response
+     * @throws MeilisearchException if an error occurs
+     */
+    String getRawDocuments(String uid) throws MeilisearchException {
+        return httpClient.get(new DocumentsQuery().toQuery(uid), String.class);
+    }
 
-        String attributesToRetrieveCommaSeparated = String.join(",", attributesToRetrieve);
-        String urlQuery =
-                "/indexes/"
-                        + uid
-                        + "/documents?limit="
-                        + limit
-                        + "&offset="
-                        + offset
-                        + "&attributesToRetrieve="
-                        + attributesToRetrieveCommaSeparated;
-
-        return httpClient.get(urlQuery, String.class);
+    /**
+     * Retrieves the document as String from the specified index
+     *
+     * @param uid Partial index identifier for the requested documents
+     * @param param accepted by the documents route
+     * @return Meilisearch API response
+     * @throws MeilisearchException if an error occurs
+     */
+    String getRawDocuments(String uid, DocumentsQuery param) throws MeilisearchException {
+        return httpClient.<String>get(param.toQuery(uid, param), String.class);
     }
 
     /**
@@ -111,10 +138,12 @@ String getDocuments(String uid, int limit, int offset, List<String> attributesTo
      */
     TaskInfo addDocuments(String uid, String document, String primaryKey)
             throws MeilisearchException {
-        String urlQuery = "/indexes/" + uid + "/documents";
+        URLBuilder urlb = new URLBuilder();
+        urlb.addSubroute("indexes").addSubroute(uid).addSubroute("documents");
         if (primaryKey != null) {
-            urlQuery += "?primaryKey=" + primaryKey;
+            urlb.addParameter("primaryKey", primaryKey);
         }
+        String urlQuery = urlb.getURL();
         return httpClient.post(urlQuery, document, TaskInfo.class);
     }
 
@@ -129,24 +158,26 @@ TaskInfo addDocuments(String uid, String document, String primaryKey)
      */
     TaskInfo updateDocuments(String uid, String document, String primaryKey)
             throws MeilisearchException {
-        String urlPath = "/indexes/" + uid + "/documents";
+        URLBuilder urlb = new URLBuilder();
+        urlb.addSubroute("indexes").addSubroute(uid).addSubroute("documents");
         if (primaryKey != null) {
-            urlPath += "?primaryKey=" + primaryKey;
+            urlb.addParameter("primaryKey", primaryKey);
         }
+        String urlPath = urlb.getURL();
         return httpClient.put(urlPath, document, TaskInfo.class);
     }
 
     /**
-     * Deletes the document at the specified index uid with the specified identifier
+     * Deletes the document from the specified index uid with the specified identifier
      *
      * @param uid Partial index identifier for the requested document
      * @param identifier ID of the document
      * @return Meilisearch's TaskInfo API response
      * @throws MeilisearchException if the client request causes an error
      */
     TaskInfo deleteDocument(String uid, String identifier) throws MeilisearchException {
-        String urlPath = "/indexes/" + uid + "/documents/" + identifier;
-        return httpClient.delete(urlPath, TaskInfo.class);
+        return httpClient.<TaskInfo>delete(
+                new DocumentsQuery().toQuery(uid, identifier), TaskInfo.class);
     }
 
     /**
@@ -158,7 +189,12 @@ TaskInfo deleteDocument(String uid, String identifier) throws MeilisearchExcepti
      * @throws MeilisearchException if the client request causes an error
      */
     TaskInfo deleteDocuments(String uid, List<String> identifiers) throws MeilisearchException {
-        String urlPath = "/indexes/" + uid + "/documents/" + "delete-batch";
+        URLBuilder urlb = new URLBuilder();
+        urlb.addSubroute("indexes")
+                .addSubroute(uid)
+                .addSubroute("documents")
+                .addSubroute("delete-batch");
+        String urlPath = urlb.getURL();
         return httpClient.post(urlPath, identifiers, TaskInfo.class);
     }
 
@@ -170,7 +206,6 @@ TaskInfo deleteDocuments(String uid, List<String> identifiers) throws Meilisearc
      * @throws MeilisearchException if the client request causes an error
      */
     TaskInfo deleteAllDocuments(String uid) throws MeilisearchException {
-        String urlPath = "/indexes/" + uid + "/documents";
-        return httpClient.delete(urlPath, TaskInfo.class);
+        return httpClient.<TaskInfo>delete(new DocumentsQuery().toQuery(uid), TaskInfo.class);
     }
 }

src/main/java/com/meilisearch/sdk/Index.java

@@ -1,7 +1,9 @@
 package com.meilisearch.sdk;
 
 import com.meilisearch.sdk.exceptions.MeilisearchException;
+import com.meilisearch.sdk.model.DocumentsQuery;
 import com.meilisearch.sdk.model.IndexStats;
+import com.meilisearch.sdk.model.Results;
 import com.meilisearch.sdk.model.SearchResult;
 import com.meilisearch.sdk.model.Settings;
 import com.meilisearch.sdk.model.Task;
@@ -49,63 +51,107 @@ void setConfig(Config config) {
      * Gets a documents with the specified uid Refer
      * https://docs.meilisearch.com/reference/api/documents.html#get-one-document
      *
+     * @param <T> Type of documents returned
      * @param identifier Identifier of the document to get
-     * @return Meilisearch API response
+     * @param targetClass Class of the document returned
+     * @return Object containing the requested document
+     * @throws MeilisearchException if an error occurs
+     */
+    public <T> T getDocument(String identifier, Class<T> targetClass) throws MeilisearchException {
+        return this.documents.<T>getDocument(this.uid, identifier, targetClass);
+    }
+
+    /**
+     * Gets a documents with the specified uid Refer
+     * https://docs.meilisearch.com/reference/api/documents.html#get-one-document
+     *
+     * @param <T> Type of documents returned
+     * @param identifier Identifier of the document to get
+     * @param param accepted by the get document route
+     * @param targetClass Class of documents returned
+     * @return Object containing the requested document
      * @throws MeilisearchException if an error occurs
      */
-    public String getDocument(String identifier) throws MeilisearchException {
-        return this.documents.getDocument(this.uid, identifier);
+    public <T> T getDocument(String identifier, DocumentsQuery param, Class<T> targetClass)
+            throws MeilisearchException {
+        return this.documents.<T>getDocument(this.uid, identifier, param, targetClass);
     }
 
     /**
-     * Gets documenta at the specified index Refer
+     * Gets a documents with the specified uid Refer
+     * https://docs.meilisearch.com/reference/api/documents.html#get-one-document
+     *
+     * @param identifier Identifier of the document to get
+     * @return String containing the requested document
+     * @throws MeilisearchException if an error occurs
+     */
+    public String getRawDocument(String identifier) throws MeilisearchException {
+        return this.documents.getRawDocument(this.uid, identifier);
+    }
+
+    /**
+     * Gets a document with the specified uid and parameters
+     * https://docs.meilisearch.com/reference/api/documents.html#get-one-document
+     *
+     * @param identifier Identifier of the document to get
+     * @param param accept by the documents route
+     * @return String containing the requested document
+     * @throws MeilisearchException if an error occurs
+     */
+    public String getRawDocument(String identifier, DocumentsQuery param)
+            throws MeilisearchException {
+        return this.documents.getRawDocument(this.uid, identifier, param);
+    }
+
+    /**
+     * Gets documents at the specified index Refer
      * https://docs.meilisearch.com/reference/api/documents.html#get-documents
      *
-     * @return Meilisearch API response
+     * @param <T> Type of documents returned
+     * @param targetClass Class of documents returned
+     * @return Results containing a list of Object containing the requested document
      * @throws MeilisearchException if an error occurs
      */
-    public String getDocuments() throws MeilisearchException {
-        return this.documents.getDocuments(this.uid);
+    public <T> Results<T> getDocuments(Class<T> targetClass) throws MeilisearchException {
+        return this.documents.getDocuments(this.uid, targetClass);
     }
 
     /**
-     * Gets documents at the specified index and limit the number of documents returned Refer
+     * Gets documents at the specified index Refer
      * https://docs.meilisearch.com/reference/api/documents.html#get-documents
      *
-     * @param limits Maximum amount of documents to return
-     * @return Meilisearch API response
+     * @param <T> Type of documents returned
+     * @param param accept by the documents route
+     * @param targetClass Class of documents returned
+     * @return Results containing a list of Object containing the requested document
      * @throws MeilisearchException if an error occurs
      */
-    public String getDocuments(int limits) throws MeilisearchException {
-        return this.documents.getDocuments(this.uid, limits);
+    public <T> Results<T> getDocuments(DocumentsQuery param, Class<T> targetClass)
+            throws MeilisearchException {
+        return this.documents.getDocuments(this.uid, param, targetClass);
     }
 
     /**
-     * Gets documents at the specified index and limit the number of documents returned Refer
+     * Gets documents as String at the specified index Refer
      * https://docs.meilisearch.com/reference/api/documents.html#get-documents
      *
-     * @param limits Maximum amount of documents to return
-     * @param offset Number of documents to skip
-     * @return Meilisearch API response
+     * @return String containing a list of documents
      * @throws MeilisearchException if an error occurs
      */
-    public String getDocuments(int limits, int offset) throws MeilisearchException {
-        return this.documents.getDocuments(this.uid, limits, offset);
+    public String getRawDocuments() throws MeilisearchException {
+        return this.documents.getRawDocuments(this.uid);
     }
 
     /**
-     * Gets documents at the specified index and limit the number of documents returned Refer
+     * Gets documents as String at the specified index Refer
      * https://docs.meilisearch.com/reference/api/documents.html#get-documents
      *
-     * @param limits Maximum amount of documents to return
-     * @param offset Number of documents to skip
-     * @param attributesToRetrieve Document attributes to show
-     * @return Meilisearch API response
+     * @param param accept by the documents route
+     * @return String containing a list of documents
      * @throws MeilisearchException if an error occurs
      */
-    public String getDocuments(int limits, int offset, List<String> attributesToRetrieve)
-            throws MeilisearchException {
-        return this.documents.getDocuments(this.uid, limits, offset, attributesToRetrieve);
+    public String getRawDocuments(DocumentsQuery param) throws MeilisearchException {
+        return this.documents.getRawDocuments(this.uid, param);
     }
 
     /**