WebService學習之四：關於JAX-WS 註釋

　　基於 XML 的 Web Service 的 Java API」（JAX-WS）經過使用註釋來指定與 Web Service 實現相關聯的元數據以及簡化 Web Service 的開發。註釋描述如何將服務器端的服務實現做爲 Web Service 來訪問或者客戶端的 Java 類如何訪問 Web Service。

JAX-WS 編程標準支持將具備用於定義服務端點應用程序的元數據的 Java 類做爲 Web Service 來註釋以及註釋客戶機能夠如何訪問 Web Service。JAX-WS 支持使用基於 Metadata Facility for the Java Programming Language（Java 規範請求（JSR）175）規範和「用於 Java 平臺的 Web Service 元數據」（JSR 181）規範的註釋，還可使用由 JAX-WS 2.0（JSR 224）規範定義的註釋（包括 JAXB 註釋）。經過使用符合 JSR 181 標準的註釋，能夠簡單地註釋服務實現類或服務接口，而且如今將應用程序做爲 Web Service 來啓用。經過在 Java 源代碼中使用註釋能夠簡化 Web Service 的開發和部署，由於會定義一些一般從部署描述符文件和 WSDL 文件中得到的附加信息，或者會將元數據從 XML 和 WSDL 映射至源工件中。

使用註釋來配置綁定、處理程序鏈、端口類型的集合名稱、服務以及其餘 WSDL 參數。註釋用於將 Java 映射至 WSDL 和模式，以及在運行時控制 JAX-WS 運行時處理和響應 Web Service 調用的方式。

下表中列示了 JAX-WS 支持的註釋。註釋的目標適用於下列 Java 對象：

• 諸如 Java 類、枚舉或接口等類型
• 方法
• 用於表示 Java 類中局部實例變量的字段
• Java 方法中的參數

Web Service 元數據註釋（JSR 181）

