View Javadoc

1   //
2   //  ========================================================================
3   //  Copyright (c) 1995-2014 Mort Bay Consulting Pty. Ltd.
4   //  ------------------------------------------------------------------------
5   //  All rights reserved. This program and the accompanying materials
6   //  are made available under the terms of the Eclipse Public License v1.0
7   //  and Apache License v2.0 which accompanies this distribution.
8   //
9   //      The Eclipse Public License is available at
10  //      http://www.eclipse.org/legal/epl-v10.html
11  //
12  //      The Apache License v2.0 is available at
13  //      http://www.opensource.org/licenses/apache2.0.php
14  //
15  //  You may elect to redistribute this code under either of these licenses.
16  //  ========================================================================
17  //
18  
19  package org.eclipse.jetty.server;
20  
21  import java.io.IOException;
22  
23  import org.eclipse.jetty.io.Buffers;
24  import org.eclipse.jetty.io.EndPoint;
25  import org.eclipse.jetty.util.component.LifeCycle;
26  import org.eclipse.jetty.util.thread.ThreadPool;
27  
28  /** HTTP Connector.
29   * Implementations of this interface provide connectors for the HTTP protocol.
30   * A connector receives requests (normally from a socket) and calls the 
31   * handle method of the Handler object.  These operations are performed using
32   * threads from the ThreadPool set on the connector.
33   * 
34   * When a connector is registered with an instance of Server, then the server
35   * will set itself as both the ThreadPool and the Handler.  Note that a connector
36   * can be used without a Server if a thread pool and handler are directly provided.
37   * 
38   * 
39   * 
40   */
41  /**
42   * @author gregw
43   *
44   */
45  public interface Connector extends LifeCycle
46  { 
47      /* ------------------------------------------------------------ */
48      /**
49       * @return the name of the connector. Defaults to the HostName:port
50       */
51      String getName();
52      
53      /* ------------------------------------------------------------ */
54      /**
55       * Opens the connector 
56       * @throws IOException
57       */
58      void open() throws IOException;
59  
60      /* ------------------------------------------------------------ */
61      void close() throws IOException;
62  
63      /* ------------------------------------------------------------ */
64      void setServer(Server server);
65      
66      /* ------------------------------------------------------------ */
67      Server getServer();
68  
69      /* ------------------------------------------------------------ */
70      /**
71       * @return Returns the request header buffer size in bytes.
72       */
73      int getRequestHeaderSize();
74      
75      /* ------------------------------------------------------------ */
76      /**
77       * Set the size of the buffer to be used for request headers.
78       * @param size The size in bytes.
79       */
80      void setRequestHeaderSize(int size);
81  
82      /* ------------------------------------------------------------ */
83      /**
84       * @return Returns the response header buffer size in bytes.
85       */
86      int getResponseHeaderSize();
87      
88      /* ------------------------------------------------------------ */
89      /**
90       * Set the size of the buffer to be used for request headers.
91       * @param size The size in bytes.
92       */
93      void setResponseHeaderSize(int size);
94      
95  
96      /* ------------------------------------------------------------ */
97      /**
98       * @return factory for request buffers
99       */
100     Buffers getRequestBuffers();
101 
102     /* ------------------------------------------------------------ */
103     /**
104      * @return factory for response buffers
105      */
106     Buffers getResponseBuffers();
107     
108     
109     /* ------------------------------------------------------------ */
110     /**
111      * @return Returns the requestBufferSize.
112      */
113     int getRequestBufferSize();
114     
115     /* ------------------------------------------------------------ */
116     /**
117      * Set the size of the content buffer for receiving requests. 
118      * These buffers are only used for active connections that have
119      * requests with bodies that will not fit within the header buffer.
120      * @param requestBufferSize The requestBufferSize to set.
121      */
122     void setRequestBufferSize(int requestBufferSize);
123     
124     /* ------------------------------------------------------------ */
125     /**
126      * @return Returns the responseBufferSize.
127      */
128     int getResponseBufferSize();
129     
130     /* ------------------------------------------------------------ */
131     /**
132      * Set the size of the content buffer for sending responses. 
133      * These buffers are only used for active connections that are sending 
134      * responses with bodies that will not fit within the header buffer.
135      * @param responseBufferSize The responseBufferSize to set.
136      */
137     void setResponseBufferSize(int responseBufferSize);
138     
139 
140     /* ------------------------------------------------------------ */
141     /**
142      * @return The port to use when redirecting a request if a data constraint of integral is 
143      * required. See {@link org.eclipse.jetty.util.security.Constraint#getDataConstraint()}
144      */
145     int getIntegralPort();
146 
147     /* ------------------------------------------------------------ */
148     /**
149      * @return The schema to use when redirecting a request if a data constraint of integral is 
150      * required. See {@link org.eclipse.jetty.util.security.Constraint#getDataConstraint()}
151      */
152     String getIntegralScheme();
153 
154     /* ------------------------------------------------------------ */
155     /**
156      * @param request A request
157      * @return true if the request is integral. This normally means the https schema has been used.
158      */
159     boolean isIntegral(Request request);
160 
161     /* ------------------------------------------------------------ */
162     /**
163      * @return The port to use when redirecting a request if a data constraint of confidential is 
164      * required. See {@link org.eclipse.jetty.util.security.Constraint#getDataConstraint()}
165      */
166     int getConfidentialPort();
167     
168 
169     /* ------------------------------------------------------------ */
170     /**
171      * @return The schema to use when redirecting a request if a data constraint of confidential is 
172      * required. See {@link org.eclipse.jetty.util.security.Constraint#getDataConstraint()}
173      */
174     String getConfidentialScheme();
175     
176     /* ------------------------------------------------------------ */
177     /**
178      * @param request A request
179      * @return true if the request is confidential. This normally means the https schema has been used.
180      */
181     boolean isConfidential(Request request);
182 
183     /* ------------------------------------------------------------ */
184     /** Customize a request for an endpoint.
185      * Called on every request to allow customization of the request for
186      * the particular endpoint (eg security properties from a SSL connection).
187      * @param endpoint
188      * @param request
189      * @throws IOException
190      */
191     void customize(EndPoint endpoint, Request request) throws IOException;
192 
193     /* ------------------------------------------------------------ */
194     /** Persist an endpoint.
195      * Called after every request if the connection is to remain open.
196      * @param endpoint
197      * @throws IOException
198      */
199     void persist(EndPoint endpoint) throws IOException;
200     
201     /* ------------------------------------------------------------ */
202     /**
203      * @return The hostname representing the interface to which 
204      * this connector will bind, or null for all interfaces.
205      */
206     String getHost();
207     
208     /* ------------------------------------------------------------ */
209     /**
210      * Set the hostname of the interface to bind to.
211      * @param hostname The hostname representing the interface to which 
212      * this connector will bind, or null for all interfaces.
213      */
214     void setHost(String hostname);
215 
216     /* ------------------------------------------------------------ */
217     /**
218      * @param port The port to listen of for connections or 0 if any available
219      * port may be used.
220      */
221     void setPort(int port);
222     
223     /* ------------------------------------------------------------ */
224     /**
225      * @return The configured port for the connector or 0 if any available
226      * port may be used.
227      */
228     int getPort();
229     
230     /* ------------------------------------------------------------ */
231     /**
232      * @return The actual port the connector is listening on or
233      * -1 if it has not been opened, or -2 if it has been closed.
234      */
235     int getLocalPort();
236     
237     /* ------------------------------------------------------------ */
238     /**
239      * @return Max Idle time for connections in milliseconds
240      */
241     int getMaxIdleTime();
242     
243     /**
244      * @param ms Max Idle time for connections in milliseconds
245      */
246     void setMaxIdleTime(int ms);
247     
248     /* ------------------------------------------------------------ */
249     int getLowResourceMaxIdleTime();
250     void setLowResourceMaxIdleTime(int ms);
251     
252     /* ------------------------------------------------------------ */
253     /**
254      * @return the underlying socket, channel, buffer etc. for the connector.
255      */
256     Object getConnection();
257     
258     
259     /* ------------------------------------------------------------ */
260     /**
261      * @return true if names resolution should be done.
262      */
263     boolean getResolveNames();
264     
265     
266 
267     /* ------------------------------------------------------------ */
268     /**
269      * @return Get the number of requests handled by this connector
270      * since last call of statsReset(). If setStatsOn(false) then this
271      * is undefined.
272      */
273     public int getRequests();
274 
275     /* ------------------------------------------------------------ */
276     /**
277      * @return Returns the connectionsDurationTotal.
278      */
279     public long getConnectionsDurationTotal();
280 
281     /* ------------------------------------------------------------ */
282     /** 
283      * @return Number of connections accepted by the server since
284      * statsReset() called. Undefined if setStatsOn(false).
285      */
286     public int getConnections() ;
287 
288     /* ------------------------------------------------------------ */
289     /** 
290      * @return Number of connections currently open that were opened
291      * since statsReset() called. Undefined if setStatsOn(false).
292      */
293     public int getConnectionsOpen() ;
294 
295     /* ------------------------------------------------------------ */
296     /** 
297      * @return Maximum number of connections opened simultaneously
298      * since statsReset() called. Undefined if setStatsOn(false).
299      */
300     public int getConnectionsOpenMax() ;
301 
302     /* ------------------------------------------------------------ */
303     /** 
304      * @return Maximum duration in milliseconds of an open connection
305      * since statsReset() called. Undefined if setStatsOn(false).
306      */
307     public long getConnectionsDurationMax();
308 
309     /* ------------------------------------------------------------ */
310     /** 
311      * @return Mean duration in milliseconds of open connections
312      * since statsReset() called. Undefined if setStatsOn(false).
313      */
314     public double getConnectionsDurationMean() ;
315 
316     /* ------------------------------------------------------------ */
317     /** 
318      * @return Standard deviation of duration in milliseconds of
319      * open connections since statsReset() called. Undefined if
320      * setStatsOn(false).
321      */
322     public double getConnectionsDurationStdDev() ;
323 
324     /* ------------------------------------------------------------ */
325     /** 
326      * @return Mean number of requests per connection
327      * since statsReset() called. Undefined if setStatsOn(false).
328      */
329     public double getConnectionsRequestsMean() ;
330 
331     /* ------------------------------------------------------------ */
332     /** 
333      * @return Standard Deviation of number of requests per connection
334      * since statsReset() called. Undefined if setStatsOn(false).
335      */
336     public double getConnectionsRequestsStdDev() ;
337 
338     /* ------------------------------------------------------------ */
339     /** 
340      * @return Maximum number of requests per connection
341      * since statsReset() called. Undefined if setStatsOn(false).
342      */
343     public int getConnectionsRequestsMax();
344 
345     /* ------------------------------------------------------------ */
346     /** Reset statistics.
347      */
348     public void statsReset();
349     
350     /* ------------------------------------------------------------ */
351     public void setStatsOn(boolean on);
352     
353     /* ------------------------------------------------------------ */
354     /** 
355      * @return True if statistics collection is turned on.
356      */
357     public boolean getStatsOn();
358     
359     /* ------------------------------------------------------------ */
360     /** 
361      * @return Timestamp stats were started at.
362      */
363     public long getStatsOnMs();
364     
365 
366     /* ------------------------------------------------------------ */
367     /** Check if low on resources.
368      * For most connectors, low resources is measured by calling 
369      * {@link ThreadPool#isLowOnThreads()} on the connector threadpool
370      * or the server threadpool if there is no connector threadpool.
371      * <p>
372      * For blocking connectors, low resources is used to trigger
373      * usage of {@link #getLowResourceMaxIdleTime()} for the timeout
374      * of an idle connection.
375      * <p>
376      * for non-blocking connectors, the number of connections is
377      * used instead of this method, to select the timeout of an 
378      * idle connection.
379      * <p>
380      * For all connectors, low resources is used to trigger the 
381      * usage of {@link #getLowResourceMaxIdleTime()} for read and 
382      * write operations.
383      * 
384      * @return true if this connector is low on resources.
385      */
386     public boolean isLowResources();
387 }