001: /*
002: * $Header: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Container.java,v 1.7 2001/11/09 19:37:50 remm Exp $
003: * $Revision: 1.7 $
004: * $Date: 2001/11/09 19:37:50 $
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 java.beans.PropertyChangeListener;
067: import java.io.IOException;
068: import javax.servlet.ServletException;
069: import javax.naming.directory.DirContext;
070:
071: /**
072: * A <b>Container</b> is an object that can execute requests received from
073: * a client, and return responses based on those requests. A Container may
074: * optionally support a pipeline of Valves that process the request in an
075: * order configured at runtime, by implementing the <b>Pipeline</b> interface
076: * as well.
077: * <p>
078: * Containers will exist at several conceptual levels within Catalina. The
079: * following examples represent common cases:
080: * <ul>
081: * <li><b>Engine</b> - Representation of the entire Catalina servlet engine,
082: * most likely containing one or more subcontainers that are either Host
083: * or Context implementations, or other custom groups.
084: * <li><b>Host</b> - Representation of a virtual host containing a number
085: * of Contexts.
086: * <li><b>Context</b> - Representation of a single ServletContext, which will
087: * typically contain one or more Wrappers for the supported servlets.
088: * <li><b>Wrapper</b> - Representation of an individual servlet definition
089: * (which may support multiple servlet instances if the servlet itself
090: * implements SingleThreadModel).
091: * </ul>
092: * A given deployment of Catalina need not include Containers at all of the
093: * levels described above. For example, an administration application
094: * embedded within a network device (such as a router) might only contain
095: * a single Context and a few Wrappers, or even a single Wrapper if the
096: * application is relatively small. Therefore, Container implementations
097: * need to be designed so that they will operate correctly in the absence
098: * of parent Containers in a given deployment.
099: * <p>
100: * A Container may also be associated with a number of support components
101: * that provide functionality which might be shared (by attaching it to a
102: * parent Container) or individually customized. The following support
103: * components are currently recognized:
104: * <ul>
105: * <li><b>Loader</b> - Class loader to use for integrating new Java classes
106: * for this Container into the JVM in which Catalina is running.
107: * <li><b>Logger</b> - Implementation of the <code>log()</code> method
108: * signatures of the <code>ServletContext</code> interface.
109: * <li><b>Manager</b> - Manager for the pool of Sessions associated with
110: * this Container.
111: * <li><b>Realm</b> - Read-only interface to a security domain, for
112: * authenticating user identities and their corresponding roles.
113: * <li><b>Resources</b> - JNDI directory context enabling access to static
114: * resources, enabling custom linkages to existing server components when
115: * Catalina is embedded in a larger server.
116: * </ul>
117: *
118: * @author Craig R. McClanahan
119: * @author Remy Maucherat
120: * @version $Revision: 1.7 $ $Date: 2001/11/09 19:37:50 $
121: */
122:
123: public interface Container {
124:
125: // ----------------------------------------------------- Manifest Constants
126:
127: /**
128: * The ContainerEvent event type sent when a child container is added
129: * by <code>addChild()</code>.
130: */
131: public static final String ADD_CHILD_EVENT = "addChild";
132:
133: /**
134: * The ContainerEvent event type sent when a Mapper is added
135: * by <code>addMapper()</code>.
136: */
137: public static final String ADD_MAPPER_EVENT = "addMapper";
138:
139: /**
140: * The ContainerEvent event type sent when a valve is added
141: * by <code>addValve()</code>, if this Container supports pipelines.
142: */
143: public static final String ADD_VALVE_EVENT = "addValve";
144:
145: /**
146: * The ContainerEvent event type sent when a child container is removed
147: * by <code>removeChild()</code>.
148: */
149: public static final String REMOVE_CHILD_EVENT = "removeChild";
150:
151: /**
152: * The ContainerEvent event type sent when a Mapper is removed
153: * by <code>removeMapper()</code>.
154: */
155: public static final String REMOVE_MAPPER_EVENT = "removeMapper";
156:
157: /**
158: * The ContainerEvent event type sent when a valve is removed
159: * by <code>removeValve()</code>, if this Container supports pipelines.
160: */
161: public static final String REMOVE_VALVE_EVENT = "removeValve";
162:
163: // ------------------------------------------------------------- Properties
164:
165: /**
166: * Return descriptive information about this Container implementation and
167: * the corresponding version number, in the format
168: * <code><description>/<version></code>.
169: */
170: public String getInfo();
171:
172: /**
173: * Return the Loader with which this Container is associated. If there is
174: * no associated Loader, return the Loader associated with our parent
175: * Container (if any); otherwise, return <code>null</code>.
176: */
177: public Loader getLoader();
178:
179: /**
180: * Set the Loader with which this Container is associated.
181: *
182: * @param loader The newly associated loader
183: */
184: public void setLoader(Loader loader);
185:
186: /**
187: * Return the Logger with which this Container is associated. If there is
188: * no associated Logger, return the Logger associated with our parent
189: * Container (if any); otherwise return <code>null</code>.
190: */
191: public Logger getLogger();
192:
193: /**
194: * Set the Logger with which this Container is associated.
195: *
196: * @param logger The newly associated Logger
197: */
198: public void setLogger(Logger logger);
199:
200: /**
201: * Return the Manager with which this Container is associated. If there is
202: * no associated Manager, return the Manager associated with our parent
203: * Container (if any); otherwise return <code>null</code>.
204: */
205: public Manager getManager();
206:
207: /**
208: * Set the Manager with which this Container is associated.
209: *
210: * @param manager The newly associated Manager
211: */
212: public void setManager(Manager manager);
213:
214: /**
215: * Return the Cluster with which this Container is associated. If there is
216: * no associated Cluster, return the Cluster associated with our parent
217: * Container (if any); otherwise return <code>null</code>.
218: */
219: public Cluster getCluster();
220:
221: /**
222: * Set the Cluster with which this Container is associated.
223: *
224: * @param connector The Connector to be added
225: */
226: public void setCluster(Cluster cluster);
227:
228: /**
229: * Return a name string (suitable for use by humans) that describes this
230: * Container. Within the set of child containers belonging to a particular
231: * parent, Container names must be unique.
232: */
233: public String getName();
234:
235: /**
236: * Set a name string (suitable for use by humans) that describes this
237: * Container. Within the set of child containers belonging to a particular
238: * parent, Container names must be unique.
239: *
240: * @param name New name of this container
241: *
242: * @exception IllegalStateException if this Container has already been
243: * added to the children of a parent Container (after which the name
244: * may not be changed)
245: */
246: public void setName(String name);
247:
248: /**
249: * Return the Container for which this Container is a child, if there is
250: * one. If there is no defined parent, return <code>null</code>.
251: */
252: public Container getParent();
253:
254: /**
255: * Set the parent Container to which this Container is being added as a
256: * child. This Container may refuse to become attached to the specified
257: * Container by throwing an exception.
258: *
259: * @param container Container to which this Container is being added
260: * as a child
261: *
262: * @exception IllegalArgumentException if this Container refuses to become
263: * attached to the specified Container
264: */
265: public void setParent(Container container);
266:
267: /**
268: * Return the parent class loader (if any) for web applications.
269: */
270: public ClassLoader getParentClassLoader();
271:
272: /**
273: * Set the parent class loader (if any) for web applications.
274: * This call is meaningful only <strong>before</strong> a Loader has
275: * been configured, and the specified value (if non-null) should be
276: * passed as an argument to the class loader constructor.
277: *
278: * @param parent The new parent class loader
279: */
280: public void setParentClassLoader(ClassLoader parent);
281:
282: /**
283: * Return the Realm with which this Container is associated. If there is
284: * no associated Realm, return the Realm associated with our parent
285: * Container (if any); otherwise return <code>null</code>.
286: */
287: public Realm getRealm();
288:
289: /**
290: * Set the Realm with which this Container is associated.
291: *
292: * @param realm The newly associated Realm
293: */
294: public void setRealm(Realm realm);
295:
296: /**
297: * Return the Resources with which this Container is associated. If there
298: * is no associated Resources object, return the Resources associated with
299: * our parent Container (if any); otherwise return <code>null</code>.
300: */
301: public DirContext getResources();
302:
303: /**
304: * Set the Resources object with which this Container is associated.
305: *
306: * @param resources The newly associated Resources
307: */
308: public void setResources(DirContext resources);
309:
310: // --------------------------------------------------------- Public Methods
311:
312: /**
313: * Add a new child Container to those associated with this Container,
314: * if supported. Prior to adding this Container to the set of children,
315: * the child's <code>setParent()</code> method must be called, with this
316: * Container as an argument. This method may thrown an
317: * <code>IllegalArgumentException</code> if this Container chooses not
318: * to be attached to the specified Container, in which case it is not added
319: *
320: * @param child New child Container to be added
321: *
322: * @exception IllegalArgumentException if this exception is thrown by
323: * the <code>setParent()</code> method of the child Container
324: * @exception IllegalArgumentException if the new child does not have
325: * a name unique from that of existing children of this Container
326: * @exception IllegalStateException if this Container does not support
327: * child Containers
328: */
329: public void addChild(Container child);
330:
331: /**
332: * Add a container event listener to this component.
333: *
334: * @param listener The listener to add
335: */
336: public void addContainerListener(ContainerListener listener);
337:
338: /**
339: * Add the specified Mapper associated with this Container.
340: *
341: * @param mapper The corresponding Mapper implementation
342: *
343: * @exception IllegalArgumentException if this exception is thrown by
344: * the <code>setContainer()</code> method of the Mapper
345: */
346: public void addMapper(Mapper mapper);
347:
348: /**
349: * Add a property change listener to this component.
350: *
351: * @param listener The listener to add
352: */
353: public void addPropertyChangeListener(
354: PropertyChangeListener listener);
355:
356: /**
357: * Return the child Container, associated with this Container, with
358: * the specified name (if any); otherwise, return <code>null</code>
359: *
360: * @param name Name of the child Container to be retrieved
361: */
362: public Container findChild(String name);
363:
364: /**
365: * Return the set of children Containers associated with this Container.
366: * If this Container has no children, a zero-length array is returned.
367: */
368: public Container[] findChildren();
369:
370: /**
371: * Return the set of container listeners associated with this Container.
372: * If this Container has no registered container listeners, a zero-length
373: * array is returned.
374: */
375: public ContainerListener[] findContainerListeners();
376:
377: /**
378: * Return the Mapper associated with the specified protocol, if there
379: * is one. If there is only one defined Mapper, use it for all protocols.
380: * If there is no matching Mapper, return <code>null</code>.
381: *
382: * @param protocol Protocol for which to find a Mapper
383: */
384: public Mapper findMapper(String protocol);
385:
386: /**
387: * Return the set of Mappers associated with this Container. If this
388: * Container has no Mappers, a zero-length array is returned.
389: */
390: public Mapper[] findMappers();
391:
392: /**
393: * Process the specified Request, and generate the corresponding Response,
394: * according to the design of this particular Container.
395: *
396: * @param request Request to be processed
397: * @param response Response to be produced
398: *
399: * @exception IOException if an input/output error occurred while
400: * processing
401: * @exception ServletException if a ServletException was thrown
402: * while processing this request
403: */
404: public void invoke(Request request, Response response)
405: throws IOException, ServletException;
406:
407: /**
408: * Return the child Container that should be used to process this Request,
409: * based upon its characteristics. If no such child Container can be
410: * identified, return <code>null</code> instead.
411: *
412: * @param request Request being processed
413: * @param update Update the Request to reflect the mapping selection?
414: */
415: public Container map(Request request, boolean update);
416:
417: /**
418: * Remove an existing child Container from association with this parent
419: * Container.
420: *
421: * @param child Existing child Container to be removed
422: */
423: public void removeChild(Container child);
424:
425: /**
426: * Remove a container event listener from this component.
427: *
428: * @param listener The listener to remove
429: */
430: public void removeContainerListener(ContainerListener listener);
431:
432: /**
433: * Remove a Mapper associated with this Container, if any.
434: *
435: * @param mapper The Mapper to be removed
436: */
437: public void removeMapper(Mapper mapper);
438:
439: /**
440: * Remove a property change listener from this component.
441: *
442: * @param listener The listener to remove
443: */
444: public void removePropertyChangeListener(
445: PropertyChangeListener listener);
446:
447: }
|