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 }