NetBeans IDE - REST風格的Web服務入門指南

代表性狀態傳輸 (REpresentational State Transfer, REST) 是一種用於分布式超媒體系統（如萬維 網）的體系結構樣式。REST 風格的體系結構的核心概念是由統一資源標識符 (Uniform Resource Identifier, URI) 標識的資源。可以使用標准接口（如 HTTP）來處理這些資源以及使用這些資源的表示 形式來交換信息。在本教程中，將首先了解一些關於 REST 的知識，然後演示 NetBeans IDE 是如何支持 這種體系結構樣式的。

目錄

簡介

REST 風格的 Web 服務、持久性和實體類

通過數據庫創建 REST 風格的 Web 服務

創建項目

生成實體類和 REST 風格的服務

測試 REST 風格的 Web 服務

添加 Google 地圖功能

Spring Framework 中 REST 風格的 Web 服務

要學習本教程，您需要具備以下軟件和資源。

軟件或資源 要求的版本 NetBeans IDE Java EE 下載包 Java Development Kit (JDK) 版本 6 符合 Java EE 規范的 Web 服務器或應用服務器

EE5 項目：Tomcat Web Server 6.x-7.x、Oracle WebLogic Server 11g
或 GlassFish Server Open Source Edition。
重要信息：如果在本教程中使用 Tomcat，請參見
有關在 Tomcat 上部署 REST 風格的服務的 NetBeans Wiki。

EE6 項目：GlassFish Server Open Source Edition 3.x
 

jdbc/sample 數據庫，位於
Java DB (Derby) 數據庫服務器或 MySQL
數據庫服務器上

在 Java DB (Derby) 上，jdbc/sample 數據庫是在將 IDE 與 GlassFish 應用服務器
一起安裝時由 NetBeans IDE 生成的。

在 MySQL 上，通過 IDE 在 MySQL 服務器上創建 sample 數據庫後，IDE 將填充該數據庫 。

Tomcat 和 GlassFish 服務器都可以隨同 NetBeans IDE 的 Web 和 Java EE 分發一起安裝。此外， 也可以訪問 GlassFish 服務器下載頁或 Apache Tomcat 下載頁。

簡介

REST 風格的 Web 服務是使用 REST 風格的體系結構樣式構建的服務。由於其輕量的特性並且支持直 接通過 HTTP 傳輸數據，使用 REST 風格的方法構建 Web 服務作為一種新興趨勢已經開始替代傳統的 Web 服務構建方式，即使用基於 SOAP 的技術在 Internet 上部署服務。

IDE 支持使用 JSR 311 - Java API for RESTful Web Services (JAX-RS) 和 Jersey（JAX-RS 的引 用實現）快速開發 REST 風格的 Web 服務。

有關詳細信息，請參見以下內容：

JSR 311: JAX-RS: The Java API for RESTful Web Services

Jersey, the open source JAX-RS (JSR 311) Reference Implementation for building RESTful Web services

除了支持構建 REST 風格的 Web 服務之外，IDE 還支持測試、構建可訪問 REST 風格的 Web 服務的 客戶端應用程序，以及生成用於調用 Web 服務（REST 風格和基於 SOAP）的代碼。

下面是 IDE 提供的 REST 風格的功能列表：

通過 JPA 實體類和模式快速創建 REST 風格的 Web 服務。

通過從“服務”窗口的 Web 服務管理器中拖放組件，快速生成用於調用 Web 服務的代碼，例如， Google 地圖、Yahoo 新聞搜索和 StrikeIron Web 服務。

為 Web 服務管理器中注冊的服務生成 REST 風格的 Java 客戶端。

生成測試客戶端，用於測試 REST 風格的 Web 服務。

提供可輕松浏覽項目中 REST 風格的 Web 服務實現類的邏輯視圖。

完全集成的 Spring Framework，提供 Spring 事務處理。

