001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2014-2015 ForgeRock AS.
015 */
016package org.forgerock.http.spi;
017
018import java.io.Closeable;
019import java.io.IOException;
020
021import org.forgerock.http.protocol.Request;
022import org.forgerock.http.protocol.Response;
023import org.forgerock.util.promise.NeverThrowsException;
024import org.forgerock.util.promise.Promise;
025
026/**
027 * An SPI interface for HTTP {@code Client} implementations. A
028 * {@link HttpClientProvider} is loaded during construction of a new HTTP
029 * {@link org.forgerock.http.Client Client}. The first available provider is
030 * selected and its {@link HttpClientProvider#newHttpClient(org.forgerock.util.Options)} method
031 * invoked in order to construct and configure a new {@link HttpClient}.
032 */
033public interface HttpClient extends Closeable {
034
035    /**
036     * Returns a {@link Promise} representing the asynchronous {@link Response} of the given {@code request}.
037     * If any (asynchronous) processing goes wrong, the promise still contains a {@link Response} (probably from the
038     * {@literal 4xx} or {@literal 5xx} status code family).
039     * <p>
040     * The returned {@link Promise} contains the response returned from the server as-is.
041     * This is responsibility of the client to produce the appropriate error response ({@literal 404},
042     * {@literal 500}, ...) in case of processing or transport errors.
043     *
044     * @param request
045     *            The HTTP request to send.
046     * @return A promise representing the pending HTTP response.
047     */
048    Promise<Response, NeverThrowsException> sendAsync(Request request);
049
050    /**
051     * Completes all pending requests and release resources associated with
052     * underlying implementation.
053     *
054     * @throws IOException if an I/O error occurs
055     */
056    @Override
057    void close() throws IOException;
058}