註釋類：	註釋：	屬性：
javax.jws.WebService	當實現 Web Service 時，@WebService 註釋標記 Java 類；實現 Web Service 接口時，標記服務端點接口（SEI）。 要點： • 實現 Web Service 的 Java 類必須指定 @WebService 或 @WebServiceProvider 註釋。不能同時提供這兩種註釋。 此註釋適用於客戶機/服務器 SEI 或 JavaBeans 端點的服務器端點實現類。 • 若是註釋經過endpointInterface屬性引用了某個 SEI，那麼還必須使用 @WebService 註釋來註釋該 SEI。 • 請參閱適用於使用 @WebService 註釋的類的方法的規則，以瞭解更多信息。	註釋目標：類型 屬性： - name wsdl:portType的名稱。缺省值爲 Java 類或接口的非限定名稱。（字符串） - targetNamespace 指定從 Web Service 生成的 WSDL 和 XML 元素的 XML 名稱空間。缺省值爲從包含該 Web Service 的包名映射的名稱空間。（字符串） - serviceName 指定 Web Service 的服務名稱：wsdl:service。缺省值爲 Java 類的簡單名稱 + Service。（字符串） - endpointInterface 指定用於定義服務的抽象 Web Service 約定的服務端點接口的限定名。若是指定了此限定名，那麼會使用該服務端點接口來肯定抽象 WSDL 約定。（字符串） - portName wsdl:portName。缺省值爲 WebService.name+Port。（字符串） - wsdlLocation 指定用於定義 Web Service 的 WSDL 文檔的 Web 地址。Web 地址能夠是相對路徑或絕對路徑。（字符串）
javax.jws.WebMethod	@WebMethod 註釋表示做爲一項 Web Service 操做的方法。 將此註釋應用於客戶機或服務器服務端點接口（SEI）上的方法，或者應用於 JavaBeans 端點的服務器端點實現類。 要點： • 僅支持在使用 @WebService 註釋來註釋的類上使用 @WebMethod 註釋。	註釋目標：方法 屬性： - operationName 指定與此方法相匹配的wsdl:operation的名稱。缺省值爲 Java 方法的名稱。（字符串） - action 定義此操做的行爲。對於 SOAP 綁定，此值將肯定 SOAPAction 頭的值。缺省值爲 Java 方法的名稱。（字符串） - exclude 指定是否從 Web Service 中排除某一方法。缺省值爲false。（布爾值）
javax.jws.Oneway	@Oneway 註釋將一個方法表示爲只有輸入消息而沒有輸出消息的 Web Service 單向操做。 將此註釋應用於客戶機或服務器服務端點接口（SEI）上的方法，或者應用於 JavaBeans 端點的服務器端點實現類。	註釋目標：方法 沒有適用於 Oneway 註釋的屬性。
javax.jws.WebParam	@WebParam 註釋用於定製從單個參數至 Web Service 消息部件和 XML 元素的映射。 將此註釋應用於客戶機或服務器服務端點接口（SEI）上的方法，或者應用於 JavaBeans 端點的服務器端點實現類。	註釋目標：參數 屬性： - name 參數的名稱。若是操做是遠程過程調用（RPC）類型而且未指定partName屬性，那麼這是用於表示參數的wsdl:part屬性的名稱。若是操做是文檔類型或者參數映射至某個頭，那麼-name是用於表示該參數的 XML 元素的局部名稱。若是操做是文檔類型、參數類型爲BARE而且方式爲OUT或INOUT，那麼必須指定此屬性。（字符串） - partName 定義用於表示此參數的wsdl:part屬性的名稱。僅當操做類型爲 RPC 或者操做是文檔類型而且參數類型爲BARE時才使用此參數。（字符串） - targetNamespace 指定參數的 XML 元素的 XML 名稱空間。當屬性映射至 XML 元素時，僅應用於文檔綁定。缺省值爲 Web Service 的targetNamespace。（字符串） - mode 此值表示此方法的參數流的方向。有效值爲IN、INOUT和OUT。（字符串） - header 指定參數是在消息頭仍是消息體中。缺省值爲false。（布爾值）
javax.jws.WebResult	@WebResult 註釋用於定製從返回值至 WSDL 部件或 XML 元素的映射。 將此註釋應用於客戶機或服務器服務端點接口（SEI）上的方法，或者應用於 JavaBeans 端點的服務器端點實現類。	註釋目標：方法 屬性： - name 當返回值列示在 WSDL 文件中而且在鏈接上的消息中找到該返回值時，指定該返回值的名稱。對於 RPC 綁定，這是用於表示返回值的wsdl:part屬性的名稱。對於文檔綁定，-name參數是用於表示返回值的 XML 元素的局部名。對於 RPC 和 DOCUMENT/WRAPPED 綁定，缺省值爲return。對於 DOCUMENT/BARE 綁定，缺省值爲方法名 +Response。（字符串） - targetNamespace 指定返回值的 XML 名稱空間。僅當操做類型爲 RPC 或者操做是文檔類型而且參數類型爲 BARE 時才使用此參數。（字符串） - header 指定頭中是否附帶結果。缺省值爲false。（布爾值） - partName 指定 RPC 或 DOCUMENT/BARE 操做的結果的部件名稱。缺省值爲@WebResult.name。（字符串）
javax.jws.HandlerChain	@HandlerChain 註釋用於使 Web Service 與外部定義的處理程序鏈相關聯。 只能經過對 SEI 或實現類使用 @HandlerChain 註釋來配置服務器端的處理程序。 可是可使用多種方法來配置客戶端的處理程序。能夠經過對生成的服務類或者 SEI 使用 @HandlerChain 註釋來配置客戶端的處理程序。此外，能夠按程序在服務上註冊您本身的 HandlerResolver 接口實現，或者按程序在綁定對象上設置處理程序鏈。	註釋目標：類型 屬性： - file 指定處理程序鏈文件所在的位置。文件位置能夠是採用外部格式的絕對 java.net.URL，也能夠是類文件中的相對路徑。（字符串） - name 指定配置文件中處理程序鏈的名稱。（字符串）
javax.jws.SOAPBinding	@SOAPBinding 註釋指定 Web Service 與 SOAP 消息協議之間的映射。 將此註釋應用於客戶機或服務器服務端點接口（SEI）上的類型或方法，或者應用於 JavaBeans 端點的服務器端點實現類。 方法級別的註釋僅限於它能夠指定的對象，僅當style屬性爲DOCUMENT時才使用該註釋。若是未指定方法級別的註釋，那麼將使用類型的 @SOAPBinding 行爲。	註釋目標：類型或方法 屬性： - style 定義發送至 Web Service 和來自 Web Service 的消息的編碼樣式。有效值爲DOCUMENT和RPC。缺省值爲DOCUMENT。（字符串） - use 定義用於發送至 Web Service 和來自 Web Service 的消息的格式。缺省值爲LITERAL。ENCODED在 Feature Pack for Web Services 中不受支持。（字符串） - parameterStyle 肯定方法的參數是否表示整個消息體，或者參數是不是封裝在執行操做以後命名的頂級元素中的元素。有效值爲WRAPPED或BARE。對於DOCUMENT類型的綁定只能使用BARE值。缺省值爲WRAPPED。（字符串）

