001/*
002 * ====================================================================
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *   http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing,
014 * software distributed under the License is distributed on an
015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
016 * KIND, either express or implied.  See the License for the
017 * specific language governing permissions and limitations
018 * under the License.
019 * ====================================================================
020 *
021 * This software consists of voluntary contributions made by many
022 * individuals on behalf of the Apache Software Foundation.  For more
023 * information on the Apache Software Foundation, please see
024 * <http://www.apache.org/>.
025 *
026 */
027
028package org.apache.http.nio.protocol;
029
030import org.apache.http.HttpRequest;
031import org.apache.http.HttpResponse;
032import org.apache.http.concurrent.Cancellable;
033
034/**
035 * {@code HttpAsyncExchange} represents a server-side HTTP message exchange
036 * where an HTTP response can be deferred without blocking the I/O event thread
037 * and triggered asynchronously at a later point of later time.
038 *
039 * @since 4.2
040 */
041public interface HttpAsyncExchange {
042
043    /**
044     * Returns the received HTTP request message.
045     *
046     * @return received HTTP request message.
047     */
048    HttpRequest getRequest();
049
050    /**
051     * Returns the default HTTP response message. Once ready the response
052     * message can submitted using {@link #submitResponse()} method.
053     *
054     * @return default HTTP response message.
055     */
056    HttpResponse getResponse();
057
058    /**
059     * Submits the default HTTP response and completed the message exchange.
060     * If the response encloses an {@link org.apache.http.HttpEntity} instance
061     * the entity is also expected to implement the
062     * {@link org.apache.http.nio.entity.HttpAsyncContentProducer }
063     * interface for efficient content streaming to a non-blocking HTTP
064     * connection.
065     *
066     * @throws IllegalStateException if a response has already been submitted.
067     */
068    void submitResponse();
069
070    /**
071     * Submits an HTTP response using a custom
072     * {@link HttpAsyncResponseProducer}.
073     *
074     * @throws IllegalStateException if a response has already been submitted.
075     */
076    void submitResponse(HttpAsyncResponseProducer responseProducer);
077
078    /**
079     * Determines whether or not the message exchange has been completed.
080     *
081     * @return {@code true} if the message exchange has been completed,
082     * {@code false} otherwise.
083     */
084    boolean isCompleted();
085
086    /**
087     * Sets {@link Cancellable} callback to be invoked in case the underlying
088     * connection times out or gets terminated prematurely by the client. This
089     * callback can be used to cancel a long running response generating
090     * process if a response is no longer needed.
091     */
092    void setCallback(Cancellable cancellable);
093
094    /**
095     * Sets timeout for this message exchange.
096     */
097    void setTimeout(int timeout);
098
099    /**
100     * Returns timeout for this message exchange.
101     */
102    int getTimeout();
103
104}