Java Servlet API说明文档（2.1a版）（2）

API对象的说明

这一部分包含了对Java Servlet API的全部类和接口的详细说明。这个说明与Javadoc API差不多，但是这份文档提供了更多的信息。
API包含了两个软件包，十二个接口和九个类。
软件包：javax.servlet
所包含的接口：RequestDispatcher；Servlet；ServletConfig；ServletContext；ServletRequest；ServletResponse；SingleThreadModel。
所包含的类：GenericServlet；ServletInputStream；ServletOutputStream；ServletException；UnavailableException。

一、RequestDispatcher接口：
定义：
public interface RequestDispatcher;
定义一个对象，从客户端接收请求，然后将它发给服务器的可用资源（例如Servlet、CGI、HTML文件、JSP文件）。Servlet引擎创建request dispatcher对象，用于封装由一个特定的URL定义的服务器资源。
这个接口是专用于封装Servlet的，但是一个Servlet引擎可以创建request dispatcher对象用于封装任何类型的资源。
request dispatcher对象是由Servlet引擎建立的，而不是由Servlet开发者建立的。
方法
1、forward
public void forward(ServletRequest request, ServletReponse response)
throws ServletException, IOException;
被用来从这个Servlet向其它服务器资源传递请求。当一个Servlet对响应作了初步的处理，并要求其它的对象对此作出响应时，可以使用这个方法。
当request对象被传递到目标对象时，请求的URL路径和其他路径参数会被调整为反映目标对象的目标URL路径。
如果已经通过响应返回了一个ServletOutputStream对象或PrintWriter对象，这个方法将不能使用，否则，这个方法会抛出一个IllegalStateException。
2、include
public void include(ServletRequest request, ServletResponse response)
throws ServletException, IOException
用来包括发送给其他服务器资源的响应的内容。本质上来说，这个方法反映了服务器端的内容。
请求对象传到目标对象后会反映调用请求的请求URL路径和路径信息。这个响应对象只能调用这个Servlet的ServletOutputStream对象和PrintWriter对象。
一个调用include的Servlet不能设置头域，如果这个Servlet调用了必须设置头域的方法（例如cookie），这个方法将不能保证正常使用。作为一个Servlet开发者，你必须妥善地解决那些可能直接存储头域的方法。例如，即使你使用会话跟踪，为了保证session的正常工作，你必须在一个调用include的Servlet之外开始你的session

二、Servlet接口。
定义\r
public interface Servlet
这个接口定义了一个Servlet：一个在Web服务器上继承了这个功能的Java类。
方法
1、init
public void init(ServletConfig config) throws ServletException;
Servlet引擎会在Servlet实例化之后，置入服务之前精确地调用init方法。在调用service方法之前，init方法必须成功退出。
如果init方法抛出一个ServletException，你不能将这个Servlet置入服务中，如果init方法在超时范围内没完成，我们也可以假定这个Servlet是不具备功能的，也不能置入服务中。
2、service
public void service(ServletRequest request, ServletResponse response)
throws ServletException, IOException;
Servlet引擎调用这个方法以允许Servlet响应请求。这个方法在Servlet未成功初始化之前无法调用。在Servlet被初始化之前，Servlet引擎能够封锁未决的请求。
在一个Servlet对象被卸载后，直到一个新的Servelt被初始化，Servlet引擎不能调用这个方法
3、destroy
public void destroy();
当一个Servlet被从服务中去除时，Servlet引擎调用这个方法。在这个对象的service方法所有线程未全部退出或者没被引擎认为发生超时操作时，destroy方法不能被调用。
4、getServletConfig
public ServletConfig getServletConfig();
返回一个ServletConfig对象，作为一个Servlet的开发者，你应该通过init方法存储ServletConfig对象以便这个方法能返回这个对象。为了你的便利，GenericServlet在执行这个接口时，已经这样做了。
5、getServletInfo
public String getServletInfo();
允许Servlet向主机的Servlet运行者提供有关它本身的信息。返回的字符串应该是纯文本格式而不应有任何标志（例如HTML，XML等）。

三、ServletConfig接口
定义\r
public interface ServletConfig
这个接口定义了一个对象，通过这个对象，Servlet引擎配置一个Servlet并且允许Servlet获得一个有关它的ServletContext接口的说明。每一个ServletConfig对象对应着一个唯一的Servlet。
方法
1、getInitParameter
public String getInitParameter(String name);
这个方法返回一个包含Servlet指定的初始化参数的String。如果这个参数不存在，返加空值。
2、getInitParameterNames
public Enumeration getInitParameterNames();
这个方法返回一个列表String对象，该对象包括Servlet的所有初始化参数名。如果Servlet没有初始化参数，getInitParameterNames返回一个空的列表。
3、getServletContext
public ServletContext getServletContext();
返回这个Servlet的ServletContext对象。

四、ServletContext接口
定义\r
public interface ServletContext
定义了一个Servlet的环境对象，通过这个对象，Servlet引擎向Servlet提供环境信息。
一个Servlet的环境对象必须至少与它所驻留的主机是一一对应的。在一个处理多个虚拟主机的Servlet引擎中（例如，使用了HTTP1.1的主机头域），每一个虚拟主机必须被视为一个单独的环境。此外，Servlet引擎还可以创建对应于一组Servlet的环境对象。
方法
1、getAttribute
public Object getAttribute(String name);
返回Servlet环境对象中指定的属性对象。如果该属性对象不存在，返回空值。这个方法允许访问有关这个Servlet引擎的在该接口的其他方法中尚未提供的附加信息。
2、getAttributeNames
public Enumeration getAttributeNames();
返回一个Servlet环境对象中可用的属性名的列表。
3、getContext
public ServletContext getContext(String uripath);
返回一个Servlet环境对象，这个对象包括了特定URI路径的Servlets和资源，如果该路径不存在，则返回一个空值。URI路径格式是/dir/dir/filename.ext。
为了安全，如果通过这个方法访问一个受限制的Servlet的环境对象，会返回一个空值。
4、getMajorVersion
public int getMajorVersion();
返回Servlet引擎支持的Servlet API的主版本号。例如对于2.1版，这个方法会返回一个整数2。
5、getMinorVersion
public int getMinorVersion();
返回Servlet引擎支持的Servlet API的次版本号。例如对于2.1版，这个方法会返回一个整数2。
6、getMimeType
public String getMimeType(String file);
返回指定文件的MIME类型，如果这种MIME类型未知，则返回一个空值。MIME类型是由Servlet引擎的配置决定的。
7、getRealPath
public String getRealPath(String path);
一个符合URL路径格式的指定的虚拟路径的格式是：/dir/dir/filename.ext。用这个方法，可以返回与一个符合该格式的虚拟路径相对应的真实路径的String。这个真实路径的格式应该适合于运行这个Servlet引擎的计算机（包括其相应的路径解析器）。
不管是什么原因，如果这一从虚拟路径转换成实际路径的过程不能执行，该方法将会返回一个空值。
8、getResource
public URL getResource(String uripath);
返回一个URL对象，该对象反映位于给定的URL地址（格式：/dir/dir/filename.ext）的Servlet环境对象已知的资源。无论 URLStreamHandlers对于访问给定的环境是不是必须的，Servlet引擎都必须执行。如果给定的路径的Servlet环境没有已知的资源，该方法会返回一个空值。
这个方法和java.lang.Class的getResource方法不完全相同。 java.lang.Class的getResource方法通过装载类来寻找资源。而这个方法允许服务器产生环境变量给任何资源的任何Servlet，而不必依赖于装载类、特定区域等等。
9、getResourceAsStream
public InputStream getResourceAsStream(String uripath);
返回一个InputStream对象，该对象引用指定的URL的Servlet环境对象的内容。如果没找到Servlet环境变量，就会返回空值，URL路径应该具有这种格式：/dir/dir/filename.ext。
这个方法是一个通过getResource方法获得URL对象的方便的途径。请注意，当你使用这个方法时，meta-information（例如内容长度、内容类型）会丢失。
10、getRequestDispatcher
public RequestDispatcher getRequestDispatcher(String uripath);
如果这个指定的路径下能够找到活动的资源(例如一个Servlet，JSP页面，CGI等等)就返回一个特定URL的RequestDispatcher对象，否则，就返回一个空值，Servlet引擎负责用一个request dispatcher对象封装目标路径。这个request dispatcher对象可以用来完全请求的传送。
11、getServerInfo
public String getServerInfo();
返回一个String对象，该对象至少包括Servlet引擎的名字和版本号。
12、log
public void log(String msg);
public void log(String msg, Throwable t);
public void log(Exception exception, String msg); // 这种用法将被取消\r
写指定的信息到一个Servlet环境对象的log文件中。被写入的log文件由Servlet引擎指定，但是通常这是一个事件log。当这个方法被一个异常调用时，log中将包括堆栈跟踪。
13、setAttribute
public void setAttribute(String name, Object o);
给予Servlet环境对象中你所指定的对象一个名称。
14、removeAttribute
public void removeAttribute(String name);
从指定的Servlet环境对象中删除一个属性。
注：以下几个方法将被取消\r
15、getServlet
public Servlet getServlet(String name) throws ServletException;
最初用来返回一个指定名称的Servlet，如果没找到就返回一个空值。如果这个Servlet能够返回，这就意味着它已经被初始化，而且已经可以接受 service请求。这是一个危险的方法。当调用这个方法时，可能并不知道Servlet的状态，这就可能导致有关服务器状态的问题。而允许一个 Servlet访问其他Servlet的这个方法也同样的危险。
现在这个方法返回一个空值，为了保持和以前版本的兼容性，现在这个方法还没有被取消。在以后的API版本中，该方法将被取消。
16、getServletNames
public Enumeration getServletNames();
最初用来返回一个String对象的列表，该列表表示了在这个Servlet环境下所有已知的Servlet对象名。这个列表总是包含这个Servlet自身。
基于与上一个方法同样的理由，这也是一个危险的方法。
现在这个方法返回一个空的列表。为了保持和以前版本的兼容性，现在这个方法还没有被取消。在以后的API版本中，该方法将被取消。
17、getServlets
public Enumeration getServlets();
最初用来返回在这个Servelet环境下所有已知的Servlet对象的列表。这个列表总是包含这个Servlet自身。
基于与getServlet方法同样的理由，这也是一个危险的方法。
现在这个方法返回一个空的列表。为了保持和以前版本的兼容性，现在这个方法还没有被取消。在以后的API版本中，该方法将被取消。

五、ServletRequest接口
定义\r
public interface ServletRequest
定义一个Servlet引擎产生的对象，通过这个对象，Servlet可以获得客户端请求的数据。这个对象通过读取请求体的数据提供包括参数的名称、值和属性以及输入流的所有数据。
方法
1、getAttribute
public Object getAttribute(String name);
返回请求中指定属性的值，如果这个属性不存在，就返回一个空值。这个方法允许访问一些不提供给这个接口中其他方法的请求信息以及其他Servlet放置在这个请求对象内的数据。
2、getAttributeNames
public Enumeration getAttributeNames();
返回包含在这个请求中的所有属性名的列表。
3、getCharacterEncoding
public String getCharacterEncoding();
返回请求中输入内容的字符编码类型，如果没有定义字符编码类型就返回空值。
4、getContentLength
public int getContentLength();
请求内容的长度，如果长度未知就返回-1。
5、getContentType
public String getContentType();
返回请求数据体的MIME类型，如果类型未知返回空值。
6、getInputStream
public ServletInputStream getInputStream() throws IOException;
返回一个输入流用来从请求体读取二进制数据。如果在此之前已经通过getReader方法获得了要读取的结果，这个方法会抛出一个IllegalStateException。
7、getParameter
public String getParameter(String name);
以一个String返回指定的参数的值，如果这个参数不存在返回空值。例如，在一个HTTP Servlet中，这个方法会返回一个指定的查询语句产生的参数的值或一个被提交的表单中的参数值。如果一个参数名对应着几个参数值，这个方法只能返回通过getParameterValues方法返回的数组中的第一个值。因此，如果这个参数有（或者可能有）多个值，你只能使用 getParameterValues方法。
8、getParameterNames
public Enumeration getParameterNames();
返回所有参数名的String对象列表，如果没有输入参数，该方法返回一个空值。
9、getParameterValues
public String[] getParameterValues(String name);
通过一个String对象的数组返回指定参数的值，如果这个参数不存在，该方法返回一个空值。
10、getProtocol
public String getProtocol();
返回这个请求所用的协议，其形式是协议/主版本号.次版本号。例如对于一个HTTP1.0的请求，该方法返回HTTP/1.0。
11、getReader
public BufferedReader getReader() throws IOException;
这个方法返回一个buffered reader用来读取请求体的实体，其编码方式依照请求数据的编码方式。如果这个请求的输入流已经被getInputStream调用获得，这个方法会抛出一个IllegalStateException。
12、getRemoteAddr
public String getRemoteAddr();
返回发送请求者的IP地址。
13、getRemoteHost
public String getRemoteHost();
返回发送请求者的主机名称。如果引擎不能或者选择不解析主机名（为了改善性能），这个方法会直接返回IP地址。
14、getScheme
public String getScheme();
返回请求所使用的URL的模式。例如，对于一个HTTP请求，这个模式就是http。
15、getServerName
public String getServerName();
返回接收请求的服务器的主机名。
16、getServerPort
public int getServerPort();
返回接收请求的端口号。
17、setAttribute
public void setAttribute(String name, Object object);
这个方法在请求中添加一个属性，这个属性可以被其他可以访问这个请求对象的对象（例如一个嵌套的Servlet）使用。
注：以下方法将被取消\r
getRealPath
public String getRealPath(String path);
返回与虚拟路径相对应的真实路径，如果因为某种原因，这一过程不能进行，该方法将返回一个空值。
这个方法和ServletContext接口中的getRealPath方法重复。在2.1版中，ServletContext接口将阐明一个 Servlet所能用的所有的路径的映射。该方法执行的结果将会与ServletContext中getRealPath方法的结果完全一样。

六、ServletResponse接口
定义\r
public interface ServletResponse
定义一个Servlet引擎产生的对象，通过这个对象，Servlet对客户端的请求作出响应。这个响应应该是一个MIME实体，可能是一个HTML页、图象数据或其他MIME的格式。
方法
1、getCharacterEncoding
public String getCharacterEncoding();
返回MIME实体的字符编码。这个字符编码可以是指定的类型，也可以是与请求头域所反映的客户端所能接受的字符编码最匹配的类型。在HTTP协议中，这个信息被通过Accept-Charset传送到Servlet引擎。
有关字符编码和MIME的更多信息请参看RFC 2047。
2、getOutputStream
public ServletOutputStream getOutputStream() throws IOException;
返回一个记录二进制的响应数据的输出流。
如果这个响应对象已经调用getWriter，将会抛出IllegalStateException。
3、getWriter
public PrintWriter getWriter throws IOException;
这个方法返回一个PringWriter对象用来记录格式化的响应实体。如果要反映使用的字符编码，必须修改响应的MIME类型。在调用这个方法之前，必须设定响应的content类型。
如果没有提供这样的编码类型，会抛出一个UnsupportedEncodingException，如果这个响应对象已调用getOutputStream，会抛出一个getOutputStream。
4、setContentLength
public void setContentLength(int length);
设置响应的内容的长度，这个方法会覆盖以前对内容长度的设定。
为了保证成功地设定响应头的内容长度，在响应被提交到输出流之前必须调用这个方法。
5、setContentType
public void setContentType(String type);
这个方法用来设定响应的content类型。这个类型以后可能会在另外的一些情况下被隐式地修改，这里所说的另外的情况可能当服务器发现有必要的情况下对MIME的字符设置。
为了保证成功地设定响应头的content类型，在响应被提交到输出流之前必须调用这个方法。

七、SingleThreadModel接口
定义\r
public interface SingleThreadModel;
这是一个空接口，它指定了系统如何处理对同一个Servlet的调用。如果一个Servlet被这个接口指定，那么在这个Servlet中的service方法中将不会有两个线程被同时执行。
Servlet可以通过维持一个各自独立的Servlet实例池，或者通过只让Servlet的service中只有一个线程的方法来实现这个保证。

八、GenericServlet类\r
public abstract class GenericServlet implements Servlet,
ServletConfig, Serializable;
这个类的存在使得编写Servlet更加方便。它提供了一个简单的方案，这个方案用来执行有关Servlet生命周期的方法以及在初始化时对ServletConfig对象和ServletContext对象进行说明。
方法
1、destroy
public void destroy();
在这里destroy方法不做任何其他的工作。
2、getInitParameter
public String getInitParameter(String name);
这是一个简便的途径，它将会调用ServletConfig对象的同名的方法。
3、getInitParameterNames
public Enumeration getInitParameterNames();
这是一个简便的途径，它将会调用ServletConfig对象的同名的方法。
4、getServletConfig
public ServletConfig getServletConfig();
返回一个通过这个类的init方法产生的ServletConfig对象的说明。
5、getServletContext
public ServletContext getServletContext();
这是一个简便的途径，它将会调用ServletConfig对象的同名的方法。
6、getServletInfo
public String getServletInfo();
返回一个反映Servlet版本的String。
7、init
public void init() throws ServletException;
public void init(ServletConfig config) throws ServletException;
init(ServletConfig config)方法是一个对这个Servlet的生命周期进行初始化的简便的途径。
init()方法是用来让你对GenericServlet类进行扩充的，使用这个方法时，你不需要存储config对象，也不需要调用super.init(config)。
init(ServletConfig config)方法会存储config对象然后调用init()。如果你重载了这个方法，你必须调用super.init(config)，这样GenericServlet类的其他方法才能正常工作。
8、log
public void log(String msg);
public void log(String msg, Throwable cause);
通过Servlet content对象将Servlet的类名和给定的信息写入log文件中。
9、service
public abstract void service(ServletRequest request, ServletResponse
response) throws ServletException, IOException;
这是一个抽象的方法，当你扩展这个类时，为了执行网络请求，你必须执行它。

