001: /*
002: * $Header: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Connector.java,v 1.12 2001/12/20 21:25:23 remm Exp $
003: * $Revision: 1.12 $
004: * $Date: 2001/12/20 21:25:23 $
005: *
006: * ====================================================================
007: *
008: * The Apache Software License, Version 1.1
009: *
010: * Copyright (c) 1999 The Apache Software Foundation. All rights
011: * reserved.
012: *
013: * Redistribution and use in source and binary forms, with or without
014: * modification, are permitted provided that the following conditions
015: * are met:
016: *
017: * 1. Redistributions of source code must retain the above copyright
018: * notice, this list of conditions and the following disclaimer.
019: *
020: * 2. Redistributions in binary form must reproduce the above copyright
021: * notice, this list of conditions and the following disclaimer in
022: * the documentation and/or other materials provided with the
023: * distribution.
024: *
025: * 3. The end-user documentation included with the redistribution, if
026: * any, must include the following acknowlegement:
027: * "This product includes software developed by the
028: * Apache Software Foundation (http://www.apache.org/)."
029: * Alternately, this acknowlegement may appear in the software itself,
030: * if and wherever such third-party acknowlegements normally appear.
031: *
032: * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
033: * Foundation" must not be used to endorse or promote products derived
034: * from this software without prior written permission. For written
035: * permission, please contact apache@apache.org.
036: *
037: * 5. Products derived from this software may not be called "Apache"
038: * nor may "Apache" appear in their names without prior written
039: * permission of the Apache Group.
040: *
041: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
042: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
043: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
044: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
045: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
046: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
047: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
048: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
049: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
050: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
051: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
052: * SUCH DAMAGE.
053: * ====================================================================
054: *
055: * This software consists of voluntary contributions made by many
056: * individuals on behalf of the Apache Software Foundation. For more
057: * information on the Apache Software Foundation, please see
058: * <http://www.apache.org/>.
059: *
060: * [Additional notices, if required by prior licensing conditions]
061: *
062: */
063:
064: package org.apache.catalina;
065:
066: import org.apache.catalina.net.ServerSocketFactory;
067:
068: /**
069: * A <b>Connector</b> is a component responsible receiving requests from,
070: * and returning responses to, a client application. A Connector performs
071: * the following general logic:
072: * <ul>
073: * <li>Receive a request from the client application.
074: * <li>Create (or allocate from a pool) appropriate Request and Response
075: * instances, and populate their properties based on the contents of
076: * the received request, as described below.
077: * <ul>
078: * <li>For all Requests, the <code>connector</code>,
079: * <code>protocol</code>, <code>remoteAddr</code>,
080: * <code>response</code>, <code>scheme</code>,
081: * <code>secure</code>, <code>serverName</code>,
082: * <code>serverPort</code> and <code>stream</code>
083: * properties <b>MUST</b> be set. The <code>contentLength</code>
084: * and <code>contentType</code> properties are also generally set.
085: * <li>For HttpRequests, the <code>method</code>, <code>queryString</code>,
086: * <code>requestedSessionCookie</code>,
087: * <code>requestedSessionId</code>, <code>requestedSessionURL</code>,
088: * <code>requestURI</code>, and <code>secure</code> properties
089: * <b>MUST</b> be set. In addition, the various <code>addXxx</code>
090: * methods must be called to record the presence of cookies, headers,
091: * and locales in the original request.
092: * <li>For all Responses, the <code>connector</code>, <code>request</code>,
093: * and <code>stream</code> properties <b>MUST</b> be set.
094: * <li>No additional headers must be set by the Connector for
095: * HttpResponses.
096: * </ul>
097: * <li>Identify an appropriate Container to use for processing this request.
098: * For a stand alone Catalina installation, this will probably be a
099: * (singleton) Engine implementation. For a Connector attaching Catalina
100: * to a web server such as Apache, this step could take advantage of
101: * parsing already performed within the web server to identify the
102: * Context, and perhaps even the Wrapper, to utilize in satisfying this
103: * Request.
104: * <li>Call the <code>invoke()</code> method of the selected Container,
105: * passing the initialized Request and Response instances as arguments.
106: * <li>Return any response created by the Container to the client, or
107: * return an appropriate error message if an exception of any type
108: * was thrown.
109: * <li>If utilizing a pool of Request and Response objects, recycle the pair
110: * of instances that was just used.
111: * </ul>
112: * It is expected that the implementation details of various Connectors will
113: * vary widely, so the logic above should considered typical rather than
114: * normative.
115: *
116: * @author Craig R. McClanahan
117: * @version $Revision: 1.12 $ $Date: 2001/12/20 21:25:23 $
118: */
119:
120: public interface Connector {
121:
122: // ------------------------------------------------------------- Properties
123:
124: /**
125: * Return the Container used for processing requests received by this
126: * Connector.
127: */
128: public Container getContainer();
129:
130: /**
131: * Set the Container used for processing requests received by this
132: * Connector.
133: *
134: * @param container The new Container to use
135: */
136: public void setContainer(Container container);
137:
138: /**
139: * Return the "enable DNS lookups" flag.
140: */
141: public boolean getEnableLookups();
142:
143: /**
144: * Set the "enable DNS lookups" flag.
145: *
146: * @param enableLookups The new "enable DNS lookups" flag value
147: */
148: public void setEnableLookups(boolean enableLookups);
149:
150: /**
151: * Return the server socket factory used by this Container.
152: */
153: public ServerSocketFactory getFactory();
154:
155: /**
156: * Set the server socket factory used by this Container.
157: *
158: * @param factory The new server socket factory
159: */
160: public void setFactory(ServerSocketFactory factory);
161:
162: /**
163: * Return descriptive information about this Connector implementation.
164: */
165: public String getInfo();
166:
167: /**
168: * Return the port number to which a request should be redirected if
169: * it comes in on a non-SSL port and is subject to a security constraint
170: * with a transport guarantee that requires SSL.
171: */
172: public int getRedirectPort();
173:
174: /**
175: * Set the redirect port number.
176: *
177: * @param redirectPort The redirect port number (non-SSL to SSL)
178: */
179: public void setRedirectPort(int redirectPort);
180:
181: /**
182: * Return the scheme that will be assigned to requests received
183: * through this connector. Default value is "http".
184: */
185: public String getScheme();
186:
187: /**
188: * Set the scheme that will be assigned to requests received through
189: * this connector.
190: *
191: * @param scheme The new scheme
192: */
193: public void setScheme(String scheme);
194:
195: /**
196: * Return the secure connection flag that will be assigned to requests
197: * received through this connector. Default value is "false".
198: */
199: public boolean getSecure();
200:
201: /**
202: * Set the secure connection flag that will be assigned to requests
203: * received through this connector.
204: *
205: * @param secure The new secure connection flag
206: */
207: public void setSecure(boolean secure);
208:
209: /**
210: * Return the <code>Service</code> with which we are associated (if any).
211: */
212: public Service getService();
213:
214: /**
215: * Set the <code>Service</code> with which we are associated (if any).
216: *
217: * @param service The service that owns this Engine
218: */
219: public void setService(Service service);
220:
221: // --------------------------------------------------------- Public Methods
222:
223: /**
224: * Create (or allocate) and return a Request object suitable for
225: * specifying the contents of a Request to the responsible Container.
226: */
227: public Request createRequest();
228:
229: /**
230: * Create (or allocate) and return a Response object suitable for
231: * receiving the contents of a Response from the responsible Container.
232: */
233: public Response createResponse();
234:
235: /**
236: * Invoke a pre-startup initialization. This is used to allow connectors
237: * to bind to restricted ports under Unix operating environments.
238: *
239: * @exception LifecycleException If this server was already initialized.
240: */
241: public void initialize() throws LifecycleException;
242:
243: }
|