Add support for multiple query parameter values

This changes the API to `List<String>` for each parameter value.  Even though most cases don't require this, it's important we provide functionality for it.  In the future maybe we can make the API a bit better around these use cases.

Author: jentfoo

client/src/main/java/org/threadly/litesockets/client/http/HTTPClient.java

@@ -171,12 +171,18 @@ public void closeAllClients() {
    * Sets the default timeout in milliseconds to wait for HTTPRequest responses from the server.
    * 
    * @param timeout time in milliseconds to wait for HTTPRequests to finish.
+   * @param unit The unit the {@code timeout} value is represented in
    */
   public void setTimeout(long timeout, TimeUnit unit) {
     this.defaultTimeoutMS = Math.min(Math.max(unit.toMillis(timeout),HTTPRequest.MIN_TIMEOUT_MS), 
                                      HTTPRequest.MAX_TIMEOUT_MS);
   }
 
+  /**
+   * Checks the configured maximum connection idle time.
+   * 
+   * @return The number of milliseconds until an idle connection is closed
+   */
   public long getMaxIdleTimeout() {
     return this.maxIdleTime;
   }
@@ -185,10 +191,11 @@ public long getMaxIdleTimeout() {
    * Sets the max amount of time we will hold onto idle connections.  A 0 means we close connections when done, less
    * than zero means we will never expire connections.
    * 
-   * @param it the time in milliseconds to wait before timing out a connection.
+   * @param idleTimeout the time in milliseconds to wait before timing out a connection.
+   * @param unit The unit the {@code idleTimeout} value is represented in
    */
-  public void setMaxIdleTimeout(long it, TimeUnit unit) {
-    this.maxIdleTime = unit.toMillis(it);
+  public void setMaxIdleTimeout(long idleTimeout, TimeUnit unit) {
+    this.maxIdleTime = unit.toMillis(idleTimeout);
     if(this.maxIdleTime > 0) {
       this.checkIdle = new Runnable() {
         @Override
@@ -207,7 +214,7 @@ public void run() {
    * Sends a blocking HTTP request.
    * 
    * @param url the url to send the request too.
-   * @return an {@link HTTPResponseData} object containing the headers and content of the response.
+   * @return A {@link HTTPResponseData} object containing the headers and content of the response.
    * @throws HTTPParsingException is thrown if the server sends back protocol or a response that is larger then allowed.
    */
   public HTTPResponseData request(final URL url) throws HTTPParsingException {
@@ -220,7 +227,7 @@ public HTTPResponseData request(final URL url) throws HTTPParsingException {
    * @param url the url to send the request too.
    * @param rm the {@link HTTPRequestMethod} to use on the request.
    * @param bb the data to put in the body for this request.
-   * @return an {@link HTTPResponseData} object containing the headers and content of the response.
+   * @return A {@link HTTPResponseData} object containing the headers and content of the response.
    * @throws HTTPParsingException is thrown if the server sends back protocol or a response that is larger then allowed.
    */
   public HTTPResponseData request(final URL url, final HTTPRequestMethod rm, final ByteBuffer bb) throws HTTPParsingException {
@@ -242,12 +249,8 @@ public HTTPResponseData request(final URL url, final HTTPRequestMethod rm, final
   /**
    * Sends a blocking HTTP request.
    * 
-   * @param ha the {@link HTTPAddress} to connect to, any hostname in the actual HTTPRequest will just be sent in the protocol. 
    * @param request the {@link HTTPRequest} to send the server once connected.
-   * @param body the body to send with this request.  You must have set the {@link HTTPRequest} correctly for this body.
-   * @param unit the time unit of the timeout argument 
-   * @param timeout the maximum time to wait
-   * @return an {@link HTTPResponseData} object containing the headers and content of the response.
+   * @return A {@link HTTPResponseData} object containing the headers and content of the response.
    * @throws HTTPParsingException is thrown if the server sends back protocol or a response that is larger then allowed.
    */
   public HTTPResponseData request(final ClientHTTPRequest request) throws HTTPParsingException {
@@ -272,7 +275,7 @@ public HTTPResponseData request(final ClientHTTPRequest request) throws HTTPPars
    * Sends an asynchronous HTTP request.
    * 
    * @param url the {@link URL} to send the request too.
-   * @return an {@link ListenableFuture} containing a {@link HTTPResponseData} object that will be completed when the request is finished, 
+   * @return A {@link ListenableFuture} containing a {@link HTTPResponseData} object that will be completed when the request is finished, 
    * successfully or with errors.
    */
   public ListenableFuture<HTTPResponseData> requestAsync(final URL url) {
@@ -285,7 +288,7 @@ public ListenableFuture<HTTPResponseData> requestAsync(final URL url) {
    * @param url the {@link URL} to send the request too.
    * @param rm the {@link HTTPRequestMethod} to use on the request.
    * @param bb the data to put in the body for this request.
-   * @return an {@link ListenableFuture} containing a {@link HTTPResponseData} object that will be completed when the request is finished, 
+   * @return A {@link ListenableFuture} containing a {@link HTTPResponseData} object that will be completed when the request is finished, 
    * successfully or with errors.
    */
   public ListenableFuture<HTTPResponseData> requestAsync(final URL url, final HTTPRequestMethod rm, 
@@ -302,11 +305,7 @@ public ListenableFuture<HTTPResponseData> requestAsync(final URL url, final HTTP
   /**
    * Sends an asynchronous HTTP request.
    * 
-   * @param ha the {@link HTTPAddress} to connect to, any hostname in the actual HTTPRequest will just be sent in the protocol. 
    * @param request the {@link HTTPRequest} to send the server once connected.
-   * @param body the body to send with this request.  You must have set the {@link HTTPRequest} correctly for this body.
-   * @param unit the time unit of the timeout argument 
-   * @param timeout the maximum time to wait
    * @return an {@link ListenableFuture} containing a {@link HTTPResponseData} object that will be completed when the request is finished, 
    * successfully or with errors.
    */
@@ -509,7 +508,8 @@ public void onRead(Client client) {
   }
 
   /**
-   * 
+   * Wrapper for the request that will handle the incoming response data (as well as notifying 
+   * back to the client once the response is complete).
    */
   private class HTTPRequestWrapper implements HTTPResponseCallback {
     private final SettableListenableFuture<HTTPResponseData> slf = new SettableListenableFuture<>(false);

client/src/main/java/org/threadly/litesockets/client/http/HTTPStreamClient.java

@@ -62,12 +62,17 @@ public class HTTPStreamClient implements StreamingClient {
    * Creates an HTTPStreaming client from an already existing TCPClient.
    * 
    * @param client the {@link TCPClient} to use for this connection.
-   * @param headerSent true if the http headers have already been sent, false if they still need to be sent.
    */
   public HTTPStreamClient(TCPClient client) {
     this(client, client.getRemoteSocketAddress().getHostName());
   }
-  
+
+  /**
+   * Creates an HTTPStreaming client from an already existing TCPClient.
+   * 
+   * @param client the {@link TCPClient} to use for this connection.
+   * @param host the hostname or ip address to connect to.
+   */
   public HTTPStreamClient(TCPClient client, String host) {
     this.client = client;
     this.host = host;

client/src/main/java/org/threadly/litesockets/client/ws/WebSocketClient.java

@@ -71,7 +71,6 @@ public class WebSocketClient implements StreamingClient {
    * This takes over an existing TCPClient to do websocket communications. 
    * 
    * @param client the TCPClient to use for this connection.
-   * @param alreadyUpgraded true if the connection has already upgraded to do websockets false if the http upgrade is still required.
    */
   public WebSocketClient(final TCPClient client) {
     if(client.isClosed()) {
@@ -196,7 +195,7 @@ public boolean getPingAutoReply() {
    * Sets the default {@link WebSocketOpCode} to use when calling {@link #write(ByteBuffer)}.
    * 
    * Only standard WebSocket OpCodes can be used as a "default" to use anything other then the 
-   * standard OpCodes use the {@link #write(ByteBuffer, byte, boolean)} method.
+   * standard OpCodes use the {@link #write(ByteBuffer, WebSocketOpCode, boolean)} method.
    * 
    * @param wsoc the default {@link WebSocketOpCode} to use on this connection.
    */

gradle.properties

@@ -1,5 +1,5 @@
 group = org.threadly
-version = 0.16
-threadlyVersion = 5.16
+version = 0.17
+threadlyVersion = 5.18
 litesocketsVersion = 4.3
 org.gradle.parallel=true

protocol/src/main/java/org/threadly/litesockets/protocols/http/request/HTTPRequestBuilder.java

@@ -3,7 +3,9 @@
 import java.net.URL;
 import java.nio.ByteBuffer;
 import java.nio.charset.Charset;
+import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.Map.Entry;
 import java.util.TreeMap;
@@ -152,8 +154,8 @@ public HTTPRequestBuilder setQueryString(final String query) {
    * @return the current {@link HTTPRequestBuilder} object.
    */
   public HTTPRequestBuilder appendQuery(final String key, final String value) {
-    HashMap<String, String> map = new HashMap<String, String>(request.getRequestQuery());
-    map.put(key, value);
+    HashMap<String, List<String>> map = new HashMap<>(request.getRequestQuery());
+    map.computeIfAbsent(key, (ignored) -> new ArrayList<>(1)).add(value);
     this.request = new HTTPRequestHeader(request.getRequestMethod(), request.getRequestPath(), map, request.getHttpVersion());
     return this;
   }
@@ -165,7 +167,7 @@ public HTTPRequestBuilder appendQuery(final String key, final String value) {
    * @return the current {@link HTTPRequestBuilder} object.
    */
   public HTTPRequestBuilder removeQuery(final String key) {
-    HashMap<String, String> map = new HashMap<String, String>(request.getRequestQuery());
+    HashMap<String, List<String>> map = new HashMap<>(request.getRequestQuery());
     map.remove(key);
     this.request = new HTTPRequestHeader(request.getRequestMethod(), request.getRequestPath(), map, request.getHttpVersion());
     return this;
@@ -174,7 +176,7 @@ public HTTPRequestBuilder removeQuery(final String key) {
 
   /**
    * Sets the {@link HTTPAddress} for this builder.  This will add a Host header into the headers of this builder
-   * when this object it built.  This is also used with the {@link #buildHTTPAddress(boolean)} method.
+   * when this object it built.  This is also used with the {@link #buildHTTPAddress()} method.
    * 
    * @param ha the {@link HTTPAddress} to be set.
    * @return the current {@link HTTPRequestBuilder} object.
@@ -187,7 +189,7 @@ public HTTPRequestBuilder setHTTPAddress(final HTTPAddress ha) {
   }
 
   /**
-   * Sets the Host: header in the client.  This is also used with the {@link #buildHTTPAddress(boolean)} method.
+   * Sets the Host: header in the client.  This is also used with the {@link #buildHTTPAddress()} method.
    * Setting to null will remove this header.
    * 
    * 
@@ -204,14 +206,19 @@ public HTTPRequestBuilder setHost(final String host) {
     return this;
   }
 
+  /**
+   * Sets if the request should be made using ssl or not.
+   * 
+   * @param doSSL {@code true} if ssl should be used.
+   * @return the current {@link HTTPRequestBuilder} object.
+   */
   public HTTPRequestBuilder setSSL(final boolean doSSL) {
     this.doSSL = doSSL;
     return this;
   }
 
-
   /**
-   * This sets the port to use in the {@link #buildHTTPAddress(boolean)} method.  If not set the default port
+   * This sets the port to use in the {@link #buildHTTPAddress()} method.  If not set the default port
    * for the protocol type (http or https) will be used.
    * 
    * @param port port number to set.

protocol/src/main/java/org/threadly/litesockets/protocols/http/request/HTTPRequestHeader.java

@@ -3,6 +3,7 @@
 import java.nio.ByteBuffer;
 import java.util.Collections;
 import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
 
 import org.threadly.litesockets.protocols.http.shared.HTTPConstants;
@@ -19,7 +20,7 @@ public class HTTPRequestHeader {
   private final String rawRequest;
   private final String requestMethod;
   private final String requestPath;
-  private final Map<String, String> requestQuery;
+  private final Map<String, List<String>> requestQuery;
   private final String httpVersion;
 
   /**
@@ -60,7 +61,7 @@ public HTTPRequestHeader(final String requestHeader) {
    * @param httpVersion the httpVersion to set.
    */
   public HTTPRequestHeader(HTTPRequestMethod requestMethod, String requestPath, 
-                           Map<String, String> requestQuery, String httpVersion){
+                           Map<String, List<String>> requestQuery, String httpVersion){
     this(requestMethod.toString(), requestPath, requestQuery, httpVersion);
   }
 
@@ -74,9 +75,9 @@ public HTTPRequestHeader(HTTPRequestMethod requestMethod, String requestPath,
    * @param httpVersion the httpVersion to set.
    */
   public HTTPRequestHeader(String requestMethod, String requestPath, 
-                           Map<String, String> requestQuery, String httpVersion){
+                           Map<String, List<String>> requestQuery, String httpVersion){ // TODO
     this.requestMethod = requestMethod;
-    final LinkedHashMap<String, String> rqm = new LinkedHashMap<>();
+    final LinkedHashMap<String, List<String>> rqm = new LinkedHashMap<>();
     int queryParamPos = requestPath.indexOf("?");
     if(queryParamPos >= 0) {
       this.requestPath = requestPath.substring(0, queryParamPos);
@@ -132,10 +133,27 @@ public String getRequestPath() {
    *  
    * @return the request query.
    */
-  public Map<String, String> getRequestQuery() {
+  public Map<String, List<String>> getRequestQuery() {
     return requestQuery;
   }
 
+  /**
+   * Gets the value to a given query parameter.  This will throw an exception if there is multiple 
+   * values associated to the key.
+   *  
+   * @return the request parameter value or {@code null} if none is associated
+   */
+  public String getRequestQueryValue(String paramKey) {
+    List<String> values = requestQuery.get(paramKey);
+    if (values == null || values.isEmpty()) {
+      return null;
+    } else if (values.size() > 1) {
+      throw new IllegalStateException("Multiple values for parameter: " + paramKey);
+    } else {
+      return values.get(0);
+    }
+  }
+  
   /**
    * Gets the http version.
    * 

protocol/src/main/java/org/threadly/litesockets/protocols/http/shared/HTTPUtils.java

@@ -1,8 +1,10 @@
 package org.threadly.litesockets.protocols.http.shared;
 
 import java.nio.ByteBuffer;
+import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 
 import org.threadly.litesockets.buffers.MergedByteBuffers;
@@ -51,32 +53,40 @@ public static ByteBuffer wrapInChunk(ByteBuffer bb) {
     return newBB;
   }
 
-  public static String queryToString(Map<String,String> map) {
+  public static String queryToString(Map<String, List<String>> map) {
     if(map.isEmpty()) {
       return "";
     }
 
     StringBuilder sb = new StringBuilder();
     sb.append('?');
-    for(String k: map.keySet()) {
-      if(sb.length() > 1) {
-        sb.append('&');  
-      }
-      sb.append(k);
-      String v = map.get(k);
-      if(! StringUtils.isNullOrEmpty(v)) {
-        sb.append('=');
-        sb.append(v);
+    for(Map.Entry<String, List<String>> e : map.entrySet()) {
+      if (e.getValue() == null || e.getValue().isEmpty()) {
+        if(sb.length() > 1) {
+          sb.append('&');  
+        }
+        sb.append(e.getKey());
+      } else {
+        for (String v : e.getValue()) {
+          if(sb.length() > 1) {
+            sb.append('&');  
+          }
+          sb.append(e.getKey());
+          if(! StringUtils.isNullOrEmpty(v)) {
+            sb.append('=');
+            sb.append(v);
+          }
+        }
       }
     }
     return sb.toString();
   }
 
-  public static Map<String, String> queryToMap(String query) {
+  public static Map<String, List<String>> queryToMap(String query) {
     if (StringUtils.isNullOrEmpty(query)) {
       return Collections.emptyMap();
     }
-    Map<String, String> map = new HashMap<>();
+    Map<String, List<String>> map = new HashMap<>();
     if(query.startsWith("?")) {
       query = query.substring(1);
     } else if (query.contains("?")){
@@ -90,10 +100,11 @@ public static Map<String, String> queryToMap(String query) {
         // case where either no `=` or empty key string
         continue;
       }
+      List<String> paramValues = map.computeIfAbsent(tmpkv[0], (ignored) -> new ArrayList<>(1));
       if(tmpkv.length == 1) {
-        map.put(tmpkv[0].trim(), "");
+        paramValues.add("");
       } else {
-        map.put(tmpkv[0].trim(), tmpkv[1].trim());
+        paramValues.add(tmpkv[1].trim());
       }
     }
     return Collections.unmodifiableMap(map);