在本教程中，將介紹 IDE 如何支持生成、實現和測試 REST 風格的 Web 服務。

REST 風格的 Web 服務、持久性和實體類

Java 中的 REST 風格的 Web 服務依靠 Java 持久性 API 與數據庫進行通信。具體來說，REST 風格 的 Web 服務依靠持久性 API 中定義的實體類和持久性單元。實體類是指映射到關系 數據庫中的對象的 Java 類。按照 Java EE5 教程中的說法，“實體是一個小型持久性域對象。通常，實 體表示關系數據庫中的表，每個實體實例與該表中的一行相對應”。持久性單元包含 persistence.xml 文件中定義的實體類、數據源、持久性提供器以及持久性單元自身的名稱集合。

您可以使用 NetBeans IDE 在相同過程中創建實體類和 REST 風格的 Web 服務，也可以使用 IDE 通 過現有實體類創建 REST 風格的 Web 服務。在本教程中，將使用數據庫向導中的 REST 風格的服務在相 同過程中生成實體類和 REST 風格的 Web 服務。該向導自動生成持久性單元。

使用 MySQL 數據庫服務器

如果使用的是 MySQL 數據庫服務器而不是 JavaDB (Derby)，您需要在 IDE 中注冊該數據庫服務器， 然後將 sample 數據庫添加到該服務器上。

在本教程中使用 MySQL 數據庫服務器：

如果未注冊 MySQL 服務器，請在 IDE 中注冊該服務器。要注冊 MySQL 服務器，請轉至 IDE 的“服 務”窗口，右鍵單擊“數據庫”節點，然後選擇“注冊 MySQL 服務器”。

 

將打開一個對話框，您可以在其中鍵入 MySQL 服務器的配置詳細信息，包括管理員用戶名和口令。請 參見連接到 MySQL 數據庫中的“配置 MySQL 服務器屬性”。

啟動並連接到 MySQL 服務器。請參見連接到 MySQL 數據庫中的“啟動 MySQL 服務器”。

右鍵單擊 MySQL 服務器節點，然後選擇“創建數據庫”。將打開“創建 MySQL 數據庫”對話框。

鍵入 sample 作為新數據庫名稱。為超級用戶或所選的用戶授予完全訪問權限。

單擊“確定”。將打開一個對話框，通知您 sample 是樣例數據庫的名稱，並詢問您是否要為該數據 庫創建表、對象和數據。

單擊“是”。IDE 將創建並填充該數據庫，並添加到該數據庫的連接。

通過數據庫創建 REST 風格的 Web 服務

本練習的目標是創建一個項目，並通過數據庫生成實體類和 REST 風格的 Web 服務。

此部分使用 JavaDB (Derby) 數據庫和 jdbc/sample 數據源。JavaDB 包含在 SDK 中。jdbc/sample 數據源是在將 IDE 與 GlassFish 一起安裝時由 NetBeans IDE 自動生成的。

創建項目

要創建 REST 風格的 Web 服務，您需要創建 Java Web 應用程序項目。

要創建此項目，請執行以下操作：

 

選擇“文件”>“新建項目 (Ctrl-Shift-N)”。在“類別”下，選擇 "Java Web"。在 “項目”下，選擇“Web 應用程序”。單擊“下一步”。將打開“新建 Web 應用程序”向導。

或者，也可以創建 Maven Web 應用程序。選擇“文件”>“新建項目 (Ctrl-Shift-N)”。在“ 類別”下，選擇 "Maven"。在“項目”下，選擇“Maven Web 應用程序”，然後單擊“下一步 ”。

在“項目名稱”字段中，輸入 CustomerDB。單擊“下一步”。

選擇 EE 6 或 EE 5。在“服務器”下，選擇要使用的服務器，但要注意，EE 6 項目需要使用 GlassFish Server 3 或更高版本。單擊其余選項，然後單擊“完成”。

