JAX_WS注釋詳解

轉自：https://www.ibm.com/support/knowledgecenter/zh/SSAW57_8.5.5/com.ibm.websphere.nd.doc/ae/rwbs_jaxwsannotations.html

下表中列出了 JAX-WS 支援的注釋。注釋的目标适用于下列 Java 對象：

· 諸如 Java 類、枚舉或接口等類型

· 方法

· 代表 Java 類中局部執行個體變量的字段

· Java 方法中的參數

Table 1. Web Service 中繼資料注釋 (JSR 181). 描述受支援的 Web Service 中繼資料注釋及其關聯屬性。
注釋類	注釋	屬性
javax.jws.WebService	@WebService 注釋用于将 Java 類标記為實作 Web Service 或者将服務端點接口 (SEI) 标記為實作 Web Service 接口。 Important · 實作 Web Service 的 Java 類必須指定 @WebService 或 @WebServiceProvider 注釋。不能同時提供這兩種注釋。此注釋适用于客戶機/伺服器 SEI 或伺服器端點實作類。 · 如果注釋通過 endpointInterface 屬性引用某個 SEI，那麼還必須使用 @WebService 注釋對該 SEI 進行注釋。 · 請參閱“在基于 SEI 的 JAX-WS Web Service 中公布方法”資訊，以了解有關對服務端點實作使用 @WebService 和 @WebMethod 注釋以指定要作為 JAX-WS Web Service 公布的 Java 方法的最佳實踐。	· 注釋目标：類型 · 屬性： - 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) 上的方法，或者應用于伺服器端點實作類。 避免故障 從包括 JAX-WS 工具 V2.1.6 的 Sun 和 HP JDK V1.6 開始，JAX-WS 運作時環境和工具在确定暴露哪些方法作為 Web Service 操作方面的行為發生了更改，以便更符合 JAX-WS 規範。可能受此更改影響的應用程式包括不指定 WDL 檔案或顯式服務端點接口 (SEI) 的 Web Service 應用程式。有關更多資訊，請參閱“在基于 SEI 的 JAX-WS Web Service 資訊中暴露方法”一文。	· 注釋目标：方法 · 屬性： - operationName ·  指定與此方法相比對的 wsdl:operation 的名稱。預設值為 Java 方法的名稱。（字元串） ·  - action ·  定義此操作的行為。對于 SOAP 綁定，此值将确定 SOAPAction 頭的值 ，且必須顯式設定 。 ·  - exclude ·  指定是否從 Web Service 中排除某一方法。預設值為 false。（布爾值） ·
javax.jws.Oneway	@Oneway 注釋用于将某一方法表示為隻有輸入消息而沒有輸出消息的 Web Service 單向操作。 将此注釋應用于客戶機或伺服器服務端點接口 (SEI) 上的方法，或者應用于伺服器端點實作類。	· 注釋目标：方法 · 沒有适用于 Oneway 注釋的屬性。
javax.jws.WebParam	@WebParam 注釋用于定制從單個參數至 Web Service 消息部分和 XML 元素的映射。 将此注釋應用于客戶機或伺服器服務端點接口 (SEI) 上的方法，或者應用于伺服器端點實作類。	· 注釋目标：參數 · 屬性： - 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) 上的方法，或者應用于伺服器端點實作類。	· 注釋目标：方法 · 屬性： - 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) 上的類型或方法，或者應用于伺服器端點實作類。 方法級别的注釋僅限于它可以指定的對象，僅當 style 屬性為 DOCUMENT 時才使用該注釋。如果未指定方法級别的注釋，那麼将使用類型的 @SOAPBinding 行為。	· 注釋目标：類型或方法 · 屬性： - style ·  定義發送到 Web Service 和來自 Web Service 的消息的編碼樣式。有效值為 DOCUMENT 和 RPC。預設值為 DOCUMENT。（字元串） ·  - use ·  定義用于發送到 Web Service 和來自 Web Service 的消息的格式。預設值為 LITERAL。不支援 ENCODED。（字元串） ·  - parameterStyle ·  确定方法的參數是否表示整個消息體，或者參數是否是封裝在執行操作之後命名的頂級元素中的元素。有效值為 WRAPPED 或 BARE。對于 DOCUMENT 類型的綁定隻能使用 BARE 值。預設值為 WRAPPED。（字元串） ·

