added framework-independent HttpRequest

this can be used in java-saml-core where previously we would use
HttpServletRequest, therefore removing the requirement for clients to be
running inside a servlet container.

Author: Luis Miranda

core/src/main/java/com/onelogin/saml2/http/HttpRequest.java

@@ -0,0 +1,129 @@
+package com.onelogin.saml2.http;
+
+import static com.onelogin.saml2.util.Preconditions.checkNotNull;
+import static java.util.Collections.unmodifiableList;
+import static java.util.Collections.unmodifiableMap;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * Framework-agnostic representation of an HTTP request.
+ *
+ * @since 2.0.0
+ */
+public final class HttpRequest {
+    private final String requestURL;
+    private final Map<String, List<String>> parameters;
+
+    /**
+     * Creates a new HttpRequest.
+     *
+     * @param requestURL the request URL (up to but not including query parameters)
+     * @throws NullPointerException if requestURL is null
+     */
+    public HttpRequest(String requestURL) {
+        this(requestURL, Collections.<String, List<String>>emptyMap());
+    }
+
+    /**
+     * Creates a new HttpRequest.
+     *
+     * @param requestURL  the request URL (up to but not including query parameters)
+     * @param parameters the request query parameters
+     * @throws NullPointerException if any of the parameters is null
+     */
+    public HttpRequest(String requestURL, Map<String, List<String>> parameters) {
+        this.requestURL = checkNotNull(requestURL, "requestURL");
+        this.parameters = unmodifiableCopyOf(checkNotNull(parameters, "queryParams"));
+    }
+
+    /**
+     * @param name  the query parameter name
+     * @param value the query parameter value
+     * @return a new HttpRequest with the given query parameter added
+     * @throws NullPointerException if any of the parameters is null
+     */
+    public HttpRequest addParameter(String name, String value) {
+        checkNotNull(name, "name");
+        checkNotNull(value, "value");
+
+        final List<String> oldValues = parameters.containsKey(name) ? parameters.get(name) : new ArrayList<String>();
+        final List<String> newValues = new ArrayList<>(oldValues);
+        newValues.add(value);
+        final Map<String, List<String>> params = new HashMap<>(parameters);
+        params.put(name, newValues);
+
+        return new HttpRequest(requestURL, params);
+    }
+
+    /**
+     * The URL the client used to make the request. Includes a protocol, server name, port number, and server path, but
+     * not the query string parameters.
+     *
+     * @return the request URL
+     */
+    public String getRequestURL() {
+        return requestURL;
+    }
+
+    /**
+     * @param name the query parameter name
+     * @return the first value for the parameter, or null
+     */
+    public String getParameter(String name) {
+        List<String> values = getParameters(name);
+        return values.isEmpty() ? null : values.get(0);
+    }
+
+    /**
+     * @param name the query parameter name
+     * @return a List containing all values for the parameter
+     */
+    public List<String> getParameters(String name) {
+        List<String> values = parameters.get(name);
+        return values != null ? values : Collections.<String>emptyList();
+    }
+
+    /**
+     * @return a map of all query parameters
+     */
+    public Map<String, List<String>> getParameters() {
+        return parameters;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        HttpRequest that = (HttpRequest) o;
+        return Objects.equals(requestURL, that.requestURL) &&
+                Objects.equals(parameters, that.parameters);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(requestURL, parameters);
+    }
+
+    @Override
+    public String toString() {
+        return "HttpRequest{" +
+                "requestURL='" + requestURL + '\'' +
+                ", parameters=" + parameters +
+                '}';
+    }
+
+    private static Map<String, List<String>> unmodifiableCopyOf(Map<String, List<String>> orig) {
+        Map<String, List<String>> copy = new HashMap<>();
+        for (Map.Entry<String, List<String>> entry : orig.entrySet()) {
+            copy.put(entry.getKey(), unmodifiableList(new ArrayList<>(entry.getValue())));
+        }
+
+        return unmodifiableMap(copy);
+    }
+}

core/src/main/java/com/onelogin/saml2/util/Preconditions.java

@@ -0,0 +1,22 @@
+package com.onelogin.saml2.util;
+
+public final class Preconditions {
+    /**
+     * Throws a NullPointerException if {@code t} is null.
+     *
+     * @param t       the value to check for null
+     * @param message the message to include in the thrown exception
+     * @return t
+     * @throws NullPointerException if {@code t} is null
+     */
+    public static <T> T checkNotNull(T t, String message) {
+        if (t == null) {
+            throw new NullPointerException(message);
+        } else {
+            return t;
+        }
+    }
+
+    private Preconditions() {
+    }
+}

core/src/test/java/com/onelogin/saml2/http/HttpRequestTest.java

@@ -0,0 +1,57 @@
+package com.onelogin.saml2.http;
+
+import static java.util.Collections.singletonList;
+import static java.util.Collections.singletonMap;
+import static org.hamcrest.CoreMatchers.equalTo;
+import static org.hamcrest.CoreMatchers.nullValue;
+import static org.junit.Assert.assertThat;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.Test;
+
+public class HttpRequestTest {
+    @Test
+    public void testConstructorWithNoQueryParams() throws Exception {
+        final String url = "url";
+
+        final HttpRequest request = new HttpRequest(url);
+        assertThat(request.getRequestURL(), equalTo(url));
+        assertThat(request.getParameters(), equalTo(Collections.<String, List<String>>emptyMap()));
+        assertThat(request.getParameters("x"), equalTo(Collections.<String>emptyList()));
+        assertThat(request.getParameter("x"), nullValue());
+    }
+
+    @Test
+    public void testConstructorWithQueryParams() throws Exception {
+        final String url = "url";
+        final String name = "name";
+        final String value1 = "val1";
+        final String value2 = "val2";
+
+        final List<String> values = Arrays.asList(value1, value2);
+        final Map<String, List<String>> parametersMap = singletonMap(name, values);
+
+        final HttpRequest request = new HttpRequest(url, parametersMap);
+        assertThat(request.getRequestURL(), equalTo(url));
+        assertThat(request.getParameters(), equalTo(parametersMap));
+        assertThat(request.getParameters(name), equalTo(values));
+        assertThat(request.getParameter(name), equalTo(value1));
+    }
+
+    @Test
+    public void testAddParameter() throws Exception {
+        final String url = "some_url";
+        final String name = "name";
+        final String value = "value";
+
+        final HttpRequest request = new HttpRequest(url).addParameter(name, value);
+        assertThat(request.getRequestURL(), equalTo(url));
+        assertThat(request.getParameters(), equalTo(singletonMap(name, singletonList(value))));
+        assertThat(request.getParameters(name), equalTo(singletonList(value)));
+        assertThat(request.getParameter(name), equalTo(value));
+    }
+}