Add support for per-request options (#388)

* feat(request-options): Add support for per-request options

WIP: This is an “empty shell” so far: it supports adding untyped headers, but that’s pretty much all.

* feat(request-options): Support URL parameters in request options

This required a refactoring of the raw request methods to separate the URL parameters (the query string) from the rest of the URL (up to the path).

* test(request-options): Add test for URL parameters in request options

Author: Clément Le Provost

algoliasearch/src/main/java/com/algolia/search/saas/AbstractClient.java

@@ -398,28 +398,28 @@ private enum Method {
         GET, POST, PUT, DELETE
     }
 
-    protected byte[] getRequestRaw(String url, boolean search) throws AlgoliaException {
-        return _requestRaw(Method.GET, url, null, getReadHostsThatAreUp(), connectTimeout, search ? searchTimeout : readTimeout);
+    protected byte[] getRequestRaw(@NonNull String url, @Nullable Map<String, String> urlParameters, boolean search, @Nullable RequestOptions requestOptions) throws AlgoliaException {
+        return _requestRaw(Method.GET, url, urlParameters, /* json: */ null, getReadHostsThatAreUp(), connectTimeout, search ? searchTimeout : readTimeout, requestOptions);
     }
 
-    protected JSONObject getRequest(String url, boolean search) throws AlgoliaException {
-        return _request(Method.GET, url, null, getReadHostsThatAreUp(), connectTimeout, search ? searchTimeout : readTimeout);
+    protected JSONObject getRequest(@NonNull String url, @Nullable Map<String, String> urlParameters, boolean search, @Nullable RequestOptions requestOptions) throws AlgoliaException {
+        return _request(Method.GET, url, urlParameters, /* json: */ null, getReadHostsThatAreUp(), connectTimeout, search ? searchTimeout : readTimeout, requestOptions);
     }
 
-    protected JSONObject deleteRequest(String url) throws AlgoliaException {
-        return _request(Method.DELETE, url, null, getWriteHostsThatAreUp(), connectTimeout, readTimeout);
+    protected JSONObject deleteRequest(@NonNull String url, @Nullable Map<String, String> urlParameters, @Nullable RequestOptions requestOptions) throws AlgoliaException {
+        return _request(Method.DELETE, url, urlParameters, /* json: */ null, getWriteHostsThatAreUp(), connectTimeout, readTimeout, requestOptions);
     }
 
-    protected JSONObject postRequest(String url, String obj, boolean readOperation) throws AlgoliaException {
-        return _request(Method.POST, url, obj, (readOperation ? getReadHostsThatAreUp() : getWriteHostsThatAreUp()), connectTimeout, (readOperation ? searchTimeout : readTimeout));
+    protected JSONObject postRequest(@NonNull String url, @Nullable Map<String, String> urlParameters, @Nullable String obj, boolean readOperation, @Nullable RequestOptions requestOptions) throws AlgoliaException {
+        return _request(Method.POST, url, urlParameters, obj, (readOperation ? getReadHostsThatAreUp() : getWriteHostsThatAreUp()), connectTimeout, (readOperation ? searchTimeout : readTimeout), requestOptions);
     }
 
-    protected byte[] postRequestRaw(String url, String obj, boolean readOperation) throws AlgoliaException {
-        return _requestRaw(Method.POST, url, obj, (readOperation ? getReadHostsThatAreUp() : getWriteHostsThatAreUp()), connectTimeout, (readOperation ? searchTimeout : readTimeout));
+    protected byte[] postRequestRaw(@NonNull String url, @Nullable Map<String, String> urlParameters, @Nullable String obj, boolean readOperation, @Nullable RequestOptions requestOptions) throws AlgoliaException {
+        return _requestRaw(Method.POST, url, urlParameters, obj, (readOperation ? getReadHostsThatAreUp() : getWriteHostsThatAreUp()), connectTimeout, (readOperation ? searchTimeout : readTimeout), requestOptions);
     }
 
-    protected JSONObject putRequest(String url, String obj) throws AlgoliaException {
-        return _request(Method.PUT, url, obj, getWriteHostsThatAreUp(), connectTimeout, readTimeout);
+    protected JSONObject putRequest(@NonNull String url, @Nullable Map<String, String> urlParameters, @NonNull String obj, @Nullable RequestOptions requestOptions) throws AlgoliaException {
+        return _request(Method.PUT, url, urlParameters, obj, getWriteHostsThatAreUp(), connectTimeout, readTimeout, requestOptions);
     }
 
     /**
@@ -482,17 +482,18 @@ private static JSONObject _getAnswerJSONObject(InputStream istream) throws IOExc
      * Send the query according to parameters and returns its result as a JSONObject
      *
      * @param m              HTTP Method to use
-     * @param url            endpoint URL
+     * @param url            Endpoint URL, *without query string*. The query string is handled by `urlParameters`.
+     * @param urlParameters  URL parameters
      * @param json           optional JSON Object to send
      * @param hostsArray     array of hosts to try successively
      * @param connectTimeout maximum wait time to open connection
      * @param readTimeout    maximum time to read data on socket
      * @return a JSONObject containing the resulting data or error
      * @throws AlgoliaException if the request data is not valid json
      */
-    private JSONObject _request(Method m, String url, String json, List<String> hostsArray, int connectTimeout, int readTimeout) throws AlgoliaException {
+    private JSONObject _request(@NonNull Method m, @NonNull String url, @Nullable Map<String, String> urlParameters, @Nullable String json, @NonNull List<String> hostsArray, int connectTimeout, int readTimeout, @Nullable RequestOptions requestOptions) throws AlgoliaException {
         try {
-            return _getJSONObject(_requestRaw(m, url, json, hostsArray, connectTimeout, readTimeout));
+            return _getJSONObject(_requestRaw(m, url, urlParameters, json, hostsArray, connectTimeout, readTimeout, requestOptions));
         } catch (JSONException e) {
             throw new AlgoliaException("JSON decode error:" + e.getMessage());
         } catch (UnsupportedEncodingException e) {
@@ -504,15 +505,16 @@ private JSONObject _request(Method m, String url, String json, List<String> host
      * Send the query according to parameters and returns its result as a JSONObject
      *
      * @param m              HTTP Method to use
-     * @param url            endpoint URL
-     * @param json           optional JSON Object to send
+     * @param url            Endpoint URL, *without query string*. The query string is handled by `urlParameters`.
+     * @param urlParameters  URL parameters
+     * @param json           (optional) JSON body
      * @param hostsArray     array of hosts to try successively
      * @param connectTimeout maximum wait time to open connection
      * @param readTimeout    maximum time to read data on socket
      * @return a JSONObject containing the resulting data or error
      * @throws AlgoliaException in case of connection or data handling error
      */
-    private byte[] _requestRaw(Method m, String url, String json, List<String> hostsArray, int connectTimeout, int readTimeout) throws AlgoliaException {
+    private byte[] _requestRaw(@NonNull Method m, @NonNull String url, @Nullable Map<String, String> urlParameters, @Nullable String json, @NonNull List<String> hostsArray, int connectTimeout, int readTimeout, @Nullable RequestOptions requestOptions) throws AlgoliaException {
         String requestMethod;
         List<Exception> errors = new ArrayList<>(hostsArray.size());
         // for each host
@@ -536,17 +538,32 @@ private byte[] _requestRaw(Method m, String url, String json, List<String> hosts
 
             InputStream stream = null;
             HttpURLConnection hostConnection = null;
-            // set URL
             try {
-                URL hostURL = new URL("https://" + host + url);
+                // Compute final URL parameters.
+                final Map<String, String> parameters = new HashMap<>();
+                if (urlParameters != null) {
+                    parameters.putAll(urlParameters);
+                }
+                if (requestOptions != null) {
+                    parameters.putAll(requestOptions.urlParameters);
+                }
+
+                // Build URL.
+                String urlString = "https://" + host + url;
+                if (!parameters.isEmpty()) {
+                    urlString += "?" + AbstractQuery.build(parameters);
+                }
+                URL hostURL = new URL(urlString);
+
+                // Open connection.
                 hostConnection = (HttpURLConnection) hostURL.openConnection();
 
                 //set timeouts
                 hostConnection.setRequestMethod(requestMethod);
                 hostConnection.setConnectTimeout(connectTimeout);
                 hostConnection.setReadTimeout(readTimeout);
 
-                // set auth headers
+                // Headers
                 hostConnection.setRequestProperty("X-Algolia-Application-Id", this.applicationID);
                 // If API key is too big, send it in the request's body (if applicable).
                 if (this.apiKey != null && this.apiKey.length() > MAX_API_KEY_LENGTH && json != null) {
@@ -560,9 +577,16 @@ private byte[] _requestRaw(Method m, String url, String json, List<String> hosts
                 } else {
                     hostConnection.setRequestProperty("X-Algolia-API-Key", this.apiKey);
                 }
+                // Client-level headers
                 for (Map.Entry<String, String> entry : this.headers.entrySet()) {
                     hostConnection.setRequestProperty(entry.getKey(), entry.getValue());
                 }
+                // Request-level headers
+                if (requestOptions != null) {
+                    for (Map.Entry<String, String> entry : requestOptions.headers.entrySet()) {
+                        hostConnection.setRequestProperty(entry.getKey(), entry.getValue());
+                    }
+                }
 
                 // set user agent
                 hostConnection.setRequestProperty("User-Agent", userAgentRaw);

algoliasearch/src/main/java/com/algolia/search/saas/AbstractQuery.java

@@ -113,6 +113,14 @@ public int hashCode() {
     // NOTE: Using a tree map to have parameters sorted by key on output.
     @NonNull private Map<String, String> parameters = new TreeMap<>();
 
+    /**
+     * Access the store of query parameters. For internal use only.
+     * @return The parameters in this query.
+     */
+    Map<String, String> getParameters() {
+        return parameters;
+    }
+
     // ----------------------------------------------------------------------
     // Construction
     // ----------------------------------------------------------------------
@@ -167,6 +175,14 @@ public int hashCode() {
      * @return A string suitable for use inside the query part of a URL (i.e. after the question mark).
      */
     public @NonNull String build() {
+        return build(parameters);
+    }
+
+    /**
+     * Build a query string from a map of URL parameters.
+     * @return A string suitable for use inside the query part of a URL (i.e. after the question mark).
+     */
+    static @NonNull String build(@NonNull Map<String, String> parameters) {
         StringBuilder stringBuilder = new StringBuilder();
         try {
             for (Map.Entry<String, String> entry : parameters.entrySet()) {