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 }