Add support for request interceptors

Request interceptors have the opportunity to manipulate requests before
they're sent to the API. They may also return their own custom response
which can be used in place of a normal API response.

Author: gcurtis

src/main/java/com/box/sdk/BoxAPIConnection.java

@@ -49,6 +49,7 @@ public class BoxAPIConnection {
     private boolean autoRefresh;
     private int maxRequestAttempts;
     private List<BoxAPIConnectionListener> listeners;
+    private RequestInterceptor interceptor;
 
     /**
      * Constructs a new BoxAPIConnection that authenticates with a developer or access token.
@@ -374,4 +375,20 @@ public void addListener(BoxAPIConnectionListener listener) {
     public void removeListener(BoxAPIConnectionListener listener) {
         this.listeners.remove(listener);
     }
+
+    /**
+     * Gets the RequestInterceptor associated with this API connection.
+     * @return the RequestInterceptor associated with this API connection.
+     */
+    public RequestInterceptor getRequestInterceptor() {
+        return this.interceptor;
+    }
+
+    /**
+     * Sets a RequestInterceptor that can intercept requests and manipulate them before they're sent to the Box API.
+     * @param interceptor the RequestInterceptor.
+     */
+    public void setRequestInterceptor(RequestInterceptor interceptor) {
+        this.interceptor = interceptor;
+    }
 }

src/main/java/com/box/sdk/BoxAPIRequest.java

@@ -308,6 +308,16 @@ void setBackoffCounter(BackoffCounter counter) {
     }
 
     private BoxAPIResponse trySend(ProgressListener listener) {
+        if (this.api != null) {
+            RequestInterceptor interceptor = this.api.getRequestInterceptor();
+            if (interceptor != null) {
+                BoxAPIResponse response = interceptor.onRequest(this);
+                if (response != null) {
+                    return response;
+                }
+            }
+        }
+
         HttpURLConnection connection = this.createConnection();
 
         if (this.bodyLength > 0) {

src/main/java/com/box/sdk/BoxAPIResponse.java

@@ -44,6 +44,13 @@ public class BoxAPIResponse {
      */
     private InputStream inputStream;
 
+    /**
+     * Constructs an empty BoxAPIResponse without an associated HttpURLConnection.
+     */
+    public BoxAPIResponse() {
+        this.connection = null;
+    }
+
     /**
      * Constructs a BoxAPIResponse using an HttpURLConnection.
      * @param  connection a connection that has already sent a request to the API.

src/main/java/com/box/sdk/RequestInterceptor.java

@@ -0,0 +1,37 @@
+package com.box.sdk;
+
+/**
+ * The interface for intercepting requests to the Box API.
+ *
+ * <p>An interceptor may handle a request in any way it sees fit. It may update a request before it's sent, or it may
+ * choose to return a custom response. If an interceptor returns a null response, then the request will continue to be
+ * sent to the API along with any changes that the interceptor may have made to it.</p>
+ *
+ * <pre>public BoxAPIResponse onRequest(BoxAPIRequest request) {
+ *    request.addHeader("My-Header", "My-Value");
+ *
+ *    // Returning null means the request will be sent along with our new header.
+ *    return null;
+ *}</pre>
+ *
+ * <p>However, if a response is returned, then the request won't be sent and the interceptor's response will take the
+ * place of the normal response.</p>
+ *
+ * <pre>public BoxAPIResponse onRequest(BoxAPIRequest request) {
+ *    // Returning our own response means the request won't be sent at all.
+ *    return new BoxAPIResponse();
+ *}</pre>
+ *
+ * <p>A RequestInterceptor can be very useful for testing purposes. Requests to the Box API can be intercepted and fake
+ * responses can be returned, allowing you to effectively test your code without needing to actually communicate with
+ * the Box API.</p>
+ */
+public interface RequestInterceptor {
+    /**
+     * Invoked when a request is about to be sent to the API.
+     * @param  request the request that is about to be sent.
+     * @return         an optional response to the request. If the response is null, then the request will continue to
+     *                 be sent to the Box API.
+     */
+    BoxAPIResponse onRequest(BoxAPIRequest request);
+}

src/test/java/com/box/sdk/BoxAPIConnectionTest.java

@@ -1,9 +1,15 @@
 package com.box.sdk;
 
+import java.net.MalformedURLException;
+import java.net.URL;
+
 import static org.hamcrest.Matchers.equalTo;
 import static org.hamcrest.Matchers.is;
 import static org.hamcrest.Matchers.not;
 import static org.junit.Assert.assertThat;
+import static org.mockito.Matchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
 
 import org.junit.Test;
 import org.junit.experimental.categories.Category;
@@ -44,6 +50,38 @@ public void doesNotNeedRefreshWhenExpiresIsZero() {
         assertThat(api.needsRefresh(), is(not(true)));
     }
 
+    @Test
+    @Category(UnitTest.class)
+    public void interceptorReceivesSentRequest() throws MalformedURLException {
+        BoxAPIConnection api = new BoxAPIConnection("");
+
+        BoxAPIResponse fakeResponse = new BoxAPIResponse();
+
+        RequestInterceptor mockInterceptor = mock(RequestInterceptor.class);
+        when(mockInterceptor.onRequest(any(BoxAPIRequest.class))).thenReturn(fakeResponse);
+        api.setRequestInterceptor(mockInterceptor);
+
+        BoxAPIRequest request = new BoxAPIRequest(api, new URL("http://anyurl.com"), "GET");
+        BoxAPIResponse response = request.send();
+
+        assertThat(response, is(equalTo(fakeResponse)));
+    }
+
+    @Test
+    @Category(IntegrationTest.class)
+    public void requestIsSentNormallyWhenInterceptorReturnsNullResponse() throws MalformedURLException {
+        BoxAPIConnection api = new BoxAPIConnection("");
+
+        RequestInterceptor mockInterceptor = mock(RequestInterceptor.class);
+        when(mockInterceptor.onRequest(any(BoxAPIRequest.class))).thenReturn(null);
+        api.setRequestInterceptor(mockInterceptor);
+
+        BoxAPIRequest request = new BoxAPIRequest(api, new URL("http://box.com"), "GET");
+        BoxAPIResponse response = request.send();
+
+        assertThat(response.getResponseCode(), is(200));
+    }
+
     @Test
     @Category(IntegrationTest.class)
     public void refreshSucceeds() {