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