Maven 項目重要說明：在創建 Maven Web 應用程序時，無法設置服務器。不過，您必 須在創建持久性單元之前設置服務器。因此，在創建 Maven Web 應用程序後，請打開項目的“屬性”對 話框並在“運行”屬性中設置服務器。要打開項目的“屬性”對話框，請右鍵單擊項目節點，然後從上下 文菜單中選擇“屬性”。

Tomcat 7 和 EE6：Tomcat 7 無法與 NetBeans IDE 7.0 或更高版本生成的 EE6 REST 風格的服務一起使用。這是因為 NetBeans 7.0 為 REST 風格的服務提供了會話 Facade，而 Tomcat 7 沒有支持 EJB 3.1 或 EE6 EJB 的插件。請參見 Apache Geronimo 項目和 Apache OpenEJB 插 件項目以了解這些問題的最新信息。

生成實體類和 REST 風格的服務

在創建 Java Web 應用程序後，將實體類和 REST 風格的 Web 服務添加到項目中。

生成實體類和 REST 風格的 Web 服務：

右鍵單擊 CustomerDB 節點，然後選擇“新建”>“其他”>“Web 服務”>“基於數據庫的 REST 風格的 Web 服務”。將在“數據庫表”面板中打開“新建 REST 風格的 Web 服務”向導。

在“數據庫表”面板中，如果使用的是 GlassFish 服務器，請從“數據源”下拉列表字段中選擇 jdbc/sample 數據源。

如果使用的是 Tomcat，請選擇 jdbc:derby://localhost:1527/sample。如果 Derby 數據庫服務器未 能自動啟動，需要從“服務”窗口的“數據庫”標簽中啟動它。

MySQL 用戶注意事項：您必須創建新的數據源。選擇“新建數據源”，指定任意描述性名稱，然後選 擇 jdbc:mysql://localhost:3306/sample 數據庫連接。在 MySQL 上創建樣例數據庫時，將會創建該連 接。

在“可用表”下，選擇 "CUSTOMER"，然後單擊“添加”。DISCOUNT_CODE 表（與 CUSTOMER 表有關聯）將自動添加到“選定表”列表中。現在您應該看到以下內容：
 

單擊“下一步”。將打開“實體類”頁。在“包”下，鍵入 entities。現在您應該看到以下內容：

EE6 服務注意事項：“基於數據庫的 REST 風格的 Web 服務”向導自動生成 JAXB 標注。如果使用“ 通過數據庫生成實體類”向導為 EE6 應用程序生成實體類，並且以後可能通過這些實例類創建 REST 風 格的 Web 服務，請確保選中“生成 JAXB 標注”框。還可以在運行“基於實體類的 REST 風格的 Web 服 務”向導之前手動將 JAXB 標注添加到實體類中。有關詳細信息，請參見用於生成更簡單的 REST 風格 Web 服務的 NetBeans。

單擊“下一步”。將打開“生成的類”面板。在該面板中，您可以設置 IDE 為項目生成的 REST 風格 的 Web 服務類的位置。對於 EE5 和 EE6 REST 風格的 Web 服務，“生成的類”面板是不同的，因為 EE5 項目包含轉換器類，而 EE6 Web 服務在實體類中改用 JAXB 標注。

接受缺省包和位置，然後單擊“完成”。IDE 將生成實體類。然後，將打開一個對話框，詢問您是否 要注冊 REST 風格的資源。對於 EE5 項目，您可以選擇使用 web.xml 部署描述符中的 Jersey REST 風 格的 Servlet 適配器（缺省），也可以手動編碼您自己的解決方案。對於 EE6 項目，您還可以選擇使用 javax.ws.rs.core.Application 的子類（缺省）。

對於 EE5 或 EE6 應用程序，在 web.xml 中創建缺省 Jersey REST Servlet 適配器，然後單擊“確 定”。這與 GlassFish 問題 16118 有關。

