1 /* 2 * ==================================================================== 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * ==================================================================== 20 * 21 * This software consists of voluntary contributions made by many 22 * individuals on behalf of the Apache Software Foundation. For more 23 * information on the Apache Software Foundation, please see 24 * <http://www.apache.org/>. 25 * 26 */ 27 package org.apache.http.nio.protocol; 28 29 import java.io.Closeable; 30 import java.io.IOException; 31 32 import org.apache.http.HttpException; 33 import org.apache.http.HttpHost; 34 import org.apache.http.HttpRequest; 35 import org.apache.http.nio.ContentEncoder; 36 import org.apache.http.nio.IOControl; 37 import org.apache.http.protocol.HttpContext; 38 39 /** 40 * {@code HttpAsyncRequestProducer} is a callback interface whose methods 41 * get invoked to generate an HTTP request message and to stream message 42 * content to a non-blocking HTTP connection. 43 * <p> 44 * Repeatable request producers capable of generating the same request 45 * message more than once can be reset to their initial state by calling 46 * the {@link #resetRequest()} method, at which point request producers are 47 * expected to release currently allocated resources that are no longer needed 48 * or re-acquire resources needed to repeat the process. 49 * 50 * @since 4.2 51 */ 52 public interface HttpAsyncRequestProducer extends Closeable { 53 54 /** 55 * Invoked to obtain the request target host. 56 */ 57 HttpHost getTarget(); 58 59 /** 60 * Invoked to generate a HTTP request message head. The message is expected 61 * to implement the {@link org.apache.http.HttpEntityEnclosingRequest} interface 62 * if it is to enclose a content entity. The {@link #produceContent( 63 * ContentEncoder, IOControl)} method will not be invoked if 64 * {@link org.apache.http.HttpEntityEnclosingRequest#getEntity()} 65 * returns {@code null}. 66 * 67 * @return HTTP request message. 68 * @throws HttpException in case of HTTP protocol violation 69 * @throws IOException in case of an I/O error 70 */ 71 HttpRequest generateRequest() throws IOException, HttpException; 72 73 /** 74 * Invoked to write out a chunk of content to the {@link ContentEncoder}. 75 * The {@link IOControl} interface can be used to suspend output event 76 * notifications if the producer is temporarily unable to produce more content. 77 * <p> 78 * When all content is finished, the producer <b>MUST</b> call 79 * {@link ContentEncoder#complete()}. Failure to do so may cause the entity 80 * to be incorrectly delimited. 81 * <p> 82 * Please note that the {@link ContentEncoder} object is not thread-safe and 83 * should only be used within the context of this method call. 84 * The {@link IOControl} object can be shared and used on other thread 85 * to resume output event notifications when more content is made available. 86 * 87 * @param encoder content encoder. 88 * @param ioControl I/O control of the underlying connection. 89 * @throws IOException in case of an I/O error 90 */ 91 void produceContent(ContentEncoder encoder, IOControl ioControl) throws IOException; 92 93 /** 94 * Invoked to signal that the request has been fully written out. 95 * 96 * @param context HTTP context 97 */ 98 void requestCompleted(HttpContext context); 99 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 }