REST是一種混合的架構風格，它的由來以及它的架構元素在筆者的前兩篇文《REST架構風格的由來》和《REST架構風格的架構元素》中已經描述了。本篇主要描述一下J2EE對REST的支援。
Java是在J2EE6中引入了對REST的支援，即JSR-311(JAX-RS 1.1: The JavaTM API for RESTful Web Services)，現在JAX-RS到2.0版本了，對應的是JSR-339，JSR是Java技術規範提案，由JCP組織進行管理。該規範使得使用Java進行開發的人員使用一套固定的介面來開發 REST 應用，避免了依賴於第三方框架。JAX-RS是一套介面，具體實現由第三方提供，例如 Sun 的參考實現 Jersey、Apache 的CXF 以及 JBoss 的 RESTEasy，下文會有對它們如何釋出rest服務的簡單介紹。
1.常用API介紹
1.1 javax.ws.rs包(用於建立RESTful服務資源的高階介面和註解)
1.1.1 統一介面
JAX-RS使用@javax.ws.rs.POST 、@javax.ws.rs.GET 、@javax.ws.rs.PUT、@javax.ws.rs.DELETE四個註解代表了對資源的CRUD(Create, Retrieve, Update, Delete)操作。
1.1.2 定位資源
注:下文中url中的root代表你的web應用的名稱加上你在web.xml中servlet-mapping元素設定的路徑。
@javax.ws.rs.ApplicationPath 標識應用路徑，用於由@Path提供的所有資源uri的基本uri。當釋出在一個servlet容器中，它的值可以使用web.xml中的servlet-mapping進行重寫。
@javax.ws.rs.Path 標識要請求的資源類或類方法的uri路徑。
@javax.ws.rs.PathParam 將uri中指定的路徑引數繫結到資源方法引數，資源類的欄位，或資源類的bean屬性。
比如：
|
1 2 3 4 5 6 7 8 9 |
@Path("/user") public class UserResource { @GET @Path("{userName}") @Produces(MediaType.APPLICATION_JSON) public User getUser(@PathParam("userName") String userName) { ... } } |
當瀏覽器請求http://localhost:8080/root/user/boglond時，方法中userName值為boglond。
@javax.ws.rs.QueryParam 將http請求的Query引數繫結到資源方法引數，資源類的欄位，或資源類的bean屬性。
eg:
|
1 2 3 4 5 6 7 8 9 |
@Path("/user") public class UserRecource { @GET @Path("/getUser") @Produces(MediaType.APPLICATION_JSON) public User getUser(@QueryParam("userName") String userName,@QueryParam("age") int age) { ... } } |
當瀏覽器請求http://localhost:8080/root/user/getUser?userName=boglond&age=26時，方法中userName值為boglond，age值為26。
@javax.ws.rs.FormParam 將http請求的Form表單中的引數繫結到資源方法引數。
eg:
|
1 2 3 4 5 6 7 8 9 |
@Path("/user") public class UserRecource { @javax.ws.rs.POST @Path("/insert") @Consumes(MediaType.APPLICATION_FORM_URLENCODED) public String insertUser(@FormParam("userName") String userName,@FormParam("age") int age){ ... } } |
頁面中的form表單如下
|
1 2 3 4 5 |
<form action="/root/user/insert" method="post"> 姓名:<input name="userName" id= "userName" type = "text" value="boglond"/></br> 年齡:<input name="age" id= "age" type = "text" value="26"/> <button type = "submit">提交</button> </form> |
提交表單後方法中userName值為boglond，age值為26。
@javax.ws.rs.CookieParam 將http cookie的值繫結到資源方法引數，資源類的欄位，或資源類的bean屬性。
eg:
|
1 2 3 4 5 6 7 8 9 |
@Path("/user") public class UserRecource { @GET @Path("/getCookieParam") @Produces(MediaType.APPLICATION_JSON) public String getCookieParam(@CookieParam("JSESSIONID") String jsessionId) { ... } } |
當瀏覽器請求http://localhost:8080/root/user/getCookieParam時，方法中jsessionId值為”FFF7BDDC46579DBDDDEB3E94776A2623″,此值不是固定的,不同的瀏覽器有不同的值。
@javax.ws.rs.HeaderParam 將http header的值繫結到資源方法引數，資源類的欄位，或資源類的bean屬性。
eg:
|
1 2 3 4 5 6 7 8 9 10 |
@Path("/user") public class UserRecource { @GET @Path("/getHeaderParam") @Produces(MediaType.APPLICATION_JSON) public String getHeaderParam(@HeaderParam("Accept") String accept,@HeaderParam("Accept-Language") String acceptLang) { ... } } |
當瀏覽器請求http://localhost:8080/root/user/getHeaderParam時，方法中accept值為”text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8″，acceptLang值為”zh-CN,zh;q=0.8,en-US;q=0.5,en;q=0.3″，不同的瀏覽器，值有所不同。
@javax.ws.rs.MatrixParam 將uri矩陣引數的值繫結到資源方法引數，資源類的欄位，或資源類的bean屬性。
eg:
|
1 2 3 4 5 6 7 8 9 |
@Path("/user") public class UserRecource { @GET @Path("/getUser") @Produces(MediaType.APPLICATION_JSON) public User getUser(@MatrixParam("userName") String userName,@MatrixParam("age") int age) { ... } } |
當瀏覽器請求http://localhost:8080/root/user/getUser;userName=boglond;age=26時，方法中userName值為boglond，age值為26。
@javax.ws.rs.DefaultValue 設定 @PathParam, @QueryParam, @MatrixParam, @CookieParam, @FormParam, or @HeaderParam引數的預設值。如果它們沒有接收到值，就使用預設值。
@javax.ws.rs.BeanParam 將請求中的bean繫結到資源方法引數，資源類的欄位，或資源類的bean屬性。
eg:
bean的配置:
|
1 2 3 4 5 6 7 8 |
@javax.xml.bind.annotation.XmlRootElement public class UserBean{ @FormParam("userName") private String userName; @FormParam("age") private int age; ... } |
資源類方法的配置:
|
1 2 3 4 5 6 7 8 9 |
@Path("/user") public class UserRecource { @javax.ws.rs.POST @Path("/insertUserBean") @Consumes(MediaType.APPLICATION_FORM_URLENCODED) public String insertUserBean(@BeanParam UserBean userBean){ ... } } |
頁面中的form表單如下:
|
1 2 3 4 5 |
<form action="/root/user/insertUserBean" method="post"> 姓名:<input name="userName" id= "userName" type = "text" value="boglond"/></br> 年齡:<input name="age" id= "age" type = "text" value="26"/> <button type = "submit">提交</button> </form> |
當提交表單後insertUserBean方法中的userBean物件的屬性值會對映為表單中對應的值。
1.1.3 表述資源的資料格式(通過媒體型別表述)
@javax.ws.rs.Consumes 定義一個資源類的方法或MessageBodyReader能夠接受的媒體型別。方法級別的@Consumes會覆蓋類級別的@Consumes。(指定將要返回給client端的資料MIME型別)
@javax.ws.rs.Produces 定義一個資源類的方法或MessageBodyWriter能夠產生的媒體型別。方法級別的@Produces會覆蓋類級別的@Produces。(指定可以接受client傳送過來的MIME型別)
eg:@Produces(“application/json”);指定多個MIME型別 @Produces({“application/json”,”application/xml”})
常見的媒體型別如
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
text/html ： HTML格式 text/plain ：純文字格式 text/xml ： XML格式(它會忽略xml頭所指定編碼格式而預設採用us-ascii編碼) image/gif ：gif圖片格式 image/jpeg ：jpg圖片格式 image/png：png圖片格式 application/xhtml+xml ：XHTML格式 application/xml ： XML格式(它會根據xml頭指定的編碼格式來編碼) application/atom+xml ：Atom XML聚合格式 application/json ： JSON資料格式 application/pdf ：pdf格式 application/msword ： Word文件格式 application/octet-stream ： 二進位制流資料（如常見的檔案下載） application/x-www-form-urlencoded ： <form encType=””>中預設的encType，form表單資料被編碼為key/value格式傳送到伺服器（表單預設的提交資料的格式） multipart/form-data ： 需要在表單中進行檔案上傳時，就需要使用該格式。 |
媒體型別的常量值在javax.ws.rs.core.MediaType中。
1.1.4 編解碼
@javax.ws.rs.Encoded 禁用由 @QueryParam, @PathParam, @FormParam or @MatrixParam繫結的引數值的自動解碼
eg:
|
1 2 3 4 5 6 7 8 9 10 |
@Path("/user") public class UserRecource { @GET @Path("/getUser") @Produces(MediaType.APPLICATION_JSON) public User getUser(@MatrixParam("userName") String userName, @MatrixParam("age") int age) { ... } } |
此時沒有使用@Encoded
當瀏覽器請求http://localhost:8080/root/user/getUser;userName=boglond%5CD;age=26時,方法中userName值為boglond\D，age值為26。
當給方法引數加上@Encoded時,
瀏覽器請求http://localhost:8080/root/user/getUser;userName=boglond%5CD;age=26,方法中userName值為boglond%5CD，age值為26。
@Encoded可加在方法的上面禁用此方法所有引數的自動解碼。
1.2 javax.ws.rs.client包(JAX-RS客戶端API)
javax.ws.rs.client.WebTarget 由資源URI標識的資源目標。
javax.ws.rs.client.ClientBuilder 用於載入客戶端例項的主入口點。
eg:使用 request() 函式來初始化一個請求並用後續的 post 或者get等方法來指定請求的型別。
|
1 2 |
Client client = ClientBuilder.newClient(); client.target(..).request().get(); |
通過 path() 和 resolveTemplate() 方法來處理動態的 URL 路徑引數。
|
1 2 3 4 |
client.target(..).path(..).resolveTemplate(..); javax.ws.rs.client.InvocationCallback<RESPONSE> 可以實現從呼叫處理接收非同步處理事件。 javax.ws.rs.client.ClientRequestFilter 客戶端請求過濾器。 javax.ws.rs.client.ClientResponseFilter 客戶端響應過濾器。 |
1.3 javax.ws.rs.container包(特定容器JAX-RS API )
@javax.ws.rs.container.ResourceContext 提供對資源類例項的訪問,使用@javax.ws.rs.core.Context 注入。
eg:
|
1 2 3 |
public String getResourceContext(@javax.ws.rs.core.Context ResourceContext resourceContext) { ... } |
@javax.ws.rs.container.ContainerRequestContext 容器請求過濾器上下文。為過濾器提供特定於請求的資訊的可變類，例如請求URI，訊息頭，訊息實體或請求範圍屬性。暴露的setter方法允許修改暴露的請求特定資訊。
@javax.ws.rs.container.ContainerResponseContext 容器響應過濾器上下文。為過濾器提供特定於響應的資訊的可變類，例如訊息頭，訊息實體或請求範圍屬性。暴露的setter方法允許修改暴露的響應特定資訊。
1.4 javax.ws.rs.core包(用於建立RESTful服務資源的低階介面和註解)
@javax.ws.rs.core.MediaType 媒體型別常量類。
j
avax.ws.rs.core.Cookie 在請求中轉移的HTTP Cookie的值。
eg:
|
1 2 |
Cookie c = new Cookie(name, value); javax.ws.rs.core.Form 表示使用"application / x-www-form-urlencoded"媒體型別編碼的HTML表單資料請求實體。 |
eg:
|
1 2 |
Form f = new Form(); f.param(name, value) |
javax.ws.rs.core.Response.Status http所定義的響應狀態碼。
javax.ws.rs.core.HttpHeaders 一個可注入的介面，提供對HTTP頭資訊的訪問。
eg:
|
1 2 3 4 5 6 |
@GET @Path("/getHttpHeaders") @Produces(MediaType.APPLICATION_JSON) public String getHttpHeaders(@javax.ws.rs.core.Context HttpHeaders httpHeaders) { ... } |
@javax.ws.rs.core.UriInfo 一個可注入的介面，提供對應用程式和請求URI資訊的訪問。
eg:
|
1 2 3 4 5 6 |
@GET @Path("/getUriInfo") @Produces(MediaType.APPLICATION_JSON) public String getUriInfo(@javax.ws.rs.core.Context UriInfo uriInfo) { ... } |
@javax.ws.rs.core.Context 將資訊注入類欄位，bean屬性或方法引數。如
1.5 javax.ws.rs.ext包(為JAX-RS API支援的型別提供擴充套件)
javax.ws.rs.ext.MessageBodyReader<T> 反序列化
javax.ws.rs.ext.MessageBodyWriter<T> 序列化
2.Jersey釋出rest服務簡介
Jersey專案使用apache Maven構建，它的相關模組都可從Maven中央倉庫獲取。本專案是基於JAX-RS 2.0的。
2.1 建立一個maven工程
如圖
2.2 在pom中新增依賴
|
1 2 3 4 5 6 7 8 9 10 11 |
<dependency> <groupId>javax.ws.rs</groupId> <artifactId>javax.ws.rs-api</artifactId> <version>2.0.1</version> </dependency> <dependency> <groupId>org.glassfish.jersey.containers</groupId> <!-- if your container implements Servlet API older than 3.0, use "jersey-container-servlet-core" --> <artifactId>jersey-container-servlet</artifactId> <version>2.25</version> </dependency> |
2.3 配置web.xml
在web.xml中新增
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
<servlet> <servlet-name>jersey-demo</servlet-name> <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class> <init-param> <param-name>jersey.config.server.provider.packages</param-name> <!-- 這個包路徑換成你的包路徑,多個包路徑可以使用逗號分隔--> <param-value>com.boglond.jersey</param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>jersey-demo</servlet-name> <!-- 這個設定為你想要的路徑--> <url-pattern>/resources/*</url-pattern> </servlet-mapping> |
2.4 建立資源類
|
1 2 3 4 5 6 7 8 9 10 |
@Path("/user") public class UserRecource { @GET @Path("/getUser") @Produces(MediaType.APPLICATION_JSON) public User getUser(@QueryParam("userName") String userName, @QueryParam("age") int age) { ... } } |
訪問:在瀏覽器裡輸入http://localhost:8080/jersey-demo/resources/user/getUser?userName=boglond&age=30即可訪問。
3.CXF釋出rest服務簡介
3.1 建立一個maven工程
如圖
3.2 在pom中新增依賴
CXF的依賴
|
1 2 3 4 5 6 7 8 9 10 |
<dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-frontend-jaxrs</artifactId> <version>3.0.0</version> </dependency> <dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-transports-http-jetty</artifactId> <version>3.0.0</version> </dependency> |
日誌的依賴
|
1 2 3 4 5 6 7 8 9 10 |
<dependency> <groupId>log4j</groupId> <artifactId>log4j</artifactId> <version>1.2.17</version> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-log4j12</artifactId> <version>1.7.6</version> </dependency> |
3.3 建立資源類
|
1 2 3 4 5 6 7 8 9 10 |
@Path("/user") public class UserRecource { @GET @Path("/getUser") @Produces(MediaType.APPLICATION_JSON) public User getUser(@QueryParam("userName") String userName, @QueryParam("age") int age) { ... } } |
3.4 釋出REST服務
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
package com.boglond.cxf; import java.util.ArrayList; import java.util.List; import org.apache.cxf.jaxrs.JAXRSServerFactoryBean; import org.apache.cxf.jaxrs.lifecycle.ResourceProvider; import org.apache.cxf.jaxrs.lifecycle.SingletonResourceProvider; import org.slf4j.Logger; import org.slf4j.LoggerFactory; public class CxfServer { private final static Logger logger = LoggerFactory.getLogger(CxfServer.class); public static void main(String[] args) { List<Class<?>> resourceClassList = new ArrayList<Class<?>>(); resourceClassList.add(UserRecource.class); List<ResourceProvider> resourceProviderList = new ArrayList<ResourceProvider>(); resourceProviderList.add(new SingletonResourceProvider(new UserRecource())); // 釋出 REST 服務 JAXRSServerFactoryBean factory = new JAXRSServerFactoryBean(); factory.setAddress("http://localhost:11002/cxf-demo/recources"); factory.setResourceClasses(resourceClassList); factory.setResourceProviders(resourceProviderList); factory.create(); logger.info("使用CXF釋出REST服務成功"); } } |
訪問:在瀏覽器裡輸入http://localhost:8080/cxf-demo/recources/user/getUser?userName=boglond&age=26即可訪問。
4.RESTEasy釋出rest服務簡介
4.1 建立一個maven工程
如圖
4.2 在pom中新增依賴
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
<dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-jaxrs</artifactId> <version>3.1.0.Final</version> </dependency> <dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-jaxb-provider</artifactId> <version>3.1.0.Final</version> </dependency> 如果servlet容器使用的是servlet3.0 需要加入如下依賴 <dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-servlet-initializer</artifactId> <version>3.1.0.Final</version> </dependency> |
注:如果你配置的maven倉庫地址下載不下來resteasy依賴的jar,就將你的maven conf資料夾下的setting.xml 中的倉庫url替換為下面的url。<url>http://repository.jboss.org/nexus/content/groups/public/</url>
4.3 配置web.xml
在web.xml中新增
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
<context-param> <param-name>resteasy.resources</param-name> <!-- 這是你的資源類 --> <param-value>com.boglond.resteasy.UserRecource</param-value> </context-param> <listener> <listener-class> org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap </listener-class> </listener> <servlet> <servlet-name>Resteasy</servlet-name> <servlet-class> org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher </servlet-class> </servlet> <servlet-mapping> <servlet-name>Resteasy</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> |
4.4 建立資源類
|
1 2 3 4 5 6 7 8 9 10 |
@Path("/user") public class UserRecource { @GET @Path("/getUser") @Produces(MediaType.APPLICATION_JSON) public User getUser(@QueryParam("userName") String userName, @QueryParam("age") int age) { ... } } |
訪問:在瀏覽器裡輸入http://localhost:8080/resteasy-demo/user/getUser?userName=boglond&age=30即可訪問。
打賞支援我寫出更多好文章，謝謝！
打賞作者
打賞支援我寫出更多好文章，謝謝！
任選一種支付方式
