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.util.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.util.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.util.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.util.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 }