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