02. Servlet 主要API介绍

Servlet 主要API介绍

• Servlet API 主要由2个Java包构成：javax.servlet 、java.servlet.http；
  
• javax.servlet 包定义了与 Servlet 接口相关的通用接口和类；
  
• java.servlet.http 包主要定义了与HTTP协议相关的 HttpServlet类、HttpServletRequest类、HttpServletResponse类；
  

 

Servlet 接口

Servlet API 的核心为 javax.servlet.Servlet 接口，所有Servlet类必须实现该接口；

其中定义的接口方法如下：

void init(ServletConfig config)	负责初始化Servlet对象，容器在创建Servlet对象后，会调用该方法
void service(ServletRequest req, ServletResponse res)	负责响应客户的请求，为客户提供相应服务
void destroy()	负责释放 Servlet 对象占用的资源，但Servlet对象结束生命周期时，会调用该方法
ServletConfig getServletConfig()	返回 ServeltConfig 对象，包含Servlet的初始化信息
String getServletInfo()	返回包含Servlet创建者、版本信息等的字符串

Servlet API 中，javax.servlet.GenericServlet 抽象类 和 其子类 java.servlet.http.HttpServlet 实现了 Servlet 接口，用户开发自己的Servlet类时，一般如果没有特殊需求，可以选择直接通过继承这2个类来实现；

GenericServlet 抽象类

对于GenericServlet类的 init() 方法，如果希望当前 Servlet 类对象与 ServeltConfig 对象关联，在初始化方法中应调用 super.init(config)方法，如下：

public void init(ServletConfig config){
    super.init(config);
    ......
}

HttpServlet 抽象类

HttpServlet 是 GenericServlet 的子类，拓展了与http协议相关的方法，主要有如下：

doGet（HttpServletRequest req, HttpServletResponse res)	处理 GET 请求
doPost（HttpServletRequest req, HttpServletResponse res）	处理 POST 请求
doPut（HttpServletRequest req, HttpServletResponse res）	处理 PUT 请求（主要用于FTP）
doDelete（HttpServletRequest req, HttpServletResponse res）	处理 DELETE 请求（主要用于FTP）

HttpServlet 的在处理请求的过程中，会首先调用service()方法，service方法()在判断请求类型之后，根据请求类型调用相应的doGet，doPost，doPut，doDelete等方法，如果要维持以上的调用特性，在继承HttpServlet重写service()方法时，要首先调用super.service()方法，如下：

public void service(HttpServletRequest req,HttpServletResponse res){
    super.service(req,res);
    ......
}

ServletRequest 接口

ServletRequest 用于表示客户端的请求，提供了一系列用于读取客户端请求数据的方法，常用API如下；

请求范围与属性相关
setAttribute(String name,Object obj)	在请求范围保存一个属性
getAttribute(String name)	在请求范围内返回一个指定属性
removeAttribute(String name)	在请求范围内删除指定属性
请求报头相关
getContentLength()	返回请求正文长度，未知时返回-1
getContentType()	返回请求正文的MINE类型，未知时返回null
getParameter(String name)	返回指定请求参数的参数值
getLocalAddr()	返回服务器端的IP地址
getLocalName()	返回服务器端的主机名
getLocalPort()	返回服务器端的 FTP 端口号
getRemoteAddr()	返回客户端的IP地址
getRemoteHost()	返回客户端的主机名
getRemotePort()	返回客户端的 FTP 端口号
getProtocol()	返回客户端与服务端通信的协议名称和版本号
getInputStream()	返回用于读取请求正文的 InputStream 对象
getReader()	返回用于读取请求正文的 BufferedReader 对象

※ 关于请求范围的概念，详见 点击打开链接

HttpServletRequest 接口

HttpServletRequest 是 ServletRequest 的子接口，在 ServletRequest 提供的方法的基础上，提供了http相关的支持方法，主要API如下：

