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