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; 029 030import java.io.IOException; 031 032import org.apache.http.HttpException; 033 034/** 035 * Abstract client-side HTTP protocol handler. 036 * 037 * @since 4.2 038 */ 039public interface NHttpClientEventHandler { 040 041 /** 042 * Triggered when a new outgoing connection is created. 043 * 044 * @param conn new outgoing HTTP connection. 045 * @param attachment an object that was attached to the session request 046 */ 047 void connected( 048 NHttpClientConnection conn, 049 Object attachment) throws IOException, HttpException; 050 051 /** 052 * Triggered when the connection is ready to accept a new HTTP request. 053 * The protocol handler does not have to submit a request if it is not 054 * ready. 055 * 056 * @see NHttpClientConnection 057 * 058 * @param conn HTTP connection that is ready to accept a new HTTP request. 059 */ 060 void requestReady( 061 NHttpClientConnection conn) throws IOException, HttpException; 062 063 /** 064 * Triggered when an HTTP response is received. The connection 065 * passed as a parameter to this method is guaranteed to return 066 * a valid HTTP response object. 067 * <p> 068 * If the response received encloses a response entity this method will 069 * be followed by a series of 070 * {@link #inputReady(NHttpClientConnection, ContentDecoder)} calls 071 * to transfer the response content. 072 * 073 * @see NHttpClientConnection 074 * 075 * @param conn HTTP connection that contains an HTTP response 076 */ 077 void responseReceived( 078 NHttpClientConnection conn) throws IOException, HttpException; 079 080 /** 081 * Triggered when the underlying channel is ready for reading a 082 * new portion of the response entity through the corresponding 083 * content decoder. 084 * <p> 085 * If the content consumer is unable to process incoming content, 086 * input event notifications can be temporarily suspended using 087 * {@link IOControl} interface (super interface of {@link NHttpClientConnection}). 088 * <p> 089 * Please note that the {@link NHttpClientConnection} and {@link ContentDecoder} 090 * objects are not thread-safe and should only be used within the context of 091 * this method call. The {@link IOControl} object can be shared and used on other 092 * thread to resume input event notifications when the handler is capable of 093 * processing more content. 094 * 095 * @see NHttpClientConnection 096 * @see ContentDecoder 097 * @see IOControl 098 * 099 * @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}