JAX-RS入門 一 ：基礎

lvzhou_MadSky發表於2014-04-22

簡介

JAX-RS是一套用java實現REST服務的規範，提供了一些標註將一個資源類，一個POJOJava類，封裝為Web資源。標註包括：

  • @Path，標註資源類或方法的相對路徑
  • @GET，@PUT，@POST，@DELETE，標註方法是用的HTTP請求的型別
  • @Produces，標註返回的MIME媒體型別
  • @Consumes，標註可接受請求的MIME媒體型別
  • @PathParam，@QueryParam，@HeaderParam，@CookieParam，@MatrixParam，@FormParam, 分別標註方法的引數來自於HTTP請求的不同位置，例如@PathParam來自於URL的路徑，@QueryParam來自於URL的查詢參 數，@HeaderParam來自於HTTP請求的頭資訊，@CookieParam來自於HTTP請求的Cookie。

目前JAX-RS的實現包括：

（以上來自：http://zh.wikipedia.org/wiki/JAX-RS）

 

裝備

本文使用的工具有：

  • Eclipse-jee-helios
  • Java-1.6.0_26
  • apache-tomcat-6.0.30
  • SoapUI-3.6

使用到的外部jar包有（必須的部分，需要加到Web容器中）

  • neethi-3.0.2.jar
  • jsr311-api-1.1.1.jar
  • cxf-bundle-2.6.0.jar

使用到的外部jar包有（可選的部分，當且僅當作為一個獨立的application執行時）

  • jetty-http-7.5.4.v20111024.jar
  • jetty-io-7.5.4.v20111024.jar
  • jetty-server-7.5.4.v20111024.jar
  • jetty-util-7.5.4.v20111024.jar
  • jetty-continuation-7.5.4.v20111024.jar
  • wsdl4j-1.6.2.jar

 準備

 （以下例子來自： Oreilly - RESTful Java with JAX-RS (12-2009) (ATTiCA).pdf）

 

建立工程

為了後續順利進行，首先在eclipse上先建立一個Dynamic Web Project，完成以後，一個符合war結構的工程目錄會自動生成，之後可以很簡單的匯出為war檔案，其中需要把以下jar包放到 /WebContent/WEB-INF/lib 裡：

  • neethi-3.0.2.jar
  • jsr311-api-1.1.1.jar
  • cxf-bundle-2.6.0.jar 

另外，在工程目錄下，新建一個 lib 資料夾用來存放以下可選的jar包：

 

  • jetty-http-7.5.4.v20111024.jar
  • jetty-io-7.5.4.v20111024.jar
  • jetty-server-7.5.4.v20111024.jar
  • jetty-util-7.5.4.v20111024.jar
  • jetty-continuation-7.5.4.v20111024.jar
  • wsdl4j-1.6.2.jar

最後一步就是把所有這9個jar都加到工程的build path裡去，這樣工程就準備好了。

 

定義服務

這裡要實現一個簡單的REST服務用於對客戶進行管理，包括：

  • 建立客戶
  • 檢視客戶
  • 更新客戶

首先給出對應的於這些操作的服務介面：

Java程式碼  收藏程式碼
  1. import java.io.InputStream;  
  2.   
  3. import javax.ws.rs.Consumes;  
  4. import javax.ws.rs.GET;  
  5. import javax.ws.rs.POST;  
  6. import javax.ws.rs.PUT;  
  7. import javax.ws.rs.Path;  
  8. import javax.ws.rs.PathParam;  
  9. import javax.ws.rs.Produces;  
  10. import javax.ws.rs.core.Response;  
  11. import javax.ws.rs.core.StreamingOutput;  
  12.   
  13. @Path("/customers")  
  14. public interface CustomerResource {  
  15.   
  16.     @POST  
  17.     @Consumes("application/xml")  
  18.     public Response createCustomer(InputStream is);  
  19.   
  20.     @GET  
  21.     @Path("{id}")  
  22.     @Produces("application/xml")  
  23.     public StreamingOutput getCustomer(@PathParam("id") int id);  
  24.   
  25.     @PUT  
  26.     @Path("{id}")  
  27.     @Consumes("application/xml")  
  28.     public void updateCustomer(@PathParam("id") int id, InputStream is) ;  
  29. }  

 

 令人驚奇的是，這個介面已經包含了所有實現我們既定目標的關鍵部分：

  1. @Path: 定義服務路徑，介面中定義的整個服務的頂級路徑為"/customers "，方法對應的服務路徑為介面路徑加方法定義的Path值，如果未定義，則用介面路徑，例如getCustomer()的服務路徑為：" /customers/{id} "。所以此REST對外服務路徑都是 服務的上下文路徑/customers/ 子級目錄，
  2. @POST，@GET，@PUT：標註方法所支援HTTP請求的型別 （參考上面的說明）
  3. @Produces，@Consumes：標註方法支援或返回的請求MIME型別。

由上可以看到，每個方法被呼叫的條件如下：

  1. createConsumer()： 請求HTTP方法為POST；請求MIME型別為application/xml；請求路徑為： 上下文路徑/customers
  2. getCustomer()： 請求的HTTP方法為GET；請求的MIME型別為application/xml；請求的路徑為： 上下文路徑/customers/{id}
    注： {id}為某個存在（或不存在）customer的編號
  3. updateCustomer()： 請求的HTTP方法為PUT；請求的MIME型別為application/xml；請求的路徑： 上下文路徑/customers/{id}
    注： {id}為某個存在（或不存在）customer的編號

