PC World 2002 May

home *** CD-ROM | disk | FTP | other *** search

/ PC World 2002 May / PCWorld_2002-05_cd.bin / Komunik / sambar / sambar51p.exe / lib / javaeng.jar / javax / servlet / ServletContext.java < prev next >

Wrap

Java Source | 2001-10-22 | 20.8 KB | 638 lines

/* * The Apache Software License, Version 1.1 * * Copyright (c) 1999 The Apache Software Foundation. All rights * reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * * 3. The end-user documentation included with the redistribution, if * any, must include the following acknowlegement: * "This product includes software developed by the * Apache Software Foundation (http://www.apache.org/)." * Alternately, this acknowlegement may appear in the software itself, * if and wherever such third-party acknowlegements normally appear. * * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software * Foundation" must not be used to endorse or promote products derived * from this software without prior written permission. For written * permission, please contact apache@apache.org. * * 5. Products derived from this software may not be called "Apache" * nor may "Apache" appear in their names without prior written * permission of the Apache Group. * * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * ==================================================================== * * This software consists of voluntary contributions made by many * individuals on behalf of the Apache Software Foundation. For more * information on the Apache Software Foundation, please see * <http://www.apache.org/>. * * ==================================================================== * * This source code implements specifications defined by the Java * Community Process. In order to remain compliant with the specification * DO NOT add / change / or delete method signatures! */ package javax.servlet; import java.io.InputStream; import java.io.IOException; import java.net.URL; import java.net.MalformedURLException; import java.util.Enumeration; /** * * Defines a set of methods that a servlet uses to communicate with its * servlet container, for example, to get the MIME type of a file, dispatch * requests, or write to a log file. * * There is one context per "web application" per Java Virtual Machine. (A * "web application" is a collection of servlets and content installed under a * specific subset of the server's URL namespace such as <code>/catalog</code> * and possibly installed via a <code>.war</code> file.) * * In the case of a web * application marked "distributed" in its deployment descriptor, there will * be one context instance for each virtual machine. In this situation, the * context cannot be used as a location to share global information (because * the information won't be truly global). Use an external resource like * a database instead. * * The <code>ServletContext</code> object is contained within * the {@link ServletConfig} object, which the Web server provides the * servlet when the servlet is initialized. * * @author Various * @version $Version$ * * @see Servlet#getServletConfig * @see ServletConfig#getServletContext * */ public interface ServletContext { /** * Returns a <code>ServletContext</code> object that * corresponds to a specified URL on the server. * * This method allows servlets to gain * access to the context for various parts of the server, and as * needed obtain {@link RequestDispatcher} objects from the context. * The given path must be absolute (beginning with "/") and is * interpreted based on the server's document root. * * In a security conscious environment, the servlet container may * return <code>null</code> for a given URL. * * @param uripath a <code>String</code> specifying the absolute URL of * a resource on the server * * @return the <code>ServletContext</code> object that * corresponds to the named URL * * @see RequestDispatcher * */ public ServletContext getContext(String uripath); /** * Returns the major version of the Java Servlet API that this * servlet container supports. All implementations that comply * with Version 2.2 must have this method * return the integer 2. * * @return 2 * */ public int getMajorVersion(); /** * Returns the minor version of the Servlet API that this * servlet container supports. All implementations that comply * with Version 2.2 must have this method * return the integer 2. * * @return 2 * */ public int getMinorVersion(); /** * Returns the MIME type of the specified file, or <code>null</code> if * the MIME type is not known. The MIME type is determined * by the configuration of the servlet container, and may be specified * in a web application deployment descriptor. Common MIME * types are <code>"text/html"</code> and <code>"image/gif"</code>. * * * @param file a <code>String</code> specifying the name * of a file * * @return a <code>String</code> specifying the file's MIME type * */ public String getMimeType(String file); /** * Returns a URL to the resource that is mapped to a specified * path. The path must begin with a "/" and is interpreted * as relative to the current context root. * * This method allows the servlet container to make a resource * available to servlets from any source. Resources * can be located on a local or remote * file system, in a database, or in a <code>.war</code> file. * * The servlet container must implement the URL handlers * and <code>URLConnection</code> objects that are necessary * to access the resource. * * This method returns <code>null</code> * if no resource is mapped to the pathname. * * Some containers may allow writing to the URL returned by * this method using the methods of the URL class. * * The resource content is returned directly, so be aware that * requesting a <code>.jsp</code> page returns the JSP source code. * Use a <code>RequestDispatcher</code> instead to include results of * an execution. * * This method has a different purpose than * <code>java.lang.Class.getResource</code>, * which looks up resources based on a class loader. This * method does not use class loaders. * * @param path a <code>String</code> specifying * the path to the resource * * @return the resource located at the named path, * or <code>null</code> if there is no resource * at that path * * @exception MalformedURLException if the pathname is not given in * the correct form * */ public URL getResource(String path) throws MalformedURLException; /** * Returns the resource located at the named path as * an <code>InputStream</code> object. * * The data in the <code>InputStream</code> can be * of any type or length. The path must be specified according * to the rules given in <code>getResource</code>. * This method returns <code>null</code> if no resource exists at * the specified path. * * Meta-information such as content length and content type * that is available via <code>getResource</code> * method is lost when using this method. * * The servlet container must implement the URL handlers * and <code>URLConnection</code> objects necessary to access * the resource. * * This method is different from * <code>java.lang.Class.getResourceAsStream</code>, * which uses a class loader. This method allows servlet containers * to make a resource available * to a servlet from any location, without using a class loader. * * * @param name a <code>String</code> specifying the path * to the resource * * @return the <code>InputStream</code> returned to the * servlet, or <code>null</code> if no resource * exists at the specified path * * */ public InputStream getResourceAsStream(String path); /** * * Returns a {@link RequestDispatcher} object that acts * as a wrapper for the resource located at the given path. * A <code>RequestDispatcher</code> object can be used to forward * a request to the resource or to include the resource in a response. * The resource can be dynamic or static. * * The pathname must begin with a "/" and is interpreted as relative * to the current context root. Use <code>getContext</code> to obtain * a <code>RequestDispatcher</code> for resources in foreign contexts. * This method returns <code>null</code> if the <code>ServletContext</code> * cannot return a <code>RequestDispatcher</code>. * * @param path a <code>String</code> specifying the pathname * to the resource * * @return a <code>RequestDispatcher</code> object * that acts as a wrapper for the resource * at the specified path * * @see RequestDispatcher * @see ServletContext#getContext * */ public RequestDispatcher getRequestDispatcher(String path); /** * Returns a {@link RequestDispatcher} object that acts * as a wrapper for the named servlet. * * Servlets (and JSP pages also) may be given names via server * administration or via a web application deployment descriptor. * A servlet instance can determine its name using * {@link ServletConfig#getServletName}. * * This method returns <code>null</code> if the * <code>ServletContext</code> * cannot return a <code>RequestDispatcher</code> for any reason. * * @param name a <code>String</code> specifying the name * of a servlet to wrap * * @return a <code>RequestDispatcher</code> object * that acts as a wrapper for the named servlet * * @see RequestDispatcher * @see ServletContext#getContext * @see ServletConfig#getServletName * */ public RequestDispatcher getNamedDispatcher(String name); /** * * @deprecated As of Java Servlet API 2.1, with no direct replacement. * * This method was originally defined to retrieve a servlet * from a <code>ServletContext</code>. In this version, this method * always returns <code>null</code> and remains only to preserve * binary compatibility. This method will be permanently removed * in a future version of the Java Servlet API. * * In lieu of this method, servlets can share information using the * <code>ServletContext</code> class and can perform shared business logic * by invoking methods on common non-servlet classes. * */ public Servlet getServlet(String name) throws ServletException; /** * * @deprecated As of Java Servlet API 2.0, with no replacement. * * This method was originally defined to return an <code>Enumeration</code> * of all the servlets known to this servlet context. In this * version, this method always returns an empty enumeration and * remains only to preserve binary compatibility. This method * will be permanently removed in a future version of the Java * Servlet API. * */ public Enumeration getServlets(); /** * @deprecated As of Java Servlet API 2.1, with no replacement. * * This method was originally defined to return an * <code>Enumeration</code> * of all the servlet names known to this context. In this version, * this method always returns an empty <code>Enumeration</code> and * remains only to preserve binary compatibility. This method will * be permanently removed in a future version of the Java Servlet API. * */ public Enumeration getServletNames(); /** * * Writes the specified message to a servlet log file, usually * an event log. The name and type of the servlet log file is * specific to the servlet container. * * * @param msg a <code>String</code> specifying the * message to be written to the log file * */ public void log(String msg); /** * @deprecated As of Java Servlet API 2.1, use * {@link #log(String message, Throwable throwable)} * instead. * * This method was originally defined to write an * exception's stack trace and an explanatory error message * to the servlet log file. * */ public void log(Exception exception, String msg); /** * Writes an explanatory message and a stack trace * for a given <code>Throwable</code> exception * to the servlet log file. The name and type of the servlet log * file is specific to the servlet container, usually an event log. * * * @param message a <code>String</code> that * describes the error or exception * * @param throwable the <code>Throwable</code> error * or exception * */ public void log(String message, Throwable throwable); /** * Returns a <code>String</code> containing the real path * for a given virtual path. For example, the virtual path "/index.html" * has a real path of whatever file on the server's filesystem would be * served by a request for "/index.html". * * The real path returned will be in a form * appropriate to the computer and operating system on * which the servlet container is running, including the * proper path separators. This method returns <code>null</code> * if the servlet container cannot translate the virtual path * to a real path for any reason (such as when the content is * being made available from a <code>.war</code> archive). * * * @param path a <code>String</code> specifying a virtual path * * * @return a <code>String</code> specifying the real path, * or null if the translation cannot be performed * * */ public String getRealPath(String path); /** * Returns the name and version of the servlet container on which * the servlet is running. * * The form of the returned string is * servername/versionnumber. * For example, the JavaServer Web Development Kit may return the string * <code>JavaServer Web Dev Kit/1.0</code>. * * The servlet container may return other optional information * after the primary string in parentheses, for example, * <code>JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86)</code>. * * * @return a <code>String</code> containing at least the * servlet container name and version number * */ public String getServerInfo(); /** * Returns a <code>String</code> containing the value of the named * context-wide initialization parameter, or <code>null</code> if the * parameter does not exist. * * This method can make available configuration information useful * to an entire "web application". For example, it can provide a * webmaster's email address or the name of a system that holds * critical data. * * @param name a <code>String</code> containing the name of the * parameter whose value is requested * * @return a <code>String</code> containing at least the * servlet container name and version number * * @see ServletConfig#getInitParameter */ public String getInitParameter(String name); /** * Returns the names of the context's initialization parameters as an * <code>Enumeration</code> of <code>String</code> objects, or an * empty <code>Enumeration</code> if the context has no initialization * parameters. * * @return an <code>Enumeration</code> of <code>String</code> * objects containing the names of the context's * initialization parameters * * @see ServletConfig#getInitParameter */ public Enumeration getInitParameterNames(); /** * Returns the servlet container attribute with the given name, * or <code>null</code> if there is no attribute by that name. * An attribute allows a servlet container to give the * servlet additional information not * already provided by this interface. See your * server documentation for information about its attributes. * A list of supported attributes can be retrieved using * <code>getAttributeNames</code>. * * The attribute is returned as a <code>java.lang.Object</code> * or some subclass. * Attribute names should follow the same convention as package * names. The Java Servlet API specification reserves names * matching <code>java.*</code>, <code>javax.*</code>, * and <code>sun.*</code>. * * * @param name a <code>String</code> specifying the name * of the attribute * * @return an <code>Object</code> containing the value * of the attribute, or <code>null</code> * if no attribute exists matching the given * name * * @see ServletContext#getAttributeNames * */ public Object getAttribute(String name); /** * Returns an <code>Enumeration</code> containing the * attribute names available * within this servlet context. Use the * {@link #getAttribute} method with an attribute name * to get the value of an attribute. * * @return an <code>Enumeration</code> of attribute * names * * @see #getAttribute * */ public Enumeration getAttributeNames(); /** * * Binds an object to a given attribute name in this servlet context. If * the name specified is already used for an attribute, this * method will remove the old attribute and bind the name * to the new attribute. * * Attribute names should follow the same convention as package * names. The Java Servlet API specification reserves names * matching <code>java.*</code>, <code>javax.*</code>, and * <code>sun.*</code>. * * * @param name a <code>String</code> specifying the name * of the attribute * * @param object an <code>Object</code> representing the * attribute to be bound * * * */ public void setAttribute(String name, Object object); /** * Removes the attribute with the given name from * the servlet context. After removal, subsequent calls to * {@link #getAttribute} to retrieve the attribute's value * will return <code>null</code>. * * * @param name a <code>String</code> specifying the name * of the attribute to be removed * */ public void removeAttribute(String name); }