Home » apache-tomcat-6.0.26-src » org.apache » catalina » [javadoc | source]

    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 (Tue, 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   }

Home » apache-tomcat-6.0.26-src » org.apache » catalina » [javadoc | source]