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 28 package org.apache.http.nio; 29 30 import java.io.IOException; 31 32 import org.apache.http.HttpException; 33 34 /** 35 * Abstract client-side HTTP protocol handler. 36 * 37 * @since 4.2 38 */ 39 public interface NHttpClientEventHandler { 40 41 /** 42 * Triggered when a new outgoing connection is created. 43 * 44 * @param conn new outgoing HTTP connection. 45 * @param attachment an object that was attached to the session request 46 */ 47 void connected( 48 NHttpClientConnection conn, 49 Object attachment) throws IOException, HttpException; 50 51 /** 52 * Triggered when the connection is ready to accept a new HTTP request. 53 * The protocol handler does not have to submit a request if it is not 54 * ready. 55 * 56 * @see NHttpClientConnection 57 * 58 * @param conn HTTP connection that is ready to accept a new HTTP request. 59 */ 60 void requestReady( 61 NHttpClientConnection conn) throws IOException, HttpException; 62 63 /** 64 * Triggered when an HTTP response is received. The connection 65 * passed as a parameter to this method is guaranteed to return 66 * a valid HTTP response object. 67 * <p> 68 * If the response received encloses a response entity this method will 69 * be followed by a series of 70 * {@link #inputReady(NHttpClientConnection, ContentDecoder)} calls 71 * to transfer the response content. 72 * 73 * @see NHttpClientConnection 74 * 75 * @param conn HTTP connection that contains an HTTP response 76 */ 77 void responseReceived( 78 NHttpClientConnection conn) throws IOException, HttpException; 79 80 /** 81 * Triggered when the underlying channel is ready for reading a 82 * new portion of the response entity through the corresponding 83 * content decoder. 84 * <p> 85 * If the content consumer is unable to process incoming content, 86 * input event notifications can be temporarily suspended using 87 * {@link IOControl} interface (super interface of {@link NHttpClientConnection}). 88 * <p> 89 * Please note that the {@link NHttpClientConnection} and {@link ContentDecoder} 90 * objects are not thread-safe and should only be used within the context of 91 * this method call. The {@link IOControl} object can be shared and used on other 92 * thread to resume input event notifications when the handler is capable of 93 * processing more content. 94 * 95 * @see NHttpClientConnection 96 * @see ContentDecoder 97 * @see IOControl 98 * 99 * @param conn HTTP connection that can produce a new portion of the 100 * incoming response content. 101 * @param decoder The content decoder to use to read content. 102 */ 103 void inputReady( 104 NHttpClientConnection conn, 105 ContentDecoder decoder) throws IOException, HttpException; 106 107 /** 108 * Triggered when the underlying channel is ready for writing a next portion 109 * of the request entity through the corresponding content encoder. 110 * <p> 111 * If the content producer is unable to generate outgoing content, 112 * output event notifications can be temporarily suspended using 113 * {@link IOControl} interface (super interface of {@link NHttpClientConnection}). 114 * <p> 115 * Please note that the {@link NHttpClientConnection} and {@link ContentEncoder} 116 * objects are not thread-safe and should only be used within the context of 117 * this method call. The {@link IOControl} object can be shared and used on other 118 * thread to resume output event notifications when more content is made available. 119 * 120 * @see NHttpClientConnection 121 * @see ContentEncoder 122 * @see IOControl 123 * 124 * @param conn HTTP connection that can accommodate a new portion 125 * of the outgoing request content. 126 * @param encoder The content encoder to use to write content. 127 */ 128 void outputReady( 129 NHttpClientConnection conn, 130 ContentEncoder encoder) throws IOException, HttpException; 131 132 /** 133 * Triggered when the connection is closed by the opposite end point 134 * (half-closed). 135 * 136 * @param conn half-closed HTTP connection. 137 */ 138 void endOfInput( 139 NHttpClientConnection conn) throws IOException; 140 141 /** 142 * Triggered when no input is detected on this connection over the 143 * maximum period of inactivity. 144 * 145 * @param conn HTTP connection that caused timeout condition. 146 */ 147 void timeout( 148 NHttpClientConnection conn) throws IOException, HttpException; 149 150 /** 151 * Triggered when the connection is closed. 152 * 153 * @param conn closed HTTP connection. 154 */ 155 void closed(NHttpClientConnection conn); 156 157 /** 158 * Triggered if an error occurs during the HTTP exchange. 159 * 160 * @param conn HTTP connection that caused an I/O error 161 * @param ex exception 162 */ 163 void exception(NHttpClientConnection conn, Exception ex); 164 165 }