001: /*
002: * Copyright 1999,2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.catalina;
018:
019: import java.beans.PropertyChangeListener;
020: import java.io.IOException;
021: import javax.servlet.ServletException;
022: import javax.naming.directory.DirContext;
023:
024: /**
025: * A <b>Container</b> is an object that can execute requests received from
026: * a client, and return responses based on those requests. A Container may
027: * optionally support a pipeline of Valves that process the request in an
028: * order configured at runtime, by implementing the <b>Pipeline</b> interface
029: * as well.
030: * <p>
031: * Containers will exist at several conceptual levels within Catalina. The
032: * following examples represent common cases:
033: * <ul>
034: * <li><b>Engine</b> - Representation of the entire Catalina servlet engine,
035: * most likely containing one or more subcontainers that are either Host
036: * or Context implementations, or other custom groups.
037: * <li><b>Host</b> - Representation of a virtual host containing a number
038: * of Contexts.
039: * <li><b>Context</b> - Representation of a single ServletContext, which will
040: * typically contain one or more Wrappers for the supported servlets.
041: * <li><b>Wrapper</b> - Representation of an individual servlet definition
042: * (which may support multiple servlet instances if the servlet itself
043: * implements SingleThreadModel).
044: * </ul>
045: * A given deployment of Catalina need not include Containers at all of the
046: * levels described above. For example, an administration application
047: * embedded within a network device (such as a router) might only contain
048: * a single Context and a few Wrappers, or even a single Wrapper if the
049: * application is relatively small. Therefore, Container implementations
050: * need to be designed so that they will operate correctly in the absence
051: * of parent Containers in a given deployment.
052: * <p>
053: * A Container may also be associated with a number of support components
054: * that provide functionality which might be shared (by attaching it to a
055: * parent Container) or individually customized. The following support
056: * components are currently recognized:
057: * <ul>
058: * <li><b>Loader</b> - Class loader to use for integrating new Java classes
059: * for this Container into the JVM in which Catalina is running.
060: * <li><b>Logger</b> - Implementation of the <code>log()</code> method
061: * signatures of the <code>ServletContext</code> interface.
062: * <li><b>Manager</b> - Manager for the pool of Sessions associated with
063: * this Container.
064: * <li><b>Realm</b> - Read-only interface to a security domain, for
065: * authenticating user identities and their corresponding roles.
066: * <li><b>Resources</b> - JNDI directory context enabling access to static
067: * resources, enabling custom linkages to existing server components when
068: * Catalina is embedded in a larger server.
069: * </ul>
070: *
071: * @author Craig R. McClanahan
072: * @author Remy Maucherat
073: * @version $Revision: 1.8 $ $Date: 2004/05/26 15:25:05 $
074: */
075:
076: public interface Container {
077:
078: // ----------------------------------------------------- Manifest Constants
079:
080: /**
081: * The ContainerEvent event type sent when a child container is added
082: * by <code>addChild()</code>.
083: */
084: public static final String ADD_CHILD_EVENT = "addChild";
085:
086: /**
087: * The ContainerEvent event type sent when a Mapper is added
088: * by <code>addMapper()</code>.
089: */
090: public static final String ADD_MAPPER_EVENT = "addMapper";
091:
092: /**
093: * The ContainerEvent event type sent when a valve is added
094: * by <code>addValve()</code>, if this Container supports pipelines.
095: */
096: public static final String ADD_VALVE_EVENT = "addValve";
097:
098: /**
099: * The ContainerEvent event type sent when a child container is removed
100: * by <code>removeChild()</code>.
101: */
102: public static final String REMOVE_CHILD_EVENT = "removeChild";
103:
104: /**
105: * The ContainerEvent event type sent when a Mapper is removed
106: * by <code>removeMapper()</code>.
107: */
108: public static final String REMOVE_MAPPER_EVENT = "removeMapper";
109:
110: /**
111: * The ContainerEvent event type sent when a valve is removed
112: * by <code>removeValve()</code>, if this Container supports pipelines.
113: */
114: public static final String REMOVE_VALVE_EVENT = "removeValve";
115:
116: // ------------------------------------------------------------- Properties
117:
118: /**
119: * Return descriptive information about this Container implementation and
120: * the corresponding version number, in the format
121: * <code><description>/<version></code>.
122: */
123: public String getInfo();
124:
125: /**
126: * Return the Loader with which this Container is associated. If there is
127: * no associated Loader, return the Loader associated with our parent
128: * Container (if any); otherwise, return <code>null</code>.
129: */
130: public Loader getLoader();
131:
132: /**
133: * Set the Loader with which this Container is associated.
134: *
135: * @param loader The newly associated loader
136: */
137: public void setLoader(Loader loader);
138:
139: /**
140: * Return the Logger with which this Container is associated. If there is
141: * no associated Logger, return the Logger associated with our parent
142: * Container (if any); otherwise return <code>null</code>.
143: */
144: public Logger getLogger();
145:
146: /**
147: * Set the Logger with which this Container is associated.
148: *
149: * @param logger The newly associated Logger
150: */
151: public void setLogger(Logger logger);
152:
153: /**
154: * Return the Manager with which this Container is associated. If there is
155: * no associated Manager, return the Manager associated with our parent
156: * Container (if any); otherwise return <code>null</code>.
157: */
158: public Manager getManager();
159:
160: /**
161: * Set the Manager with which this Container is associated.
162: *
163: * @param manager The newly associated Manager
164: */
165: public void setManager(Manager manager);
166:
167: /**
168: * Return an object which may be utilized for mapping to this component.
169: */
170: public Object getMappingObject();
171:
172: /**
173: * Return the Pipeline object that manages the Valves associated with
174: * this Container.
175: */
176: public Pipeline getPipeline();
177:
178: /**
179: * Return the Cluster with which this Container is associated. If there is
180: * no associated Cluster, return the Cluster associated with our parent
181: * Container (if any); otherwise return <code>null</code>.
182: */
183: public Cluster getCluster();
184:
185: /**
186: * Set the Cluster with which this Container is associated.
187: *
188: * @param cluster the Cluster with which this Container is associated.
189: */
190: public void setCluster(Cluster cluster);
191:
192: /**
193: * Get the delay between the invocation of the backgroundProcess method on
194: * this container and its children. Child containers will not be invoked
195: * if their delay value is not negative (which would mean they are using
196: * their own thread). Setting this to a positive value will cause
197: * a thread to be spawn. After waiting the specified amount of time,
198: * the thread will invoke the executePeriodic method on this container
199: * and all its children.
200: */
201: public int getBackgroundProcessorDelay();
202:
203: /**
204: * Set the delay between the invocation of the execute method on this
205: * container and its children.
206: *
207: * @param delay The delay in seconds between the invocation of
208: * backgroundProcess methods
209: */
210: public void setBackgroundProcessorDelay(int delay);
211:
212: /**
213: * Return a name string (suitable for use by humans) that describes this
214: * Container. Within the set of child containers belonging to a particular
215: * parent, Container names must be unique.
216: */
217: public String getName();
218:
219: /**
220: * Set a name string (suitable for use by humans) that describes this
221: * Container. Within the set of child containers belonging to a particular
222: * parent, Container names must be unique.
223: *
224: * @param name New name of this container
225: *
226: * @exception IllegalStateException if this Container has already been
227: * added to the children of a parent Container (after which the name
228: * may not be changed)
229: */
230: public void setName(String name);
231:
232: /**
233: * Return the Container for which this Container is a child, if there is
234: * one. If there is no defined parent, return <code>null</code>.
235: */
236: public Container getParent();
237:
238: /**
239: * Set the parent Container to which this Container is being added as a
240: * child. This Container may refuse to become attached to the specified
241: * Container by throwing an exception.
242: *
243: * @param container Container to which this Container is being added
244: * as a child
245: *
246: * @exception IllegalArgumentException if this Container refuses to become
247: * attached to the specified Container
248: */
249: public void setParent(Container container);
250:
251: /**
252: * Return the parent class loader (if any) for web applications.
253: */
254: public ClassLoader getParentClassLoader();
255:
256: /**
257: * Set the parent class loader (if any) for web applications.
258: * This call is meaningful only <strong>before</strong> a Loader has
259: * been configured, and the specified value (if non-null) should be
260: * passed as an argument to the class loader constructor.
261: *
262: * @param parent The new parent class loader
263: */
264: public void setParentClassLoader(ClassLoader parent);
265:
266: /**
267: * Return the Realm with which this Container is associated. If there is
268: * no associated Realm, return the Realm associated with our parent
269: * Container (if any); otherwise return <code>null</code>.
270: */
271: public Realm getRealm();
272:
273: /**
274: * Set the Realm with which this Container is associated.
275: *
276: * @param realm The newly associated Realm
277: */
278: public void setRealm(Realm realm);
279:
280: /**
281: * Return the Resources with which this Container is associated. If there
282: * is no associated Resources object, return the Resources associated with
283: * our parent Container (if any); otherwise return <code>null</code>.
284: */
285: public DirContext getResources();
286:
287: /**
288: * Set the Resources object with which this Container is associated.
289: *
290: * @param resources The newly associated Resources
291: */
292: public void setResources(DirContext resources);
293:
294: // --------------------------------------------------------- Public Methods
295:
296: /**
297: * Execute a periodic task, such as reloading, etc. This method will be
298: * invoked inside the classloading context of this container. Unexpected
299: * throwables will be caught and logged.
300: */
301: public void backgroundProcess();
302:
303: /**
304: * Add a new child Container to those associated with this Container,
305: * if supported. Prior to adding this Container to the set of children,
306: * the child's <code>setParent()</code> method must be called, with this
307: * Container as an argument. This method may thrown an
308: * <code>IllegalArgumentException</code> if this Container chooses not
309: * to be attached to the specified Container, in which case it is not added
310: *
311: * @param child New child Container to be added
312: *
313: * @exception IllegalArgumentException if this exception is thrown by
314: * the <code>setParent()</code> method of the child Container
315: * @exception IllegalArgumentException if the new child does not have
316: * a name unique from that of existing children of this Container
317: * @exception IllegalStateException if this Container does not support
318: * child Containers
319: */
320: public void addChild(Container child);
321:
322: /**
323: * Add a container event listener to this component.
324: *
325: * @param listener The listener to add
326: */
327: public void addContainerListener(ContainerListener listener);
328:
329: /**
330: * Add a property change listener to this component.
331: *
332: * @param listener The listener to add
333: */
334: public void addPropertyChangeListener(
335: PropertyChangeListener listener);
336:
337: /**
338: * Return the child Container, associated with this Container, with
339: * the specified name (if any); otherwise, return <code>null</code>
340: *
341: * @param name Name of the child Container to be retrieved
342: */
343: public Container findChild(String name);
344:
345: /**
346: * Return the set of children Containers associated with this Container.
347: * If this Container has no children, a zero-length array is returned.
348: */
349: public Container[] findChildren();
350:
351: /**
352: * Return the set of container listeners associated with this Container.
353: * If this Container has no registered container listeners, a zero-length
354: * array is returned.
355: */
356: public ContainerListener[] findContainerListeners();
357:
358: /**
359: * Process the specified Request, and generate the corresponding Response,
360: * according to the design of this particular Container.
361: *
362: * @param request Request to be processed
363: * @param response Response to be produced
364: *
365: * @exception IOException if an input/output error occurred while
366: * processing
367: * @exception ServletException if a ServletException was thrown
368: * while processing this request
369: */
370: public void invoke(Request request, Response response)
371: throws IOException, ServletException;
372:
373: /**
374: * Remove an existing child Container from association with this parent
375: * Container.
376: *
377: * @param child Existing child Container to be removed
378: */
379: public void removeChild(Container child);
380:
381: /**
382: * Remove a container event listener from this component.
383: *
384: * @param listener The listener to remove
385: */
386: public void removeContainerListener(ContainerListener listener);
387:
388: /**
389: * Remove a property change listener from this component.
390: *
391: * @param listener The listener to remove
392: */
393: public void removePropertyChangeListener(
394: PropertyChangeListener listener);
395:
396: }
|