JAX-WS 註釋（JSR 224）

註釋類：	註釋：	屬性：
javax.xml.ws.BindingType	@BindingType 註釋指定在發佈此類型的端點時要使用的綁定。 將此註釋應用於 JavaBeans 端點或提供程序端點的服務器端點實現類。 要點： • 能夠經過將該註釋的值指定爲javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_MTOM_BINDING或javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_MTOM_BINDING來對 Java bean 端點實現類使用 @BindingType 註釋以啓用 MTOM。	註釋目標：類型 屬性： - value 指示綁定標識 Web 地址。有效值爲javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_BINDING、javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_BINDING和javax.xml.ws.http.HTTPBinding.HTTP2HTTP_BINDING。缺省值爲javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_BINDING。（字符串）
javax.xml.ws.RequestWrapper	@RequestWrapper 註釋提供 JAXB 生成的請求包裝器 bean、元素名稱和名稱空間，用於對在運行時使用的請求包裝器 bean 進行序列化和反序列化。 從 Java 對象開始時，此元素用來解決 document literal 方式下的重載衝突。在這種狀況下，只有className屬性是必需的。 將此註釋應用於客戶機或服務器服務端點接口（SEI）上的方法，或者應用於 JavaBeans 端點的服務器端點實現類。	註釋目標：方法 屬性： - localName 指定用於表示請求包裝器的 XML 模式元素的局部名稱。缺省值爲在 javax.jws.WebMethod 註釋中定義的operationName。（字符串） - targetNamespace 指定請求包裝器方法的 XML 名稱空間。缺省值爲 SEI 的目標名稱空間。（字符串） - className 指定用於表示請求包裝器的類的名稱。（字符串）
javax.xml.ws.ResponseWrapper	@ResponseWrapper 註釋提供 JAXB 生成的響應包裝器 bean、元素名稱和名稱空間，用於對在運行時使用的響應包裝器 bean 進行序列化和反序列化。 從 Java 對象開始時，此元素用來解決 document literal 方式下的重載衝突。在這種狀況下，只有className屬性是必需的。 將此註釋應用於客戶機或服務器服務端點接口（SEI）上的方法，或者應用於 JavaBeans 端點的服務器端點實現類。	註釋目標：方法 屬性： - localName 指定用於表示請求包裝器的 XML 模式元素的局部名稱。缺省值爲operationName+ Response。operationName是在 javax.jws.WebMethod 註釋中定義的。（字符串） - targetNamespace 指定請求包裝器方法的 XML 名稱空間。缺省值爲 SEI 的目標名稱空間。（字符串） - className 指定用於表示響應包裝器的類的名稱。（字符串）
javax.xml.ws.ServiceMode	@ServiceMode 註釋指定服務提供者是須要對整個協議消息具備訪問權仍是隻需對消息有效內容具備訪問權。 要點： • 僅支持在使用 @WebServiceProvider 註釋來註釋的類上使用 @ServiceMode 註釋。	註釋目標：類型 屬性： - value 指示提供者類是接受消息的有效內容PAYLOAD仍是整個消息MESSAGE。缺省值爲PAYLOAD。（字符串）
javax.xml.ws.WebFault	@WebFault 註釋將 WSDL 故障映射至 Java 異常。對從 WSDL 故障消息引用的全局元素生成的 JAXB 類型進行序列化期間，該註釋用來捕獲故障的名稱。它還能夠用來定製從特定於服務的異常到 WSDL 故障的映射。 此註釋只能應用於客戶機或服務器上的故障實現類。	註釋目標：類型 屬性： - name 指定用於表示 WSDL 文件中相應故障的 XML 元素的局部名稱。必須指定實際值。（字符串） - targetNamespace 指定用於表示 WSDL 文件中相應故障的 XML 元素的名稱空間。（字符串） - faultBean 指定故障 bean 類的名稱。（字符串）
javax.xml.ws.WebServiceProvider	@WebServiceProvider 註釋表示一個類知足 JAX-WS 提供程序實現類的要求。 要點： • 實現 Web Service 的 Java 類必須指定 @WebService 或 @WebServiceProvider 註釋。不能同時提供這兩種註釋。 • 只有服務實現類才支持 @WebServiceProvider 註釋。 • 任何具備 @WebServiceProvider 註釋的類都必須具備名爲invoke的操做。	註釋目標：類型 屬性： - targetNamespace 指定從 Web Service 生成的 WSDL 和 XML 元素的 XML 名稱空間。缺省值爲從包含該 Web Service 的包名映射的名稱空間。（字符串） - serviceName 指定 Web Service 的服務名稱：wsdl:service。缺省值爲 Java 類的簡單名稱 + Service。（字符串） - portName wsdl:portName。缺省值爲類的名稱 + Port。（字符串） - wsdlLocation 用於定義 Web Service 的 WSDL 文檔的 Web 地址。此屬性是必需的。（字符串）

