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