現在，IDE 將生成 REST 風格的 Web 服務。在 IDE 完成後，查看“項目”窗口。生成的實體類位於 entities 包中。服務位於 service 包中。對於 EE5 項目，converter 包中包含一些轉換器類，並在“ 配置文件”下面包含 web.xml 部署描述符。

注意：IDE 可能會提示您解決項目的引用問題。在這種情況下，右鍵單擊 CustomerDB 項目節點，然後選擇“解決引用問題”。如果該服務是在 WebLogic 安裝上運行的第一個 Jersey 應用程 序，則可能會發生該問題。在這種情況下，IDE 通過將 Jersey 庫復制到服務器來解決引用問題。

對於來自數據庫的 EE6 REST 風格 Web 服務，NetBeans IDE 在實體類以及服務類的 EJB 會話 Facade 中使用 JAXB 標注。這避免了需要使用轉換器類並生成更簡單的代碼。

有關 NetBeans IDE 7.0 和更高版本生成的 EE6 REST 風格 Web 服務的更多詳細信息，請參見用於生 成更簡單的 REST 風格 Web 服務的 NetBeans。

測試 REST 風格的 Web 服務

本練習的目標是試驗您的應用程序。

右鍵單擊該項目節點，並選擇“測試 REST 風格的 Web 服務”。服務器啟動，應用程序部署。部署完 成後，浏覽器將顯示應用程序，其中含有到各 Web 服務的鏈接。

如果輸出窗口顯示錯誤消息，指出一個或多個類不存在，且項目未生成，則請將 Jersey 庫添加到編 譯時庫中。右鍵單擊項目節點，然後選擇“屬性”。在“屬性”樹狀菜單中選擇“庫”。單擊“添加庫” 並定位到 Jersey 庫。

左側是根資源集。此處，它們命名為 customers 和 discountCodes。

單擊 customers 節點。浏覽器窗口顯示用於測試 Customers 服務的參數列表。

可以設置下列參數：

選擇要測試的方法：從下拉列表中選擇 GET 或 POST 方法以及 MIME 類型。

開始：要顯示的第一個實體。請注意編號從 0 開始，而不是從 1 開始。

最大數目：可獲取的最大實體數目。如果設置為 0，將獲取所有實體。

展開級別：一項高級功能。有些服務返回無限重復的樹狀分層結構。此參數指定要在“原始視圖”中 顯示此類分層結構的深度。

查詢：一項高級功能。根據 JPA 語法搜索 XML 或 JSON 文檔。

單擊“方法”下拉列表，選擇 GET(application/xml)。在“最大數目”字段中鍵入 "3" 。保留其他參數中的缺省值，並單擊“測試”。測試結果將顯示在“測試輸出”部分。

“測試輸出”區域中有 5 個標簽。

“表格視圖”是一個平面視圖，它顯示生成文檔中的所有 URI，您可以通過單擊這些鏈接進行導航。

“原始視圖”顯示返回的實際數據。根據您選擇的 mime 類型（application/xml 或 application/json），顯示的數據將分別為 XML 或 JSON 格式。

“子資源”標簽將顯示根資源和子資源的 URL。當 REST 風格的 Web 服務是基於數據庫實體類時，根 資源代表了數據庫表，而子資源則代表列。

“頭”標簽顯示 HTTP 頭信息。

“HTTP 監視”標簽顯示發送和接收的實際 HTTP 請求數和響應數。

請注意，盡管您指定了最多顯示 3 個實體，但卻列出了 6 個結果。打開“原始視圖”標簽可看到相 關的原因。每個實體對應一個 <customer> 元素，測試結果中只有 3 個客戶。但是，“表格視圖 ”列出的是 URI，而不是實體，每個實體有兩個 URI，一個是父 <customer> 元素的屬性，另一個 是子 <discountCode> 元素的屬性。因此，盡管只有 3 個 customer 實體，但總共有 6 個 URI。

