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 }