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 */
027package org.apache.http.nio.protocol;
028
029import java.io.Closeable;
030import java.io.IOException;
031
032import org.apache.http.HttpException;
033import org.apache.http.HttpHost;
034import org.apache.http.HttpRequest;
035import org.apache.http.nio.ContentEncoder;
036import org.apache.http.nio.IOControl;
037import org.apache.http.protocol.HttpContext;
038
039/**
040 * {@code HttpAsyncRequestProducer} is a callback interface whose methods
041 * get invoked to generate an HTTP request message and to stream message
042 * content to a non-blocking HTTP connection.
043 * <p>
044 * Repeatable request producers capable of generating the same request
045 * message more than once can be reset to their initial state by calling
046 * the {@link #resetRequest()} method, at which point request producers are
047 * expected to release currently allocated resources that are no longer needed
048 * or re-acquire resources needed to repeat the process.
049 *
050 * @since 4.2
051 */
052public interface HttpAsyncRequestProducer extends Closeable {
053
054    /**
055     * Invoked to obtain the request target host.
056     */
057    HttpHost getTarget();
058
059    /**
060     * Invoked to generate a HTTP request message head. The message is expected
061     * to implement the {@link org.apache.http.HttpEntityEnclosingRequest} interface
062     * if it is to enclose a content entity. The {@link #produceContent(
063     * ContentEncoder, IOControl)} method will not be invoked if
064     * {@link org.apache.http.HttpEntityEnclosingRequest#getEntity()}
065     * returns {@code null}.
066     *
067     * @return HTTP request message.
068     * @throws HttpException in case of HTTP protocol violation
069     * @throws IOException in case of an I/O error
070     */
071    HttpRequest generateRequest() throws IOException, HttpException;
072
073    /**
074     * Invoked to write out a chunk of content to the {@link ContentEncoder}.
075     * The {@link IOControl} interface can be used to suspend output event
076     * notifications if the producer is temporarily unable to produce more content.
077     * <p>
078     * When all content is finished, the producer <b>MUST</b> call
079     * {@link ContentEncoder#complete()}. Failure to do so may cause the entity
080     * to be incorrectly delimited.
081     * <p>
082     * Please note that the {@link ContentEncoder} object is not thread-safe and
083     * should only be used within the context of this method call.
084     * The {@link IOControl} object can be shared and used on other thread
085     * to resume output event notifications when more content is made available.
086     *
087     * @param encoder content encoder.
088     * @param ioctrl I/O control of the underlying connection.
089     * @throws IOException in case of an I/O error
090     */
091    void produceContent(ContentEncoder encoder, IOControl ioctrl) throws IOException;
092
093    /**
094     * Invoked to signal that the request has been fully written out.
095     *
096     * @param context HTTP context
097     */
098    void requestCompleted(HttpContext context);
099
100    /**
101     * Invoked to signal that the response processing terminated abnormally.
102     *
103     * @param ex exception
104     */
105    void failed(Exception ex);
106
107    /**
108     * Determines whether or not this producer is capable of producing
109     * HTTP request messages more than once.
110     */
111    boolean isRepeatable();
112
113    /**
114     * Invoked to reset the producer to its initial state. Repeatable request
115     * producers are expected to release currently allocated resources that are
116     * no longer needed or re-acquire resources needed to repeat the process.
117     *
118     * @throws IOException in case of an I/O error
119     */
120    void resetRequest() throws IOException;
121
122}