1 //========================================================================
2 //$Id: Connector.java,v 1.7 2005/11/25 21:01:45 gregwilkins Exp $
3 //Copyright 2004-2005 Mort Bay Consulting Pty. Ltd.
4 //------------------------------------------------------------------------
5 //Licensed under the Apache License, Version 2.0 (the "License");
6 //you may not use this file except in compliance with the License.
7 //You may obtain a copy of the License at
8 //http://www.apache.org/licenses/LICENSE-2.0
9 //Unless required by applicable law or agreed to in writing, software
10 //distributed under the License is distributed on an "AS IS" BASIS,
11 //WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 //See the License for the specific language governing permissions and
13 //limitations under the License.
14 //========================================================================
15
16 package org.mortbay.jetty;
17
18 import java.io.IOException;
19
20 import org.mortbay.component.LifeCycle;
21 import org.mortbay.io.Buffers;
22 import org.mortbay.io.EndPoint;
23 import org.mortbay.util.ajax.Continuation;
24
25 /** HTTP Connector.
26 * Implementations of this interface provide connectors for the HTTP protocol.
27 * A connector receives requests (normally from a socket) and calls the
28 * handle method of the Handler object. These operations are performed using
29 * threads from the ThreadPool set on the connector.
30 *
31 * When a connector is registered with an instance of Server, then the server
32 * will set itself as both the ThreadPool and the Handler. Note that a connector
33 * can be used without a Server if a thread pool and handler are directly provided.
34 *
35 * @author gregw
36 *
37 */
38 public interface Connector extends LifeCycle, Buffers
39 {
40 /* ------------------------------------------------------------ */
41 /**
42 * @return the name of the connector. Defaults to the HostName:port
43 */
44 String getName();
45
46 /* ------------------------------------------------------------ */
47 /**
48 * Opens the connector
49 * @throws IOException
50 */
51 void open() throws IOException;
52
53 /* ------------------------------------------------------------ */
54 void close() throws IOException;
55
56 /* ------------------------------------------------------------ */
57 void setServer(Server server);
58
59 /* ------------------------------------------------------------ */
60 Server getServer();
61
62 /* ------------------------------------------------------------ */
63 /**
64 * @return Returns the headerBufferSize.
65 */
66 int getHeaderBufferSize();
67
68 /* ------------------------------------------------------------ */
69 /**
70 * Set the size of the buffer to be used for request and response headers.
71 * An idle connection will at most have one buffer of this size allocated.
72 * @param headerBufferSize The headerBufferSize to set.
73 */
74 void setHeaderBufferSize(int headerBufferSize);
75
76
77 /* ------------------------------------------------------------ */
78 /**
79 * @return Returns the requestBufferSize.
80 */
81 int getRequestBufferSize();
82
83 /* ------------------------------------------------------------ */
84 /**
85 * Set the size of the content buffer for receiving requests.
86 * These buffers are only used for active connections that have
87 * requests with bodies that will not fit within the header buffer.
88 * @param requestBufferSize The requestBufferSize to set.
89 */
90 void setRequestBufferSize(int requestBufferSize);
91
92 /* ------------------------------------------------------------ */
93 /**
94 * @return Returns the responseBufferSize.
95 */
96 int getResponseBufferSize();
97
98 /* ------------------------------------------------------------ */
99 /**
100 * Set the size of the content buffer for sending responses.
101 * These buffers are only used for active connections that are sending
102 * responses with bodies that will not fit within the header buffer.
103 * @param responseBufferSize The responseBufferSize to set.
104 */
105 void setResponseBufferSize(int responseBufferSize);
106
107
108 /* ------------------------------------------------------------ */
109 /**
110 * @return The port to use when redirecting a request if a data constraint of integral is
111 * required. See {@link org.mortbay.jetty.security.Constraint#getDataConstraint()}
112 */
113 int getIntegralPort();
114
115 /* ------------------------------------------------------------ */
116 /**
117 * @return The schema to use when redirecting a request if a data constraint of integral is
118 * required. See {@link org.mortbay.jetty.security.Constraint#getDataConstraint()}
119 */
120 String getIntegralScheme();
121
122 /* ------------------------------------------------------------ */
123 /**
124 * @param request A request
125 * @return true if the request is integral. This normally means the https schema has been used.
126 */
127 boolean isIntegral(Request request);
128
129 /* ------------------------------------------------------------ */
130 /**
131 * @return The port to use when redirecting a request if a data constraint of confidential is
132 * required. See {@link org.mortbay.jetty.security.Constraint#getDataConstraint()}
133 */
134 int getConfidentialPort();
135
136
137 /* ------------------------------------------------------------ */
138 /**
139 * @return The schema to use when redirecting a request if a data constraint of confidential is
140 * required. See {@link org.mortbay.jetty.security.Constraint#getDataConstraint()}
141 */
142 String getConfidentialScheme();
143
144 /* ------------------------------------------------------------ */
145 /**
146 * @param request A request
147 * @return true if the request is confidential. This normally means the https schema has been used.
148 */
149 boolean isConfidential(Request request);
150
151 /* ------------------------------------------------------------ */
152 /** Customize a request for an endpoint.
153 * Called on every request to allow customization of the request for
154 * the particular endpoint (eg security properties from a SSL connection).
155 * @param endpoint
156 * @param request
157 * @throws IOException
158 */
159 void customize(EndPoint endpoint, Request request) throws IOException;
160
161 /* ------------------------------------------------------------ */
162 /** Persist an endpoint.
163 * Called after every request if the connection is to remain open.
164 * @param endpoint
165 * @param request
166 * @throws IOException
167 */
168 void persist(EndPoint endpoint) throws IOException;
169
170 /* ------------------------------------------------------------ */
171 Continuation newContinuation();
172
173 /* ------------------------------------------------------------ */
174 String getHost();
175
176 /* ------------------------------------------------------------ */
177 void setHost(String hostname);
178
179 /* ------------------------------------------------------------ */
180 /**
181 * @param port The port fto listen of for connections or 0 if any available
182 * port may be used.
183 */
184 void setPort(int port);
185
186 /* ------------------------------------------------------------ */
187 /**
188 * @return The configured port for the connector or 0 if any available
189 * port may be used.
190 */
191 int getPort();
192
193 /* ------------------------------------------------------------ */
194 /**
195 * @return The actual port the connector is listening on or -1 if there
196 * is no port or the connector is not open.
197 */
198 int getLocalPort();
199
200 /* ------------------------------------------------------------ */
201 int getMaxIdleTime();
202 void setMaxIdleTime(int ms);
203
204 /* ------------------------------------------------------------ */
205 int getLowResourceMaxIdleTime();
206 void setLowResourceMaxIdleTime(int ms);
207
208 /* ------------------------------------------------------------ */
209 /**
210 * @return the underlying socket, channel, buffer etc. for the connector.
211 */
212 Object getConnection();
213
214
215 /* ------------------------------------------------------------ */
216 /**
217 * @return true if names resolution should be done.
218 */
219 boolean getResolveNames();
220
221
222
223 /* ------------------------------------------------------------ */
224 /**
225 * @return Get the number of requests handled by this connector
226 * since last call of statsReset(). If setStatsOn(false) then this
227 * is undefined.
228 */
229 public int getRequests();
230
231 /* ------------------------------------------------------------ */
232 /**
233 * @return Returns the connectionsDurationMin.
234 */
235 public long getConnectionsDurationMin();
236
237 /* ------------------------------------------------------------ */
238 /**
239 * @return Returns the connectionsDurationTotal.
240 */
241 public long getConnectionsDurationTotal();
242
243 /* ------------------------------------------------------------ */
244 /**
245 * @return Returns the connectionsOpenMin.
246 */
247 public int getConnectionsOpenMin();
248
249 /* ------------------------------------------------------------ */
250 /**
251 * @return Returns the connectionsRequestsMin.
252 */
253 public int getConnectionsRequestsMin();
254
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 Average duration in milliseconds of open connections
280 * since statsReset() called. Undefined if setStatsOn(false).
281 */
282 public long getConnectionsDurationAve() ;
283
284 /* ------------------------------------------------------------ */
285 /**
286 * @return Maximum duration in milliseconds of an open connection
287 * since statsReset() called. Undefined if setStatsOn(false).
288 */
289 public long getConnectionsDurationMax();
290
291 /* ------------------------------------------------------------ */
292 /**
293 * @return Average number of requests per connection
294 * since statsReset() called. Undefined if setStatsOn(false).
295 */
296 public int getConnectionsRequestsAve() ;
297
298 /* ------------------------------------------------------------ */
299 /**
300 * @return Maximum number of requests per connection
301 * since statsReset() called. Undefined if setStatsOn(false).
302 */
303 public int getConnectionsRequestsMax();
304
305
306
307 /* ------------------------------------------------------------ */
308 /** Reset statistics.
309 */
310 public void statsReset();
311
312 /* ------------------------------------------------------------ */
313 public void setStatsOn(boolean on);
314
315 /* ------------------------------------------------------------ */
316 /**
317 * @return True if statistics collection is turned on.
318 */
319 public boolean getStatsOn();
320
321 /* ------------------------------------------------------------ */
322 /**
323 * @return Timestamp stats were started at.
324 */
325 public long getStatsOnMs();
326
327
328 }