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