一個好的實現方法是將REST服務的定義和實現分開，這樣程式碼的結構簡潔、清晰，在後期也可以很方便的進行實現的替換和服務定義的修改。

 

下面就是新增實現部分：

Java程式碼  收藏程式碼
  1. public class CustomerResourceService implements CustomerResource{  
  2.     private Map<Integer, Customer> customerDB = new ConcurrentHashMap<Integer, Customer>();  
  3.     private AtomicInteger idCounter = new AtomicInteger();  
  4.   
  5.     public Response createCustomer(InputStream is) {  
  6.         Customer customer = readCustomer(is);  
  7.         customer.setId(idCounter.incrementAndGet());  
  8.         customerDB.put(customer.getId(), customer);  
  9.         System.out.println("Created customer " + customer.getId());  
  10.         return Response.created(URI.create("/customers/" + customer.getId()))  
  11.                 .build();  
  12.     }  
  13.   
  14.     public StreamingOutput getCustomer(int id) {  
  15.         final Customer customer = customerDB.get(id);  
  16.         if (customer == null) {  
  17.             throw new WebApplicationException(Response.Status.NOT_FOUND);  
  18.         }  
  19.         return new StreamingOutput() {  
  20.             public void write(OutputStream outputStream) throws IOException,  
  21.                     WebApplicationException {  
  22.                 outputCustomer(outputStream, customer);  
  23.             }  
  24.         };  
  25.     }  
  26.   
  27.     public void updateCustomer(int id, InputStream is) {  
  28.         Customer update = readCustomer(is);  
  29.         Customer current = customerDB.get(id);  
  30.         if (current == null)  
  31.             throw new WebApplicationException(Response.Status.NOT_FOUND);  
  32.         current.setFirstName(update.getFirstName());  
  33.         current.setLastName(update.getLastName());  
  34.         current.setStreet(update.getStreet());  
  35.         current.setState(update.getState());  
  36.         current.setZip(update.getZip());  
  37.         current.setCountry(update.getCountry());  
  38.     }  
  39.   
  40.     protected void outputCustomer(OutputStream os, Customer cust)  
  41.             throws IOException {  
  42.         PrintStream writer = new PrintStream(os);  
  43.         writer.println("<customer id=\"" + cust.getId() + "\">");  
  44.         writer.println(" <first-name>" + cust.getFirstName() + "</first-name>");  
  45.         writer.println(" <last-name>" + cust.getLastName() + "</last-name>");  
  46.         writer.println(" <street>" + cust.getStreet() + "</street>");  
  47.         writer.println(" <city>" + cust.getCity() + "</city>");  
  48.         writer.println(" <state>" + cust.getState() + "</state>");  
  49.         writer.println(" <zip>" + cust.getZip() + "</zip>");  
  50.         writer.println(" <country>" + cust.getCountry() + "</country>");  
  51.         writer.println("</customer>");  
  52.     }  
  53.   
  54.     protected Customer readCustomer(InputStream is) {  
  55.         try {  
  56.             DocumentBuilder builder = DocumentBuilderFactory.newInstance()  
  57.                     .newDocumentBuilder();  
  58.             Document doc = builder.parse(is);  
  59.             Element root = doc.getDocumentElement();  
  60.             Customer cust = new Customer();  
  61.             if (root.getAttribute("id") != null  
  62.                     && !root.getAttribute("id").trim().equals("")) {  
  63.                 cust.setId(Integer.valueOf(root.getAttribute("id")));  
  64.             }  
  65.             NodeList nodes = root.getChildNodes();  
  66.             for (int i = 0; i < nodes.getLength(); i++) {  
  67.                 Node item = nodes.item(i);  
  68.                 if(!(item instanceof Element)){  
  69.                     continue;  
  70.                 }  
  71.                 Element element = (Element) nodes.item(i);  
  72.                 if (element.getTagName().equals("first-name")) {  
  73.                     cust.setFirstName(element.getTextContent());  
  74.                 } else if (element.getTagName().equals("last-name")) {  
  75.                     cust.setLastName(element.getTextContent());  
  76.                 } else if (element.getTagName().equals("street")) {  
  77.                     cust.setStreet(element.getTextContent());  
  78.                 } else if (element.getTagName().equals("city")) {  
  79.                     cust.setCity(element.getTextContent());  
  80.                 } else if (element.getTagName().equals("state")) {  
  81.                     cust.setState(element.getTextContent());  
  82.                 } else if (element.getTagName().equals("zip")) {  
  83.                     cust.setZip(element.getTextContent());  
  84.                 } else if (element.getTagName().equals("country")) {  
  85.                     cust.setCountry(element.getTextContent());  
  86.                 }  
  87.             }  
  88.             return cust;  
  89.         } catch (Exception e) {  
  90.             throw new WebApplicationException(e, Response.Status.BAD_REQUEST);  
  91.         }  
  92.     }  
  93. }  

 

這些方法的實現都很直接，不細說，不過有一點需要特別注意的是：

 

最好不要在實現中混雜有服務的定義部分，例如@Path標籤，@PathParam標籤等等，如果想修改定義，最好是在介面中修改；或者如果想覆蓋某個介面方法的某個annotation，則所有該介面方法的annotation定義都需要重寫，而不能僅修改變化的。

相關文章