001: /*
002: * $Header: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Wrapper.java,v 1.5 2001/07/22 20:13:30 pier Exp $
003: * $Revision: 1.5 $
004: * $Date: 2001/07/22 20:13:30 $
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 javax.servlet.Servlet;
067: import javax.servlet.ServletException;
068: import javax.servlet.UnavailableException;
069:
070: /**
071: * A <b>Wrapper</b> is a Container that represents an individual servlet
072: * definition from the deployment descriptor of the web application. It
073: * provides a convenient mechanism to use Interceptors that see every single
074: * request to the servlet represented by this definition.
075: * <p>
076: * Implementations of Wrapper are responsible for managing the servlet life
077: * cycle for their underlying servlet class, including calling init() and
078: * destroy() at appropriate times, as well as respecting the existence of
079: * the SingleThreadModel declaration on the servlet class itself.
080: * <p>
081: * The parent Container attached to a Wrapper will generally be an
082: * implementation of Context, representing the servlet context (and
083: * therefore the web application) within which this servlet executes.
084: * <p>
085: * Child Containers are not allowed on Wrapper implementations, so the
086: * <code>addChild()</code> method should throw an
087: * <code>IllegalArgumentException</code>.
088: *
089: * @author Craig R. McClanahan
090: * @version $Revision: 1.5 $ $Date: 2001/07/22 20:13:30 $
091: */
092:
093: public interface Wrapper extends Container {
094:
095: // ------------------------------------------------------------- Properties
096:
097: /**
098: * Return the available date/time for this servlet, in milliseconds since
099: * the epoch. If this date/time is in the future, any request for this
100: * servlet will return an SC_SERVICE_UNAVAILABLE error. If it is zero,
101: * the servlet is currently available. A value equal to Long.MAX_VALUE
102: * is considered to mean that unavailability is permanent.
103: */
104: public long getAvailable();
105:
106: /**
107: * Set the available date/time for this servlet, in milliseconds since the
108: * epoch. If this date/time is in the future, any request for this servlet
109: * will return an SC_SERVICE_UNAVAILABLE error. A value equal to
110: * Long.MAX_VALUE is considered to mean that unavailability is permanent.
111: *
112: * @param available The new available date/time
113: */
114: public void setAvailable(long available);
115:
116: /**
117: * Return the context-relative URI of the JSP file for this servlet.
118: */
119: public String getJspFile();
120:
121: /**
122: * Set the context-relative URI of the JSP file for this servlet.
123: *
124: * @param jspFile JSP file URI
125: */
126: public void setJspFile(String jspFile);
127:
128: /**
129: * Return the load-on-startup order value (negative value means
130: * load on first call).
131: */
132: public int getLoadOnStartup();
133:
134: /**
135: * Set the load-on-startup order value (negative value means
136: * load on first call).
137: *
138: * @param value New load-on-startup value
139: */
140: public void setLoadOnStartup(int value);
141:
142: /**
143: * Return the run-as identity for this servlet.
144: */
145: public String getRunAs();
146:
147: /**
148: * Set the run-as identity for this servlet.
149: *
150: * @param value New run-as identity value
151: */
152: public void setRunAs(String runAs);
153:
154: /**
155: * Return the fully qualified servlet class name for this servlet.
156: */
157: public String getServletClass();
158:
159: /**
160: * Set the fully qualified servlet class name for this servlet.
161: *
162: * @param servletClass Servlet class name
163: */
164: public void setServletClass(String servletClass);
165:
166: /**
167: * Is this servlet currently unavailable?
168: */
169: public boolean isUnavailable();
170:
171: // --------------------------------------------------------- Public Methods
172:
173: /**
174: * Add a new servlet initialization parameter for this servlet.
175: *
176: * @param name Name of this initialization parameter to add
177: * @param value Value of this initialization parameter to add
178: */
179: public void addInitParameter(String name, String value);
180:
181: /**
182: * Add a new listener interested in InstanceEvents.
183: *
184: * @param listener The new listener
185: */
186: public void addInstanceListener(InstanceListener listener);
187:
188: /**
189: * Add a new security role reference record to the set of records for
190: * this servlet.
191: *
192: * @param name Role name used within this servlet
193: * @param link Role name used within the web application
194: * @param description Description of this security role reference
195: */
196: public void addSecurityReference(String name, String link);
197:
198: /**
199: * Allocate an initialized instance of this Servlet that is ready to have
200: * its <code>service()</code> method called. If the servlet class does
201: * not implement <code>SingleThreadModel</code>, the (only) initialized
202: * instance may be returned immediately. If the servlet class implements
203: * <code>SingleThreadModel</code>, the Wrapper implementation must ensure
204: * that this instance is not allocated again until it is deallocated by a
205: * call to <code>deallocate()</code>.
206: *
207: * @exception ServletException if the servlet init() method threw
208: * an exception
209: * @exception ServletException if a loading error occurs
210: */
211: public Servlet allocate() throws ServletException;
212:
213: /**
214: * Return this previously allocated servlet to the pool of available
215: * instances. If this servlet class does not implement SingleThreadModel,
216: * no action is actually required.
217: *
218: * @param servlet The servlet to be returned
219: *
220: * @exception ServletException if a deallocation error occurs
221: */
222: public void deallocate(Servlet servlet) throws ServletException;
223:
224: /**
225: * Return the value for the specified initialization parameter name,
226: * if any; otherwise return <code>null</code>.
227: *
228: * @param name Name of the requested initialization parameter
229: */
230: public String findInitParameter(String name);
231:
232: /**
233: * Return the names of all defined initialization parameters for this
234: * servlet.
235: */
236: public String[] findInitParameters();
237:
238: /**
239: * Return the security role link for the specified security role
240: * reference name, if any; otherwise return <code>null</code>.
241: *
242: * @param name Security role reference used within this servlet
243: */
244: public String findSecurityReference(String name);
245:
246: /**
247: * Return the set of security role reference names associated with
248: * this servlet, if any; otherwise return a zero-length array.
249: */
250: public String[] findSecurityReferences();
251:
252: /**
253: * Load and initialize an instance of this servlet, if there is not already
254: * at least one initialized instance. This can be used, for example, to
255: * load servlets that are marked in the deployment descriptor to be loaded
256: * at server startup time.
257: *
258: * @exception ServletException if the servlet init() method threw
259: * an exception
260: * @exception ServletException if some other loading problem occurs
261: */
262: public void load() throws ServletException;
263:
264: /**
265: * Remove the specified initialization parameter from this servlet.
266: *
267: * @param name Name of the initialization parameter to remove
268: */
269: public void removeInitParameter(String name);
270:
271: /**
272: * Remove a listener no longer interested in InstanceEvents.
273: *
274: * @param listener The listener to remove
275: */
276: public void removeInstanceListener(InstanceListener listener);
277:
278: /**
279: * Remove any security role reference for the specified role name.
280: *
281: * @param name Security role used within this servlet to be removed
282: */
283: public void removeSecurityReference(String name);
284:
285: /**
286: * Process an UnavailableException, marking this servlet as unavailable
287: * for the specified amount of time.
288: *
289: * @param unavailable The exception that occurred, or <code>null</code>
290: * to mark this servlet as permanently unavailable
291: */
292: public void unavailable(UnavailableException unavailable);
293:
294: /**
295: * Unload all initialized instances of this servlet, after calling the
296: * <code>destroy()</code> method for each instance. This can be used,
297: * for example, prior to shutting down the entire servlet engine, or
298: * prior to reloading all of the classes from the Loader associated with
299: * our Loader's repository.
300: *
301: * @exception ServletException if an unload error occurs
302: */
303: public void unload() throws ServletException;
304:
305: }
|