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 java.io.Closeable;
031import java.io.IOException;
032
033import org.apache.http.HttpException;
034import org.apache.http.HttpRequest;
035import org.apache.http.HttpResponse;
036import org.apache.http.concurrent.Cancellable;
037import org.apache.http.nio.ContentDecoder;
038import org.apache.http.nio.ContentEncoder;
039import org.apache.http.nio.IOControl;
040
041/**
042 * {@code HttpAsyncClientExchangeHandler} represents a callback interface whose
043 * methods get invoked when executing one or multiple HTTP message exchanges
044 * on the client side.
045 * <p>
046 * Individual {@code HttpAsyncClientExchangeHandler} are expected to make use of
047 * a {@link org.apache.http.protocol.HttpProcessor} to generate mandatory protocol
048 * headers for all outgoing messages and apply common, cross-cutting message
049 * transformations to all incoming and outgoing messages.
050 * {@code HttpAsyncClientExchangeHandler}s can delegate implementation
051 * of application specific content generation and processing to
052 * a {@link HttpAsyncRequestProducer} and a {@link HttpAsyncResponseConsumer}.
053 *
054 * @since 4.3
055 */
056public interface HttpAsyncClientExchangeHandler extends Closeable, Cancellable {
057
058    /**
059     * Invoked to generate a HTTP request message head. The message is expected
060     * to implement the {@link org.apache.http.HttpEntityEnclosingRequest} interface if it is
061     * to enclose a content entity. The {@link #produceContent(ContentEncoder,
062     * IOControl)} method will not be invoked if
063     * {@link org.apache.http.HttpEntityEnclosingRequest#getEntity()} returns
064     * {@code null}.
065     *
066     * @return HTTP request message.
067     * @throws HttpException in case of HTTP protocol violation
068     * @throws IOException in case of an I/O error
069     */
070    HttpRequest generateRequest() throws IOException, HttpException;
071
072    /**
073     * Invoked to write out a chunk of content to the {@link ContentEncoder}.
074     * The {@link IOControl} interface can be used to suspend output event
075     * notifications if the producer is temporarily unable to produce more content.
076     * <p>
077     * When all content is finished, the producer <b>MUST</b> call
078     * {@link ContentEncoder#complete()}. Failure to do so may cause the entity
079     * to be incorrectly delimited.
080     * <p>
081     * Please note that the {@link ContentEncoder} object is not thread-safe and
082     * should only be used within the context of this method call.
083     * The {@link IOControl} object can be shared and used on other thread
084     * to resume output event notifications when more content is made available.
085     *
086     * @param encoder content encoder.
087     * @param ioctrl I/O control of the underlying connection.
088     * @throws IOException in case of an I/O error
089     */
090    void produceContent(ContentEncoder encoder, IOControl ioctrl) throws IOException;
091
092    /**
093     * Invoked to signal that the request has been fully written out.
094     */
095    void requestCompleted();
096
097    /**
098     * Invoked when a HTTP response message is received. Please note
099     * that the {@link #consumeContent(ContentDecoder, IOControl)} method
100     * will be invoked only if the response messages has a content entity
101     * enclosed.
102     *
103     * @param response HTTP response message.
104     * @throws HttpException in case of HTTP protocol violation
105     * @throws IOException in case of an I/O error
106     */
107    void responseReceived(HttpResponse response) throws IOException, HttpException;
108
109    /**
110     * Invoked to process a chunk of content from the {@link ContentDecoder}.
111     * The {@link IOControl} interface can be used to suspend input event
112     * notifications if the consumer is temporarily unable to process content.
113     * <p>
114     * The consumer can use the {@link ContentDecoder#isCompleted()} method
115     * to find out whether or not the message content has been fully consumed.
116     * <p>
117     * Please note that the {@link ContentDecoder} object is not thread-safe and
118     * should only be used within the context of this method call.
119     * The {@link IOControl} object can be shared and used on other thread
120     * to resume input event notifications when the consumer is capable of
121     * processing more content.
122     *
123     * @param decoder content decoder.
124     * @param ioctrl I/O control of the underlying connection.
125     * @throws IOException in case of an I/O error
126     */
127    void consumeContent(ContentDecoder decoder, IOControl ioctrl) throws IOException;
128
129    /**
130     * Invoked to signal that the response has been fully processed.
131     */
132    void responseCompleted() throws IOException, HttpException;
133
134    /**
135     * Invoked to signal that the connection has been terminated prematurely
136     * by the opposite end.
137     */
138    void inputTerminated();
139
140    /**
141     * Invoked to signal that the response processing terminated abnormally.
142     *
143     * @param ex exception
144     */
145    void failed(Exception ex);
146
147    /**
148     * Determines whether or not the response processing completed.
149     */
150    boolean isDone();
151
152}