Home » apache-tomcat-6.0.26-src » javax » servlet » [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   package javax.servlet;
   18   
   19   import java.io.InputStream;
   20   import java.net.MalformedURLException;
   21   import java.net.URL;
   22   import java.util.Enumeration;
   23   import java.util.Set;
   24   
   25   
   26   /**
   27    * 
   28    * Defines a set of methods that a servlet uses to communicate with its
   29    * servlet container, for example, to get the MIME type of a file, dispatch
   30    * requests, or write to a log file.
   31    *
   32    * <p>There is one context per "web application" per Java Virtual Machine.  (A
   33    * "web application" is a collection of servlets and content installed under a
   34    * specific subset of the server's URL namespace such as <code>/catalog</code>
   35    * and possibly installed via a <code>.war</code> file.) 
   36    *
   37    * <p>In the case of a web
   38    * application marked "distributed" in its deployment descriptor, there will
   39    * be one context instance for each virtual machine.  In this situation, the 
   40    * context cannot be used as a location to share global information (because
   41    * the information won't be truly global).  Use an external resource like 
   42    * a database instead.
   43    *
   44    * <p>The <code>ServletContext</code> object is contained within 
   45    * the {@link ServletConfig} object, which the Web server provides the
   46    * servlet when the servlet is initialized.
   47    *
   48    * @author 	Various
   49    * @version 	$Version$
   50    *
   51    * @see 	Servlet#getServletConfig
   52    * @see 	ServletConfig#getServletContext
   53    *
   54    */
   55   
   56   public interface ServletContext {
   57   
   58   
   59       /**
   60        * Returns a <code>ServletContext</code> object that 
   61        * corresponds to a specified URL on the server.
   62        *
   63        * <p>This method allows servlets to gain
   64        * access to the context for various parts of the server, and as
   65        * needed obtain {@link RequestDispatcher} objects from the context.
   66        * The given path must be begin with "/", is interpreted relative 
   67        * to the server's document root and is matched against the context roots of
   68        * other web applications hosted on this container.
   69        * 
   70        * <p>In a security conscious environment, the servlet container may
   71        * return <code>null</code> for a given URL.
   72        *       
   73        * @param uripath 	a <code>String</code> specifying the context path of
   74        *			another web application in the container.
   75        * @return		the <code>ServletContext</code> object that
   76        *			corresponds to the named URL, or null if either
   77   			none exists or the container wishes to restrict 
   78        * 			this access.
   79        *
   80        * @see 		RequestDispatcher
   81        *
   82        */
   83   
   84       public ServletContext getContext(String uripath);
   85       
   86   
   87       public String getContextPath();
   88   
   89   
   90       /**
   91        * Returns the major version of the Java Servlet API that this
   92        * servlet container supports. All implementations that comply
   93        * with Version 2.4 must have this method
   94        * return the integer 2.
   95        *
   96        * @return 		2
   97        *
   98        */
   99       
  100       public int getMajorVersion();
  101       
  102       
  103   
  104       /**
  105        * Returns the minor version of the Servlet API that this
  106        * servlet container supports. All implementations that comply
  107        * with Version 2.5 must have this method
  108        * return the integer 5.
  109        *
  110        * @return 		5
  111        *
  112        */
  113   
  114       public int getMinorVersion();
  115       
  116       
  117   
  118       /**
  119        * Returns the MIME type of the specified file, or <code>null</code> if 
  120        * the MIME type is not known. The MIME type is determined
  121        * by the configuration of the servlet container, and may be specified
  122        * in a web application deployment descriptor. Common MIME
  123        * types are <code>"text/html"</code> and <code>"image/gif"</code>.
  124        *
  125        *
  126        * @param   file    a <code>String</code> specifying the name
  127        *			of a file
  128        *
  129        * @return 		a <code>String</code> specifying the file's MIME type
  130        *
  131        */
  132   
  133       public String getMimeType(String file);
  134       
  135       /**
  136       * Returns a directory-like listing of all the paths to resources within the web application whose longest sub-path
  137       * matches the supplied path argument. Paths indicating subdirectory paths end with a '/'. The returned paths are all 
  138       * relative to the root of the web application and have a leading '/'. For example, for a web application 
  139       * containing<br><br>
  140   
  141       * /welcome.html<br>
  142       * /catalog/index.html<br>
  143       * /catalog/products.html<br>
  144       * /catalog/offers/books.html<br>
  145       * /catalog/offers/music.html<br>
  146       * /customer/login.jsp<br>
  147       * /WEB-INF/web.xml<br>
  148       * /WEB-INF/classes/com.acme.OrderServlet.class,<br><br>
  149       *
  150       * getResourcePaths("/") returns {"/welcome.html", "/catalog/", "/customer/", "/WEB-INF/"}<br>
  151       * getResourcePaths("/catalog/") returns {"/catalog/index.html", "/catalog/products.html", "/catalog/offers/"}.<br>
  152   	   
  153   
  154   
  155       *@param path		the partial path used to match the resources,
  156       *				which must start with a /
  157       *@return a Set containing the directory listing, or null if there are no resources in the web application whose path
  158   	* begins with the supplied path.
  159   
  160       * @since Servlet 2.3
  161       */
  162       
  163       public Set getResourcePaths(String path);
  164       
  165       
  166   
  167       /**
  168        * Returns a URL to the resource that is mapped to a specified
  169        * path. The path must begin with a "/" and is interpreted
  170        * as relative to the current context root.
  171        *
  172        * <p>This method allows the servlet container to make a resource 
  173        * available to servlets from any source. Resources 
  174        * can be located on a local or remote
  175        * file system, in a database, or in a <code>.war</code> file. 
  176        *
  177        * <p>The servlet container must implement the URL handlers
  178        * and <code>URLConnection</code> objects that are necessary
  179        * to access the resource.
  180        *
  181        * <p>This method returns <code>null</code>
  182        * if no resource is mapped to the pathname.
  183        *
  184        * <p>Some containers may allow writing to the URL returned by
  185        * this method using the methods of the URL class.
  186        *
  187        * <p>The resource content is returned directly, so be aware that 
  188        * requesting a <code>.jsp</code> page returns the JSP source code.
  189        * Use a <code>RequestDispatcher</code> instead to include results of 
  190        * an execution.
  191        *
  192        * <p>This method has a different purpose than
  193        * <code>java.lang.Class.getResource</code>,
  194        * which looks up resources based on a class loader. This
  195        * method does not use class loaders.
  196        * 
  197        * @param path 				a <code>String</code> specifying
  198        *						the path to the resource
  199        *
  200        * @return 					the resource located at the named path,
  201        * 						or <code>null</code> if there is no resource
  202        *						at that path
  203        *
  204        * @exception MalformedURLException 	if the pathname is not given in 
  205        * 						the correct form
  206        *
  207        */
  208       
  209       public URL getResource(String path) throws MalformedURLException;
  210       
  211       
  212   
  213       /**
  214        * Returns the resource located at the named path as
  215        * an <code>InputStream</code> object.
  216        *
  217        * <p>The data in the <code>InputStream</code> can be 
  218        * of any type or length. The path must be specified according
  219        * to the rules given in <code>getResource</code>.
  220        * This method returns <code>null</code> if no resource exists at
  221        * the specified path. 
  222        * 
  223        * <p>Meta-information such as content length and content type
  224        * that is available via <code>getResource</code>
  225        * method is lost when using this method.
  226        *
  227        * <p>The servlet container must implement the URL handlers
  228        * and <code>URLConnection</code> objects necessary to access
  229        * the resource.
  230        *
  231        * <p>This method is different from 
  232        * <code>java.lang.Class.getResourceAsStream</code>,
  233        * which uses a class loader. This method allows servlet containers 
  234        * to make a resource available
  235        * to a servlet from any location, without using a class loader.
  236        * 
  237        *
  238        * @param path 	a <code>String</code> specifying the path
  239        *			to the resource
  240        *
  241        * @return 		the <code>InputStream</code> returned to the 
  242        *			servlet, or <code>null</code> if no resource
  243        *			exists at the specified path 
  244        *
  245        *
  246        */
  247   
  248       public InputStream getResourceAsStream(String path);
  249       
  250   
  251   
  252   
  253       /**
  254        * 
  255        * Returns a {@link RequestDispatcher} object that acts
  256        * as a wrapper for the resource located at the given path.
  257        * A <code>RequestDispatcher</code> object can be used to forward 
  258        * a request to the resource or to include the resource in a response.
  259        * The resource can be dynamic or static.
  260        *
  261        * <p>The pathname must begin with a "/" and is interpreted as relative
  262        * to the current context root.  Use <code>getContext</code> to obtain
  263        * a <code>RequestDispatcher</code> for resources in foreign contexts.
  264        * This method returns <code>null</code> if the <code>ServletContext</code>
  265        * cannot return a <code>RequestDispatcher</code>.
  266        *
  267        * @param path 	a <code>String</code> specifying the pathname
  268        *			to the resource
  269        *
  270        * @return 		a <code>RequestDispatcher</code> object
  271        *			that acts as a wrapper for the resource
  272        *			at the specified path, or <code>null</code> if 
  273        *			the <code>ServletContext</code> cannot return
  274        *			a <code>RequestDispatcher</code>
  275        *
  276        * @see 		RequestDispatcher
  277        * @see 		ServletContext#getContext
  278        *
  279        */
  280   
  281       public RequestDispatcher getRequestDispatcher(String path);
  282   
  283   
  284   
  285       /**
  286        * Returns a {@link RequestDispatcher} object that acts
  287        * as a wrapper for the named servlet.
  288        *
  289        * <p>Servlets (and JSP pages also) may be given names via server 
  290        * administration or via a web application deployment descriptor.
  291        * A servlet instance can determine its name using 
  292        * {@link ServletConfig#getServletName}.
  293        *
  294        * <p>This method returns <code>null</code> if the 
  295        * <code>ServletContext</code>
  296        * cannot return a <code>RequestDispatcher</code> for any reason.
  297        *
  298        * @param name 	a <code>String</code> specifying the name
  299        *			of a servlet to wrap
  300        *
  301        * @return 		a <code>RequestDispatcher</code> object
  302        *			that acts as a wrapper for the named servlet,
  303        *			or <code>null</code> if the <code>ServletContext</code>
  304        *			cannot return a <code>RequestDispatcher</code>
  305        *
  306        * @see 		RequestDispatcher
  307        * @see 		ServletContext#getContext
  308        * @see 		ServletConfig#getServletName
  309        *
  310        */
  311   
  312       public RequestDispatcher getNamedDispatcher(String name);
  313       
  314       
  315       
  316       
  317       /**
  318        *
  319        * @deprecated	As of Java Servlet API 2.1, with no direct replacement.
  320        *
  321        * <p>This method was originally defined to retrieve a servlet
  322        * from a <code>ServletContext</code>. In this version, this method 
  323        * always returns <code>null</code> and remains only to preserve 
  324        * binary compatibility. This method will be permanently removed 
  325        * in a future version of the Java Servlet API.
  326        *
  327        * <p>In lieu of this method, servlets can share information using the 
  328        * <code>ServletContext</code> class and can perform shared business logic
  329        * by invoking methods on common non-servlet classes.
  330        *
  331        */
  332   
  333       public Servlet getServlet(String name) throws ServletException;
  334       
  335     
  336     
  337     
  338       
  339   
  340       /**
  341        *
  342        * @deprecated	As of Java Servlet API 2.0, with no replacement.
  343        *
  344        * <p>This method was originally defined to return an <code>Enumeration</code>
  345        * of all the servlets known to this servlet context. In this
  346        * version, this method always returns an empty enumeration and
  347        * remains only to preserve binary compatibility. This method
  348        * will be permanently removed in a future version of the Java
  349        * Servlet API.
  350        *
  351        */
  352       
  353       public Enumeration getServlets();
  354       
  355       
  356       
  357       
  358       
  359   
  360       /**
  361        * @deprecated	As of Java Servlet API 2.1, with no replacement.
  362        *
  363        * <p>This method was originally defined to return an 
  364        * <code>Enumeration</code>
  365        * of all the servlet names known to this context. In this version,
  366        * this method always returns an empty <code>Enumeration</code> and 
  367        * remains only to preserve binary compatibility. This method will 
  368        * be permanently removed in a future version of the Java Servlet API.
  369        *
  370        */
  371    
  372       public Enumeration getServletNames();
  373       
  374     
  375     
  376       
  377       
  378       /**
  379        *
  380        * Writes the specified message to a servlet log file, usually
  381        * an event log. The name and type of the servlet log file is 
  382        * specific to the servlet container.
  383        *
  384        *
  385        * @param msg 	a <code>String</code> specifying the 
  386        *			message to be written to the log file
  387        *
  388        */
  389        
  390       public void log(String msg);
  391       
  392       
  393       
  394       
  395   
  396       /**
  397        * @deprecated	As of Java Servlet API 2.1, use
  398        * 			{@link #log(String message, Throwable throwable)} 
  399        *			instead.
  400        *
  401        * <p>This method was originally defined to write an 
  402        * exception's stack trace and an explanatory error message
  403        * to the servlet log file.
  404        *
  405        */
  406   
  407       public void log(Exception exception, String msg);
  408       
  409       
  410       
  411       
  412   
  413       /**
  414        * Writes an explanatory message and a stack trace
  415        * for a given <code>Throwable</code> exception
  416        * to the servlet log file. The name and type of the servlet log 
  417        * file is specific to the servlet container, usually an event log.
  418        *
  419        *
  420        * @param message 		a <code>String</code> that 
  421        *				describes the error or exception
  422        *
  423        * @param throwable 	the <code>Throwable</code> error 
  424        *				or exception
  425        *
  426        */
  427       
  428       public void log(String message, Throwable throwable);
  429       
  430       
  431       
  432       
  433       
  434       /**
  435        * Returns a <code>String</code> containing the real path 
  436        * for a given virtual path. For example, the path "/index.html"
  437        * returns the absolute file path on the server's filesystem would be
  438        * served by a request for "http://host/contextPath/index.html",
  439        * where contextPath is the context path of this ServletContext..
  440        *
  441        * <p>The real path returned will be in a form
  442        * appropriate to the computer and operating system on
  443        * which the servlet container is running, including the
  444        * proper path separators. This method returns <code>null</code>
  445        * if the servlet container cannot translate the virtual path
  446        * to a real path for any reason (such as when the content is
  447        * being made available from a <code>.war</code> archive).
  448        *
  449        *
  450        * @param path 	a <code>String</code> specifying a virtual path
  451        *
  452        *
  453        * @return 		a <code>String</code> specifying the real path,
  454        *                  or null if the translation cannot be performed
  455        *			
  456        *
  457        */
  458   
  459       public String getRealPath(String path);
  460       
  461       
  462   
  463   
  464       /**
  465        * Returns the name and version of the servlet container on which
  466        * the servlet is running. 
  467        *
  468        * <p>The form of the returned string is 
  469        * <i>servername</i>/<i>versionnumber</i>.
  470        * For example, the JavaServer Web Development Kit may return the string
  471        * <code>JavaServer Web Dev Kit/1.0</code>.
  472        *
  473        * <p>The servlet container may return other optional information 
  474        * after the primary string in parentheses, for example,
  475        * <code>JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86)</code>.
  476        *
  477        *
  478        * @return 		a <code>String</code> containing at least the 
  479        *			servlet container name and version number
  480        *
  481        */
  482   
  483       public String getServerInfo();
  484       
  485       
  486   
  487   
  488       /**
  489        * Returns a <code>String</code> containing the value of the named
  490        * context-wide initialization parameter, or <code>null</code> if the 
  491        * parameter does not exist.
  492        *
  493        * <p>This method can make available configuration information useful
  494        * to an entire "web application".  For example, it can provide a 
  495        * webmaster's email address or the name of a system that holds 
  496        * critical data.
  497        *
  498        * @param	name	a <code>String</code> containing the name of the
  499        *                  parameter whose value is requested
  500        * 
  501        * @return 		a <code>String</code> containing at least the 
  502        *			servlet container name and version number
  503        *
  504        * @see ServletConfig#getInitParameter
  505        */
  506   
  507       public String getInitParameter(String name);
  508       
  509       
  510   
  511   
  512       /**
  513        * Returns the names of the context's initialization parameters as an
  514        * <code>Enumeration</code> of <code>String</code> objects, or an
  515        * empty <code>Enumeration</code> if the context has no initialization
  516        * parameters.
  517        *
  518        * @return 		an <code>Enumeration</code> of <code>String</code> 
  519        *                  objects containing the names of the context's
  520        *                  initialization parameters
  521        *
  522        * @see ServletConfig#getInitParameter
  523        */
  524   
  525       public Enumeration getInitParameterNames();
  526       
  527       
  528   
  529       /**
  530        * Returns the servlet container attribute with the given name, 
  531        * or <code>null</code> if there is no attribute by that name.
  532        * An attribute allows a servlet container to give the
  533        * servlet additional information not
  534        * already provided by this interface. See your
  535        * server documentation for information about its attributes.
  536        * A list of supported attributes can be retrieved using
  537        * <code>getAttributeNames</code>.
  538        *
  539        * <p>The attribute is returned as a <code>java.lang.Object</code>
  540        * or some subclass.
  541        * Attribute names should follow the same convention as package
  542        * names. The Java Servlet API specification reserves names
  543        * matching <code>java.*</code>, <code>javax.*</code>,
  544        * and <code>sun.*</code>.
  545        *
  546        *
  547        * @param name 	a <code>String</code> specifying the name 
  548        *			of the attribute
  549        *
  550        * @return 		an <code>Object</code> containing the value 
  551        *			of the attribute, or <code>null</code>
  552        *			if no attribute exists matching the given
  553        *			name
  554        *
  555        * @see 		ServletContext#getAttributeNames
  556        *
  557        */
  558     
  559       public Object getAttribute(String name);
  560       
  561       
  562       
  563   
  564       /**
  565        * Returns an <code>Enumeration</code> containing the 
  566        * attribute names available
  567        * within this servlet context. Use the
  568        * {@link #getAttribute} method with an attribute name
  569        * to get the value of an attribute.
  570        *
  571        * @return 		an <code>Enumeration</code> of attribute 
  572        *			names
  573        *
  574        * @see		#getAttribute
  575        *
  576        */
  577   
  578       public Enumeration getAttributeNames();
  579       
  580       
  581       
  582       
  583       /**
  584        *
  585        * Binds an object to a given attribute name in this servlet context. If
  586        * the name specified is already used for an attribute, this
  587        * method will replace the attribute with the new to the new attribute.
  588        * <p>If listeners are configured on the <code>ServletContext</code> the  
  589        * container notifies them accordingly.
  590        * <p>
  591        * If a null value is passed, the effect is the same as calling 
  592        * <code>removeAttribute()</code>.
  593        * 
  594        * <p>Attribute names should follow the same convention as package
  595        * names. The Java Servlet API specification reserves names
  596        * matching <code>java.*</code>, <code>javax.*</code>, and
  597        * <code>sun.*</code>.
  598        *
  599        *
  600        * @param name 	a <code>String</code> specifying the name 
  601        *			of the attribute
  602        *
  603        * @param object 	an <code>Object</code> representing the
  604        *			attribute to be bound
  605        *
  606        *
  607        *
  608        */
  609       
  610       public void setAttribute(String name, Object object);
  611       
  612       
  613   
  614   
  615   
  616       /**
  617        * Removes the attribute with the given name from 
  618        * the servlet context. After removal, subsequent calls to
  619        * {@link #getAttribute} to retrieve the attribute's value
  620        * will return <code>null</code>.
  621   
  622        * <p>If listeners are configured on the <code>ServletContext</code> the 
  623        * container notifies them accordingly.
  624   
  625        *
  626        *
  627        * @param name	a <code>String</code> specifying the name 
  628        * 			of the attribute to be removed
  629        *
  630        */
  631   
  632       public void removeAttribute(String name);
  633       
  634       /**
  635        * Returns the name of this web application corresponding to this ServletContext as specified in the deployment
  636        * descriptor for this web application by the display-name element.
  637        *
  638        *
  639        * @return	    The name of the web application or null if no name has been declared in the deployment descriptor.
  640        * @since Servlet 2.3
  641        */
  642       
  643       public String getServletContextName();
  644   }
  645   
  646   

Home » apache-tomcat-6.0.26-src » javax » servlet » [javadoc | source]