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.WebServiceContext 值。如果類型是缺省值，那麼必須將資源添加到字段或方法中。在這種情況下， 字段的類型或者由方法定義的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 繼承的方法。