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 註釋的類的方法的規則，以瞭解更多信息。	註釋目標：類型 屬性： - namewsdl:portType 的名稱。缺省值爲 Java 類或接口的非限定名稱。（字符串） - targetNamespace指定從 Web Service 生成的 WSDL 和 XML 元素的 XML 名稱空間。缺省值爲從包含該 Web Service 的包名映射的名稱空間。（字符串） - serviceName指定 Web Service 的服務名稱：wsdl:service。缺省值爲 Java 類的簡單名稱 + Service。（字符串） - endpointInterface指定用於定義服務的抽象 Web Service 約定的服務端點接口的限定名。如果指定了此限定名，那麼會使用該服務端點接口來確定抽象 WSDL 約定。（字符串） - portNamewsdl: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。（字符串） - portNamewsdl: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 繼承的方法。