HttpListener


1   // ========================================================================
2   // $Id: HttpListener.java,v 1.17 2005/03/15 10:03:40 gregwilkins Exp $
3   // Copyright 1999-2004 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.http;
17  import java.io.Serializable  ;
18  import java.net.UnknownHostException  ;
19  
20  import org.mortbay.util.LifeCycle;
21  
22  
23  /* ------------------------------------------------------------ */
24  /** HTTP Listener.
25   * This interface describes the methods of a generic request listener for the HttpServer.
26   * 
27   * This class should probably be called HttpConnector, but it's name predates the 
28   * EventListener API in java.
29   *
30   * Once a HttpListener is started, it is responsible for listening for new
31   * connections. Once a new connection is accepted it should be handled by
32   * creating a HttpConnection instance and calling either the HttpConnection.handle()
33   * or HttpConnection.handleNext() methods from a Thread allocated to that
34   * connection.
35   *
36   * @see HttpConnection
37   * @see HttpServer
38   * @version $Id: HttpListener.java,v 1.17 2005/03/15 10:03:40 gregwilkins Exp $
39   * @author Greg Wilkins (gregw)
40   */
41  public interface HttpListener extends LifeCycle, Serializable  
42  {
43      public static final String   ATTRIBUTE="org.mortbay.http.HttpListener";
44          
45      /* ------------------------------------------------------------ */
46      /** Set the HttpServer instance for this HttpListener.
47       * This method is called by the HttpServer.addListener method.
48       * It should not be called directly.
49       * @param server The HttpServer instance this HttpListener has been added to.
50       */
51      public void setHttpServer(HttpServer server);
52  
53      /* ------------------------------------------------------------ */
54      /** Get the HttpServer instance for this HttpListener.
55       * @return The HttpServer instance this HttpListener has been added to,
56       * or null if the listener is not added to any HttpServer.
57       */
58      public HttpServer getHttpServer();
59      
60      /* ------------------------------------------------------------ */
61      /** Set the host or IP of the interface used by this listener. 
62       * @param host The hostname or IP address of the interface used by this
63       * listeners. If null or "0.0.0.0" then all available interfaces are used
64       * by this listener.
65       */
66      public void setHost(String   host)
67          throws UnknownHostException  ;
68  
69      /* ------------------------------------------------------------ */
70      /** Get the host or IP of the interface used by this listener. 
71       * @return The hostname or IP address of the interface used by this
72       * listeners. If null or "0.0.0.0" then all available interfaces are used
73       * by this listener.
74       */
75      public String   getHost();
76      
77      /* ------------------------------------------------------------ */
78      /** Set the port number of the listener. 
79       * @param port The TCP/IP port number to be used by this listener.
80       */
81      public void setPort(int port);
82  
83      /* ------------------------------------------------------------ */
84      /** Get the port number of the listener.
85       * @return The TCP/IP port number used by this listener.
86       */
87      public int getPort();
88  
89      /* ------------------------------------------------------------ */
90      /** Get the size of the buffers used by connections from this listener. 
91       * @return The default buffer size in bytes.
92       */
93      public int getBufferSize();
94      
95      /* ------------------------------------------------------------ */
96      /** Get the size of the header reserve area.
97       * Get the size of the header reserve area within the buffers used
98       * by connections from this listener.  The header reserve is space
99       * reserved in the first buffer of a response to allow a HTTP header to
100      * be written in the same packet.  The reserve should be large enough to
101      * avoid moving data to fit the header, but not too large as to waste memory.
102      * @return The default buffer reserve size in bytes.
103      */
104     public int getBufferReserve();
105     
106     /* ------------------------------------------------------------ */
107     /** Get the default scheme for requests.
108      * If a request is received from a HttpConnection created by this
109      * listener, that does not include a scheme in it's request URL, then
110      * this method is used to determine the protocol scheme most likely used
111      * to connect to this listener.
112      * @return The protocol scheme name (eg "http" or "https").
113      */
114     public String   getDefaultScheme();
115     
116     /* ------------------------------------------------------------ */
117     /** Customize a request for a listener/connection combination.
118      * This method is called by HttpConnection after a request has been read
119      * from that connection and before processing that request.
120      * Implementations may use this callback to add additional listener
121      * and/or connection specific attributes to the request (eg SSL attributes).
122      * @param connection The connection the request was received on, which must
123      * be a HttpConnection created by this listener.
124      * @param request The request to customize.
125      */
126     public void customizeRequest(HttpConnection connection,
127                                  HttpRequest request);
128     
129     /* ------------------------------------------------------------ */
130     /** Prepare a connection for persistance.
131      * This method is called by the HttpConnection on a persistent connection
132      * after each request has been handled and before starting to read for
133      * the next connection.  Implementations may use this callback to change
134      * the parameters or scheduling of the connection.
135      * @param connection The perstent connection, which must be a
136      * HttpConnection created by this listener.
137      */
138     public void persistConnection(HttpConnection connection);
139     
140     /* ------------------------------------------------------------ */
141     /** Get the low on resources state of the listener.
142      * For most implementations, Threads are the resource 
143      * reported on by this method.
144      * @return True if the listener is out of resources.
145      */
146     public boolean isLowOnResources();
147     
148     /* ------------------------------------------------------------ */
149     /** Get the out of resources state of the listener.
150      * For most implementations, Threads are the resource 
151      * reported on by this method.
152      * @return True if the listener is out of resources.
153      */
154     public boolean isOutOfResources();
155 
156     /* ------------------------------------------------------------ */
157     /** Get the integral status of a connection.
158      * @param connection The connection to test.
159      * @return True of the connection checks the integrity of the data. For
160      * most implementations this is true for https connections.
161      */
162     public boolean isIntegral(HttpConnection connection);
163     
164     /* ------------------------------------------------------------ */
165     /** Get the protocol scheme to use for integral redirections.
166      * If an INTEGRAL security constraint is not met for a request, the
167      * request is redirected to an integral port. This scheme return by this
168      * method is used for that redirection.
169      * @return The integral scheme. For most implementations this is "https"
170      */
171     public String   getIntegralScheme();
172     
173     /* ------------------------------------------------------------ */
174     /** Get the protocol port to use for integral redirections.
175      * If an INTEGRAL security constraint is not met for a request, the
176      * request is redirected to an integral port. This port return by this
177      * method is used for that redirection.
178      * @return The integral port. For most implementations this is 443 for https
179      */
180     public int    getIntegralPort();
181     
182     /* ------------------------------------------------------------ */
183     /** Get the confidential status of a connection.
184      * @param connection The connection to test.
185      * @return True of the connection checks the integrity of the data. For
186      * most implementations this is true for https connections.
187      */
188     public boolean isConfidential(HttpConnection connection);
189     
190     /* ------------------------------------------------------------ */
191     /** Get the protocol scheme to use for confidential redirections.
192      * If an CONFIDENTIAL security constraint is not met for a request, the
193      * request is redirected to an confidential port. This scheme return by this
194      * method is used for that redirection.
195      * @return The confidential scheme. For most implementations this is "https"
196      */
197     public String   getConfidentialScheme();
198     
199     /* ------------------------------------------------------------ */
200     /** Get the protocol port to use for confidential redirections.
201      * If an CONFIDENTIAL security constraint is not met for a request, the
202      * request is redirected to an confidential port. This port return by this
203      * method is used for that redirection.
204      * @return The confidential port. For most implementations this is 443 for https
205      */
206     public int    getConfidentialPort();
207     
208     /* ------------------------------------------------------------ */
209     /** Get an optional HttpHandler for the listener.
210      * If Set, then HttpConnection will pass requests from this listener
211      * to this handler with an empty context path, before passing the
212      * request to the HttpServer.  This allows listener specific handling
213      * to be added or even a HttpContext (which is a HttpHandler) to be
214      * bound directly to HttpListener. 
215      */
216     public HttpHandler getHttpHandler();
217     
218     
219 }
220 
221 
222 
223 
224 
225 
226 
227 
228 
229 
230 
231
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags