java 利用JAX-RS快速開發RESTful 服務

JAX-RS(Java API for RESTful Web Services)同樣也是JSR的一部分，詳細規範定義見 https://jcp.org/en/jsr/detail?id=311 。從JAVA EE 6開始，已經内置了該技術，跟.NET中的RESTful WCF類似，隻要在正常方法上使用一些簡單的注解，就可以對外暴露成RESTful 服務.

注：本文運作環境為Jboss EAP 6.x ，其它容器特别是tomcat，并未自帶JAX-RS依賴的jar包，如果采用tomcat，需要自己導入這些相關依賴jar包。

一、最基礎的HelloWorld (無參數)

java 利用JAX-RS快速開發RESTful 服務

1 @Path("/")
 2 public class MyService {
 3 
 4     final String XMLNS_NAMESPACE = "javascript:void(0)/rest/service";
 5     final String ROOT_NODE = "root";
 6 
 7     @GET
 8     @Path("/json/hello")
 9     @Produces(MediaType.APPLICATION_JSON)
10     public JAXBElement<String> getHelloWorldJSON() {
11         JAXBElement<String> result = new JAXBElement<String>(new QName("",
12                 ROOT_NODE), String.class, sayHelloWorld());
13         return result;
14     }
15 。。。
16 ｝

getHelloWorldJSON

java 利用JAX-RS快速開發RESTful 服務

1     private String sayHelloWorld() {
2         return "Hello JAX-RS!";
3     }

sayHelloWorld

解釋:

@GET 表示該服務可以直接在浏覽器位址欄裡通路(對應HTTP請求中的GET方法)

@Path 這裡用了二次，第一次是在Class上，相當服務的基位址；第二次是在方法上，表示具體某個服務方法的URL.

此外web.xml中，還需要增加以下内容：

java 利用JAX-RS快速開發RESTful 服務

1     <servlet-mapping>
2         <servlet-name>javax.ws.rs.core.Application</servlet-name>
3         <url-pattern>/rest/*</url-pattern>
4     </servlet-mapping>

web.xml

@Produces 表示傳回消息的格式，配合MediaType.APPLICATION_JSON說明，本方法傳回Json字元串格式

以上幾項綜合起來，最終可以用類似 http://localhost:8080/jboss-as-helloworld-rs/rest/json/hello 的位址來通路，傳回的結果為：

JAXBElement<T> 類似一個包裝器(Wrapper)，用于将傳回對象做下json/xml格式的包裝，比如上圖中的{root:}就是它的功勞，感興趣的朋友，可以把傳回類似改成最原始的String對比下差異.

如果需要傳回XML格式，隻需要把@Produces後面的MediaType.APPLICATION_JSON換成MediaType.APPLICATION_XML就行了，即：

java 利用JAX-RS快速開發RESTful 服務

1     @GET
2     @Path("/xml/hello")
3     @Produces(MediaType.APPLICATION_XML)
4     public JAXBElement<String> getHelloWorldXML() {
5         JAXBElement<String> result = new JAXBElement<String>(new QName(
6                 XMLNS_NAMESPACE, ROOT_NODE), String.class, sayHelloWorld());
7         return result;
8     }

getHelloWorldXML

效果如下：

二、帶一個基本類型參數的HelloWorld

java 利用JAX-RS快速開發RESTful 服務

1     @GET
 2     @Path("/json/hi/{name}")
 3     @Produces(MediaType.APPLICATION_JSON)
 4     public JAXBElement<String> getHelloToNameJSON(@PathParam("name") String name) {
 5         JAXBElement<String> result = new JAXBElement<String>(new QName("",
 6                 ROOT_NODE), String.class, sayHelloToName(name));
 7         return result;
 8     }
 9 
10     @GET
11     @Path("/xml/hi/{name}")
12     @Produces(MediaType.APPLICATION_XML)
13     public JAXBElement<String> getHelloToNameXML(@PathParam("name") String name) {
14         JAXBElement<String> result = new JAXBElement<String>(new QName(
15                 XMLNS_NAMESPACE, ROOT_NODE), String.class, sayHelloToName(name));
16         return result;
17     }

getHelloToNameJSON & getHelloToNameXML

java 利用JAX-RS快速開發RESTful 服務

1     private String sayHelloToName(String name) {
2         return "Hello " + name + ",welcome to the world of JAX-RS!";
3     }

sayHelloToName

對比一下剛才的代碼，有二個變化：

2.1 @Path上多了一個{name}的部分，表示url中，将允許以 /json/hi/xxx 的通路URL響應請求

2.2 方法參數前有一個 @PathParam("name") 的注解，表示如果按/json/hi/xxx的方式通路，則url中xxx的部分，會被映射到name這個參數上(說得更通俗點，就是通過解析url最後的xxx部分直接把name傳進來)

運作效果如下:

三、傳回結果為實體Bean

實際應用中，web服務傳回的結果，除了基本類型，還有可能是實體Bean，先來定義一個User類

java 利用JAX-RS快速開發RESTful 服務

1 package yjmyzz.service.model;
 2 
 3 import javax.xml.bind.annotation.XmlAttribute;
 4 import javax.xml.bind.annotation.XmlElement;
 5 import javax.xml.bind.annotation.XmlRootElement;
 6  
 7 @XmlRootElement(name = "user")
 8 public class User {
 9  
10     String username;
11     String password;
12     int pin;
13  
14     @XmlElement
15     public String getUsername() {
16         return username;
17     }
18  
19     public void setUsername(String username) {
20         this.username = username;
21     }
22  
23     @XmlElement
24     public String getPassword() {
25         return password;
26     }
27  
28     public void setPassword(String password) {
29         this.password = password;
30     }
31  
32     @XmlAttribute
33     public int getPin() {
34         return pin;
35     }
36  
37     public void setPin(int pin) {
38         this.pin = pin;
39     }
40  
41 }

User

代碼中加的一堆@XML開頭的注解，是為了在傳輸過程中，如果需要以XML格式傳輸，這些注解可以幫助完成 XML <-> Obj的轉換（詳情可參見JAXB相關内容）

java 利用JAX-RS快速開發RESTful 服務

1     @GET
 2     @Path("/xml/user")
 3     @Produces(MediaType.APPLICATION_XML)
 4     public User getUserInXML() {
 5         return getUser("unknown");
 6     }
 7 
 8     @GET
 9     @Path("/json/user")
10     @Produces(MediaType.APPLICATION_JSON)
11     public User getUserInJSON() {
12         return getUser("unknown");
13     }

getUserInXML & getUserInJSON

注意：這裡我們沒有使用JAXBElement<T>對結果進行包裝，輔助方法getUser()代碼如下

java 利用JAX-RS快速開發RESTful 服務

1     private User getUser(String username) {
2         User user = new User();
3         user.setUsername(username);
4         String pwd = new Long(Math.round(Math.random() * 100000)).toString();
5         user.setPassword(pwd);
6         int pin = (int) (Math.random() * 1000);
7         user.setPin(pin);
8         return user;
9     }

getUser

運作結果如下：

當然，也可以給方法增加參數，先從最基本類型的String參數耍起：

java 利用JAX-RS快速開發RESTful 服務

1     @GET
 2     @Path("/xml/userByName/{name}")
 3     @Produces(MediaType.APPLICATION_XML)
 4     public User getUserInXML(@PathParam("name") String username) {
 5         return getUser(username);
 6     }
 7 
 8     @GET
 9     @Path("/json/userByName/{name}")
10     @Produces(MediaType.APPLICATION_JSON)
11     public User getUserInJSON(@PathParam("name") String username) {
12         return getUser(username);
13     }

getUserWithStringParameter

如果加上包裝器JAXBElement<User>後，傳回結果會變成什麼樣呢？我也很好奇，so, 嘿-喂狗！

java 利用JAX-RS快速開發RESTful 服務

1     @GET
 2     @Path("/xml/userByName2/{name}")
 3     @Produces(MediaType.APPLICATION_XML)
 4     public JAXBElement<User> getUserInXML2(@PathParam("name") String username) {
 5         JAXBElement<User> result = new JAXBElement<User>(new QName(
 6                 XMLNS_NAMESPACE, ROOT_NODE), User.class, getUser(username));
 7         return result;
 8     }
 9 
10     @GET
11     @Path("/json/userByName2/{name}")
12     @Produces(MediaType.APPLICATION_JSON)
13     public JAXBElement<User> getUserInJSON2(@PathParam("name") String username) {
14         JAXBElement<User> result = new JAXBElement<User>(new QName("",
15                 ROOT_NODE), User.class, getUser(username));
16         return result;
17     }

getUserWithWrapper

結果如下：

個中差異，請自行體會

四、單個String參數的實體Bean注入

web服務中方法的傳入參數，不可能都是基礎類型，同樣也可以是實體Bean

java 利用JAX-RS快速開發RESTful 服務

1     @GET
 2     @Path("/xml/product/{name}")
 3     @Produces(MediaType.APPLICATION_XML)
 4     public Product getProductXML(@PathParam("name") Product product) {
 5         return getProductFromServer(product);
 6     }
 7 
 8     @GET
 9     @Path("/xml/product2/{name}")
10     @Produces(MediaType.APPLICATION_XML)
11     public JAXBElement<Product> getProductXML2(
12             @PathParam("name") Product product) {
13         JAXBElement<Product> result = new JAXBElement<Product>(new QName(
14                 XMLNS_NAMESPACE, ROOT_NODE), Product.class,
15                 getProductFromServer(product));
16         return result;
17     }

getProductXML & getProductXML2

這裡我們用到了一個新的Bean ：Product類，代碼如下：

java 利用JAX-RS快速開發RESTful 服務

1 package yjmyzz.service.model;
 2 
 3 import javax.xml.bind.annotation.XmlElement;
 4 import javax.xml.bind.annotation.XmlRootElement;
 5 
 6 @XmlRootElement(name = "product")
 7 public class Product {
 8 
 9     public Product() {
10         System.out.println("construct: Product() is called!");
11     }
12     
13     public Product(String name) {
14         System.out.println("construct: Product(String name) is called!");
15         this.productName = name;
16     }
17 
18     @XmlElement
19     public String getProductName() {
20         return productName;
21     }
22 
23     public void setProductName(String productName) {
24         this.productName = productName;
25     }
26 
27     private String productName;
28 
29 }

Product Bean

先提個問題：從@Path上看，我們希望用類似 /xml/product/xxx 來請求該web方法，但是方法中的參數是一個Bean執行個體，而url中的xxx部分隻是一個字元串，一個字元串如何被映射成一個Bean執行個體呢？

關鍵在于Product中的構造函數：Product(String name) ，方法getProductXML(@PathParam("name") Product product) 被請求時，url中的xxx部分會先映射成參數name，然後name又會被傳入到構造函數Product(String name)中，于是一個嶄新的Product對象誕生了！(可以通過eclipse Console的輸出來印證Product(String name)是否被調用)

運作結果：

eclipse的控制台裡，也可以看到構造器，确實被調用了

除了利用“帶參數的構造器”來實作“url參數->Bean執行個體”的注入，JAX-RS機制還允許使用Bean自身提供的static valueOf()方法來實作注入，再來看一下示例：

從Product派生一個子類Book：

java 利用JAX-RS快速開發RESTful 服務

1 package yjmyzz.service.model;
 2 
 3 import java.util.Calendar;
 4 import java.util.Date;
 5 
 6 import javax.xml.bind.annotation.XmlElement;
 7 import javax.xml.bind.annotation.XmlRootElement;
 8 
 9 @XmlRootElement(name = "book")
10 public class Book extends Product {
11 
12     private String isbn;
13 
14     private String author;
15 
16     private Date publishDate;
17 
18     public Book() {
19         System.out.println("construct: Book() is called!");
20     }
21 
22     public static Book valueOf(String isbn) {
23         System.out.println("Book: valueOf(String isbn) is called!");
24 
25         Book book = new Book();
26         book.setISBN(isbn);
27         book.setProductName("Java程式設計思想（第4版）");
28 
29         book.setAuthor("[美]埃克爾");
30 
31         Calendar calendar = Calendar.getInstance();
32         calendar.set(2007, 6, 1);
33         book.setPublishDate(calendar.getTime());
34         return book;
35     }
36 
37     @XmlElement
38     public String getISBN() {
39         return isbn;
40     }
41 
42     public void setISBN(String isbn) {
43         this.isbn = isbn;
44     }
45 
46     @XmlElement
47     public String getAuthor() {
48         return author;
49     }
50 
51     public void setAuthor(String author) {
52         this.author = author;
53     }
54 
55     @XmlElement
56     public Date getPublishDate() {
57         return publishDate;
58     }
59 
60     public void setPublishDate(Date publishDate) {
61         this.publishDate = publishDate;
62     }
63 
64 }

Book

再定義一個新方法：

java 利用JAX-RS快速開發RESTful 服務

1     @GET
2     @Path("/xml/book/{ISBN}")
3     @Produces(MediaType.APPLICATION_XML)
4     public Book getBookXML(@PathParam("ISBN") Book book) {
5         return getBookFromServer(book);
6     }

getBookXML

裡面有一個輔助方法，代碼如下：

java 利用JAX-RS快速開發RESTful 服務

1     private Book getBookFromServer(Book book) {
2         book.setProductName(book.getProductName() + " from server!");
3         return book;
4     }

getBookFromServer

eclipse的控制台資訊如下：

五、POST方式的Bean執行個體參數注入

前面提到的都是GET方式的web服務方法，GET方式能傳輸的資料大小有限，對于較大的參數資料，直接POST的場景更常見，下面是一個示例：

java 利用JAX-RS快速開發RESTful 服務

1     @POST
 2     @Path("/json/add-book")
 3     @Produces(MediaType.APPLICATION_JSON)
 4     @Consumes(MediaType.APPLICATION_JSON)
 5     public Book addBookJSON(Book book) {
 6         return getBookFromServer(book);
 7     }
 8     
 9     
10     @POST
11     @Path("/xml/add-book")
12     @Produces(MediaType.APPLICATION_XML)
13     @Consumes(MediaType.APPLICATION_XML)
14     public Book addBookXML(Book book) {
15         return getBookFromServer(book);
16     }

add-book

解釋一下：

又遇到了一個新的注解：@Consumes(MediaType.APPLICATION_JSON) 它表示傳入的Book執行個體是json格式。

我們用jQuery以Ajax方式調用這個服務示範一下：

java 利用JAX-RS快速開發RESTful 服務

1         function testJsonAddBook(){
 2             $(document).ready(function(){
 3                 $.ajax({
 4                     type:"POST",
 5                     url:"rest/json/add-book",
 6                     dataType: "json",
 7                     contentType: 'application/json',
 8                     data:JSON.stringify({"productName":"Java程式設計思想（第4版）","isbn":"9787111213826","author":"[美]埃克爾","publishDate":1183270161125}),
 9                     success: function(data, textStatus, jqXHR){
10                         alert("以下是從伺服器傳回的Book對象:\n\n" + JSON.stringify(data));
11                     },
12                     error: function(jqXHR, textStatus, errorThrown){
13                         alert('error: ' + textStatus);
14                     }
15                 });
16             })
17         }
18 
19 
20         function testXmlAddBook(){
21             $(document).ready(function(){
22                 $.ajax({
23                     type:"POST",
24                     url:"rest/xml/add-book",
25                     dataType: "xml",
26                     contentType: 'application/xml',
27                     data:"<book><productName>Java程式設計思想（第4版） from server!</productName><author>[美]埃克爾</author><ISBN>9787111213826</ISBN><publishDate>2007-07-01T13:33:30.782+08:00</publishDate></book>",
28                     success: function(data, textStatus, jqXHR){
29                         alert("以下是從伺服器傳回的Book對象:\n\n" + data.documentElement.outerHTML);
30                     },
31                     error: function(jqXHR, textStatus, errorThrown){
32                         alert('error: ' + textStatus);
33                     }
34                 });
35             })
36         }

testJsonAddBook & testXmlAddBook

運作效果如下：

如果斷點調試ajax，可以看到傳過來的json串已經映射成Bean執行個體了

作者：菩提樹下的楊過

java 利用JAX-RS快速開發RESTful 服務

繼續閱讀

關于Gradle配置的小結

Java小案例——随機數猜測随機數猜測

nginx location中斜線的位置的重要性

27 Best Free Eclipse Plug-ins for Java Developer to be ProductiveCode Quality PluginsText Editor PluginsDependency ManagementVersion Control Integration PluginsFramework Development Continuous Integration Related PluginsOther Utility Plugins

Java String.format方法的簡單使用

neo4j之cypher使用文檔

GitHub連夜封殺！這份阿裡 10W 字内部 Java 字面試手冊到底有多強？

spark/scala關于【資源檔案】加載方法概述外部檔案加載方案測試資源檔案打包入jar包中小結

mybatis_入門程式Mybatis入門

AOP程式設計_Android優雅權限架構(1)概念基礎，2021金三銀四前言正文大綱正文

Effective Java 8:通用程式設計

OOM三種類型

工廠模式-三種類型

【遞歸】高效率求2的n次幂

win10本地scala和spark安裝安裝scala安裝spark

scala (3) Function 和 Method