1 // ========================================================================
2 // Copyright (c) 2004-2009 Mort Bay Consulting Pty. Ltd.
3 // ------------------------------------------------------------------------
4 // All rights reserved. This program and the accompanying materials
5 // are made available under the terms of the Eclipse Public License v1.0
6 // and Apache License v2.0 which accompanies this distribution.
7 // The Eclipse Public License is available at
8 // http://www.eclipse.org/legal/epl-v10.html
9 // The Apache License v2.0 is available at
10 // http://www.opensource.org/licenses/apache2.0.php
11 // You may elect to redistribute this code under either of these licenses.
12 // ========================================================================
13
14 package org.eclipse.jetty.server;
15
16 import java.io.IOException;
17
18 import org.eclipse.jetty.io.Buffers;
19 import org.eclipse.jetty.io.EndPoint;
20 import org.eclipse.jetty.util.component.LifeCycle;
21 import org.eclipse.jetty.util.thread.ThreadPool;
22
23 /** HTTP Connector.
24 * Implementations of this interface provide connectors for the HTTP protocol.
25 * A connector receives requests (normally from a socket) and calls the
26 * handle method of the Handler object. These operations are performed using
27 * threads from the ThreadPool set on the connector.
28 *
29 * When a connector is registered with an instance of Server, then the server
30 * will set itself as both the ThreadPool and the Handler. Note that a connector
31 * can be used without a Server if a thread pool and handler are directly provided.
32 *
33 *
34 *
35 */
36 public interface Connector extends LifeCycle
37 {
38 /* ------------------------------------------------------------ */
39 /**
40 * @return the name of the connector. Defaults to the HostName:port
41 */
42 String getName();
43
44 /* ------------------------------------------------------------ */
45 /**
46 * Opens the connector
47 * @throws IOException
48 */
49 void open() throws IOException;
50
51 /* ------------------------------------------------------------ */
52 void close() throws IOException;
53
54 /* ------------------------------------------------------------ */
55 void setServer(Server server);
56
57 /* ------------------------------------------------------------ */
58 Server getServer();
59
60 /* ------------------------------------------------------------ */
61 /**
62 * @return Returns the request header buffer size in bytes.
63 */
64 int getRequestHeaderSize();
65
66 /* ------------------------------------------------------------ */
67 /**
68 * Set the size of the buffer to be used for request headers.
69 * @param size The size in bytes.
70 */
71 void setRequestHeaderSize(int size);
72
73 /* ------------------------------------------------------------ */
74 /**
75 * @return Returns the response header buffer size in bytes.
76 */
77 int getResponseHeaderSize();
78
79 /* ------------------------------------------------------------ */
80 /**
81 * Set the size of the buffer to be used for request headers.
82 * @param size The size in bytes.
83 */
84 void setResponseHeaderSize(int size);
85
86
87 /* ------------------------------------------------------------ */
88 /**
89 * @return factory for request buffers
90 */
91 Buffers getRequestBuffers();
92
93 /* ------------------------------------------------------------ */
94 /**
95 * @return factory for response buffers
96 */
97 Buffers getResponseBuffers();
98
99
100 /* ------------------------------------------------------------ */
101 /**
102 * @return Returns the requestBufferSize.
103 */
104 int getRequestBufferSize();
105
106 /* ------------------------------------------------------------ */
107 /**
108 * Set the size of the content buffer for receiving requests.
109 * These buffers are only used for active connections that have
110 * requests with bodies that will not fit within the header buffer.
111 * @param requestBufferSize The requestBufferSize to set.
112 */
113 void setRequestBufferSize(int requestBufferSize);
114
115 /* ------------------------------------------------------------ */
116 /**
117 * @return Returns the responseBufferSize.
118 */
119 int getResponseBufferSize();
120
121 /* ------------------------------------------------------------ */
122 /**
123 * Set the size of the content buffer for sending responses.
124 * These buffers are only used for active connections that are sending
125 * responses with bodies that will not fit within the header buffer.
126 * @param responseBufferSize The responseBufferSize to set.
127 */
128 void setResponseBufferSize(int responseBufferSize);
129
130
131 /* ------------------------------------------------------------ */
132 /**
133 * @return The port to use when redirecting a request if a data constraint of integral is
134 * required. See {@link org.eclipse.jetty.server.server.security.Constraint#getDataConstraint()}
135 */
136 int getIntegralPort();
137
138 /* ------------------------------------------------------------ */
139 /**
140 * @return The schema to use when redirecting a request if a data constraint of integral is
141 * required. See {@link org.eclipse.jetty.server.server.security.Constraint#getDataConstraint()}
142 */
143 String getIntegralScheme();
144
145 /* ------------------------------------------------------------ */
146 /**
147 * @param request A request
148 * @return true if the request is integral. This normally means the https schema has been used.
149 */
150 boolean isIntegral(Request request);
151
152 /* ------------------------------------------------------------ */
153 /**
154 * @return The port to use when redirecting a request if a data constraint of confidential is
155 * required. See {@link org.eclipse.jetty.server.server.security.Constraint#getDataConstraint()}
156 */
157 int getConfidentialPort();
158
159
160 /* ------------------------------------------------------------ */
161 /**
162 * @return The schema to use when redirecting a request if a data constraint of confidential is
163 * required. See {@link org.eclipse.jetty.server.server.security.Constraint#getDataConstraint()}
164 */
165 String getConfidentialScheme();
166
167 /* ------------------------------------------------------------ */
168 /**
169 * @param request A request
170 * @return true if the request is confidential. This normally means the https schema has been used.
171 */
172 boolean isConfidential(Request request);
173
174 /* ------------------------------------------------------------ */
175 /** Customize a request for an endpoint.
176 * Called on every request to allow customization of the request for
177 * the particular endpoint (eg security properties from a SSL connection).
178 * @param endpoint
179 * @param request
180 * @throws IOException
181 */
182 void customize(EndPoint endpoint, Request request) throws IOException;
183
184 /* ------------------------------------------------------------ */
185 /** Persist an endpoint.
186 * Called after every request if the connection is to remain open.
187 * @param endpoint
188 * @param request
189 * @throws IOException
190 */
191 void persist(EndPoint endpoint) throws IOException;
192
193 /* ------------------------------------------------------------ */
194 String getHost();
195
196 /* ------------------------------------------------------------ */
197 void setHost(String hostname);
198
199 /* ------------------------------------------------------------ */
200 /**
201 * @param port The port fto listen of for connections or 0 if any available
202 * port may be used.
203 */
204 void setPort(int port);
205
206 /* ------------------------------------------------------------ */
207 /**
208 * @return The configured port for the connector or 0 if any available
209 * port may be used.
210 */
211 int getPort();
212
213 /* ------------------------------------------------------------ */
214 /**
215 * @return The actual port the connector is listening on or -1 if there
216 * is no port or the connector is not open.
217 */
218 int getLocalPort();
219
220 /* ------------------------------------------------------------ */
221 int getMaxIdleTime();
222 void setMaxIdleTime(int ms);
223
224 /* ------------------------------------------------------------ */
225 int getLowResourceMaxIdleTime();
226 void setLowResourceMaxIdleTime(int ms);
227
228 /* ------------------------------------------------------------ */
229 /**
230 * @return the underlying socket, channel, buffer etc. for the connector.
231 */
232 Object getConnection();
233
234
235 /* ------------------------------------------------------------ */
236 /**
237 * @return true if names resolution should be done.
238 */
239 boolean getResolveNames();
240
241
242
243 /* ------------------------------------------------------------ */
244 /**
245 * @return Get the number of requests handled by this connector
246 * since last call of statsReset(). If setStatsOn(false) then this
247 * is undefined.
248 */
249 public int getRequests();
250
251 /* ------------------------------------------------------------ */
252 /**
253 * @return Returns the connectionsDurationMin.
254 */
255 public long getConnectionsDurationMin();
256
257 /* ------------------------------------------------------------ */
258 /**
259 * @return Returns the connectionsDurationTotal.
260 */
261 public long getConnectionsDurationTotal();
262
263 /* ------------------------------------------------------------ */
264 /**
265 * @return Returns the connectionsOpenMin.
266 */
267 public int getConnectionsOpenMin();
268
269 /* ------------------------------------------------------------ */
270 /**
271 * @return Returns the connectionsRequestsMin.
272 */
273 public int getConnectionsRequestsMin();
274
275
276 /* ------------------------------------------------------------ */
277 /**
278 * @return Number of connections accepted by the server since
279 * statsReset() called. Undefined if setStatsOn(false).
280 */
281 public int getConnections() ;
282
283 /* ------------------------------------------------------------ */
284 /**
285 * @return Number of connections currently open that were opened
286 * since statsReset() called. Undefined if setStatsOn(false).
287 */
288 public int getConnectionsOpen() ;
289
290 /* ------------------------------------------------------------ */
291 /**
292 * @return Maximum number of connections opened simultaneously
293 * since statsReset() called. Undefined if setStatsOn(false).
294 */
295 public int getConnectionsOpenMax() ;
296
297 /* ------------------------------------------------------------ */
298 /**
299 * @return Average duration in milliseconds of open connections
300 * since statsReset() called. Undefined if setStatsOn(false).
301 */
302 public long getConnectionsDurationAve() ;
303
304 /* ------------------------------------------------------------ */
305 /**
306 * @return Maximum duration in milliseconds of an open connection
307 * since statsReset() called. Undefined if setStatsOn(false).
308 */
309 public long getConnectionsDurationMax();
310
311 /* ------------------------------------------------------------ */
312 /**
313 * @return Average number of requests per connection
314 * since statsReset() called. Undefined if setStatsOn(false).
315 */
316 public int getConnectionsRequestsAve() ;
317
318 /* ------------------------------------------------------------ */
319 /**
320 * @return Maximum number of requests per connection
321 * since statsReset() called. Undefined if setStatsOn(false).
322 */
323 public int getConnectionsRequestsMax();
324
325
326
327 /* ------------------------------------------------------------ */
328 /** Reset statistics.
329 */
330 public void statsReset();
331
332 /* ------------------------------------------------------------ */
333 public void setStatsOn(boolean on);
334
335 /* ------------------------------------------------------------ */
336 /**
337 * @return True if statistics collection is turned on.
338 */
339 public boolean getStatsOn();
340
341 /* ------------------------------------------------------------ */
342 /**
343 * @return Timestamp stats were started at.
344 */
345 public long getStatsOnMs();
346
347
348 /* ------------------------------------------------------------ */
349 /** Check if low on resources.
350 * For most connectors, low resources is measured by calling
351 * {@link ThreadPool#isLowOnThreads()} on the connector threadpool
352 * or the server threadpool if there is no connector threadpool.
353 * <p>
354 * For blocking connectors, low resources is used to trigger
355 * usage of {@link #getLowResourceMaxIdleTime()} for the timeout
356 * of an idle connection.
357 * <p>
358 * for non-blocking connectors, the number of connections is
359 * used instead of this method, to select the timeout of an
360 * idle connection.
361 * <p>
362 * For all connectors, low resources is used to trigger the
363 * usage of {@link #getLowResourceMaxIdleTime()} for read and
364 * write operations.
365 *
366 * @return true if this connector is low on resources.
367 */
368 public boolean isLowResources();
369 }