ServletContext.java
上传用户:tanyanyong
上传日期:2013-06-23
资源大小:1355k
文件大小:21k
源码类别:

电子政务应用

开发平台:

MultiPlatform

  1. /*
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 1999 The Apache Software Foundation.  All rights 
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer. 
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution, if
  20.  *    any, must include the following acknowlegement:  
  21.  *       "This product includes software developed by the 
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowlegement may appear in the software itself,
  24.  *    if and wherever such third-party acknowlegements normally appear.
  25.  *
  26.  * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
  27.  *    Foundation" must not be used to endorse or promote products derived
  28.  *    from this software without prior written permission. For written 
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache"
  32.  *    nor may "Apache" appear in their names without prior written
  33.  *    permission of the Apache Group.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  *
  54.  * ====================================================================
  55.  *
  56.  * This source code implements specifications defined by the Java
  57.  * Community Process. In order to remain compliant with the specification
  58.  * DO NOT add / change / or delete method signatures!
  59.  */
  60. package javax.servlet;
  61. import java.io.InputStream;
  62. import java.io.IOException;
  63. import java.net.URL;
  64. import java.net.MalformedURLException;
  65. import java.util.Enumeration;
  66. /**
  67.  * 
  68.  * Defines a set of methods that a servlet uses to communicate with its
  69.  * servlet container, for example, to get the MIME type of a file, dispatch
  70.  * requests, or write to a log file.
  71.  *
  72.  * <p>There is one context per "web application" per Java Virtual Machine.  (A
  73.  * "web application" is a collection of servlets and content installed under a
  74.  * specific subset of the server's URL namespace such as <code>/catalog</code>
  75.  * and possibly installed via a <code>.war</code> file.) 
  76.  *
  77.  * <p>In the case of a web
  78.  * application marked "distributed" in its deployment descriptor, there will
  79.  * be one context instance for each virtual machine.  In this situation, the 
  80.  * context cannot be used as a location to share global information (because
  81.  * the information won't be truly global).  Use an external resource like 
  82.  * a database instead.
  83.  *
  84.  * <p>The <code>ServletContext</code> object is contained within 
  85.  * the {@link ServletConfig} object, which the Web server provides the
  86.  * servlet when the servlet is initialized.
  87.  *
  88.  * @author  Various
  89.  * @version  $Version$
  90.  *
  91.  * @see  Servlet#getServletConfig
  92.  * @see  ServletConfig#getServletContext
  93.  *
  94.  */
  95. public interface ServletContext {
  96.     /**
  97.      * Returns a <code>ServletContext</code> object that 
  98.      * corresponds to a specified URL on the server.
  99.      *
  100.      * <p>This method allows servlets to gain
  101.      * access to the context for various parts of the server, and as
  102.      * needed obtain {@link RequestDispatcher} objects from the context.
  103.      * The given path must be absolute (beginning with "/") and is 
  104.      * interpreted based on the server's document root. 
  105.      * 
  106.      * <p>In a security conscious environment, the servlet container may
  107.      * return <code>null</code> for a given URL.
  108.      *       
  109.      * @param uripath  a <code>String</code> specifying the absolute URL of 
  110.      * a resource on the server
  111.      *
  112.      * @return the <code>ServletContext</code> object that
  113.      * corresponds to the named URL
  114.      *
  115.      * @see  RequestDispatcher
  116.      *
  117.      */
  118.     public ServletContext getContext(String uripath);
  119.     
  120.     
  121.     /**
  122.      * Returns the major version of the Java Servlet API that this
  123.      * servlet container supports. All implementations that comply
  124.      * with Version 2.2 must have this method
  125.      * return the integer 2.
  126.      *
  127.      * @return  2
  128.      *
  129.      */
  130.     
  131.     public int getMajorVersion();
  132.     
  133.     
  134.     /**
  135.      * Returns the minor version of the Servlet API that this
  136.      * servlet container supports. All implementations that comply
  137.      * with Version 2.2 must have this method
  138.      * return the integer 2.
  139.      *
  140.      * @return  2
  141.      *
  142.      */
  143.     public int getMinorVersion();
  144.     
  145.     
  146.     /**
  147.      * Returns the MIME type of the specified file, or <code>null</code> if 
  148.      * the MIME type is not known. The MIME type is determined
  149.      * by the configuration of the servlet container, and may be specified
  150.      * in a web application deployment descriptor. Common MIME
  151.      * types are <code>"text/html"</code> and <code>"image/gif"</code>.
  152.      *
  153.      *
  154.      * @param   file    a <code>String</code> specifying the name
  155.      * of a file
  156.      *
  157.      * @return  a <code>String</code> specifying the file's MIME type
  158.      *
  159.      */
  160.     public String getMimeType(String file);
  161.     
  162.     
  163.     /**
  164.      * Returns a URL to the resource that is mapped to a specified
  165.      * path. The path must begin with a "/" and is interpreted
  166.      * as relative to the current context root.
  167.      *
  168.      * <p>This method allows the servlet container to make a resource 
  169.      * available to servlets from any source. Resources 
  170.      * can be located on a local or remote
  171.      * file system, in a database, or in a <code>.war</code> file. 
  172.      *
  173.      * <p>The servlet container must implement the URL handlers
  174.      * and <code>URLConnection</code> objects that are necessary
  175.      * to access the resource.
  176.      *
  177.      * <p>This method returns <code>null</code>
  178.      * if no resource is mapped to the pathname.
  179.      *
  180.      * <p>Some containers may allow writing to the URL returned by
  181.      * this method using the methods of the URL class.
  182.      *
  183.      * <p>The resource content is returned directly, so be aware that 
  184.      * requesting a <code>.jsp</code> page returns the JSP source code.
  185.      * Use a <code>RequestDispatcher</code> instead to include results of 
  186.      * an execution.
  187.      *
  188.      * <p>This method has a different purpose than
  189.      * <code>java.lang.Class.getResource</code>,
  190.      * which looks up resources based on a class loader. This
  191.      * method does not use class loaders.
  192.      * 
  193.      * @param path  a <code>String</code> specifying
  194.      * the path to the resource
  195.      *
  196.      * @return  the resource located at the named path,
  197.      *  or <code>null</code> if there is no resource
  198.      * at that path
  199.      *
  200.      * @exception MalformedURLException  if the pathname is not given in 
  201.      *  the correct form
  202.      *
  203.      */
  204.     
  205.     public URL getResource(String path) throws MalformedURLException;
  206.     
  207.     
  208.     /**
  209.      * Returns the resource located at the named path as
  210.      * an <code>InputStream</code> object.
  211.      *
  212.      * <p>The data in the <code>InputStream</code> can be 
  213.      * of any type or length. The path must be specified according
  214.      * to the rules given in <code>getResource</code>.
  215.      * This method returns <code>null</code> if no resource exists at
  216.      * the specified path. 
  217.      * 
  218.      * <p>Meta-information such as content length and content type
  219.      * that is available via <code>getResource</code>
  220.      * method is lost when using this method.
  221.      *
  222.      * <p>The servlet container must implement the URL handlers
  223.      * and <code>URLConnection</code> objects necessary to access
  224.      * the resource.
  225.      *
  226.      * <p>This method is different from 
  227.      * <code>java.lang.Class.getResourceAsStream</code>,
  228.      * which uses a class loader. This method allows servlet containers 
  229.      * to make a resource available
  230.      * to a servlet from any location, without using a class loader.
  231.      * 
  232.      *
  233.      * @param name  a <code>String</code> specifying the path
  234.      * to the resource
  235.      *
  236.      * @return  the <code>InputStream</code> returned to the 
  237.      * servlet, or <code>null</code> if no resource
  238.      * exists at the specified path 
  239.      *
  240.      *
  241.      */
  242.     public InputStream getResourceAsStream(String path);
  243.     
  244.     /**
  245.      * 
  246.      * Returns a {@link RequestDispatcher} object that acts
  247.      * as a wrapper for the resource located at the given path.
  248.      * A <code>RequestDispatcher</code> object can be used to forward 
  249.      * a request to the resource or to include the resource in a response.
  250.      * The resource can be dynamic or static.
  251.      *
  252.      * <p>The pathname must begin with a "/" and is interpreted as relative
  253.      * to the current context root.  Use <code>getContext</code> to obtain
  254.      * a <code>RequestDispatcher</code> for resources in foreign contexts.
  255.      * This method returns <code>null</code> if the <code>ServletContext</code>
  256.      * cannot return a <code>RequestDispatcher</code>.
  257.      *
  258.      * @param path  a <code>String</code> specifying the pathname
  259.      * to the resource
  260.      *
  261.      * @return  a <code>RequestDispatcher</code> object
  262.      * that acts as a wrapper for the resource
  263.      * at the specified path
  264.      *
  265.      * @see  RequestDispatcher
  266.      * @see  ServletContext#getContext
  267.      *
  268.      */
  269.     public RequestDispatcher getRequestDispatcher(String path);
  270.     /**
  271.      * Returns a {@link RequestDispatcher} object that acts
  272.      * as a wrapper for the named servlet.
  273.      *
  274.      * <p>Servlets (and JSP pages also) may be given names via server 
  275.      * administration or via a web application deployment descriptor.
  276.      * A servlet instance can determine its name using 
  277.      * {@link ServletConfig#getServletName}.
  278.      *
  279.      * <p>This method returns <code>null</code> if the 
  280.      * <code>ServletContext</code>
  281.      * cannot return a <code>RequestDispatcher</code> for any reason.
  282.      *
  283.      * @param name  a <code>String</code> specifying the name
  284.      * of a servlet to wrap
  285.      *
  286.      * @return  a <code>RequestDispatcher</code> object
  287.      * that acts as a wrapper for the named servlet
  288.      *
  289.      * @see  RequestDispatcher
  290.      * @see  ServletContext#getContext
  291.      * @see  ServletConfig#getServletName
  292.      *
  293.      */
  294.     public RequestDispatcher getNamedDispatcher(String name);
  295.     
  296.     
  297.     
  298.     
  299.     /**
  300.      *
  301.      * @deprecated As of Java Servlet API 2.1, with no direct replacement.
  302.      *
  303.      * <p>This method was originally defined to retrieve a servlet
  304.      * from a <code>ServletContext</code>. In this version, this method 
  305.      * always returns <code>null</code> and remains only to preserve 
  306.      * binary compatibility. This method will be permanently removed 
  307.      * in a future version of the Java Servlet API.
  308.      *
  309.      * <p>In lieu of this method, servlets can share information using the 
  310.      * <code>ServletContext</code> class and can perform shared business logic
  311.      * by invoking methods on common non-servlet classes.
  312.      *
  313.      */
  314.     public Servlet getServlet(String name) throws ServletException;
  315.     
  316.   
  317.   
  318.   
  319.     
  320.     /**
  321.      *
  322.      * @deprecated As of Java Servlet API 2.0, with no replacement.
  323.      *
  324.      * <p>This method was originally defined to return an <code>Enumeration</code>
  325.      * of all the servlets known to this servlet context. In this
  326.      * version, this method always returns an empty enumeration and
  327.      * remains only to preserve binary compatibility. This method
  328.      * will be permanently removed in a future version of the Java
  329.      * Servlet API.
  330.      *
  331.      */
  332.     
  333.     public Enumeration getServlets();
  334.     
  335.     
  336.     
  337.     
  338.     
  339.     /**
  340.      * @deprecated As of Java Servlet API 2.1, with no replacement.
  341.      *
  342.      * <p>This method was originally defined to return an 
  343.      * <code>Enumeration</code>
  344.      * of all the servlet names known to this context. In this version,
  345.      * this method always returns an empty <code>Enumeration</code> and 
  346.      * remains only to preserve binary compatibility. This method will 
  347.      * be permanently removed in a future version of the Java Servlet API.
  348.      *
  349.      */
  350.  
  351.     public Enumeration getServletNames();
  352.     
  353.   
  354.   
  355.     
  356.     
  357.     /**
  358.      *
  359.      * Writes the specified message to a servlet log file, usually
  360.      * an event log. The name and type of the servlet log file is 
  361.      * specific to the servlet container.
  362.      *
  363.      *
  364.      * @param msg  a <code>String</code> specifying the 
  365.      * message to be written to the log file
  366.      *
  367.      */
  368.      
  369.     public void log(String msg);
  370.     
  371.     
  372.     
  373.     
  374.     /**
  375.      * @deprecated As of Java Servlet API 2.1, use
  376.      *  {@link #log(String message, Throwable throwable)} 
  377.      * instead.
  378.      *
  379.      * <p>This method was originally defined to write an 
  380.      * exception's stack trace and an explanatory error message
  381.      * to the servlet log file.
  382.      *
  383.      */
  384.     public void log(Exception exception, String msg);
  385.     
  386.     
  387.     
  388.     
  389.     /**
  390.      * Writes an explanatory message and a stack trace
  391.      * for a given <code>Throwable</code> exception
  392.      * to the servlet log file. The name and type of the servlet log 
  393.      * file is specific to the servlet container, usually an event log.
  394.      *
  395.      *
  396.      * @param message  a <code>String</code> that 
  397.      * describes the error or exception
  398.      *
  399.      * @param throwable  the <code>Throwable</code> error 
  400.      * or exception
  401.      *
  402.      */
  403.     
  404.     public void log(String message, Throwable throwable);
  405.     
  406.     
  407.     
  408.     
  409.     
  410.     /**
  411.      * Returns a <code>String</code> containing the real path 
  412.      * for a given virtual path. For example, the virtual path "/index.html"
  413.      * has a real path of whatever file on the server's filesystem would be
  414.      * served by a request for "/index.html".
  415.      *
  416.      * <p>The real path returned will be in a form
  417.      * appropriate to the computer and operating system on
  418.      * which the servlet container is running, including the
  419.      * proper path separators. This method returns <code>null</code>
  420.      * if the servlet container cannot translate the virtual path
  421.      * to a real path for any reason (such as when the content is
  422.      * being made available from a <code>.war</code> archive).
  423.      *
  424.      *
  425.      * @param path  a <code>String</code> specifying a virtual path
  426.      *
  427.      *
  428.      * @return  a <code>String</code> specifying the real path,
  429.      *                  or null if the translation cannot be performed
  430.      *
  431.      *
  432.      */
  433.     public String getRealPath(String path);
  434.     
  435.     
  436.     /**
  437.      * Returns the name and version of the servlet container on which
  438.      * the servlet is running. 
  439.      *
  440.      * <p>The form of the returned string is 
  441.      * <i>servername</i>/<i>versionnumber</i>.
  442.      * For example, the JavaServer Web Development Kit may return the string
  443.      * <code>JavaServer Web Dev Kit/1.0</code>.
  444.      *
  445.      * <p>The servlet container may return other optional information 
  446.      * after the primary string in parentheses, for example,
  447.      * <code>JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86)</code>.
  448.      *
  449.      *
  450.      * @return  a <code>String</code> containing at least the 
  451.      * servlet container name and version number
  452.      *
  453.      */
  454.     public String getServerInfo();
  455.     
  456.     
  457.     /**
  458.      * Returns a <code>String</code> containing the value of the named
  459.      * context-wide initialization parameter, or <code>null</code> if the 
  460.      * parameter does not exist.
  461.      *
  462.      * <p>This method can make available configuration information useful
  463.      * to an entire "web application".  For example, it can provide a 
  464.      * webmaster's email address or the name of a system that holds 
  465.      * critical data.
  466.      *
  467.      * @param name a <code>String</code> containing the name of the
  468.      *                  parameter whose value is requested
  469.      * 
  470.      * @return  a <code>String</code> containing at least the 
  471.      * servlet container name and version number
  472.      *
  473.      * @see ServletConfig#getInitParameter
  474.      */
  475.     public String getInitParameter(String name);
  476.     
  477.     
  478.     /**
  479.      * Returns the names of the context's initialization parameters as an
  480.      * <code>Enumeration</code> of <code>String</code> objects, or an
  481.      * empty <code>Enumeration</code> if the context has no initialization
  482.      * parameters.
  483.      *
  484.      * @return  an <code>Enumeration</code> of <code>String</code> 
  485.      *                  objects containing the names of the context's
  486.      *                  initialization parameters
  487.      *
  488.      * @see ServletConfig#getInitParameter
  489.      */
  490.     public Enumeration getInitParameterNames();
  491.     
  492.     
  493.     /**
  494.      * Returns the servlet container attribute with the given name, 
  495.      * or <code>null</code> if there is no attribute by that name.
  496.      * An attribute allows a servlet container to give the
  497.      * servlet additional information not
  498.      * already provided by this interface. See your
  499.      * server documentation for information about its attributes.
  500.      * A list of supported attributes can be retrieved using
  501.      * <code>getAttributeNames</code>.
  502.      *
  503.      * <p>The attribute is returned as a <code>java.lang.Object</code>
  504.      * or some subclass.
  505.      * Attribute names should follow the same convention as package
  506.      * names. The Java Servlet API specification reserves names
  507.      * matching <code>java.*</code>, <code>javax.*</code>,
  508.      * and <code>sun.*</code>.
  509.      *
  510.      *
  511.      * @param name  a <code>String</code> specifying the name 
  512.      * of the attribute
  513.      *
  514.      * @return  an <code>Object</code> containing the value 
  515.      * of the attribute, or <code>null</code>
  516.      * if no attribute exists matching the given
  517.      * name
  518.      *
  519.      * @see  ServletContext#getAttributeNames
  520.      *
  521.      */
  522.   
  523.     public Object getAttribute(String name);
  524.     
  525.     
  526.     
  527.     /**
  528.      * Returns an <code>Enumeration</code> containing the 
  529.      * attribute names available
  530.      * within this servlet context. Use the
  531.      * {@link #getAttribute} method with an attribute name
  532.      * to get the value of an attribute.
  533.      *
  534.      * @return  an <code>Enumeration</code> of attribute 
  535.      * names
  536.      *
  537.      * @see #getAttribute
  538.      *
  539.      */
  540.     public Enumeration getAttributeNames();
  541.     
  542.     
  543.     
  544.     
  545.     /**
  546.      *
  547.      * Binds an object to a given attribute name in this servlet context. If
  548.      * the name specified is already used for an attribute, this
  549.      * method will remove the old attribute and bind the name
  550.      * to the new attribute.
  551.      *
  552.      * <p>Attribute names should follow the same convention as package
  553.      * names. The Java Servlet API specification reserves names
  554.      * matching <code>java.*</code>, <code>javax.*</code>, and
  555.      * <code>sun.*</code>.
  556.      *
  557.      *
  558.      * @param name  a <code>String</code> specifying the name 
  559.      * of the attribute
  560.      *
  561.      * @param object  an <code>Object</code> representing the
  562.      * attribute to be bound
  563.      *
  564.      *
  565.      *
  566.      */
  567.     
  568.     public void setAttribute(String name, Object object);
  569.     
  570.     
  571.     /**
  572.      * Removes the attribute with the given name from 
  573.      * the servlet context. After removal, subsequent calls to
  574.      * {@link #getAttribute} to retrieve the attribute's value
  575.      * will return <code>null</code>.
  576.      *
  577.      *
  578.      * @param name a <code>String</code> specifying the name 
  579.      *  of the attribute to be removed
  580.      *
  581.      */
  582.     public void removeAttribute(String name);
  583. }