退出浏覽器並返回到 IDE。

添加 Google 地圖功能

本練習的目標是將 Google 地圖功能添加到 REST 風格的 Web 服務。

在編輯器中打開 CustomerResource 類。

將以下方法添加到 CustomerResource：

@GET
@Produces("text/html")
public String getGoogleMap() {
// Drag and drop the getGoogleMap operation here
 
   return "";
}

請在以下位置注冊獲取 Google 地圖密鑰：http://www.google.com/apis/maps/signup.html 。Google 地圖密鑰請求對話框中有一個字段需要輸入您網站的 URL。在該字段中鍵入 http://localhost:8080。

在 IDE 中，打開“服務”標簽並展開“Web 服務”節點。在“Web 服務”下面，展開 "Google" 節點。在 "Google" 下，展開 "Map Service"。
 

將 getGoogleMap 項目拖放至在“步驟 2”中創建的 getGoogleMap 方法的主體中，具體位置在緊靠 return = ""; 代碼行的前面。“定制 getGoogleMap SAAS”對話框打開。接受缺省選項，然 後並單擊“確定”。

IDE 在 CustomerResource 類的 getGoogleMap 方法中添加以下 try 代碼塊。

@GET
@Produces("text/html")
public String getGoogleMap() {
// Drag and drop the getGoogleMap operation here
        
    try {
             
         String address = "16 Network Circle, Menlo Park";
         java.lang.Integer zoom = 15;
         String iframe = "false";
         RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);
         //TODO - Uncomment the print Statement below to print result.
         //System.out.println("The SaasService returned: "+result.getDataAsString

());
    } catch (Exception ex) {
         ex.printStackTrace();
    }
 
    return "";
 
}

IDE 還會創建 org.netbeans.saas 和 org.netbeans.saas.google 包，其中包含有以下類和 資源：

RestConnection - HttpUrlConnection 的包裝器

RestResponse - HTTP 響應的包裝器

googlemapservice.properties - 存儲 API 密鑰的屬性文件

GoogleMapService - 包含包裝器方法的服務包裝器，它使用 RestConnection 調用 Google 地圖服務 。

在 getGoogleMap() 的 try 代碼塊中，將被注釋掉的 print 語句替換為代碼行 return result.getDataAsString();。此方法現在如下所示：

@GET
@Produces("text/html")
public String getGoogleMap() {
// Drag and drop the getGoogleMap operation here
        
    try {
             
         String address = "16 Network Circle, Menlo Park";
         java.lang.Integer zoom = 15;
         String iframe = "false";
         RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);
         return result.getDataAsString();
    } catch (Exception ex) {
         ex.printStackTrace();
    }
 
    return "";
 
        }

打開 googlemapservice.properties。粘入在步驟 3 中從 Google 獲取的 API 密鑰 。

右鍵單擊 "CustomerDB" 項目節點，並選擇“測試 REST 風格的 Web 服務”。IDE 將取消 部署，並將您的項目重新部署到服務器上，然後打開含測試客戶端的浏覽器窗口。

單擊左側邊欄中的 customers。customers 的測試標准在主窗格中打開。保留缺省選項不變，然後單 擊“測試”。用戶表打開。

從表中單擊 customer1。該客戶的測試窗口在主窗格中打開。從下拉列表中，選擇 text/html MIME 類型。單擊“測試”。"16 Network Circle, Menlo Park" 的 GoogleMap 在“原始視圖”中 打開。

將為數據庫中的所有客戶顯示 Menlo Park 地址的 Google 地圖。要顯示客戶實際地址的 Google 地 圖，應當為數據庫中的每個實體創建一個 Customer 實例，並將地址設置為等於包含每個 Customer 的地 址變量的字串。如果您使用的是 6.5 之前的 IDE 版本，還需在 try 代碼塊的末尾添加一行代碼以關閉 Customer 的實例。此方法現在如下所示（更改的內容以粗體顯示）：

