1   //========================================================================
2   //$Id: Connector.java,v 1.7 2005/11/25 21:01:45 gregwilkins Exp $
3   //Copyright 2004-2005 Mort Bay Consulting Pty. Ltd.
4   //------------------------------------------------------------------------
5   //Licensed under the Apache License, Version 2.0 (the "License");
6   //you may not use this file except in compliance with the License.
7   //You may obtain a copy of the License at 
8   //http://www.apache.org/licenses/LICENSE-2.0
9   //Unless required by applicable law or agreed to in writing, software
10  //distributed under the License is distributed on an "AS IS" BASIS,
11  //WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  //See the License for the specific language governing permissions and
13  //limitations under the License.
14  //========================================================================
15  
16  package org.mortbay.jetty;
17  
18  import java.io.IOException;
19  
20  import org.mortbay.component.LifeCycle;
21  import org.mortbay.io.Buffers;
22  import org.mortbay.io.EndPoint;
23  
24  /** HTTP Connector.
25   * Implementations of this interface provide connectors for the HTTP protocol.
26   * A connector receives requests (normally from a socket) and calls the 
27   * handle method of the Handler object.  These operations are performed using
28   * threads from the ThreadPool set on the connector.
29   * 
30   * When a connector is registered with an instance of Server, then the server
31   * will set itself as both the ThreadPool and the Handler.  Note that a connector
32   * can be used without a Server if a thread pool and handler are directly provided.
33   * 
34   * @author gregw
35   * 
36   */
37  public interface Connector extends LifeCycle, Buffers
38  { 
39      /* ------------------------------------------------------------ */
40      /**
41       * @return the name of the connector. Defaults to the HostName:port
42       */
43      String getName();
44      
45      /* ------------------------------------------------------------ */
46      /**
47       * Opens the connector 
48       * @throws IOException
49       */
50      void open() throws IOException;
51  
52      /* ------------------------------------------------------------ */
53      void close() throws IOException;
54  
55      /* ------------------------------------------------------------ */
56      void setServer(Server server);
57      
58      /* ------------------------------------------------------------ */
59      Server getServer();
60  
61      /* ------------------------------------------------------------ */
62      /**
63       * @return Returns the headerBufferSize.
64       */
65      int getHeaderBufferSize();
66      
67      /* ------------------------------------------------------------ */
68      /**
69       * Set the size of the buffer to be used for request and response headers.
70       * An idle connection will at most have one buffer of this size allocated.
71       * @param headerBufferSize The headerBufferSize to set.
72       */
73      void setHeaderBufferSize(int headerBufferSize);
74      
75      
76      /* ------------------------------------------------------------ */
77      /**
78       * @return Returns the requestBufferSize.
79       */
80      int getRequestBufferSize();
81      
82      /* ------------------------------------------------------------ */
83      /**
84       * Set the size of the content buffer for receiving requests. 
85       * These buffers are only used for active connections that have
86       * requests with bodies that will not fit within the header buffer.
87       * @param requestBufferSize The requestBufferSize to set.
88       */
89      void setRequestBufferSize(int requestBufferSize);
90      
91      /* ------------------------------------------------------------ */
92      /**
93       * @return Returns the responseBufferSize.
94       */
95      int getResponseBufferSize();
96      
97      /* ------------------------------------------------------------ */
98      /**
99       * Set the size of the content buffer for sending responses. 
100      * These buffers are only used for active connections that are sending 
101      * responses with bodies that will not fit within the header buffer.
102      * @param responseBufferSize The responseBufferSize to set.
103      */
104     void setResponseBufferSize(int responseBufferSize);
105     
106 
107     /* ------------------------------------------------------------ */
108     /**
109      * @return The port to use when redirecting a request if a data constraint of integral is 
110      * required. See {@link org.mortbay.jetty.security.Constraint#getDataConstraint()}
111      */
112     int getIntegralPort();
113 
114     /* ------------------------------------------------------------ */
115     /**
116      * @return The schema to use when redirecting a request if a data constraint of integral is 
117      * required. See {@link org.mortbay.jetty.security.Constraint#getDataConstraint()}
118      */
119     String getIntegralScheme();
120 
121     /* ------------------------------------------------------------ */
122     /**
123      * @param request A request
124      * @return true if the request is integral. This normally means the https schema has been used.
125      */
126     boolean isIntegral(Request request);
127 
128     /* ------------------------------------------------------------ */
129     /**
130      * @return The port to use when redirecting a request if a data constraint of confidential is 
131      * required. See {@link org.mortbay.jetty.security.Constraint#getDataConstraint()}
132      */
133     int getConfidentialPort();
134     
135 
136     /* ------------------------------------------------------------ */
137     /**
138      * @return The schema to use when redirecting a request if a data constraint of confidential is 
139      * required. See {@link org.mortbay.jetty.security.Constraint#getDataConstraint()}
140      */
141     String getConfidentialScheme();
142     
143     /* ------------------------------------------------------------ */
144     /**
145      * @param request A request
146      * @return true if the request is confidential. This normally means the https schema has been used.
147      */
148     boolean isConfidential(Request request);
149 
150     /* ------------------------------------------------------------ */
151     /** Customize a request for an endpoint.
152      * Called on every request to allow customization of the request for
153      * the particular endpoint (eg security properties from a SSL connection).
154      * @param endpoint
155      * @param request
156      * @throws IOException
157      */
158     void customize(EndPoint endpoint, Request request) throws IOException;
159 
160     /* ------------------------------------------------------------ */
161     /** Persist an endpoint.
162      * Called after every request if the connection is to remain open.
163      * @param endpoint
164      * @param request
165      * @throws IOException
166      */
167     void persist(EndPoint endpoint) throws IOException;
168     
169     /* ------------------------------------------------------------ */
170     String getHost();
171     
172     /* ------------------------------------------------------------ */
173     void setHost(String hostname);
174 
175     /* ------------------------------------------------------------ */
176     /**
177      * @param port The port fto listen of for connections or 0 if any available
178      * port may be used.
179      */
180     void setPort(int port);
181     
182     /* ------------------------------------------------------------ */
183     /**
184      * @return The configured port for the connector or 0 if any available
185      * port may be used.
186      */
187     int getPort();
188     
189     /* ------------------------------------------------------------ */
190     /**
191      * @return The actual port the connector is listening on or -1 if there 
192      * is no port or the connector is not open.
193      */
194     int getLocalPort();
195     
196     /* ------------------------------------------------------------ */
197     int getMaxIdleTime();
198     void setMaxIdleTime(int ms);
199     
200     /* ------------------------------------------------------------ */
201     int getLowResourceMaxIdleTime();
202     void setLowResourceMaxIdleTime(int ms);
203     
204     /* ------------------------------------------------------------ */
205     /**
206      * @return the underlying socket, channel, buffer etc. for the connector.
207      */
208     Object getConnection();
209     
210     
211     /* ------------------------------------------------------------ */
212     /**
213      * @return true if names resolution should be done.
214      */
215     boolean getResolveNames();
216     
217     
218 
219     /* ------------------------------------------------------------ */
220     /**
221      * @return Get the number of requests handled by this connector
222      * since last call of statsReset(). If setStatsOn(false) then this
223      * is undefined.
224      */
225     public int getRequests();
226 
227     /* ------------------------------------------------------------ */
228     /**
229      * @return Returns the connectionsDurationMin.
230      */
231     public long getConnectionsDurationMin();
232 
233     /* ------------------------------------------------------------ */
234     /**
235      * @return Returns the connectionsDurationTotal.
236      */
237     public long getConnectionsDurationTotal();
238     
239     /* ------------------------------------------------------------ */
240     /**
241      * @return Returns the connectionsOpenMin.
242      */
243     public int getConnectionsOpenMin();
244 
245     /* ------------------------------------------------------------ */
246     /**
247      * @return Returns the connectionsRequestsMin.
248      */
249     public int getConnectionsRequestsMin();
250 
251 
252     /* ------------------------------------------------------------ */
253     /** 
254      * @return Number of connections accepted by the server since
255      * statsReset() called. Undefined if setStatsOn(false).
256      */
257     public int getConnections() ;
258 
259     /* ------------------------------------------------------------ */
260     /** 
261      * @return Number of connections currently open that were opened
262      * since statsReset() called. Undefined if setStatsOn(false).
263      */
264     public int getConnectionsOpen() ;
265 
266     /* ------------------------------------------------------------ */
267     /** 
268      * @return Maximum number of connections opened simultaneously
269      * since statsReset() called. Undefined if setStatsOn(false).
270      */
271     public int getConnectionsOpenMax() ;
272 
273     /* ------------------------------------------------------------ */
274     /** 
275      * @return Average duration in milliseconds of open connections
276      * since statsReset() called. Undefined if setStatsOn(false).
277      */
278     public long getConnectionsDurationAve() ;
279 
280     /* ------------------------------------------------------------ */
281     /** 
282      * @return Maximum duration in milliseconds of an open connection
283      * since statsReset() called. Undefined if setStatsOn(false).
284      */
285     public long getConnectionsDurationMax();
286 
287     /* ------------------------------------------------------------ */
288     /** 
289      * @return Average number of requests per connection
290      * since statsReset() called. Undefined if setStatsOn(false).
291      */
292     public int getConnectionsRequestsAve() ;
293 
294     /* ------------------------------------------------------------ */
295     /** 
296      * @return Maximum number of requests per connection
297      * since statsReset() called. Undefined if setStatsOn(false).
298      */
299     public int getConnectionsRequestsMax();
300 
301 
302     
303     /* ------------------------------------------------------------ */
304     /** Reset statistics.
305      */
306     public void statsReset();
307     
308     /* ------------------------------------------------------------ */
309     public void setStatsOn(boolean on);
310     
311     /* ------------------------------------------------------------ */
312     /** 
313      * @return True if statistics collection is turned on.
314      */
315     public boolean getStatsOn();
316     
317     /* ------------------------------------------------------------ */
318     /** 
319      * @return Timestamp stats were started at.
320      */
321     public long getStatsOnMs();
322     
323     
324 }