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
19package org.eclipse.jetty.server;
20
21import java.io.IOException;
22
23import org.eclipse.jetty.io.Buffers;
24import org.eclipse.jetty.io.EndPoint;
25import org.eclipse.jetty.util.component.LifeCycle;
26import 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 */
45public 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}
388