servletcontext.java

JSWDK服务器

/*
 * $Id: ServletContext.java,v 1.7 1999/04/20 21:56:34 duncan Exp $
 * 
 * Copyright (c) 1995-1999 Sun Microsystems, Inc. All Rights Reserved.
 * 
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 * 
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
 * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
 * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
 * THIS SOFTWARE OR ITS DERIVATIVES.
 * 
 * CopyrightVersion 1.0
 */

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 a servlet engine, for example, to get the MIME type of a file, 
 * locate other servlets running on the server, or
 * write to a servlet log file.
 *
 * <p>The servlet engine talks to the servlet by returning
 * a <code>ServletContext</code> object (defined by this interface)
 * that gives servlets information about their environment. Servlets use the
 * {@link ServletConfig#getServletContext} method to get
 * the <code>ServletContext</code> object.
 *
 * <p>If the server supports
 * multiple or virtual hosts, the <code>ServletContext</code> object
 * must be at least as unique as the host. Servlet engines can also 
 * create <code>ServletContext</code> objects
 * that are unique to a group of servlets
 * and are tied to a specific part of the host's URL namespace.
 * You can assign this grouping administratively or define it in
 * a deployment descriptor file.
 *
 * <p>The <code>ServletContext</code> object is contained within 
 * the {@link ServletConfig} object, which the
 * Web server provides the
 * servlet when the servlet is initialized. You can access
 * the <code>ServletConfig</code> object by using the 
 * {@link Servlet#getServletConfig} method.
 *
 * @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.
     *
     * <p>This method allows servlets to gain
     * access to the resources located at a specified URL and obtain
     * {@link RequestDispatcher} objects from it.
     * 
     * <p>In security conscious environments, the servlet engine can
     * return <code>null</code> for a given URL.
     *       
     * @param uripath 	a <code>String</code> specifying the URL for 
     *			which you are requesting a <code>ServletContext</code>
     *			object
     *
     * @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
     * Web server supports. All implementations that comply
     * with Version 2.1 must have this method
     * return the integer 2.
     *
     * @return 		2
     *
     */
    
    public int getMajorVersion();
    
    

    /**
     * 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 engine. Common MIME
     * types are <code>"text/html"</code> and <code>"image/gif"</code>.
     *
     *
     * @param 		a <code>String</code> specifying the name
     *			of the file whose MIME type you want
     *			to check 
     *
     * @return 		a <code>String</code> specifying the MIME type
     *
     */

    public String getMimeType(String file);
    
    

    /**
     * Returns the minor version of the Servlet API that this
     * Web server supports. All implementations that comply
     * with Version 2.1 must have this method
     * return the integer 1.
     *
     * @return 		1
     *
     */

    public int getMinorVersion();
    
    

    /**
     * Returns the resource that is mapped to a specified
     * path. The path must be in the form
     * <code>/dir/dir/file.ext</code>.
     *
     * <p>This method allows the Web
     * server to make a resource available to a servlet from
     * any source. Resources 
     * can be located on a local or remote
     * file system, in a database, or on a remote network site.
     *
     * <p>This method can return <code>null</code>
     * if no resource is mapped to the pathname.
     *
     * <p>The servlet engine must implement the URL handlers
     * and <code>URLConnection</code> objects that are necessary
     * to access the resource.
     *
     * <p>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,
     * 						in the form <code>/dir/dir/file.ext</code>
     *
     * @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.
     *
     * <p>The data in the <code>InputStream</code> can be 
     * of any type or length. The path must be of 
     * the form <code>/dir/dir/file.ext</code>. This method 
     * returns <code>null</code> if no resource exists at
     * the specified path. 
     * 
     * <p>Metainformation such as content length and content type
     * that is available when you use the <code>getResource</code>
     * method is lost when you use this method.
     *
     * <p>The servlet engine must implement the URL handlers
     * and <code>URLConnection</code> objects necessary to access
     * the resource.
     *
     * <p>This method is different from 
     * <code>java.lang.Class.getResourceAsStream</code>,
     * which uses a class loader. This method allows servlet engines 
     * 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,
     * 			in the form <code>/dir/dir/file.ext</code>
     *
     * @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 named path.
     * You can use a <code>RequestDispatcher</code> object to forward 
     * a request to the resource or include a resource in a response.
     *
     * <p>The pathname must be in the form <code>/dir/dir/file.ext</code>.
     * This method returns <code>null</code> if the <code>ServletContext</code>
     * cannot return a <code>RequestDispatcher</code>.
     *
     * <p>The servlet engine is responsible for wrapping the resource
     * with a <code>RequestDispatcher</code> object.
     *
     * @param urlpath 	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 path you specify
     *
     * @see 		RequestDispatcher
     *
     */

    public RequestDispatcher getRequestDispatcher(String urlpath);
    
    
    
    
    /**
     *
     * @deprecated	As of Java Servlet API 2.1, with no replacement.
     *
     * <p>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