ServletContext源码翻译

package javax.servlet;

import java.io.InputStream;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.Enumeration;
import java.util.EventListener;
import java.util.Map;
import java.util.Set;
import javax.servlet.descriptor.JspConfigDescriptor;

/**
 * 定义servlet和容器交流的一组方法，如：文件MIME类型，调度请求（获取资源的URL地址），写日志文件。
 * 
 * JVM中每一个web应用程序都有一个环境。（web应用程序是servlet的集合）。
 * 比如：Servlet上下文被定位于http://localhost:8080/项目名
 * 以"/项目名" 请求路径（称为上下文路径）开始的所有请求被发送到与此ServletContext关联的Web应用程序
 * 
 * 在部署描述符中标记为“分布式”的web应用程序的情况下，每一个JVM中都有context实例。
 * 在这种情形下，context不是一个共享全局信息（原因：信息不是真正的全局），这时使用
 * 外部资源，如数据库替换。
 * 
 * ServletContext对象包含在{@link ServletConfig}，
 * 当servlet初始化init()完成时，Web服务器提供servlet。
 * 
 * @author TCM
 * @create 2017年10月20日下午4:44:50
 * @see    Servlet#getServletConfig
 * @see    ServletConfig#getServletContext
 */
public interface ServletContext {

    //ServletContext常见方法
	//...
	
    /**
     * 返回web应用程序的上下文环境路径（如：/demo，即：/项目名）
     * 
     * 注意：一个servlet容器可能匹配一个上下文由多个上下文路径（分布式）。在这种情况下
     * javax.servlet.http.HttpServletRequest.getContextPath()：
     * 返回实际的请求和所使用的上下文路径可能不同于这个方法返回的路径。
     * 该方法返回的上下文路径应该被视为应用程序的上下文路径。
     * @return 
     * @see javax.servlet.http.HttpServletRequest#getContextPath()
     * @since Servlet 2.5
     */
    public String getContextPath();


    /**
     * 获取指定URL的上下文环境ServletContext对象
     * 
     * 这种方法允许servlet服务器访问上下文的不同部分，并获取RequestDispatcher对象。
     * 路径参数必须以“/”开头。
     * 
     * 不存在URL返回null，或是容器限制访问
     * @see RequestDispatcher
     */
    public ServletContext getContext(String uripath);
    

    /**
     * 返回资源路径（没有返回null）
     * 如：
     * getResourcePaths("/")：tomcat的webapps项目文件夹下的文件及目录
     * 		返回[/index.jsp, /resources/, /WEB-INF/, /error/, /META-INF/]
     * getResourcePaths("/lian2/")：
     *      返回[/WEB-INF/lib/, /WEB-INF/jsp/, /WEB-INF/classes/, ...]
     * 
     * @since Servlet 2.3
     */    
    public Set<String> getResourcePaths(String path);
    

    /**
     * 返回资源对应的URL对象
     * getResource("/"): 返回URL对象，jndi:/localhost/lian2/
     * 必须以"/"开始：如"/"、"/WEB-INF/lib"等等
     * 
     * 该方法不同于java.lang.Class.getResource：并没有使用类加载器
     * @param path 资源路径字符串
     * @exception MalformedURLException
     */    
    public URL getResource(String path) throws MalformedURLException;
    

    /**
     * 默认从WebAPP根目录下取资源InputStream对象
     * 不同与java.lang.Class.getResourceAsStream：
     * 不以'/'开头时默认是从此类所在的包下取资源，以'/'开头则是从ClassPath根下获取
     * 
     * 参考资料：http://riddickbryant.iteye.com/blog/436693
     */
    public InputStream getResourceAsStream(String path);
    

    /**
     * @see RequestDispatcher
     * @see ServletContext#getContext
     */
    public RequestDispatcher getRequestDispatcher(String path);

    public RequestDispatcher getNamedDispatcher(String name);

    /**
     * 指定信息写入servlet日志文件，通常使用事件日志
     */
    public void log(String msg);
    
    public void log(String message, Throwable throwable);
    
    
    /**
     * 包含一个给定虚拟路径的真实路径（一般不使用）
     * 参考资料：http://www.cnblogs.com/keyi/p/6232658.html
     */
    public String getRealPath(String path);
    

    /**
     * 返回运行中servlet容器的名称和本版号：如：Apache Tomcat/7.0.70
     */
    public String getServerInfo();
    

    /**
     * 获取servlet容器初始化信息(全局信息)
     * 在web.xml下的：
     * <context-param>
     *		<param-name>contextConfigLocation</param-name>
     *		<param-value>classpath*:/applicationContext*.xml</param-value>
  	 * </context-param>
     */
    public String getInitParameter(String name);
    public Enumeration<String> getInitParameterNames();
    public boolean setInitParameter(String name, String value);


    /**
     * 获取servlet容器的属性值（四大作用域中存取的键值对）
     */
    public Object getAttribute(String name);
    public Enumeration<String> getAttributeNames();
    public void setAttribute(String name, Object object);
    public void removeAttribute(String name);

    
    //servlet环境中添加、删除一个Servlet（ServletRegistration）...
    //servlet环境中添加一个Filter对象（Filter）...
    //获取{@link SessionCookieConfig}...
    //session跟踪模式，SessionTrackingMode...
    //增加、创建监听器（ServletContextListener）...
    //...

    /**
     * 获取<jsp-config>相关配置
     * 来自web.xml和web-fragment.xml
     */
    public JspConfigDescriptor getJspConfigDescriptor();
    //获取类加载器
    public ClassLoader getClassLoader();
    
    //...
}