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 connectionsDurationTotal.
254 */
255 public long getConnectionsDurationTotal();
256
257 /* ------------------------------------------------------------ */
258 /**
259 * @return Number of connections accepted by the server since
260 * statsReset() called. Undefined if setStatsOn(false).
261 */
262 public int getConnections() ;
263
264 /* ------------------------------------------------------------ */
265 /**
266 * @return Number of connections currently open that were opened
267 * since statsReset() called. Undefined if setStatsOn(false).
268 */
269 public int getConnectionsOpen() ;
270
271 /* ------------------------------------------------------------ */
272 /**
273 * @return Maximum number of connections opened simultaneously
274 * since statsReset() called. Undefined if setStatsOn(false).
275 */
276 public int getConnectionsOpenMax() ;
277
278 /* ------------------------------------------------------------ */
279 /**
280 * @return Maximum duration in milliseconds of an open connection
281 * since statsReset() called. Undefined if setStatsOn(false).
282 */
283 public long getConnectionsDurationMax();
284
285 /* ------------------------------------------------------------ */
286 /**
287 * @return Mean duration in milliseconds of open connections
288 * since statsReset() called. Undefined if setStatsOn(false).
289 */
290 public double getConnectionsDurationMean() ;
291
292 /* ------------------------------------------------------------ */
293 /**
294 * @return Standard deviation of duration in milliseconds of
295 * open connections since statsReset() called. Undefined if
296 * setStatsOn(false).
297 */
298 public double getConnectionsDurationStdDev() ;
299
300 /* ------------------------------------------------------------ */
301 /**
302 * @return Mean number of requests per connection
303 * since statsReset() called. Undefined if setStatsOn(false).
304 */
305 public double getConnectionsRequestsMean() ;
306
307 /* ------------------------------------------------------------ */
308 /**
309 * @return Standard Deviation of number of requests per connection
310 * since statsReset() called. Undefined if setStatsOn(false).
311 */
312 public double getConnectionsRequestsStdDev() ;
313
314 /* ------------------------------------------------------------ */
315 /**
316 * @return Maximum number of requests per connection
317 * since statsReset() called. Undefined if setStatsOn(false).
318 */
319 public int getConnectionsRequestsMax();
320
321 /* ------------------------------------------------------------ */
322 /** Reset statistics.
323 */
324 public void statsReset();
325
326 /* ------------------------------------------------------------ */
327 public void setStatsOn(boolean on);
328
329 /* ------------------------------------------------------------ */
330 /**
331 * @return True if statistics collection is turned on.
332 */
333 public boolean getStatsOn();
334
335 /* ------------------------------------------------------------ */
336 /**
337 * @return Timestamp stats were started at.
338 */
339 public long getStatsOnMs();
340
341
342 /* ------------------------------------------------------------ */
343 /** Check if low on resources.
344 * For most connectors, low resources is measured by calling
345 * {@link ThreadPool#isLowOnThreads()} on the connector threadpool
346 * or the server threadpool if there is no connector threadpool.
347 * <p>
348 * For blocking connectors, low resources is used to trigger
349 * usage of {@link #getLowResourceMaxIdleTime()} for the timeout
350 * of an idle connection.
351 * <p>
352 * for non-blocking connectors, the number of connections is
353 * used instead of this method, to select the timeout of an
354 * idle connection.
355 * <p>
356 * For all connectors, low resources is used to trigger the
357 * usage of {@link #getLowResourceMaxIdleTime()} for read and
358 * write operations.
359 *
360 * @return true if this connector is low on resources.
361 */
362 public boolean isLowResources();
363 }