View Javadoc

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