Table 2. JAX-WS 注釋 (JSR 224). 描述受支援的 JAX-WS 注釋及其關聯屬性。
注釋類	注釋	屬性
javax.xml.ws.Action	@Action 注釋用于指定與 Web Service 操作關聯的 WS-Addressing 操作。 如果您将此注釋與特定方法配合使用，并生成相應的 WSDL 文檔，那麼會将 WS-Addressing 操作擴充屬性添加到與該方法對應的 WSDL 操作的 input 和 output 元素。 要将此屬性添加到 WSDL 操作，您還必須在伺服器端點實作類上指定 @Addressing 注釋。如果不想使用 @Addressing 注釋，那麼可以提供您自己的已定義 Action 屬性的 WSDL 文檔。	· 注釋目标：方法 · 屬性： - fault ·  為操作的 wsdl:fault 指定 FaultAction 數組。（字元串） ·  - input ·  為操作的 wsdl:input 指定操作。（字元串） ·  - output ·  為操作的 wsdl:output 指定操作。（字元串） ·
javax.xml.ws.BindingType	@BindingType 注釋指定在釋出此類型的端點時要使用的綁定。 将此注釋應用于伺服器端點實作類。 Important 可以通過指定 javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_MTOM_BINDING或 javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_MTOM_BINDING作為該注釋的值來對 JavaBeans 端點實作類使用 @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.FaultAction	@FaultAction 注釋指定已添加到故障響應中的 WS-Addressing 操作。 此注釋必須包含在 @Action 注釋中。 如果您将此注釋與特定方法配合使用，那麼會将 WS-Addressing FaultAction 擴充屬性添加到與該方法對應的 WSDL 操作的 fault 元素。 要将此屬性添加到 WSDL 操作，您還必須在伺服器端點實作類上指定 @Addressing 注釋。如果不想使用 @Addressing 注釋，那麼可以提供您自己的已定義 Action 屬性的 WSDL 文檔。	· 注釋目标：方法 · 屬性： - value ·  為操作的 wsdl:fault 指定操作。（字元串） ·  - output ·  指定異常類的名稱。（字元串） ·  - className ·  指定用于表示請求包裝器的類的名稱。（字元串） ·
javax.xml.ws.RequestWrapper	@RequestWrapper 注釋提供 JAXB 生成的請求包裝器 Bean、元素名稱和名稱空間，用于對在運作時使用的請求包裝器 Bean 進行序列化和反序列化。 從 Java 對象開始時，此元素用來解決 document literal 方式下的重載沖突。在這種情況下，隻有 className 屬性是必需的。 将此注釋應用于客戶機或伺服器服務端點接口 (SEI) 上的方法，或者應用于伺服器端點實作類。	· 注釋目标：方法 · 屬性： - localName ·  指定用于表示請求包裝器的 XML 模式元素的局部名稱。預設值為在 javax.jws.WebMethod 注釋中定義的 operationName。（字元串） ·  - targetNamespace ·  指定請求包裝器方法的 XML 名稱空間。預設值為 SEI 的目标名稱空間。（字元串） ·  - className ·  指定用于表示請求包裝器的類的名稱。（字元串） ·  - partName ·  指定 wsdl:part 屬性的名稱，該屬性用于表示 RequestWrapper 類的 XML 模式元素。此屬性适用于 JAX-WS 2.2 及更高版本。（字元串） ·
javax.xml.ws.ResponseWrapper	@ResponseWrapper 注釋提供 JAXB 生成的響應包裝器 Bean、元素名稱和名稱空間，用于對在運作時使用的響應包裝器 Bean 進行序列化和反序列化。 從 Java 對象開始時，此元素用來解決 document literal 方式下的重載沖突。在這種情況下，隻有 className 屬性是必需的。 将此注釋應用于客戶機或伺服器服務端點接口 (SEI) 上的方法，或者應用于伺服器端點實作類。	· 注釋目标：方法 · 屬性： - localName ·  指定用于表示請求包裝器的 XML 模式元素的局部名稱。預設值為 operationName + Response。operationName 是在 javax.jws.WebMethod 注釋中定義的。（字元串） ·  - targetNamespace ·  指定請求包裝器方法的 XML 名稱空間。預設值為 SEI 的目标名稱空間。（字元串） ·  - className ·  指定用于表示響應包裝器的類的名稱。（字元串） ·  - partName ·  指定 wsdl:part 屬性的名稱，該屬性用于表示 ResponseWrapper 類的 XML 模式元素。此屬性适用于 JAX-WS 2.2 及更高版本。（字元串） ·
javax.xml.ws.RespectBinding	@RespectBinding 注釋指定 JAX-WS 實作是否必須将 wsdl:binding的内容用于端點。 如果指定此注釋，那麼會執行檢查以確定支援 enabled 屬性設為 true 的所有必需 WSDL 可擴充性元素。 将此注釋應用于伺服器端點實作類上的方法。	· 注釋目标：方法 · 屬性： - enabled ·  指定是否必須使用 wsdl:binding。預設值為 true。（布爾值） ·
javax.xml.ws.ServiceMode	@ServiceMode 注釋指定服務提供程式是需要對整個協定消息具有通路權還是隻需對消息有效内容具有通路權。 Important 僅支援在使用 @WebServiceProvider 注釋進行注釋的類上使用 @ServiceMode 注釋。	· 注釋目标：類型 · 屬性： - value ·  訓示提供者類是接受消息的有效内容 PAYLOAD 還是整個消息 MESSAGE。預設值為 PAYLOAD。（字元串） ·
javax.xml.ws.soap.Addressing	@Addressing 注釋指定此服務需要啟用 WS-Addressing 支援。 将此注釋應用于伺服器端點實作類上的方法。	· 注釋目标：類型 · 屬性： - enabled ·  指定是否啟用 WS-Addressing。預設值為 true。（布爾值） ·  - required ·  指定 WS-Addressing 頭必須存在于入局消息上。預設值為 false。（布爾值） ·  - responses ·  指定要使用的消息交換模式。預設值為 Responses.ALL。此屬性适用于 JAX-WS 2.2 及更高版本。（字元串） ·
javax.xml.ws.soap.MTOM	@MTOM 注釋指定是否使用 MTOM 來發送 SOAP 消息體中的二進制内容。 将此注釋應用于服務端點實作類。	· 注釋目标：類 · 屬性： - enabled ·  指定是否對 JAX-WS 端點啟用 MTOM。預設值為 true。（布爾值） ·  - threshold ·  指定使用 MTOM 來發送的消息的最小大小。如果消息大小小于此指定的整數，那麼會将消息作為基本 64 位或 hexBinary 資料直接插入 XML 文檔中。（整數） ·
javax.xml.ws.WebFault	@WebFault 注釋将 WSDL 故障映射到 Java 異常。對從 WSDL 故障消息引用的全局元素生成的 JAXB 類型進行序列化期間，該注釋用來捕獲故障的名稱。它還可以用來定制從特定于服務的異常到 WSDL 故障的映射。 此注釋隻能應用于客戶機或伺服器上的故障實作類。	· 注釋目标：類型 · 屬性： - name ·  指定用于表示 WSDL 檔案中相應故障的 XML 元素的局部名稱。必須指定實際值。（字元串） ·  - targetNamespace ·  指定用于表示 WSDL 檔案中相應故障的 XML 元素的名稱空間。（字元串） ·  - faultBean ·  指定故障 Bean 類的名稱。（字元串） ·  - messageName ·  指定 wsdl:message 屬性的名稱，該屬性用于表示 WSDL 檔案中相應的故障。此屬性适用于 JAX-WS 2.2 及更高版本。（字元串） ·
javax.xml.ws.WebServiceProvider	@WebServiceProvider 注釋表示一個類滿足 JAX-WS 提供程式實作類的要求。 Important · 實作 Web Service 的 Java 類必須指定 @WebService 或 @WebServiceProvider 注釋。不能同時提供這兩種注釋。 · 僅在服務實作類上支援使用 @WebServiceProvider 注釋。 任何帶有 @WebServiceProvider 注釋的類都必須實作 javax.xml.ws.Provider 接口。	· 注釋目标：類型 · 屬性： - targetNamespace ·  指定從 Web Service 生成的 WSDL 和 XML 元素的 XML 名稱空間。預設值為從包含該 Web Service 的包名映射的名稱空間。（字元串） ·  - serviceName ·  指定 Web Service 的服務名稱：wsdl:service。預設值為 Java 類的簡單名稱 + Service。（字元串） ·  - portName ·  wsdl:portName。預設值為類的名稱 + Port。（字元串） ·  - wsdlLocation ·  這是定義 Web Service 的 WSDL 文檔的 Web 位址。此屬性是必需的。（字元串） ·
javax.xml.ws.WebServiceRef	@WebServiceRef 注釋用于定義對客戶機所調用的 Web Service 的引用。 Note · 可以使用 @WebServiceRef 注釋插入 JAX-WS 服務和端口的執行個體。 · 僅在特定的類類型中支援 @WebServiceRef 注釋。示例為 JAX-WS 端點實作類、JAX-WS 處理程式類、Enterprise JavaBeans 類以及 Servlet 類。支援此注釋的類類型與支援 @Resource 注釋的類類型相同。請參閱 Java Platform, Enterprise Edition (Java EE) 5 規範，以擷取支援的類類型的完整清單。	· 注釋目标：類型、字段或方法 · 屬性： - name ·  指定資源的 JNDI 名稱。字段名稱是字段注釋的預設值。對應于方法的 JavaBeans 屬性名是方法注釋的預設值。因為沒有預設值，是以您必須指定類注釋的值。（字元串） ·  - type ·  訓示資源的 Java 類型。字段類型是字段注釋的預設值。JavaBeans 屬性的類型是方法注釋的預設值。因為沒有預設值，是以您必須指定類注釋的值。（類） ·  - mappedName ·  指定要将此資源映射到的名稱。（字元串） ·  - value ·  訓示服務類的值，且訓示該服務類是對 javax.xml.ws.Service 進行擴充的類型。當引用類型是服務端點接口時，此屬性是必需的。（類） ·  - wsdlLocation ·  這是定義 Web Service 的 WSDL 文檔的 Web 位址。此屬性是必需的。（字元串） ·  - lookup ·  指定目标 Web Service 的 JNDI 查找名稱。此屬性适用于 JAX-WS 2.2 及更高版本。（字元串） ·
javax.xml.ws.WebServiceRefs	@WebServiceRefs 注釋會将多個 @WebServiceRef 注釋與一個特定類相關聯。 Note 僅在特定的類類型中支援 @WebServiceRef 注釋。示例為 JAX-WS 端點實作類、JAX-WS 處理程式類、Enterprise JavaBeans 類以及 Servlet 類。支援此注釋的類類型與支援 @Resource 注釋的類類型相同。請參閱 Java Platform, Enterprise Edition (Java EE) 5 規範，以擷取支援的類類型的完整清單。	· 注釋目标：類型 · 屬性： - value ·  為多個 Web Service 引用聲明指定一個數組。此屬性是必需的。 ·

