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