Container


1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  
19  package org.apache.catalina;
20  
21  
22  import java.beans.PropertyChangeListener  ;
23  import java.io.IOException  ;
24  import javax.servlet.ServletException  ;
25  import javax.naming.directory.DirContext  ;
26  
27  import org.apache.catalina.connector.Request;
28  import org.apache.catalina.connector.Response;
29  import org.apache.commons.logging.Log;
30  
31  
32  /**
33   * A <b>Container</b> is an object that can execute requests received from
34   * a client, and return responses based on those requests.  A Container may
35   * optionally support a pipeline of Valves that process the request in an
36   * order configured at runtime, by implementing the <b>Pipeline</b> interface
37   * as well.
38   * <p>
39   * Containers will exist at several conceptual levels within Catalina.  The
40   * following examples represent common cases:
41   * <ul>
42   * <li><b>Engine</b> - Representation of the entire Catalina servlet engine,
43   *     most likely containing one or more subcontainers that are either Host
44   *     or Context implementations, or other custom groups.
45   * <li><b>Host</b> - Representation of a virtual host containing a number
46   *     of Contexts.
47   * <li><b>Context</b> - Representation of a single ServletContext, which will
48   *     typically contain one or more Wrappers for the supported servlets.
49   * <li><b>Wrapper</b> - Representation of an individual servlet definition
50   *     (which may support multiple servlet instances if the servlet itself
51   *     implements SingleThreadModel).
52   * </ul>
53   * A given deployment of Catalina need not include Containers at all of the
54   * levels described above.  For example, an administration application
55   * embedded within a network device (such as a router) might only contain
56   * a single Context and a few Wrappers, or even a single Wrapper if the
57   * application is relatively small.  Therefore, Container implementations
58   * need to be designed so that they will operate correctly in the absence
59   * of parent Containers in a given deployment.
60   * <p>
61   * A Container may also be associated with a number of support components
62   * that provide functionality which might be shared (by attaching it to a
63   * parent Container) or individually customized.  The following support
64   * components are currently recognized:
65   * <ul>
66   * <li><b>Loader</b> - Class loader to use for integrating new Java classes
67   *     for this Container into the JVM in which Catalina is running.
68   * <li><b>Logger</b> - Implementation of the <code>log()</code> method
69   *     signatures of the <code>ServletContext</code> interface.
70   * <li><b>Manager</b> - Manager for the pool of Sessions associated with
71   *     this Container.
72   * <li><b>Realm</b> - Read-only interface to a security domain, for
73   *     authenticating user identities and their corresponding roles.
74   * <li><b>Resources</b> - JNDI directory context enabling access to static
75   *     resources, enabling custom linkages to existing server components when
76   *     Catalina is embedded in a larger server.
77   * </ul>
78   *
79   * @author Craig R. McClanahan
80   * @author Remy Maucherat
81   * @version $Revision: 467222 $ $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
82   */
83  
84  public interface Container {
85  
86  
87      // ----------------------------------------------------- Manifest Constants
88  
89  
90      /**
91       * The ContainerEvent event type sent when a child container is added
92       * by <code>addChild()</code>.
93       */
94      public static final String   ADD_CHILD_EVENT = "addChild";
95  
96  
97      /**
98       * The ContainerEvent event type sent when a Mapper is added
99       * by <code>addMapper()</code>.
100      */
101     public static final String   ADD_MAPPER_EVENT = "addMapper";
102 
103 
104     /**
105      * The ContainerEvent event type sent when a valve is added
106      * by <code>addValve()</code>, if this Container supports pipelines.
107      */
108     public static final String   ADD_VALVE_EVENT = "addValve";
109 
110 
111     /**
112      * The ContainerEvent event type sent when a child container is removed
113      * by <code>removeChild()</code>.
114      */
115     public static final String   REMOVE_CHILD_EVENT = "removeChild";
116 
117 
118     /**
119      * The ContainerEvent event type sent when a Mapper is removed
120      * by <code>removeMapper()</code>.
121      */
122     public static final String   REMOVE_MAPPER_EVENT = "removeMapper";
123 
124 
125     /**
126      * The ContainerEvent event type sent when a valve is removed
127      * by <code>removeValve()</code>, if this Container supports pipelines.
128      */
129     public static final String   REMOVE_VALVE_EVENT = "removeValve";
130 
131 
132     // ------------------------------------------------------------- Properties
133 
134 
135     /**
136      * Return descriptive information about this Container implementation and
137      * the corresponding version number, in the format
138      * <code>&lt;description&gt;/&lt;version&gt;</code>.
139      */
140     public String   getInfo();
141 
142 
143     /**
144      * Return the Loader with which this Container is associated.  If there is
145      * no associated Loader, return the Loader associated with our parent
146      * Container (if any); otherwise, return <code>null</code>.
147      */
148     public Loader getLoader();
149 
150 
151     /**
152      * Set the Loader with which this Container is associated.
153      *
154      * @param loader The newly associated loader
155      */
156     public void setLoader(Loader loader);
157 
158 
159     /**
160      * Return the Logger with which this Container is associated.  If there is
161      * no associated Logger, return the Logger associated with our parent
162      * Container (if any); otherwise return <code>null</code>.
163      */
164     public Log getLogger();
165 
166 
167     /**
168      * Return the Manager with which this Container is associated.  If there is
169      * no associated Manager, return the Manager associated with our parent
170      * Container (if any); otherwise return <code>null</code>.
171      */
172     public Manager getManager();
173 
174 
175     /**
176      * Set the Manager with which this Container is associated.
177      *
178      * @param manager The newly associated Manager
179      */
180     public void setManager(Manager manager);
181 
182 
183     /**
184      * Return an object which may be utilized for mapping to this component.
185      */
186     public Object   getMappingObject();
187 
188     
189     /**
190      * Return the JMX name associated with this container.
191      */
192     public String   getObjectName();    
193 
194     /**
195      * Return the Pipeline object that manages the Valves associated with
196      * this Container.
197      */
198     public Pipeline getPipeline();
199 
200 
201     /**
202      * Return the Cluster with which this Container is associated.  If there is
203      * no associated Cluster, return the Cluster associated with our parent
204      * Container (if any); otherwise return <code>null</code>.
205      */
206     public Cluster getCluster();
207 
208 
209     /**
210      * Set the Cluster with which this Container is associated.
211      *
212      * @param cluster the Cluster with which this Container is associated.
213      */
214     public void setCluster(Cluster cluster);
215 
216 
217     /**
218      * Get the delay between the invocation of the backgroundProcess method on
219      * this container and its children. Child containers will not be invoked
220      * if their delay value is not negative (which would mean they are using 
221      * their own thread). Setting this to a positive value will cause 
222      * a thread to be spawn. After waiting the specified amount of time, 
223      * the thread will invoke the executePeriodic method on this container 
224      * and all its children.
225      */
226     public int getBackgroundProcessorDelay();
227 
228 
229     /**
230      * Set the delay between the invocation of the execute method on this
231      * container and its children.
232      * 
233      * @param delay The delay in seconds between the invocation of 
234      *              backgroundProcess methods
235      */
236     public void setBackgroundProcessorDelay(int delay);
237 
238 
239     /**
240      * Return a name string (suitable for use by humans) that describes this
241      * Container.  Within the set of child containers belonging to a particular
242      * parent, Container names must be unique.
243      */
244     public String   getName();
245 
246 
247     /**
248      * Set a name string (suitable for use by humans) that describes this
249      * Container.  Within the set of child containers belonging to a particular
250      * parent, Container names must be unique.
251      *
252      * @param name New name of this container
253      *
254      * @exception IllegalStateException if this Container has already been
255      *  added to the children of a parent Container (after which the name
256      *  may not be changed)
257      */
258     public void setName(String   name);
259 
260 
261     /**
262      * Return the Container for which this Container is a child, if there is
263      * one.  If there is no defined parent, return <code>null</code>.
264      */
265     public Container getParent();
266 
267 
268     /**
269      * Set the parent Container to which this Container is being added as a
270      * child.  This Container may refuse to become attached to the specified
271      * Container by throwing an exception.
272      *
273      * @param container Container to which this Container is being added
274      *  as a child
275      *
276      * @exception IllegalArgumentException if this Container refuses to become
277      *  attached to the specified Container
278      */
279     public void setParent(Container container);
280 
281 
282     /**
283      * Return the parent class loader (if any) for web applications.
284      */
285     public ClassLoader   getParentClassLoader();
286 
287 
288     /**
289      * Set the parent class loader (if any) for web applications.
290      * This call is meaningful only <strong>before</strong> a Loader has
291      * been configured, and the specified value (if non-null) should be
292      * passed as an argument to the class loader constructor.
293      *
294      * @param parent The new parent class loader
295      */
296     public void setParentClassLoader(ClassLoader   parent);
297 
298 
299     /**
300      * Return the Realm with which this Container is associated.  If there is
301      * no associated Realm, return the Realm associated with our parent
302      * Container (if any); otherwise return <code>null</code>.
303      */
304     public Realm getRealm();
305 
306 
307     /**
308      * Set the Realm with which this Container is associated.
309      *
310      * @param realm The newly associated Realm
311      */
312     public void setRealm(Realm realm);
313 
314 
315     /**
316      * Return the Resources with which this Container is associated.  If there
317      * is no associated Resources object, return the Resources associated with
318      * our parent Container (if any); otherwise return <code>null</code>.
319      */
320     public DirContext   getResources();
321 
322 
323     /**
324      * Set the Resources object with which this Container is associated.
325      *
326      * @param resources The newly associated Resources
327      */
328     public void setResources(DirContext   resources);
329 
330 
331     // --------------------------------------------------------- Public Methods
332 
333 
334     /**
335      * Execute a periodic task, such as reloading, etc. This method will be
336      * invoked inside the classloading context of this container. Unexpected
337      * throwables will be caught and logged.
338      */
339     public void backgroundProcess();
340 
341 
342     /**
343      * Add a new child Container to those associated with this Container,
344      * if supported.  Prior to adding this Container to the set of children,
345      * the child's <code>setParent()</code> method must be called, with this
346      * Container as an argument.  This method may thrown an
347      * <code>IllegalArgumentException</code> if this Container chooses not
348      * to be attached to the specified Container, in which case it is not added
349      *
350      * @param child New child Container to be added
351      *
352      * @exception IllegalArgumentException if this exception is thrown by
353      *  the <code>setParent()</code> method of the child Container
354      * @exception IllegalArgumentException if the new child does not have
355      *  a name unique from that of existing children of this Container
356      * @exception IllegalStateException if this Container does not support
357      *  child Containers
358      */
359     public void addChild(Container child);
360 
361 
362     /**
363      * Add a container event listener to this component.
364      *
365      * @param listener The listener to add
366      */
367     public void addContainerListener(ContainerListener listener);
368 
369 
370     /**
371      * Add a property change listener to this component.
372      *
373      * @param listener The listener to add
374      */
375     public void addPropertyChangeListener(PropertyChangeListener   listener);
376 
377 
378     /**
379      * Return the child Container, associated with this Container, with
380      * the specified name (if any); otherwise, return <code>null</code>
381      *
382      * @param name Name of the child Container to be retrieved
383      */
384     public Container findChild(String   name);
385 
386 
387     /**
388      * Return the set of children Containers associated with this Container.
389      * If this Container has no children, a zero-length array is returned.
390      */
391     public Container[] findChildren();
392 
393 
394     /**
395      * Return the set of container listeners associated with this Container.
396      * If this Container has no registered container listeners, a zero-length
397      * array is returned.
398      */
399     public ContainerListener[] findContainerListeners();
400 
401 
402     /**
403      * Process the specified Request, and generate the corresponding Response,
404      * according to the design of this particular Container.
405      *
406      * @param request Request to be processed
407      * @param response Response to be produced
408      *
409      * @exception IOException if an input/output error occurred while
410      *  processing
411      * @exception ServletException if a ServletException was thrown
412      *  while processing this request
413      */
414     public void invoke(Request request, Response response)
415         throws IOException  , ServletException  ;
416 
417 
418     /**
419      * Remove an existing child Container from association with this parent
420      * Container.
421      *
422      * @param child Existing child Container to be removed
423      */
424     public void removeChild(Container child);
425 
426 
427     /**
428      * Remove a container event listener from this component.
429      *
430      * @param listener The listener to remove
431      */
432     public void removeContainerListener(ContainerListener listener);
433 
434 
435     /**
436      * Remove a property change listener from this component.
437      *
438      * @param listener The listener to remove
439      */
440     public void removePropertyChangeListener(PropertyChangeListener   listener);
441 
442 
443 }
444
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags