Java Servlet API中文说明文档(四)

　　public void log(String msg);

　　public void log(String msg, Throwable t);

　　public void log(Exception exception, String msg); // 这种用法将被取消

　　写指定的信息到一个Servlet环境对象的log文件中。被写入的log文件由Servlet引擎指定，但是通常这是一个事件log。当这个方法被一个异常调用时，log中将包括堆栈跟踪。

　　13、setAttribute

　　public void setAttribute(String name, Object o);

　　给予Servlet环境对象中你所指定的对象一个名称。

　　14、removeAttribute

　　public void removeAttribute(String name);

　　从指定的Servlet环境对象中删除一个属性。

　　注：以下几个方法将被取消

　　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接口

　　定义

　　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）使用。

　　注：以下方法将被取消

　　getRealPath

　　public String getRealPath(String path);

　　返回与虚拟路径相对应的真实路径，如果因为某种原因，这一过程不能进行，该方法将返回一个空值。

　　这个方法和ServletContext接口中的getRealPath方法重复。在2.1版中，ServletContext接口将阐明一个 Servlet所能用的所有的路径的映射。该方法执行的结果将会与ServletContext中getRealPath方法的结果完全一样。

　　六、ServletResponse接口

　　定义

　　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);

　　设置响应的内容的长度，这个方法会覆盖以前对内容长度的设定。

　　为了保证成功地设定响应头的内容长度，在响应被提交到输出流之前必须调用这个方法。