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 /**
37 * @author gregw
38 *
39 */
40 public interface Connector extends LifeCycle
41 {
42 /* ------------------------------------------------------------ */
43 /**
44 * @return the name of the connector. Defaults to the HostName:port
45 */
46 String getName();
47
48 /* ------------------------------------------------------------ */
49 /**
50 * Opens the connector
51 * @throws IOException
52 */
53 void open() throws IOException;
54
55 /* ------------------------------------------------------------ */
56 void close() throws IOException;
57
58 /* ------------------------------------------------------------ */
59 void setServer(Server server);
60
61 /* ------------------------------------------------------------ */
62 Server getServer();
63
64 /* ------------------------------------------------------------ */
65 /**
66 * @return Returns the request header buffer size in bytes.
67 */
68 int getRequestHeaderSize();
69
70 /* ------------------------------------------------------------ */
71 /**
72 * Set the size of the buffer to be used for request headers.
73 * @param size The size in bytes.
74 */
75 void setRequestHeaderSize(int size);
76
77 /* ------------------------------------------------------------ */
78 /**
79 * @return Returns the response header buffer size in bytes.
80 */
81 int getResponseHeaderSize();
82
83 /* ------------------------------------------------------------ */
84 /**
85 * Set the size of the buffer to be used for request headers.
86 * @param size The size in bytes.
87 */
88 void setResponseHeaderSize(int size);
89
90
91 /* ------------------------------------------------------------ */
92 /**
93 * @return factory for request buffers
94 */
95 Buffers getRequestBuffers();
96
97 /* ------------------------------------------------------------ */
98 /**
99 * @return factory for response buffers
100 */
101 Buffers getResponseBuffers();
102
103
104 /* ------------------------------------------------------------ */
105 /**
106 * @return Returns the requestBufferSize.
107 */
108 int getRequestBufferSize();
109
110 /* ------------------------------------------------------------ */
111 /**
112 * Set the size of the content buffer for receiving requests.
113 * These buffers are only used for active connections that have
114 * requests with bodies that will not fit within the header buffer.
115 * @param requestBufferSize The requestBufferSize to set.
116 */
117 void setRequestBufferSize(int requestBufferSize);
118
119 /* ------------------------------------------------------------ */
120 /**
121 * @return Returns the responseBufferSize.
122 */
123 int getResponseBufferSize();
124
125 /* ------------------------------------------------------------ */
126 /**
127 * Set the size of the content buffer for sending responses.
128 * These buffers are only used for active connections that are sending
129 * responses with bodies that will not fit within the header buffer.
130 * @param responseBufferSize The responseBufferSize to set.
131 */
132 void setResponseBufferSize(int responseBufferSize);
133
134
135 /* ------------------------------------------------------------ */
136 /**
137 * @return The port to use when redirecting a request if a data constraint of integral is
138 * required. See {@link org.eclipse.jetty.http.security.Constraint#getDataConstraint()}
139 */
140 int getIntegralPort();
141
142 /* ------------------------------------------------------------ */
143 /**
144 * @return The schema to use when redirecting a request if a data constraint of integral is
145 * required. See {@link org.eclipse.jetty.http.security.Constraint#getDataConstraint()}
146 */
147 String getIntegralScheme();
148
149 /* ------------------------------------------------------------ */
150 /**
151 * @param request A request
152 * @return true if the request is integral. This normally means the https schema has been used.
153 */
154 boolean isIntegral(Request request);
155
156 /* ------------------------------------------------------------ */
157 /**
158 * @return The port to use when redirecting a request if a data constraint of confidential is
159 * required. See {@link org.eclipse.jetty.http.security.Constraint#getDataConstraint()}
160 */
161 int getConfidentialPort();
162
163
164 /* ------------------------------------------------------------ */
165 /**
166 * @return The schema to use when redirecting a request if a data constraint of confidential is
167 * required. See {@link org.eclipse.jetty.http.security.Constraint#getDataConstraint()}
168 */
169 String getConfidentialScheme();
170
171 /* ------------------------------------------------------------ */
172 /**
173 * @param request A request
174 * @return true if the request is confidential. This normally means the https schema has been used.
175 */
176 boolean isConfidential(Request request);
177
178 /* ------------------------------------------------------------ */
179 /** Customize a request for an endpoint.
180 * Called on every request to allow customization of the request for
181 * the particular endpoint (eg security properties from a SSL connection).
182 * @param endpoint
183 * @param request
184 * @throws IOException
185 */
186 void customize(EndPoint endpoint, Request request) throws IOException;
187
188 /* ------------------------------------------------------------ */
189 /** Persist an endpoint.
190 * Called after every request if the connection is to remain open.
191 * @param endpoint
192 * @throws IOException
193 */
194 void persist(EndPoint endpoint) throws IOException;
195
196 /* ------------------------------------------------------------ */
197 /**
198 * @return The hostname representing the interface to which
199 * this connector will bind, or null for all interfaces.
200 */
201 String getHost();
202
203 /* ------------------------------------------------------------ */
204 /**
205 * Set the hostname of the interface to bind to.
206 * @param hostname The hostname representing the interface to which
207 * this connector will bind, or null for all interfaces.
208 */
209 void setHost(String hostname);
210
211 /* ------------------------------------------------------------ */
212 /**
213 * @param port The port fto listen of for connections or 0 if any available
214 * port may be used.
215 */
216 void setPort(int port);
217
218 /* ------------------------------------------------------------ */
219 /**
220 * @return The configured port for the connector or 0 if any available
221 * port may be used.
222 */
223 int getPort();
224
225 /* ------------------------------------------------------------ */
226 /**
227 * @return The actual port the connector is listening on or
228 * -1 if it has not been opened, or -2 if it has been closed.
229 */
230 int getLocalPort();
231
232 /* ------------------------------------------------------------ */
233 /**
234 * @return Max Idle time for connections in milliseconds
235 */
236 int getMaxIdleTime();
237
238 /**
239 * @param ms Max Idle time for connections in milliseconds
240 */
241 void setMaxIdleTime(int ms);
242
243 /* ------------------------------------------------------------ */
244 int getLowResourceMaxIdleTime();
245 void setLowResourceMaxIdleTime(int ms);
246
247 /* ------------------------------------------------------------ */
248 /**
249 * @return the underlying socket, channel, buffer etc. for the connector.
250 */
251 Object getConnection();
252
253
254 /* ------------------------------------------------------------ */
255 /**
256 * @return true if names resolution should be done.
257 */
258 boolean getResolveNames();
259
260
261
262 /* ------------------------------------------------------------ */
263 /**
264 * @return Get the number of requests handled by this connector
265 * since last call of statsReset(). If setStatsOn(false) then this
266 * is undefined.
267 */
268 public int getRequests();
269
270 /* ------------------------------------------------------------ */
271 /**
272 * @return Returns the connectionsDurationTotal.
273 */
274 public long getConnectionsDurationTotal();
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 Maximum duration in milliseconds of an open connection
300 * since statsReset() called. Undefined if setStatsOn(false).
301 */
302 public long getConnectionsDurationMax();
303
304 /* ------------------------------------------------------------ */
305 /**
306 * @return Mean duration in milliseconds of open connections
307 * since statsReset() called. Undefined if setStatsOn(false).
308 */
309 public double getConnectionsDurationMean() ;
310
311 /* ------------------------------------------------------------ */
312 /**
313 * @return Standard deviation of duration in milliseconds of
314 * open connections since statsReset() called. Undefined if
315 * setStatsOn(false).
316 */
317 public double getConnectionsDurationStdDev() ;
318
319 /* ------------------------------------------------------------ */
320 /**
321 * @return Mean number of requests per connection
322 * since statsReset() called. Undefined if setStatsOn(false).
323 */
324 public double getConnectionsRequestsMean() ;
325
326 /* ------------------------------------------------------------ */
327 /**
328 * @return Standard Deviation of number of requests per connection
329 * since statsReset() called. Undefined if setStatsOn(false).
330 */
331 public double getConnectionsRequestsStdDev() ;
332
333 /* ------------------------------------------------------------ */
334 /**
335 * @return Maximum number of requests per connection
336 * since statsReset() called. Undefined if setStatsOn(false).
337 */
338 public int getConnectionsRequestsMax();
339
340 /* ------------------------------------------------------------ */
341 /** Reset statistics.
342 */
343 public void statsReset();
344
345 /* ------------------------------------------------------------ */
346 public void setStatsOn(boolean on);
347
348 /* ------------------------------------------------------------ */
349 /**
350 * @return True if statistics collection is turned on.
351 */
352 public boolean getStatsOn();
353
354 /* ------------------------------------------------------------ */
355 /**
356 * @return Timestamp stats were started at.
357 */
358 public long getStatsOnMs();
359
360
361 /* ------------------------------------------------------------ */
362 /** Check if low on resources.
363 * For most connectors, low resources is measured by calling
364 * {@link ThreadPool#isLowOnThreads()} on the connector threadpool
365 * or the server threadpool if there is no connector threadpool.
366 * <p>
367 * For blocking connectors, low resources is used to trigger
368 * usage of {@link #getLowResourceMaxIdleTime()} for the timeout
369 * of an idle connection.
370 * <p>
371 * for non-blocking connectors, the number of connections is
372 * used instead of this method, to select the timeout of an
373 * idle connection.
374 * <p>
375 * For all connectors, low resources is used to trigger the
376 * usage of {@link #getLowResourceMaxIdleTime()} for read and
377 * write operations.
378 *
379 * @return true if this connector is low on resources.
380 */
381 public boolean isLowResources();
382 }