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}