001package com.box.sdk;
002
003/**
004 * The interface for intercepting requests to the Box API.
005 *
006 * <p>An interceptor may handle a request in any way it sees fit. It may update a request before
007 * it's sent, or it may choose to return a custom response. If an interceptor returns a null
008 * response, then the request will continue to be sent to the API along with any changes that the
009 * interceptor may have made to it.
010 *
011 * <pre>public BoxAPIResponse onRequest(BoxAPIRequest request) {
012 *    request.addHeader("My-Header", "My-Value");
013 *
014 *    // Returning null means the request will be sent along with our new header.
015 *    return null;
016 * }</pre>
017 *
018 * <p>However, if a response is returned, then the request won't be sent and the interceptor's
019 * response will take the place of the normal response.
020 *
021 * <pre>public BoxAPIResponse onRequest(BoxAPIRequest request) {
022 *    // Returning our own response means the request won't be sent at all.
023 *    return new BoxAPIResponse();
024 * }</pre>
025 *
026 * <p>A RequestInterceptor can be very useful for testing purposes. Requests to the Box API can be
027 * intercepted and fake responses can be returned, allowing you to effectively test your code
028 * without needing to actually communicate with the Box API.
029 */
030public interface RequestInterceptor {
031  /**
032   * Invoked when a request is about to be sent to the API.
033   *
034   * @param request the request that is about to be sent.
035   * @return an optional response to the request. If the response is null, then the request will
036   *     continue to be sent to the Box API.
037   */
038  BoxAPIResponse onRequest(BoxAPIRequest request);
039}