Wrapper


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