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 javax.servlet.Servlet;
46 import javax.servlet.ServletException;
47 import javax.servlet.UnavailableException;
48
49
50 /**
51 * A <b>Wrapper</b> is a Container that represents an individual servlet
52 * definition from the deployment descriptor of the web application. It
53 * provides a convenient mechanism to use Interceptors that see every single
54 * request to the servlet represented by this definition.
55 * <p>
56 * Implementations of Wrapper are responsible for managing the servlet life
57 * cycle for their underlying servlet class, including calling init() and
58 * destroy() at appropriate times, as well as respecting the existence of
59 * the SingleThreadModel declaration on the servlet class itself.
60 * <p>
61 * The parent Container attached to a Wrapper will generally be an
62 * implementation of Context, representing the servlet context (and
63 * therefore the web application) within which this servlet executes.
64 * <p>
65 * Child Containers are not allowed on Wrapper implementations, so the
66 * <code>addChild()</code> method should throw an
67 * <code>IllegalArgumentException</code>.
68 *
69 * @author Craig R. McClanahan
70 * @version $Revision: 1.3 $ $Date: 2007/05/05 05:31:52 $
71 */
72
73 public interface Wrapper extends Container {
74
75
76 // ------------------------------------------------------------- Properties
77
78
79 /**
80 * Return the available date/time for this servlet, in milliseconds since
81 * the epoch. If this date/time is in the future, any request for this
82 * servlet will return an SC_SERVICE_UNAVAILABLE error. If it is zero,
83 * the servlet is currently available. A value equal to Long.MAX_VALUE
84 * is considered to mean that unavailability is permanent.
85 */
86 public long getAvailable();
87
88
89 /**
90 * Set the available date/time for this servlet, in milliseconds since the
91 * epoch. If this date/time is in the future, any request for this servlet
92 * will return an SC_SERVICE_UNAVAILABLE error. A value equal to
93 * Long.MAX_VALUE is considered to mean that unavailability is permanent.
94 *
95 * @param available The new available date/time
96 */
97 public void setAvailable(long available);
98
99
100 /**
101 * Return the context-relative URI of the JSP file for this servlet.
102 */
103 public String getJspFile();
104
105
106 /**
107 * Set the context-relative URI of the JSP file for this servlet.
108 *
109 * @param jspFile JSP file URI
110 */
111 public void setJspFile(String jspFile);
112
113
114 /**
115 * Return the load-on-startup order value (negative value means
116 * load on first call).
117 */
118 public int getLoadOnStartup();
119
120
121 /**
122 * Set the load-on-startup order value (negative value means
123 * load on first call).
124 *
125 * @param value New load-on-startup value
126 */
127 public void setLoadOnStartup(int value);
128
129
130 /**
131 * Return the run-as identity for this servlet.
132 */
133 public String getRunAs();
134
135
136 /**
137 * Set the run-as identity for this servlet.
138 *
139 * @param value New run-as identity value
140 */
141 public void setRunAs(String runAs);
142
143
144 /**
145 * Return the fully qualified servlet class name for this servlet.
146 */
147 public String getServletClass();
148
149
150 /**
151 * Set the fully qualified servlet class name for this servlet.
152 *
153 * @param servletClass Servlet class name
154 */
155 public void setServletClass(String servletClass);
156
157
158 /**
159 * Gets the names of the methods supported by the underlying servlet.
160 *
161 * This is the same set of methods included in the Allow response header
162 * in response to an OPTIONS request method processed by the underlying
163 * servlet.
164 *
165 * @return Array of names of the methods supported by the underlying
166 * servlet
167 */
168 public String[] getServletMethods() throws ServletException;
169
170
171 /**
172 * Is this servlet currently unavailable?
173 */
174 public boolean isUnavailable();
175
176
177 // --------------------------------------------------------- Public Methods
178
179
180 /**
181 * Add a new servlet initialization parameter for this servlet.
182 *
183 * @param name Name of this initialization parameter to add
184 * @param value Value of this initialization parameter to add
185 */
186 public void addInitParameter(String name, String value);
187
188
189 /**
190 * Add a new listener interested in InstanceEvents.
191 *
192 * @param listener The new listener
193 */
194 public void addInstanceListener(InstanceListener listener);
195
196
197 /**
198 * Add a mapping associated with the Wrapper.
199 *
200 * @param pattern The new wrapper mapping
201 */
202 public void addMapping(String mapping);
203
204
205 /**
206 * Add a new security role reference record to the set of records for
207 * this servlet.
208 *
209 * @param name Role name used within this servlet
210 * @param link Role name used within the web application
211 * @param description Description of this security role reference
212 */
213 public void addSecurityReference(String name, String link);
214
215
216 /**
217 * Allocate an initialized instance of this Servlet that is ready to have
218 * its <code>service()</code> method called. If the servlet class does
219 * not implement <code>SingleThreadModel</code>, the (only) initialized
220 * instance may be returned immediately. If the servlet class implements
221 * <code>SingleThreadModel</code>, the Wrapper implementation must ensure
222 * that this instance is not allocated again until it is deallocated by a
223 * call to <code>deallocate()</code>.
224 *
225 * @exception ServletException if the servlet init() method threw
226 * an exception
227 * @exception ServletException if a loading error occurs
228 */
229 public Servlet allocate() throws ServletException;
230
231
232 /**
233 * Return this previously allocated servlet to the pool of available
234 * instances. If this servlet class does not implement SingleThreadModel,
235 * no action is actually required.
236 *
237 * @param servlet The servlet to be returned
238 *
239 * @exception ServletException if a deallocation error occurs
240 */
241 public void deallocate(Servlet servlet) throws ServletException;
242
243
244 /**
245 * Return the value for the specified initialization parameter name,
246 * if any; otherwise return <code>null</code>.
247 *
248 * @param name Name of the requested initialization parameter
249 */
250 public String findInitParameter(String name);
251
252
253 /**
254 * Return the names of all defined initialization parameters for this
255 * servlet.
256 */
257 public String[] findInitParameters();
258
259
260 /**
261 * Return the mappings associated with this wrapper.
262 */
263 public String[] findMappings();
264
265
266 /**
267 * Return the security role link for the specified security role
268 * reference name, if any; otherwise return <code>null</code>.
269 *
270 * @param name Security role reference used within this servlet
271 */
272 public String findSecurityReference(String name);
273
274
275 /**
276 * Return the set of security role reference names associated with
277 * this servlet, if any; otherwise return a zero-length array.
278 */
279 public String[] findSecurityReferences();
280
281
282 /**
283 * Increment the error count value used when monitoring.
284 */
285 public void incrementErrorCount();
286
287
288 /**
289 * Load and initialize an instance of this servlet, if there is not already
290 * at least one initialized instance. This can be used, for example, to
291 * load servlets that are marked in the deployment descriptor to be loaded
292 * at server startup time.
293 *
294 * @exception ServletException if the servlet init() method threw
295 * an exception
296 * @exception ServletException if some other loading problem occurs
297 */
298 public void load() throws ServletException;
299
300
301 /**
302 * Remove the specified initialization parameter from this servlet.
303 *
304 * @param name Name of the initialization parameter to remove
305 */
306 public void removeInitParameter(String name);
307
308
309 /**
310 * Remove a listener no longer interested in InstanceEvents.
311 *
312 * @param listener The listener to remove
313 */
314 public void removeInstanceListener(InstanceListener listener);
315
316
317 /**
318 * Remove a mapping associated with the wrapper.
319 *
320 * @param mapping The pattern to remove
321 */
322 public void removeMapping(String mapping);
323
324
325 /**
326 * Remove any security role reference for the specified role name.
327 *
328 * @param name Security role used within this servlet to be removed
329 */
330 public void removeSecurityReference(String name);
331
332
333 /**
334 * Process an UnavailableException, marking this servlet as unavailable
335 * for the specified amount of time.
336 *
337 * @param unavailable The exception that occurred, or <code>null</code>
338 * to mark this servlet as permanently unavailable
339 */
340 public void unavailable(UnavailableException unavailable);
341
342
343 /**
344 * Unload all initialized instances of this servlet, after calling the
345 * <code>destroy()</code> method for each instance. This can be used,
346 * for example, prior to shutting down the entire servlet engine, or
347 * prior to reloading all of the classes from the Loader associated with
348 * our Loader's repository.
349 *
350 * @exception ServletException if an unload error occurs
351 */
352 public void unload() throws ServletException;
353
354
355 }
Save This Page