九、ServletInputStream类\r
定义\r
public abstract class ServletInputStream extends InputStream
这个类定义了一个用来读取客户端的请求信息的输入流。这是一个Servlet引擎提供的抽象类。一个Servlet通过使用ServletRequest接口获得了对一个ServletInputStream对象的说明。
这个类的子类必须提供一个从InputStream接口读取有关信息的方法。
方法
1、readLine
public int readLine(byte[] b, int off, int len) throws IOException;
从输入流的指定的偏移量开始将指定长度的字节读入到指定的数组中。如果该行所有请求的内容都已被读取，这个读取的过程将结束。如果是遇到了新的一行，新的一行的首个字符也将被读入到数组中。

十、ServletOutputStream类\r
定义\r
public abstract class ServletOutputStream extends OutputStream
这是一个由Servlet引擎使用的抽象类。Servlet通过使用ServletResponse接口的使用获得了对一个这种类型的对象的说明。利用这个输出流可以将数据返回到客户端。
这个类的子类必须提供一个向OutputStream接口写入有关信息的方法。
在这个接口中，当一个刷新或关闭的方法被调用时。所有数据缓冲区的信息将会被发送到客户端，也就是说响应被提交了。请注意，关闭这种类型的对象时不一定要关闭隐含的socket流。
方法
1、print
public void print(String s) throws IOException;
public void print(boolean b) throws IOException;
public void print(char c) throws IOException;
public void print(int i) throws IOException;
public void print(long l) throws IOException;
public void print(float f) throws IOException;
public void print(double d) throws IOException;
输出变量到输出流中
2、println
public void println() throws IOException;
public void println(String s) throws IOException;
public void println(boolean b) throws IOException;
public void println(char c) throws IOException;
public void println(int i) throws IOException;
public void println(long l) throws IOException;
public void println(float f) throws IOException;
public void println(double d) throws IOException;
输出变量到输出流中，并增加一个回车换行符\r

十一、ServletException类\r
定义\r
public class ServletException extends Exception
当Servlet遇到问题时抛出的一个异常。
构造函数
public ServletException();
public ServletException(String message);
public ServletException(String message, Throwable cause);
public ServletException(Throwable cause);
构造一个新的ServletException，如果这个构造函数包括一个Throwable参数，这个Throwable对象将被作为可能抛出这个异常的原因。
方法
1、getRootCause
public Throwable getRootCause();
如果配置了抛出这个异常的原因，这个方法将返回这个原因，否则返回一个空值。

十二、UnavailableException类\r
定义\r
public class UnavailableException extends ServletException
不论一个Servlet是永久地还是临时地无效，都会抛出这个异常。Servlet会记录这个异常以及Servlet引擎所要采取的相应措施。
临时的无效是指Servlet在某一时间由于一个临时的问题而不能处理请求。例如，在另一个不同的应用层的服务（可能是数据库）无法使用。这个问题可能会自行纠正或者需要采取其他的纠正措施。
永久的无效是指除非管理员采取措施，这个Servlet将不能处理客户端的请求。例如，这个Servlet配置信息丢失或Servlet的状态被破坏。
Servlet引擎可以安全地处理包括永久无效在内的这两种异常，但是对临时无效的正常处理可以使得Servlet引擎更健壮。特别的，这时对Servlet的请求只是被阻止（或者是被延期）一段时间，这显然要比在service自己重新启动前完全拒绝请求更为科学。
构造函数
public UnavailableException(Servlet servlet, String message);
public UnavailableException(int seconds, Servlet servlet,
String message);
构造一个包含指定的描述信息的新的异常。如果这个构造函数有一个关于秒数的参数，这将给出Servlet发生临时无效后，能够重新处理请求的估计时间。如果不包含这个参数，这意味着这个Servlet永久无效。
方法
1、getServlet
public Servlet getServlet();
返回报告无效的Servlet。这被Servlet引擎用来识别受到影响的Servlet。
2、getUnavailableSeconds
public int getUnavailableSeconds();
返回Servlet预期的无效时间，如果这个Servlet是永久无效，返回-1。
3、isPermanent
public boolean isPermanent();
如果这个Servlet永久无效，返回布尔值true，指示必须采取一些管理行动以使得这个Servlet可用。