Table 3. JAX-WS 常用注釋 (JSR 250). 描述受支援的 JAX-WS 公共注釋及其關聯屬性。
注釋類	注釋	屬性
javax.annotation.Resource	@Resource 注釋标記應用程式所需要的 WebServiceContext 資源。 Note 将此注釋應用于 JavaBeans 端點或 Provider 端點的伺服器端點實作類上的 WebServiceContext 類型字段，會導緻容器将 WebServiceContext 的執行個體注入所指定的字段。 使用此注釋取代 @WebServiceRef 注釋時，會應用針對 @WebServiceRef 注釋描述的規則。	· 注釋目标：字段或方法 · 屬性： - type ·  訓示資源的 Java 類型。您需要使用預設值 java.lang.Object 或者 javax.xml.ws.Web ServiceContext 值。如果類型是預設值，那麼必須将資源添加到字段或方法中。在這種情況下，字段的類型或者由方法定義的 JavaBeans 屬性的類型必須為 javax.xml.ws.WebServiceContext。（類） ·  如果使用此注釋來插入 Web Service，請參閱 @WebServiceRef type 屬性的描述。 ·
javax.annotation.Resources	@Resources 注釋會将多個 @Resource 注釋與特定的類相關聯，并充當多個資源聲明的容器。	· 注釋目标：字段或方法 · 屬性： - value ·  為多個 @Resource 注釋指定一個數組。此屬性是必需的。 ·
javax.annotation.PostConstruct	@PostConstruct 注釋标記需要在對類執行依賴性注入之後才運作的方法。 将此注釋應用于 JAX-WS 應用程式處理程式或伺服器端點實作類。	· 注釋目标：方法
javax.annotation.PreDestroy	@PreDestroy 注釋标記在容器移除執行個體時必須運作的方法。 将此注釋應用于 JAX-WS 應用程式處理程式或伺服器端點實作類。	· 注釋目标：方法