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