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.http.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.http.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.http.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.http.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 * @throws IOException
189 */
190 void persist(EndPoint endpoint) throws IOException;
191
192 /* ------------------------------------------------------------ */
193 String getHost();
194
195 /* ------------------------------------------------------------ */
196 void setHost(String hostname);
197
198 /* ------------------------------------------------------------ */
199 /**
200 * @param port The port fto listen of for connections or 0 if any available
201 * port may be used.
202 */
203 void setPort(int port);
204
205 /* ------------------------------------------------------------ */
206 /**
207 * @return The configured port for the connector or 0 if any available
208 * port may be used.
209 */
210 int getPort();
211
212 /* ------------------------------------------------------------ */
213 /**
214 * @return The actual port the connector is listening on or
215 * -1 if it has not been opened, or -2 if it has been closed.
216 */
217 int getLocalPort();
218
219 /* ------------------------------------------------------------ */
220 int getMaxIdleTime();
221 void setMaxIdleTime(int ms);
222
223 /* ------------------------------------------------------------ */
224 int getLowResourceMaxIdleTime();
225 void setLowResourceMaxIdleTime(int ms);
226
227 /* ------------------------------------------------------------ */
228 /**
229 * @return the underlying socket, channel, buffer etc. for the connector.
230 */
231 Object getConnection();
232
233
234 /* ------------------------------------------------------------ */
235 /**
236 * @return true if names resolution should be done.
237 */
238 boolean getResolveNames();
239
240
241
242 /* ------------------------------------------------------------ */
243 /**
244 * @return Get the number of requests handled by this connector
245 * since last call of statsReset(). If setStatsOn(false) then this
246 * is undefined.
247 */
248 public int getRequests();
249
250 /* ------------------------------------------------------------ */
251 /**
252 * @return Returns the connectionsDurationTotal.
253 */
254 public long getConnectionsDurationTotal();
255
256 /* ------------------------------------------------------------ */
257 /**
258 * @return Number of connections accepted by the server since
259 * statsReset() called. Undefined if setStatsOn(false).
260 */
261 public int getConnections() ;
262
263 /* ------------------------------------------------------------ */
264 /**
265 * @return Number of connections currently open that were opened
266 * since statsReset() called. Undefined if setStatsOn(false).
267 */
268 public int getConnectionsOpen() ;
269
270 /* ------------------------------------------------------------ */
271 /**
272 * @return Maximum number of connections opened simultaneously
273 * since statsReset() called. Undefined if setStatsOn(false).
274 */
275 public int getConnectionsOpenMax() ;
276
277 /* ------------------------------------------------------------ */
278 /**
279 * @return Maximum duration in milliseconds of an open connection
280 * since statsReset() called. Undefined if setStatsOn(false).
281 */
282 public long getConnectionsDurationMax();
283
284 /* ------------------------------------------------------------ */
285 /**
286 * @return Mean duration in milliseconds of open connections
287 * since statsReset() called. Undefined if setStatsOn(false).
288 */
289 public double getConnectionsDurationMean() ;
290
291 /* ------------------------------------------------------------ */
292 /**
293 * @return Standard deviation of duration in milliseconds of
294 * open connections since statsReset() called. Undefined if
295 * setStatsOn(false).
296 */
297 public double getConnectionsDurationStdDev() ;
298
299 /* ------------------------------------------------------------ */
300 /**
301 * @return Mean number of requests per connection
302 * since statsReset() called. Undefined if setStatsOn(false).
303 */
304 public double getConnectionsRequestsMean() ;
305
306 /* ------------------------------------------------------------ */
307 /**
308 * @return Standard Deviation of number of requests per connection
309 * since statsReset() called. Undefined if setStatsOn(false).
310 */
311 public double getConnectionsRequestsStdDev() ;
312
313 /* ------------------------------------------------------------ */
314 /**
315 * @return Maximum number of requests per connection
316 * since statsReset() called. Undefined if setStatsOn(false).
317 */
318 public int getConnectionsRequestsMax();
319
320 /* ------------------------------------------------------------ */
321 /** Reset statistics.
322 */
323 public void statsReset();
324
325 /* ------------------------------------------------------------ */
326 public void setStatsOn(boolean on);
327
328 /* ------------------------------------------------------------ */
329 /**
330 * @return True if statistics collection is turned on.
331 */
332 public boolean getStatsOn();
333
334 /* ------------------------------------------------------------ */
335 /**
336 * @return Timestamp stats were started at.
337 */
338 public long getStatsOnMs();
339
340
341 /* ------------------------------------------------------------ */
342 /** Check if low on resources.
343 * For most connectors, low resources is measured by calling
344 * {@link ThreadPool#isLowOnThreads()} on the connector threadpool
345 * or the server threadpool if there is no connector threadpool.
346 * <p>
347 * For blocking connectors, low resources is used to trigger
348 * usage of {@link #getLowResourceMaxIdleTime()} for the timeout
349 * of an idle connection.
350 * <p>
351 * for non-blocking connectors, the number of connections is
352 * used instead of this method, to select the timeout of an
353 * idle connection.
354 * <p>
355 * For all connectors, low resources is used to trigger the
356 * usage of {@link #getLowResourceMaxIdleTime()} for read and
357 * write operations.
358 *
359 * @return true if this connector is low on resources.
360 */
361 public boolean isLowResources();
362 }