@GET
@Produces("text/html")
public String getGoogleMap() {
    try {
         Customer c = getEntity();
         String address = c.getAddressline1() + " " + c.getAddressline2() + " 

" +
                 c.getCity() + " " + c.getState() + " " + c.getZip();
         java.lang.Integer zoom = 15;
         String iframe = "false";
 
         RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);
         return result.getDataAsString();
     
     } catch (Exception ex) {
         ex.printStackTrace();
     } 
 
     //The close() method is only necessary with versions of NetBeans IDE earlier than 6.5
 
         finally {
             PersistenceService.getInstance().close();
     }
     return "";
            }

再次測試 REST 風格的 Web 服務。再次為一個客戶選擇 text/html MIME 類型 。數據庫中該客戶地址的 Google 地圖現在顯示在“原始視圖”中。對於 customer1，將顯示下面的地圖 ：

注意：如果 GoogleMaps 無法找到地址，它將顯示放大的海洋視圖。

Spring Framework 中 REST 風格的 Web 服務

從 NetBeans IDE 6.5 和 Jersey 0.8 開始，Jersey 集成到了 Spring Framework 中。在使用 Spring Framework 創建 Java Web 應用程序時，會自動創建識別 REST 的 Servlet。不過，Spring 3 不 包含 aopalliance.jar，REST 風格的 Web 服務需要使用該文件來注入 EntityManager 對象。

使用 Spring Framework 創建 REST 風格的 Web 服務

要使用 Spring Framework 創建 REST 風格的 Web 服務，只需重復本教程中介紹的操作過程，但有一 個例外。按照通過數據庫生成實體類中所述在“新建項目”向導中創建 Java Web 應用程序時，在選擇服 務器後，單擊“下一步”，而不是單擊“完成”。“框架”面板打開。選擇 "Spring Web MVC"，然後單擊“完成”。

創建 REST 風格的服務後，請注意 Spring 項目與在沒有 Spring 的情況下創建的項目之間的以下區 別：

Spring 項目的 customerdb.service 包中沒有名為 PersistenceService.java 的類。

CustomerResource.java 導入 org.springframework.transaction.annotation.Transactional 並包 含許多 @Transactional 標注。

之所以存在這兩點區別，是因為 Spring Framework 會處理事務和實體管理，而在其他項目中，IDE 必須創建一個使用 javax.transaction.UserTransaction 和 javax.persistence.EntityManager 的類。 Spring Framework 會產生更清晰的代碼以及更高效的事務處理和實體管理。

有關 NetBeans IDE 中 Spring Framework 項目功能的詳細信息，請參見 Spring Framework 簡介。

將 aopalliance.jar 添加到項目中

Spring 3 不包含 aopalliance.jar。應用程序需要使用該庫來注入 EntityManager。要解決此問題， 您需要下載該 jar 並將其添加到類路徑中。您還需要從代碼中刪除 @Error 標注。請參見 問題 193626 和 Spring 論壇。

添加 aopalliance.jar：

從 http://sourceforge.net/projects/aopalliance/files/aopalliance/1.0/ 下載 aopalliance.jar 的 Zip 歸檔文件。

將歸檔文件解壓縮到所選的位置。

在 IDE 的“項目”窗口中，右鍵單擊 Spring REST 風格的 Web 服務項目節點。上下文菜單打開。

選擇“屬性”。屬性對話框打開。

在“類別”窗格中，選擇“庫”。單擊“添加 JAR/文件夾”。將打開文件系統浏覽器。

浏覽到 aopalliance.jar。使用絕對路徑引用。單擊“打開”。

aopalliance.jar 文件現在包含在庫中。單擊“確定”。

在 IDE 的頂部菜單欄中，單擊“編輯”，然後選擇“在項目中查找...”。

在項目中搜索 @Error 標注的所有實例。

從代碼中刪除每個 @Error 行。