JAX-WS 經常使用註釋（JSR 250）

註釋類：	註釋：	屬性：
javax.annotation.Resource	@Resource 註釋標記應用程序所須要的 WebServiceContext 資源。 將此註釋應用於 JavaBeans 端點或提供程序端點的服務器端點實現類。對容器進行初始化時，容器會將 WebServiceContext 資源的實例添加到端點實現中。	註釋目標：字段或方法 屬性： - type 指示資源的 Java 類型。您須要使用缺省值java.lang.Object或者javax.xml.ws.Web ServiceContext值。若是類型是缺省值，那麼必須將資源添加到字段或方法中。在這種狀況下，字段的類型或者由方法定義的 JavaBeans 屬性的類型必須爲javax.xml.ws.WebServiceContext。（字符串）
javax.annotation.PostConstruct	@PostConstruct 註釋標記須要在對類執行依賴性注入以後才執行的方法。 將此註釋應用於 JAX-WS 應用程序處理程序、JavaBeans 端點或提供程序端點的服務器端點實現類。	註釋目標：方法
javax.annotation.PreDestroy	@PreDestroy 註釋標記在容器除去實例時必須執行的方法。 將此註釋應用於 JAX-WS 應用程序處理程序、JavaBeans 端點或提供程序端點的服務器端點實現類。	註釋目標：方法

適用於使用 @WebService 註釋的類的方法的規則

下列規則適用於使用 @WebService 註釋來註釋的類的方法。

• 若是某個實現類的 @WebService 註釋引用了 SEI，那麼該實例類不能具備任何 @WebMethod 註釋。
• 不管是否指定了 @WebMethod 註釋，SEI 的全部公用方法都被認爲是已顯示的方法。在包含exclude屬性的 SEI 上使用 @WebMethod 註釋是不正確的。
• 對於不引用 SEI 的實現類，若是對 @WebMethod 註釋指定了值exclude=true，那麼不會顯示該方法。若是未指定 @WebMethod 註釋，那麼將顯示包括繼承的方法在內的全部公用方法，可是不包括從 java.lang.Object 繼承的方法。