getContextPath()	返回客户端请求所访问的 Web 应用的 URL 入口，如客户端访问的 URL 为 http://localhost:8080/helloApp/welcome，该方法返回"/helloApp"
getCookies()	返回 HTTP 请求中的所有cookie，返回一个Cookie[] 数组
getHeader(String name)	返回 HTTP 头部中的特定项目
getHeaderNames()	返回一个包含 HTTP 头部所有信息的 Enumeration 对象
getMethod()	返回 HTTP 的请求方法（METHOD_GET,METHOD_POST等）
getRequestURL()	返回 HTTP 请求头部第1行中的URL
getQueryString()	返回 HTTP 请求中的查询字符串，即 URL 中"?"之后的内容

ServletReponse 接口

ServletReponse 用于生成响应结果，常用的API如下；

getCharacterEncoding()	获取响应正文的字符编码
getContentType()	获取相应正文的 MINE 类型
getBufereSize()	获取存放相应正文的缓冲区大小，单位byte
setCharacterEncoding(String charset)	设置响应正文的字符编码，charset值参照http://www.iana.org/assignments/character-sets，常用 “UTF-8”“GBK”“GB_2312-80”
setContentType(String type)	设置响应正文的 MINE 类型，如字符串"text/html;charset=UTF-8"
setBufereSize(int size)	设置存放相应正文缓冲区大小，单位byte
setContentLength(int len)	设置响应正文长度
reset()	清空缓冲区内的正文数据，同时清除相应码状态、响应头
resetBuffer()	清空缓冲区内的正文数据，不清除相应码状态、响应头
flushBuffer()	强制将缓冲区内的响应正文发送到客户端
isCommitted()	返回缓冲区内的数据是否提交给客户
getOutputStream()	获取传输二级制正文的 ServletOutputStream
getWriter()	获取传输字符串形式正文的 PrintWriter

一般一个 ServletReponse 响应客户端的过程如下：

• 设置响应正文的MIME类型或CharacterEncoding类型；
  
• 获取响应正文的 ServletOutputStream 或 PrintWriter 对象；
  
• 向ServletOutputStream 或 PrintWriter 对象写入数据；
  
• 当缓存区内的数据已满时，ServletOutputStream 或 PrintWriter 对象会自动将数据发送到客户端，并清空缓冲区；
  
• 当向流写入数据结束时，Servlet 容器调用 ServletReponse对象的 flushBuffer()方法，之后调用ServletOutputStream 或 PrintWriter的flush()或close() 方法；
  

简单示例

class DemoServlet extends GenericServlet{
    ...
    public service(ServletRequest request,ServletResponse reponse) throws ServletException, IOException{
        
        reponse.setContenttype("text/html;charset=UTF-8")
        PrintWriter out = reponse.getWriter();
        out.println("<html><title>test</title><body><p>hello world<p/></body><html>");
        //以下过程也可以省略
        out.flushBuffer();
        out.flush();
        out.close();
    }
    ...
}

HttpServletReponse 接口

HttpServletReponse 是 ServletReponse 的子接口，实现了与http相关的方法，常用的API如下：

addHeader(String name,String value)	向 HTTP 响应头添加一些内容
sendError(int sc,[String msg])	向客户端发送一个代表特定错误的HTTP响应状态代码和错误信息
setHeader(String ,String value)	修改 HTTP 相应头的内容
setStatus(int sc)	设置 HTTP 响应的状态码
addCookie(Cookie cookie)	向 HTTP 响应中加入一个Cookie

HttpServletReponse 中定义了一些 HTTP 响应状态码的静态常量

HttpServletReponse.SC_BAD_REQUEST	400
HttpServletReponse. SC_FOUND	302
HttpServletReponse. SC_METHOD_NOT_ALLOWED	405
HttpServletReponse. SC_NON_AUTHORITATIVE_INFORMATION	203
HttpServletReponse. SC_FORBIDDEN	403
HttpServletReponse. SC_NOT_FOUND	404
HttpServletReponse. SC_OK	200

ServletConfig 接口

ServletConfig 用于保存 Servlet 初始化信息，在 Servlet对象初始化方法 init(ServletConfig config)中使用；

getInitParameter(String name)	返回指定的配置参数
getInitParameterNames()	返回一个包含所有配置参数的 Enumeration 对象
getServletContext()	返回ServletContext对象
getServletName()	返回 Servlet 的名字，即web.xml中对应<servlet>的<servlet-name>元素

ServletContext 接口

• ServletContex是 Servlet 与 Servlet容器 之间进行通信的接口；
  
• Servlet容器在启动一个Web应用时，会为它创建一个ServletContext对象，同一个 Web应用的所有Servlet共享一个ServletContext；Servlet对象们通过它们的ServletContext访问容器中的各种资源；
  
• ServletContext对象可以在 GenericServlet , HttpServlet 中通过调用 getServletContext() 获取；
  

ServletContext提供的API方法可以分为以下几类：

用于在 Web 应用范围内存共享数据
setAttribute(String name,Object obj)	保存一个属性到 ServletContext
getAttribute(String name)	在 ServletContext 内返回一个指定属性
getAttributNames()	返回一个包含所有ServletContext中属性的Enumeration对象
removeAttribute(String name)	在 ServletContext 内删除指定属性
访问当前 Web 应用的资源
getContextPath()	返回当前 Web 应用的 URL 入口
getInitParameter(String name)	返回 Web 应用范围内的初始化配置参数
getInitParameterNames()	返回包含一个包含Web 应用范围内所有初始化配置参数的Enumeration对象
getServletContextName()	返回当前 Web 应用的名称，即 web.xml 文件中的<display-name>元素值
getRequestDispatcher(String name)	返回一个用于指向其他Web 组件转发请求的 RequestDispatcher 对象
访问 Servlet 容器中的其他 Web 应用
getContext(String urlpath)	根据指定的URL，返回当前 Servlet容器的其他Web应用的ServletContext对象； 给定的URL必须以"/"为开头，起始路径为服务器的根文档进行解释； 假如一个Servlet容器根目录中包含demoApp，helloApp 2个Web程序，从demoApp的一个Servlet访问helloApp中的ServletContext，该函数URL路径参数为“/helloApp”；
访问 Servlet 容器的相关信息
getMajorVersion()	返回 Servlet容器 支持的 Java Servlet API 的主版本号
getMinorVersion()	返回 Servlet容器 支持的 Java Servlet API 的次版本号
getServletInfo()	返回 Servlet容器 的名字和版本
访问服务器端的文件系统资源
getRealPath(String path)	根据指定的虚拟路径，返回文件系统的一个真实路径
getResource(String path)	返回一个映射到指定路径的URL
getResourceAsStream(String path)	返回一个用于读取参数指定文件的输入流（常用）
getMimeType(String file)	获取指定参数路径的文件的MIME类型
输出日志
log(String msg)	向 Servlet 的日志文件中写入日志
log(String message,java.lang.Throwable throwable)	向 Servlet 的日志文件中写入错误日志，和异常堆栈信息

RequestDispatcher 接口

• RequestDispatcher用于收来自客户端的请求并将它们发送到服务器上的任何资源（比如 servlet、HTML 文件或 JSP 文件）的对象 ，在整个Servlet模型中用于转发和包含，
  
• RequestDispatcher 对象可以由 ServletContext 的 getRequestDispatcher() 方法获取；
  

RequestDispatcher主要的API如下：

forward(ServletRequest request, ServletResponse response)	将请求从一个 servlet 转发到服务器上的另一个资源（servlet、JSP 文件或 HTML 文件）。此方法允许一个 servlet 对请求进行初步处理，并使另一个资源生成响应；
include(ServletRequest request, ServletResponse response)	包含响应中某个资源（servlet、JSP 页面和 HTML 文件）的内容。事实上，此方法支持编程式服务器端包含。

关于 RequestDispatcher转发和包含的用法详见：点击打开链接