JWS 批註參考WebService註解

原文地址：http://www.cnblogs.com/wanggd/archive/2013/04/19/3030480.html

下列部分提供了有關標準 (JSR-181) JWS 批註和 WebLogic 特定 JWS 批註的參考文檔：

JWS 批註標記概述

WebLogic Web Service 編程模型使用新的 JDK 5.0 metadata annotations 功能（JSR-175 指定）。在此編程模型中，您要創建批註的 Java 文件，然後使用 Ant 任務將該文件編譯到 Java 源代碼中，並生成所有相關工件。

Java Web Service (JWS) 批註的文件是 Web Service 的核心。它包含確定 Web Service 行爲方式的 Java 代碼。JWS 文件是使用批註來指定 Web Service 的形狀和特徵的普通 Java 類文件。可在 JWS 文件中使用的 JWS 批註包括 Web Services Metadata for the Java Platform specification (JSR-181) 中定義的標準批註以及 WebLogic 特定的一組批註。本文檔提供了有關這兩個系列批註的參考信息。

您可以將 JWS 批註定位在 JWS 文件的類級別、方法級別或參數級別。某些批註可以定位在多個級別，如可定位在類級別和方法級別的 @SecurityRoles。此部分中的文檔列出了可以將每個批註定位到的級別。

下列示例顯示了一個簡單 JWS 文件，該文件同時使用了標準 JSR-181 JWS 批註和 WebLogic 特定的 JWS 批註（以粗體顯示）：

package examples.webservices.complex;

// 導入標準 JWS 批註接口

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;

// 導入 WebLogic 特定的 JWS 批註接口

import weblogic.jws.WLHttpTransport;

// 導入 BasicStruct JavaBean

import examples.webservices.complex.BasicStruct;

// 標準 JWS 批註，用於指定 Web Service 的
// portType 名稱爲“ComplexPortType”，其公共服務名爲“ComplexService”，
// 在生成的 WSDL 中使用的 targetNamespace 爲“http://example.org”

@WebService(serviceName="ComplexService", name="ComplexPortType",
targetNamespace="http://example.org")

// 標準 JWS 批註，用於指定這是 document-literal-wrapped
// Web Service

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

// WebLogic 特定的 JWS 批註，用於指定生成 Web Service 的 URI
// 所使用的上下文路徑和服務 URI 爲“complex/ComplexService”

@WLHttpTransport(contextPath="complex", serviceUri="ComplexService",
portName="ComplexServicePort")

/**
* 此 JWS 文件形成了 WebLogic Web Service 的基礎。這些 Web Service
* 有兩個公共操作：
*
* - echoInt(int)
* - echoComplexType(BasicStruct)
*
* 這些 Web Service 定義爲“document-literal”服務，這表示
* SOAP 消息具有單個部分來引用定義
* 整個主體的 XML Schema 元素。
*
* @作者版權所有 (c) 2005，BEA Systems。保留所有權利。
*/

public class ComplexImpl {

// 標準 JWS 批註，用於指定方法應公開爲
// 公共操作。因爲批註不包括
// 成員值“operationName”，所以操作的公共名稱
// 將與方法名相同：echoInt。
//
// WebResult 批註用於指定生成的 WSDL 中的
// 操作結果的名稱是“IntegerOutput”，而不是
// 默認名稱“return”。WebParam 批註用於指定 WSDL 文件中的
// 輸入參數名爲“IntegerInput”，而不是該參數的
// Java 名稱“input”。

@WebMethod()
@WebResult(name="IntegerOutput",
             targetNamespace="http://example.org/complex")
public int echoInt(
      @WebParam(name="IntegerInput",
                targetNamespace="http://example.org/complex")
      int input)
{
    System.out.println("echoInt '" + input + "' to you too!");
    return input;
}

// 標準 JWS 批註，將方法“echoStruct”公開爲
// 名爲“echoComplexType”的公共操作
// WebResult 批註用於指定生成的 WSDL 中的操作
// 結果的名稱爲“EchoStructReturnMessage”，
// 而不是默認名稱“return”。

@WebMethod(operationName="echoComplexType")
@WebResult(name="EchoStructReturnMessage",
             targetNamespace="http://example.org/complex")
public BasicStruct echoStruct(BasicStruct struct)
{
    System.out.println("echoComplexType called");
    return struct;
}
}

標準 JSR-181 JWS 批註參考

Web Services Metadata for the Java Platform (JSR-181) 規範定義了可在 JWS 文件中用來指定 Web Service 的形狀和行爲的標準批註。此部分簡要描述了每個批註以及它的特性。有關示例請參閱 JWS 文件編程。有關這些批註的更多詳細信息，如 Java 批註類型定義和其他示例，請參閱該規範。

此部分介紹了下列標準 JWS 批註：

javax.jws.WebService

描述

目標：類

指定實現 Web Service 的 JWS 文件。

特性

表 B-1 javax.jws.WebService JWS 批註的特性

名稱

描述

數據類型

是否必需？

name

Web Service 的名稱。映射到 WSDL 文件中的 <wsdl:portType> 元素。

默認值爲 JWS 文件中 Java 類的非限定名稱。

String

否

targetNamespace

用於從此 Web Service 生成的 WSDL 和 XML 元素的 XML 名稱空間。

默認值由 JAX-RPC specification 指定。

String

否

serviceName

Web Service 的服務名。映射到 WSDL 文件中的 <wsdl:service> 元素。

默認值爲 JWS 文件中 Java 類的非限定名稱，後面加上字符串 Service。

String

否

wsdlLocation

預定義 WSDL 文件的相對或絕對 URL。如果指定此特性，則當 JWS 文件與 WSDL 文件中的端口類型和綁定不一致時，jwsc Ant 任務不生成 WSDL 文件，並且會返回錯誤。

注意：	wsdlc Ant 任務從 WSDL 生成端點接口 JWS 文件時使用此特性。通常情況下，用戶在其自己的 JWS 文件中永遠不會使用該特性。

String

否

endpointInterface

現有服務端點接口文件的完全限定名稱。如果指定此特性，則假設您已經創建了該端點接口文件，並且該文件位於 CLASSPATH 中。

String

否

示例

@WebService(name="JMSTransportPortType",
serviceName="JMSTransportService",
targetNamespace="http://example.org")

javax.jws.WebMethod

描述

目標：方法

指定方法公開爲該 Web Service 的公共操作。必須明確使用此批註來公開方法；如果不指定此批註，該方法則默認爲不公開。

特性

表 B-2 javax.jws.WebMethod JWS 批註的特性
名稱	描述	數據類型	是否必需？
operationName	操作的名稱。映射到 WSDL 文件中的 <wsdl:operation> 元素。默認值爲該方法的名稱。	String	否
action	此操作的操作。對於 SOAP 綁定，此特性的值決定 SOAP 消息中 SOAPAction 頭的值。	String	否

示例

@WebMethod(operationName="echoComplexType")

public BasicStruct echoStruct(BasicStruct struct)
{
...
}

javax.jws.Oneway

描述

目標：方法

指定該方法只具有輸入參數，但不返回值。此批註必須只與 @WebMethod 批註一起使用。 13961657879

對於返回的內容不是 void、採用 Holder 類作爲輸入參數，或者拋出 checked 異常的方法使用此批註是錯誤的。

此批註沒有任何特性。

示例

@WebMethod()
@Oneway()
public void helloWorld(String input) {
...

}

javax.jws.WebParam

描述

目標：參數

自定義 Web Service 的操作輸入參數和生成的 WSDL 文件的元素之間的映射。還用於指定參數的行爲。

特性

表 B-3 javax.jws.WebParam JWS 批註的特性
名稱	描述	數據類型	是否必需？
name	WSDL 文件中參數的名稱。對於 RPC 樣式的 Web Service，該名稱映射到表示該參數的 <wsdl:part> 元素。對於文檔樣式的 Web Service，該名稱爲表示該參數的 XML 元素的本地名稱。默認值爲該方法的參數的名稱。	String	否
targetNamespace	該參數的 XML 名稱空間。此值僅用於文檔樣式的 Web Service，其中該參數映射到 XML 元素。默認值爲該 Web Service 的 targetNamespace。	String	否
mode	該參數的流方向。有效值爲： § WebParam.Mode.IN WebParam.Mode.OUT WebParam.Mode.INOUT 默認值爲 WebParam.Mode.IN。如果指定 WebParam.Mode.OUT 或 WebParam.Mode.INOUT，則該參數的數據類型必須爲 Holder 或擴展 Holder。有關詳細信息，請參閱 JAX-RPC specification。 WebParam.Mode.OUT 和 WebParam.Mode.INOUT 模式僅對於 RPC 樣式的 Web Service 或映射到頭的參數受支持。	enum	否
header	指定該參數的值是否存在於 SOAP 頭中。默認情況下，參數位於 SOAP 正文中。有效值爲 true 和 false。默認值爲 false。	boolean	否

示例

@WebMethod()
public int echoInt(
     @WebParam(name="IntegerInput",
               targetNamespace="http://example.org/complex")
     int input)
{
   ...
}

javax.jws.WebResult

描述

目標：方法

自定義 Web Service 操作返回值和生成的 WSDL 文件的對應元素之間的映射。

特性

表 B-4 javax.jws.WebResult JWS 批註的特性
名稱	描述	數據類型	是否必需？
name	WSDL 文件中參數的名稱。對於 RPC 樣式的 Web Service，該名稱映射到表示返回值的 <wsdl:part> 元素。對於文檔樣式的 Web Service，該名稱爲表示返回值的 XML 元素的本地名稱。默認值爲硬編碼名稱 result。	String	否
targetNamespace	返回值的 XML 名稱空間。此值僅用於文檔樣式的 Web Service，其中返回值映射到 XML 元素。默認值爲該 Web Service 的 targetNamespace。	String	否

示例

@WebMethod(operationName="echoComplexType")
@WebResult(name="EchoStructReturnMessage",
targetNamespace="http://example.org/complex")
public BasicStruct echoStruct(BasicStruct struct)
{
...
}

javax.jws.HandlerChain

描述

目標：類

將 Web Service 與包含處理程序鏈的配置的外部文件相關聯。配置包括鏈中處理程序的列表、它們的執行順序、初始化參數等。

如果爲下列情況，則請在 JWS 文件中使用 @HandlerChain 批註，而不要使用 @SOAPMessageHandlers 批註：

希望多個 Web Service 共享同一個配置。
處理程序鏈包括用於多個傳輸的處理程序。
希望能夠更改 Web Service 的處理程序鏈配置，且不重新編譯實現它的 JWS 文件。

將此批註與 @SOAPMessageHandlers 批註進行組合是錯誤的。

有關外部配置文件的 XML Schema、有關創建該文件的其他信息，以及其他示例，請參閱 Web Services Metadata for the Java Platform specification。

特性

表 B-5 javax.jws.HandlerChain JWS 批註的特性
名稱	描述	數據類型	是否必需？
file	處理程序鏈配置文件的相對或絕對 URL。相對 URL 爲相對於 JWS 文件位置的 URL。	String	是
name	希望與該 Web Service 相關聯的處理程序鏈的名稱（位於由 file 特性指向的配置文件中）。	String	是

示例

package examples.webservices.handler;

...

@WebService (...)

@HandlerChain(file="HandlerConfig.xml", name="SimpleChain")

public class HandlerChainImpl {

...

}

javax.jws.soap.SOAPBinding

描述

目標：類

指定 Web Service 到 SOAP 消息協議的映射。

特性

表 B-6 javax.jws.soap.SOAPBinding JWS 批註的特性

名稱

描述

數據類型

是否必需？

style

指定請求和響應 SOAP 消息的消息樣式。

有效值爲：

§ SOAPBinding.Style.RPC
SOAPBinding.Style.DOCUMENT。

默認值爲 SOAPBinding.Style.DOCUMENT。

enum

否

use

指定請求和響應 SOAP 消息的格式設置樣式。

有效值爲：

§ SOAPBinding.Use.LITERAL
SOAPBinding.Use.ENCODED

默認值爲 SOAPBinding.Use.LITERAL。

enum

否

parameterStyle

確定方法參數是否表示整個消息正文，或者這些參數是否爲包裝在根據該操作命名的頂級元素中的元素。

有效值爲：

§ SOAPBinding.ParameterStyle.BARE
SOAPBinding.ParameterStyle.WRAPPED

默認值爲 SOAPBinding.ParameterStyle.WRAPPED

注意：	此特性僅適用於 document-literal 樣式的 Web Service。換句話說，只有也將 style 特性設置爲 SOAPBinding.Style.DOCUMENT、use 特性設置爲 SOAPBinding.Use.LITERAL 的情況下才能指定此特性。

enum

否

示例

package examples.webservices.bindings;

...

@WebService (...)

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

public class BindingsImpl {

...

}

javax.jws.soap.SOAPMessageHandler

描述

目標：無；此批註只能在 @SOAPMessageHandler 數組內使用。

指定 @SOAPMessageHandler 數組中的某個特定 SOAP 消息處理程序。該批註包括指定該處理程序的類名、初始化參數、該處理程序處理的 SOAP 頭的列表等的特性。

特性

表 B-7 javax.jws.soap.SOAPMessageHandler JWS 批註的特性
名稱	描述	數據類型	是否必需？
name	SOAP 消息處理程序的名稱。默認值爲實現 Handler 接口（或擴展 GenericHandler 抽象類）的類的名稱。	String	否
className	處理程序類的名稱。	String	是
initParams	在初始化期間傳遞到該處理程序類的名稱/值對數組。	@InitParam 數組	否
roles	該處理程序實現的 SOAP 角色的列表。	String 數組	否
headers	該處理程序處理的 SOAP 頭的列表。此數組中的每個元素都包含一個定義該處理程序所處理的頭元素的 Qname。	String 數組	否

示例

package examples.webservices.handlers;

...

@WebService (...)

@SOAPMessageHandlers ( {
  @SOAPMessageHandler (
   className="examples.webservices.soap_handlers.simple.ServerHandler1"),
@SOAPMessageHandler (
   className="examples.webservices.soap_handlers.simple.ServerHandler2")
} )

public class HandlersImpl {

...

}

javax.jws.soap.InitParam

描述

目標：無；此批註只能用作 @SOAPMessageHandler 批註的 initParams 特性的值。

在 @SOAPMessageHandler 批註的 initParams 特性中使用此批註可指定在初始化期間傳遞到處理程序類的參數（名稱/值對）數組。

特性

表 B-8 javax.jws.soap.InitParam JWS 批註的特性
名稱	描述	數據類型	是否必需？
name	初始化參數的名稱。	String	是
value	初始化參數的值。	String	是

javax.jws.soap.SOAPMessageHandlers

描述

目標：類

指定在 Web Service 的操作之前和之後執行的 SOAP 消息處理程序數組。使用 @SOAPMessageHandler 批註可指定某個特定的處理程序。因爲在 JWS 文件本身中指定處理程序列表，所以處理程序鏈的配置嵌入在 Web Service 中。

如果屬於下列情況，則請使用 @SOAPMessageHandlers 批註，而不要使用 @HandlerChain：

希望將處理程序鏈的配置嵌入到 Web Service 本身內，而不是在外部文件中指定該配置。
處理程序鏈只包括 SOAP 處理程序，而不包括任何其他傳輸的處理程序。
希望每次更改處理程序鏈配置時都重新編譯 JWS 文件。

@SOAPMessageHandlers 批註是 @SOAPMessageHandler 類型數組。這些處理程序按照它們在批註中的顯示順序運行，首先運行數組中的第一個處理程序。

此批註沒有任何特性。

示例

package examples.webservices.handlers;

...

@WebService (...)

@SOAPMessageHandlers ( {
@SOAPMessageHandler (
className="examples.webservices.soap_handlers.simple.ServerHandler1"),
@SOAPMessageHandler (
className="examples.webservices.soap_handlers.simple.ServerHandler2")
} )

public class HandlersImpl {

...

}

WebLogic 特定的 JWS 批註參考

除了標準的 JSR-181 JWS 批註之外，WebLogic Web Service 還定義了一系列可以用來指定行爲和功能的 JWS 批註。具體來說，這些 WebLogic 特定的批註爲：

weblogic.jws.AsyncFailure

描述

目標：方法

指定處理主 JWS 文件異步調用另一個 Web Service 的操作時的潛在失敗的方法。

從 JWS 文件異步調用 Web Service 操作時，不會在操作調用之後立即返回響應（或發生失敗時的異常），而是在之後的某個時間點返回。因爲操作調用不會等待響應，所以在 JWS 文件中必須有一個單獨的方法在最終返回響應對其進行處理；與之相似，必須有另一個方法處理潛在的失敗。使用 @AsyncFailure 批註可在 JWS 文件中指定要處理異步操作調用的潛在失敗的方法。

@AsyncFailure 批註採用兩個參數：要調用的 Web Service 的 JAX-RPC 存根控件的名稱，以及要異步調用的操作的名稱。該 JAX-RPC 存根控件已經成爲了帶有 @ServiceClient 批註的批註。

處理異步失敗的方法必須遵守下列指南：

返回 void。
名稱爲 onMethodNameAsyncFailure，其中 MethodName 爲要異步調用的方法的名稱（首字母總是大寫）。

在主 JWS 文件中，對於異步方法的調用如下所示：

port.getQuoteAsync(apc, symbol);

其中 getQuote 爲該方法的非異步名稱，apc 爲異步預調用上下文，symbol 爲 getQuote 操作的一般參數。

具有兩個參數：異步調用後上下文（包含在 weblogic.wsee.async.AsyncPostCallContext 對象中）和 Throwable 異常（可能由異步操作調用拋出）。

在該方法自身中，您可以從上下文獲得該方法失敗的詳細信息，查詢特定類型的異常，並採取相應的操作。

通常情況下，總是使用 @AsyncFailure 批註來明確指定處理異步操作失敗的方法。只有在希望一個方法來處理調用多個不同 Web Service 的兩個或多個存根控件的失敗時，纔不使用此批註。這種情況下，儘管這些存根控件連接不同的 Web Service，但是每個 Web Service 必須具有名稱相似的方法，因爲 Web Service 運行時依賴方法名 (onMethodNameAsyncFailure) 來確定如何處理異步失敗，而不依賴批註。但是，如果您總是希望在存根控件和處理來自其中一個操作的異步失敗的方法之間存在一對一的對應關係，BEA 則建議您明確使用 @AsyncFailure。

有關使用此批註的詳細信息和示例，請參閱使用異步請求響應調用 Web Service。

特性

表 B-9 weblogic.jws.AsyncFailure JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
target	要異步調用其操作的 Web Service 的 JAX-RPC 存根控件的名稱。該存根控件已經使用 @ServiceClient 字段級別批註進行了批註。	String	是
operation	要異步調用的操作的名稱。這是該操作的實際名稱，與顯示在 WSDL 文件中的名稱相同。當您在 JWS 文件的主代碼中調用此操作時，要將 Async 添加到其名稱。例如，如果設置 operation="getQuote"，則在 JWS 文件中要按照下列方式對其進行異步調用： port.getQuoteAsync(apc, symbol);	String	是

示例

下面的示例代碼段顯示瞭如何在異步調用另一個 Web Service 的操作的 JWS 文件中使用 @AsyncFailure 批註；只包括了相關的 Java 代碼：

package examples.webservices.async_req_res;

...

public class StockQuoteClientImpl {

@ServiceClient(wsdlLocation="http://localhost:7001/async/StockQuote?WSDL",
serviceName="StockQuoteService", portName="StockQuote")
private StockQuotePortType port;

@WebMethodpublic void getQuote (String symbol) {

AsyncPreCallContext apc = AsyncCallContextFactory.getAsyncPreCallContext();
apc.setProperty("symbol", symbol);

    try {
      port.getQuoteAsync(apc, symbol );
      System.out.println("in getQuote method of StockQuoteClient WS");
    }
    catch (RemoteException e) {
      e.printStackTrace();
    }

}

...

@AsyncFailure(target="port", operation="getQuote")
public void onGetQuoteAsyncFailure(AsyncPostCallContext apc, Throwable e) {
    System.out.println("-------------------");
    e.printStackTrace();
    System.out.println("-------------------");
}

}

該示例顯示了一個名爲 port 的 JAX-RPC 存根控件，該存根控件用於調用位於 http://localhost:7001/async/StockQuote 的 Web Service。getQuote 操作是異步調用的，根據 @AsyncFailure 批註的指定，從此調用產生的任何異常都由 onGetQuoteAsyncFailure 方法處理。

weblogic.jws.AsyncResponse

描述

目標：方法

指定處理主 JWS 文件異步調用另一個 Web Service 的操作時的響應的方法。

從 JWS 文件異步調用 Web Service 操作時，不會在操作調用之後立即返回響應，而是在之後的某個時間點返回。因爲操作調用不會等待響應，所以在 JWS 文件中必須有一個單獨的方法在最終返回響應時對其進行處理。使用 @AsyncResponse 批註可在 JWS 文件中指定要處理異步操作調用的響應的方法。

@AsyncResponse 批註採用兩個參數：要調用的 Web Service 的 JAX-RPC 存根控件的名稱，以及要異步調用的操作的名稱。該 JAX-RPC 存根控件已經成爲了帶有 @ServiceClient 批註的批註。

處理異步響應的方法必須遵守下列指南：

返回 void。
名稱爲 onMethodNameAsyncResponse，其中 MethodName 爲要異步調用的方法的名稱（首字母總是大寫）。

在主 JWS 文件中，對於異步方法的調用如下所示：

port.getQuoteAsync(apc, symbol);

其中 getQuote 爲該方法的非異步名稱，apc 爲異步預調用上下文，symbol 爲 getQuote 操作的一般參數。

具有兩個參數：異步調用後上下文（包含在 weblogic.wsee.async.AsyncPostCallContext 對象中）和該操作的一般返回值。

在異步響應方法自身中，您要添加處理該響應的代碼。您還可以從上下文獲得有關該方法調用的詳細信息。

通常情況下，總是使用 @AsyncResponse 批註來明確指定處理異步操作響應的方法。只有在希望一個方法來處理調用多個不同 Web Service 的兩個或多個存根控件的響應時，纔不使用此批註。這種情況下，儘管這些存根控件連接不同的 Web Service，但是每個 Web Service 必須具有一個名稱相似的方法，因爲 Web Service 運行時依賴方法名 (onMethodNameAsyncResponse) 來確定如何處理異步響應，而不依賴批註。但是，如果您總是希望在存根控件和處理來自其中一個操作的異步響應的方法之間存在一對一的對應關係，BEA 則建議您明確使用 @AsyncResponse。

有關使用此批註的詳細信息和示例，請參閱使用異步請求響應調用 Web Service。

特性

表 B-10 weblogic.jws.AsyncResponse JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
target	要異步調用其操作的 Web Service 的 JAX-RPC 存根控件的名稱。該存根控件已經使用 @ServiceClient 字段級別批註進行了批註。	String	是
operation	要異步調用的操作的名稱。這是該操作的實際名稱，與顯示在 WSDL 文件中的名稱相同。當您在 JWS 文件的主代碼中調用此操作時，要將 Async 添加到其名稱。例如，如果設置 operation="getQuote"，則在 JWS 文件中要按照下列方式對其進行異步調用： port.getQuoteAsync(apc, symbol);	String	是

示例

下面的示例代碼段顯示瞭如何在異步調用另一個 Web Service 的操作的 JWS 文件中使用 @AsyncResponse 批註；只包括了相關的 Java 代碼：

package examples.webservices.async_req_res;

...

public class StockQuoteClientImpl {

@ServiceClient(wsdlLocation="http://localhost:7001/async/StockQuote?WSDL",
serviceName="StockQuoteService", portName="StockQuote")
private StockQuotePortType port;

@WebMethodpublic void getQuote (String symbol) {

AsyncPreCallContext apc = AsyncCallContextFactory.getAsyncPreCallContext();
apc.setProperty("symbol", symbol);

    try {
      port.getQuoteAsync(apc, symbol );
      System.out.println("in getQuote method of StockQuoteClient WS");
    }
    catch (RemoteException e) {
      e.printStackTrace();
    }

}

...

@AsyncResponse(target="port", operation="getQuote")
public void onGetQuoteAsyncResponse(AsyncPostCallContext apc, int quote) {
    System.out.println("-------------------");
    System.out.println("Got quote " + quote );
    System.out.println("-------------------");
}

}

該示例顯示了一個名爲 port 的 JAX-RPC 存根控件，該存根控件用於調用位於 http://localhost:7001/async/StockQuote 的 Web Service。getQuote 操作是異步調用的，根據 @AsyncResponse 批註的指定，從此調用產生的響應由 onGetQuoteAsyncResponse 方法處理。

weblogic.jws.Binding

描述

目標：類

指定接受或發送 SOAP 消息時 Web Service 使用版本 1.1 還是 1.2 的簡單對象訪問協議 (SOAP) 實現。默認情況下，WebLogic Web Service 使用 SOAP 1.1。

特性

表 B-11 weblogic.jws.Binding JWS 批註標記的特性

名稱

描述

數據類型

是否必需？

value

指定調用 Web Service 時請求和響應 SOAP 消息中使用的 SOAP 版本。

此特性的有效值爲：

§ Type.SOAP11
Type.SOAP12

默認值爲 Type.SOAP11。

enum

否

示例

下面的示例顯示瞭如何指定 SOAP 1.2；只顯示了相關代碼：

package examples.webservices.soap12;

...

import javax.jws.WebMethod;
import javax.jws.WebService;

import weblogic.jws.Binding;

@WebService(name="SOAP12PortType",
serviceName="SOAP12Service",
targetNamespace="http://example.org")

@Binding(Binding.Type.SOAP12)

public class SOAP12Impl {

@WebMethod()
public String sayHello(String message) {

...

}

weblogic.jws.BufferQueue

描述

目標：類

指定 WebLogic Server 存儲下列內容的 JMS 隊列的 JNDI 名稱：

緩衝 Web Service 操作調用。
可靠 Web Service 操作調用。

用於緩衝 Web Service 時，要將此批註與 @MessageBuffer 一起使用，後者指定緩衝的 JWS 的方法。用於可靠 Web Service 時，要將此批註與 @Policy 一起使用，後者指定與該 Web Service 相關聯的可靠消息傳送 WS-Policy 文件。

如果對於 Web Service 啓用了緩衝或可靠消息傳送，但未指定 @BuffereQueue 批註，WebLogic Server 則使用默認的 Web Service JMS 隊列 (weblogic.wsee.DefaultQueue) 來存儲緩衝操作調用或可靠操作調用。此 JMS 隊列也是多種 JMS 傳輸功能的默認隊列。如果您要將此 JMS 隊列用於這些功能之一，則會假設您已經創建了該隊列。

有關創建緩衝或可靠 Web Service 的詳細信息和示例，請參閱創建緩衝的 Web Service 和使用 Web Service 可靠消息傳遞。

特性

表 B-12 weblogic.jws.BufferQueue JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
name	緩衝操作調用或可靠操作調用排入其中的 JMS 隊列的 JNDI 名稱。	String	是

示例

下面的示例顯示了 JWS 文件中一個代碼段，在其中要緩衝公共操作，並且 WebLogic Server 將該操作調用排入其中的 JMS 隊列名爲 my.buffere.queue；只顯示了相關的 Java 代碼：

package examples.webservices.buffered;

...

@WebService(name="BufferedPortType",
serviceName="BufferedService",
targetNamespace="http://example.org")

@BufferQueue(name="my.buffer.queue")

public class BufferedImpl {

...

@WebMethod()
@MessageBuffer(retryCount=10, retryDelay="10 seconds")
@Oneway()
public void sayHelloNoReturn(String message) {
System.out.println("sayHelloNoReturn: " + message);
}
}

weblogic.jws.Callback

描述

目標：字段

指定批註的變量是回調，這就表示您可以使用該變量將回調事件返回到調用目標 Web Service 的操作的客戶端 Web Service。

您要在目標 Web Service 中指定 @Callback，以便它可以回調客戶端 Web Service。批註變量的數據類型爲回調接口。

回調功能在兩個 WebLogic Web Service 之間運行。但是當您編寫該功能的代碼時，要創建下列三個 Java 文件：

回調接口：用於定義回調方法的 Java 接口文件。您不用自己明確實現此文件；而由 jwsc Ant 任務自動生成該接口的實現。該實現只需將消息從目標 Web Service 傳遞迴客戶端 Web Service。生成的 Web Service 將部署到承載客戶端 Web Service 的同一 WebLogic Server 中。
用於實現目標 Web Service 的 JWS 文件：目標 Web Service 包含一個或多個用於調用回調接口中所定義方法的標準操作；此方法又會將消息發送回最初調用目標 Web Service 操作的客戶端 Web Service。
用於實現客戶端 Web Service 的 JWS 文件：客戶端 Web Service 可以調用目標 Web Service 的操作。此 Web Service 包含一個或多個方法，這些方法可指定當客戶端通過回調方法從目標 Web Service 中收到回調消息時應採取的操作。

有關回調編程的其他概述和過程信息，請參閱使用回調通知客戶端所發生的事件。

@Callback 批註沒有任何特性。

示例

下列示例顯示了一個非常簡單的目標 Web Service，在其中使用 @Callback 批註對名爲 callback 的變量進行了批註。該變量的數據類型爲 CallbackInterface；這就表示必須存在具有此名稱的回調 Web Service。將回調信息注入到該變量之後，可以調用 CallbackInterface 中定義的回調方法；在該示例中，該回調方法爲 callbackOperation()。

粗體文本顯示了相關代碼：

package examples.webservices.callback;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Callback;

import javax.jws.WebService;
import javax.jws.WebMethod;

@WebService(name="CallbackPortType",
serviceName="TargetService",
targetNamespace="http://examples.org/")

@WLHttpTransport(contextPath="callback",
serviceUri="TargetService",
portName="TargetServicePort")

public class TargetServiceImpl {

@Callback
CallbackInterface callback;

@WebMethod
public void targetOperation (String message) {

callback.callbackOperation (message);

}

weblogic.jws.CallbackMethod

描述

目標：方法

指定客戶端 Web Service 中處理它從回調 Web Service 收到的消息的方法。使用特性可將客戶端 Web Service 中的回調消息處理程序方法與回調接口中的回調方法進行鏈接。

回調功能在兩個 WebLogic Web Service 之間運行。但是當您編寫該功能的代碼時，要創建下列三個 Java 文件：

回調接口：用於定義回調方法的 Java 接口文件。您不用自己明確實現此文件；而由 jwsc Ant 任務自動生成該接口的實現。該實現只需將消息從目標 Web Service 傳遞迴客戶端 Web Service。生成的 Web Service 將部署到承載客戶端 Web Service 的同一 WebLogic Server 中。
用於實現目標 Web Service 的 JWS 文件：目標 Web Service 包含一個或多個用於調用回調接口中所定義方法的標準操作；此方法又會將消息發送回最初調用目標 Web Service 操作的客戶端 Web Service。
用於實現客戶端 Web Service 的 JWS 文件：客戶端 Web Service 可以調用目標 Web Service 的操作。此 Web Service 包含一個或多個方法，這些方法可指定當客戶端通過回調方法從目標 Web Service 中收到回調消息時應採取的操作。

有關回調編程的其他概述和過程信息，請參閱使用回調通知客戶端所發生的事件。

特性

表 B-13 weblogic.jws.CallbackMethod JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
operation	指定調用接口中的回調方法的名稱，此方法將要爲該調用接口處理回調消息。	String	是
target	指定要爲其接收回調的 JAX-RPC 存根控件的名稱。該存根控件已經使用 @ServiceClient 字段級別批註進行了批註。	String	是

示例

下列示例顯示了使用 @CallbackMethod 批註進行了批註的客戶端 Web Service 的方法。這些特性顯示，名爲 port 的變量必須以前已經注入了 JAX-RPC 存根控件信息，該批註的方法將處理從名爲 callbackOperation() 的回調操作接收的消息。

@CallbackMethod(target="port", operation="callbackOperation")
@CallbackRolesAllowed(@SecurityRole(role="engineer", mapToPrincipals="shackell"))
public void callbackHandler(String msg) {

System.out.println (msg);

}

weblogic.jws.CallbackService

描述

目標：類

指定該 JWS 文件實際上是描述回調 Web Service 的 Java 接口。此批註與 @javax.jws.WebService 相似，但是特定於回調，並且具有的特性較少。

回調功能在兩個 WebLogic Web Service 之間運行。但是當您編寫該功能的代碼時，要創建下列三個 Java 文件：

回調接口：用於定義回調方法的 Java 接口文件。您不用自己明確實現此文件；而由 jwsc Ant 任務自動生成該接口的實現。該實現只需將消息從目標 Web Service 傳遞迴客戶端 Web Service。生成的 Web Service 將部署到承載客戶端 Web Service 的同一 WebLogic Server 中。
用於實現目標 Web Service 的 JWS 文件：目標 Web Service 包含一個或多個用於調用回調接口中所定義方法的標準操作；此方法又會將消息發送回最初調用目標 Web Service 操作的客戶端 Web Service。
用於實現客戶端 Web Service 的 JWS 文件：客戶端 Web Service 可以調用目標 Web Service 的操作。此 Web Service 包含一個或多個方法，這些方法可指定當客戶端通過回調方法從目標 Web Service 中收到回調消息時應採取的操作。

使用 @CallbackInterface 批註可指定該 Java 文件爲回調接口文件。

編寫回調接口的代碼時，您要指定一個或多個回調方法；與標準非回調 Web Service 相同，使用 @javax.jws.WebMethod 批註對這些方法進行批註可指定它們是 Web Service 操作。但與非回調方法不同的是，永遠不要編寫這些回調方法的實際實現代碼；而當您使用 jwsc Ant 任務編譯客戶端 Web Service 時，該任務將自動創建該接口的實現，並將其打包到 Web Service 中。這種生成的實現指定這些回調方法全部執行相同的任務：從調用該回調方法的目標 Web Service 向客戶端 Web Service 發回消息。

有關回調編程的其他概述和過程信息，請參閱使用回調通知客戶端所發生的事件。

特性

表 B-14 weblogic.jws.CallbackService JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
name	回調 Web Service 的名稱。映射到 WSDL 文件中的 <wsdl:portType> 元素。默認值爲 JWS 文件中 Java 類的非限定名稱。	String	否
serviceName	回調 Web Service 的服務名。映射到 WSDL 文件中的 <wsdl:service> 元素。默認值爲 JWS 文件中 Java 類的非限定名稱，後面加上字符串 Service。	String	否

示例

下列示例顯示了一個非常簡單的回調接口。生成的回調 Web Service 具有一個回調方法，callbackOperation()。

package examples.webservices.callback;

import weblogic.jws.CallbackService;

import javax.jws.Oneway;
import javax.jws.WebMethod;

@CallbackService

public interface CallbackInterface {

@WebMethod
@Oneway
public void callbackOperation (String msg);

}

weblogic.jws.Context

描述

目標：字段

指定提供對於 Web Service 的運行時上下文的訪問權限的批註字段。

當客戶端應用程序調用使用 JWS 文件實現的 WebLogic Web Service 時，WebLogic Server 會自動創建一個上下文，Web Service 可以使用該上下文來訪問有關該服務的運行時信息，有時還可以更改這些信息。此信息主要與對話相關，例如當前對話是否已完成、對話屬性的當前值以及在運行時更改對話屬性等。可以通過該上下文訪問的某些信息更爲通用，如用於調用該 Web Service 的協議（HTTP/S 或 JMS）、SOAP 消息請求中的 SOAP 頭等。該批註字段的數據類型必須爲 weblogic.wsee.jws.JwsContext，這是包括可查詢該上下文的方法的 WebLogic Web Service API。

有關使用此批註的其他信息，請參閱使用 JwsContext 訪問有關 Web Service 的運行時信息。

此批註沒有任何特性。

示例

下列 JWS 文件代碼段顯示瞭如何使用 @Context 批註；只顯示了文件的一些部分，相關代碼以粗體顯示：

...

import weblogic.jws.Context;

import weblogic.wsee.jws.JwsContext;

...

public class JwsContextImpl {

@Context
private JwsContext ctx;

@WebMethod()
public String getProtocol() {

...

weblogic.jws.Conversation

描述

目標：方法

指定使用 @Conversation 批註進行批註的方法可以作爲兩個 WebLogic Web Service 之間或一個獨立 Java 客戶端和一個對話 Web Service 之間對話的一部分進行調用。

對話 Web Service 通常指定三個方法，每個方法分別使用與對話的啓動、持續和完成階段相對應的 @Conversation 批註進行批註。使用 @Conversational 批註可以在類級別指定某個 Web Service 爲對話 Web Service，還可以配置該對話的屬性，如最長空閒時間。

如果該對話爲兩個 Web Service 之間的對話，客戶端服務則使用 @ServiceClient 批註指定被調用對話服務的 wsdl、服務名和端口。在服務客戶端和獨立客戶端兩種情況下，該客戶端之後都會按照合適的順序調用啓動、持續和完成方法，以執行對話。使得某個 Web Service 成爲對話 Web Service 的唯一附加要求是它要實現 java.io.Serializable。

有關使用此批註的詳細信息和示例，請參閱創建對話 Web Service。

特性

表 B-15 weblogic.jws.Conversation JWS 批註標記的特性

名稱

描述

數據類型

是否必需？

value

指定批註的方法實現的對話階段。

可能的值有：

§ Phase.START

指定該方法啓動一個新對話。調用此方法會創建新的對話 ID 和上下文，還會重置其空閒計時器和期限計時器。

Phase.CONTINUE

指定該方法是正在進行的某個對話的一部分。調用此方法會重置空閒計時器。此方法必須總是在啓動方法之後、完成方法之前調用。

Phase.FINISH

指定該方法明確完成正在進行的對話。

默認值爲 Phase.CONTINUE

enum

否

示例

下列示例代碼段顯示了一個包含三個方法（start、middle 和 finish）的 JWS 文件，這三個方法使用 @Conversation 批註進行了批註，分別指定對話的啓動、持續和完成階段。

...

public class ConversationalServiceImpl implements Serializable {

@WebMethod
@Conversation (Conversation.Phase.START)
public String start() {
// 此處爲啓動對話的 Java 代碼
}

@WebMethod
@Conversation (Conversation.Phase.CONTINUE)
public String middle(String message) {
// 此處爲繼續對話的 Java 代碼
}

@WebMethod
@Conversation (Conversation.Phase.FINISH)
public String finish(String message ) {
// 此處爲完成對話的 Java 代碼
}

}

weblogic.jws.Conversational

描述

目標：類

指定 JWS 文件實現對話 Web Service。

不一定非要使用此批註來指定 Web Service 爲對話 Web Service；使用 @Conversation 批註對一個方法進行批註，該 JWS 文件的所有方法即全部自動標記爲對話方法。只有當您希望更改某些對話行爲或者希望在類級別清楚顯示該 JWS 爲對話型時，才使用類級別的 @Conversational 批註。

如果在 JWS 文件確實使用了 @Conversational 批註，並且其特性的默認值滿足您的需求，則可以不帶任何特性指定該批註。但是，如果要更改一些值（如對話可以保持空閒狀態的最長時間、對話的最長期限等），則請指定相應的特性。

有關使用此批註的詳細信息和示例，請參閱創建對話 Web Service。

特性

表 B-16 weblogic.jws.Conversational JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
maxIdleTime	指定對話在由 WebLogic Server 完成之前可以保持空閒狀態的時間長度。活動由執行該對話的其中一個階段的客戶端 Web Service 定義。有效值爲數字並帶有下列單位之一： § seconds minutes hours § days § years 例如，要指定最長空閒時間爲十分鐘，請按照下列方式指定該批註： @Conversational(maxIdleTime="10 minutes") 如果指定零長度值（如 0 seconds 或 0 minutes 等），則由於不活動該對話永遠不會超時。默認值爲 0 seconds。	String	否
maxAge	指定對話在由 WebLogic Server 完成之前可以保持活動狀態的時間長度。有效值爲數字並帶有下列單位之一： § seconds minutes hours § days § years 例如，要指定最長期限爲三天，請按照下列方式指定該批註： @Conversational(maxAge="3 days") 默認值爲 1 day。	String	否
runAsStartUser	指定是否作爲啓動現有對話的用戶運行該對話的持續和完成階段。通常情況下，由同一個用戶執行對話的啓動、持續和完成方法，這樣可以使得此特性的值更改無效。但是，如果將 singlePrincipal 特性設置爲 false，即允許執行現有對話的持續和完成階段的用戶與啓動該對話的用戶不同，則 runAsStartUser 特性會指定這些方法實際以什麼用戶運行：啓動該對話的用戶，還是執行該對話後續階段的其他用戶。有效值爲 true 和 false。默認值爲 false。	boolean	否
singlePrincipal	指定是否允許與啓動對話的用戶不同的用戶來執行該對話的持續和完成階段。通常情況下，同一個用戶執行對話的所有階段。但如果將此特性設置爲 false，則其他用戶可以獲取現有對話的對話 ID，並使用它來執行該對話的後續階段。有效值爲 true 和 false。默認值爲 false。	boolean	否

示例

下列示例代碼段顯示瞭如何指定 JWS 文件實現對話 Web Service。該對話的最長空閒時間爲十分鐘，無論是否活動，該對話的最長期限都爲一天。該對話的持續和完成階段可由與啓動該對話的用戶不同的用戶執行；如果發生這種情況，則作爲該新用戶運行相應的方法，而不作爲原始用戶運行。

package examples.webservices.conversation;

...

@Conversational(maxIdleTime="10 minutes",
                maxAge="1 day",
                runAsStartUser=false,
                singlePrincipal=false )

public class ConversationalServiceImpl implements Serializable {

...

weblogic.jws.MessageBuffer

描述

目標：類、方法

指定緩衝 JWS 的哪些公共方法。如果在類級別指定，則緩衝所有公共方法；如果希望只緩衝其中部分方法，則在相應的方法級別指定該批註。

當客戶端 Web Service 調用另一個 WebLogic Web Service 的緩衝操作時，WebLogic Server（承載被調用 Web Service）則會將調用消息置於某個 JMS 隊列中，以後當該 WebLogic Server 將該消息從 JMS 隊列的頂級傳遞到該 Web Service 實現時才處理真正的調用。該客戶端不需要等待響應，而是繼續它的執行。因此，緩衝的操作（不帶任何附加異步功能）只能返回 void 並且必須使用 @Oneway 批註進行標記。如果希望緩衝返回值的操作，則必須從調用客戶端 Web Service 使用異步請求-響應。有關詳細信息，請參閱使用異步請求響應調用 Web Service。

緩衝僅在一個調用另一個的緩衝操作的兩個 Web Service 之間運行。

使用 @MessageBuffer 的可選特性可指定 JMS 隊列嘗試調用緩衝的 Web Service 操作直到調用成功的次數，以及嘗試之間的時間長度。

使用可選的類級別 @BufferQueue 批註可以指定調用消息要排入其中的 JMS 隊列。如果不指定此批註，這些消息則排入默認的 Web Service 隊列 weblogic.wsee.DefaultQueue 中。

有關使用此批註的詳細信息和示例，請參閱創建緩衝的 Web Service。

特性

表 B-17 weblogic.jws.MessageBuffer JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
retryCount	指定被調用 WebLogic Server 實例上的 JMS 隊列嘗試將調用消息傳遞到 Web Service 實現直到操作成功調用的次數。默認值爲 3。	int	否
retryDelay	指定消息傳遞重試嘗試之間的時間長度。這些重試嘗試在 JMS 隊列上的調用消息和該消息傳遞到 Web Service 實現之間進行。有效值爲數字並帶有下列單位之一： § seconds minutes hours § days § years 例如，要指定重試延遲爲兩天，請指定： @MessageBuffer(retryDelay="2 days") 默認值爲 5 seconds.。	String	否

示例

下列示例顯示了 JWS 文件中的一個代碼段，在其中要緩衝公共操作 sayHelloNoReturn，WebLogic Server 將該操作調用排入其中的 JMS 隊列名爲 my.buffere.queue。承載被調用 Web Service 的 WebLogic Server 實例最多嘗試 10 次將調用消息從 JMS 隊列傳遞到 Web Service 實現，每次重試之間等待 10 秒鐘。下列代碼段中只顯示了相關的 Java 代碼：

package examples.webservices.buffered;

...

@WebService(name="BufferedPortType",
serviceName="BufferedService",
targetNamespace="http://example.org")

@BufferQueue(name="my.buffer.queue")

public class BufferedImpl {

...

@WebMethod()
@MessageBuffer(retryCount=10, retryDelay="10 seconds")
@Oneway()
public void sayHelloNoReturn(String message) {
System.out.println("sayHelloNoReturn: " + message);
}
}

weblogic.jws.Policies

描述

目標：類、方法

指定 @weblogic.jws.Policy 批註數組。

如果希望將多個 WS-Policy 文件附加到 JWS 文件的某個類或方法，則使用此批註。如果只希望附加一個 WS-Policy 文件，則可以在其自身上使用 @weblogic.jws.Policy。

有關使用此批註的詳細信息和示例，請參閱使用 Web Service 可靠消息傳遞和配置消息級安全（數字簽名和加密）。

此 JWS 批註沒有任何特性。

示例

@Policies({
@Policy(uri="policy:firstPolicy.xml"),
@Policy(uri="policy:secondPolicy.xml")
})

weblogic.jws.Policy

描述

目標：類、方法

指定應向請求或響應 SOAP 消息應用包含數字簽名、加密或 Web Service 可靠消息傳送的 WS-Policy 文件。

此批註可在其自身上使用，以便將一個 WS-Policy 文件應用於某個類或方法。如果要將多個 WS-Policy 文件應用於某個類或方法，則請使用 @weblogic.jws.Policies 批註將它們組合到一起。

如果在類級別指定此批註，則指明的一個或多個 WS-Policy 文件將應用於該 Web Service 的每個公共操作。如果在方法級別指定該批註，則只有相應的操作將應用該 WS-Policy 文件。

默認情況下，WS-Policy 文件同時應用於請求（入站）和響應（出站）SOAP 消息。您可以使用 direction 特性更改此默認行爲。

另外，默認情況下，指定的 WS-Policy 文件會附加到該 Web Service 的生成併發布的 WSDL 文件，以便使用者可以查看該 Web Service 的所有 WS-Policy 要求。使用 attachToWsdl 特性可以更改此默認行爲。

有關使用此批註的詳細信息和示例，請參閱使用 Web Service 可靠消息傳遞和配置消息級安全（數字簽名和加密）。

警告：	對於所有 JWS 批註來說，都不能在運行時替換 @Policy 批註，這就表示在生成時使用該批註指定的 WS-Policy 文件將總是與 Web Service 相關聯。例如，這意味着儘管可以在運行時使用管理控制檯查看相關的 WS-Policy 文件，但不能刪除（取消關聯）該文件。但您可以使用控制檯關聯其他 WS-Policy 文件，有關詳細說明，請參閱將 Web Service 與 WS-Policy 文件關聯。

特性

表 B-18 weblogic.jws.Policies JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
uri	指定從中檢索 WS-Policy 文件的位置。使用 http: 前綴可指定 Web 上 WS-Policy 文件的 URL。使用 policy: 前綴可指定 WS-Policy 文件打包在 Web Service 歸檔文件中或 WebLogic Server 的可共享 J2EE 庫中，如下列示例所示： @Policy(uri="policy:MyPolicyFile.xml") 如果您要在 Web Service 歸檔文件中發佈 WS-Policy 文件，則該 WS-Policy XML 文件必須分別位於 EJB JAR 文件（用於 EJB 實現的 Web Service）或 WAR 文件（用於 Java 類實現的 Web Service）的 META-INF/policies 或 WEB-INF/policies 目錄中。有關在庫中發佈 WS-Policy 文件的信息，請參閱創建共享 J2EE 庫和可選包。	String	是
direction	指定何時在入站請求 SOAP 消息、出站響應 SOAP 消息或兩個消息上同時（默認）應用該 policy:。此特性的有效值爲： § Policy.Direction.both Policy.Direction.inbound Policy.Direction.outbound 默認值爲 Policy.Direction.both。	enum	否
attachToWsdl	指定 WS-Policy 文件是否應附加到描述該 Web Service 的 WSDL。有效值爲 true 和 false。默認值爲 false。	boolean	否

示例

@Policy(uri="policy:myPolicy.xml",
attachToWsdl=true,
direction=Policy.Direction.outbound)

weblogic.jws.ReliabilityBuffer

描述

目標：方法

使用此批註可爲可靠 Web Service 的操作配置可靠消息傳送屬性，如 WebLogic Server 將消息從 JMS 隊列傳遞到 Web Service 實現應嘗試的次數，以及該服務器在重試之間應該等待的時間長度。

注意：	當您在 JWS 文件中指定此批註時，將通過同時包括指定具有 Web Service 可靠消息傳送策略聲明的 WS-Policy 文件的 @Policy，從而假設已經爲該 Web Service 啓用了可靠消息傳送。

注意：	如果指定 @ReliabilityBuffer 批註，但是不使用相關聯的 WS-Policy 文件啓用可靠消息傳送，WebLogic Server 則會忽略此批註。

有關爲 Web Service 啓用 Web Service 可靠消息傳送的詳細信息，請參閱使用 Web Service 可靠消息傳遞。

特性

表 B-19 weblogic.jws.ReliabilityBuffer JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
retryCount	指定目標 WebLogic Server 實例上的 JMS 隊列嘗試將消息從調用可靠操作的客戶端傳遞到 Web Service 實現的次數。默認值爲 3。	int	否
retryDelay	指定消息傳遞重試嘗試之間的時間長度。這些重試嘗試在 JMS 隊列上的客戶端請求消息和該消息傳遞到 Web Service 實現之間進行。有效值爲數字並帶有下列單位之一： § seconds minutes hours § days § years 例如，要指定重試延遲爲兩天，請指定： @ReliabilityBuffer(retryDelay="2 days") 默認值爲 5 seconds.。	String	否

示例

下列示例代碼段顯示瞭如何在方法級別使用 @ReliabilityBuffer 批註來更改可靠操作的默認重試次數和延遲；只顯示了相關的 Java 代碼：

package examples.webservices.reliable;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.Oneway;

...

import weblogic.jws.ReliabilityBuffer;
import weblogic.jws.Policy;

@WebService(name="ReliableHelloWorldPortType",
serviceName="ReliableHelloWorldService")

...

@Policy(uri="ReliableHelloWorldPolicy.xml",
direction=Policy.Direction.inbound,
attachToWsdl=true)

public class ReliableHelloWorldImpl {

@WebMethod()
@Oneway()
@ReliabilityBuffer(retryCount=10, retryDelay="10 seconds")

public void helloWorld(String input) {
System.out.println(" Hello World " + input);

}
}

weblogic.jws.ReliabilityErrorHandler

描述

目標：方法

指定處理當客戶端 Web Service 調用可靠 Web Service，但該客戶端未收到該可靠 Web Service 真正收到該消息的確認的情況下所產生錯誤的方法。

此批註僅在實現 Web Service 可靠消息傳送功能時相關；您要在調用可靠 Web Service 的客戶端 Web Service 中指定該批註。

使用 @ReliabilityErrorHandler 批註進行批註的方法採用數據類型爲 weblogic.wsee.reliability.ReliabilityErrorContext 的單個參數。您可以使用此上下文獲得有關該錯誤起因的詳細信息，如導致該錯誤的操作、目標 Web Service、錯誤等。該方法必須返回 void。

@ReliabilityErrorHandler 批註的唯一一個特性指定以前已經將客戶端 Web Service 調用的可靠 Web Service 的JAX-RPC 存根控件信息注入到其中的變量；使用 @weblogic.jws.ServiceClient 批註將此信息注入到變量中。

特性

表 B-20 weblogic.jws.ReliabilityErrorHandler JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
target	指定此方法爲其處理可靠性失敗的目標存根控件的名稱。	String	是

示例

調用可靠 Web Service 的某個客戶端 Web Service 中的下列代碼段顯示瞭如何使用 @ReliabilityErrorHandler 批註；並未顯示所有代碼，與此批註相關的代碼以粗體顯示：

package examples.webservices.reliable;

...

import weblogic.jws.ServiceClient;
import weblogic.jws.ReliabilityErrorHandler;

import examples.webservices.reliable.ReliableHelloWorldPortType;

import weblogic.wsee.reliability.ReliabilityErrorContext;
import weblogic.wsee.reliability.ReliableDeliveryException;

@WebService(name="ReliableClientPortType",
...

public class ReliableClientImpl

{

@ServiceClient(
     wsdlLocation="http://localhost:7001/ReliableHelloWorld/ReliableHelloWorld?WSDL",
     serviceName="ReliableHelloWorldService",
     portName="ReliableHelloWorldServicePort")

private ReliableHelloWorldPortType port;

@WebMethod
public void callHelloWorld(String input, String serviceUrl)
throws RemoteException {

...

}

@ReliabilityErrorHandler(target="port")
public void onReliableMessageDeliveryError(ReliabilityErrorContext ctx) {

    ReliableDeliveryException fault = ctx.getFault();
    String message = null;
    if (fault != null) {
      message = ctx.getFault().getMessage();
    }
    String operation = ctx.getOperationName();
    System.out.println("Reliable operation " + operation + " may have not invoked.The error message is " + message);
}

}

在該示例中，port 變量已經注入了與 ReliableHelloWorldService Web Service 相對應的 JAX-RPC 存根控件，並且假設在該客戶端 Web Service 的某個位置調用了此存根控件的操作。因爲使用 @ReliabilityErrorHandler 批註對 onReliableMessageDeliveryError 方法進行了批註，並且該方法與 port JAX-RPC 存根控件相鏈接，所以如果該可靠 Web Service 的調用中存在失敗的話，則會調用該方法。可靠錯誤處理方法使用 ReliabilityErrorContext 對象獲取有關失敗起因的更多詳細信息。

weblogic.jws.ServiceClient

描述

目標：字段

指定使用下列功能時 JWS 文件中批註的變量是用於調用另一個 WebLogic Web Service 的 JAX-RPC 存根控件：

Web Service 可靠消息傳送
異步請求-響應
對話

可靠消息傳送和異步請求-響應功能只在兩個 Web Service 之間使用；例如，這意味着您只能從另一個 Web Service 調用可靠 Web Service 操作，而不能從獨立客戶端進行調用。如果是可靠消息傳送，該功能則在實現 WS-ReliableMessaging 1.0 規範的任意兩個應用服務器之間運行。如果是異步請求-響應，該功能則只能在兩個 WebLogic Server 實例之間運行。

在客戶端 Web Service 中使用 @ServiceClient 批註可指定哪個變量是 @ServiceClient 特性描述的 Web Service 的 JAX-RPC 端口類型。包含客戶端 Web Service 的企業應用程序必須還包括要調用的 Web Service 的 JAX-RPC 存根控件；您要使用 clientgen Ant 任務生成這些存根控件。

有關使用 @ServiceClient 批註的其他信息和示例，請參閱高級 JWS 編程：實現異步功能。

特性

表 B-21 weblogic.jws.ServiceClient JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
serviceName	指定要調用的 Web Service 的名稱。對應於被調用 Web Service 的 WSDL 中 <service> 元素的 name 特性。如果使用 JWS 文件實現了被調用的 Web Service，此特性則對應於被調用 Web Service 的 @WebService JWS 批註的 serviceName 特性。	String	是
portName	指定要調用的 Web Service 的端口名。對應於<service> 元素的 <port> 子元素的 name 特性。如果使用 JWS 文件實現了被調用的 Web Service，此特性則對應於被調用 Web Service 的 @WLHttpTransport JWS 批註的 portName 特性。如果不指定此特性，則假設 WSDL 中的 <service> 元素僅包含一個 <port> 子元素，@ServiceClient 使用該子元素。如果具有多個端口，客戶端 Web Service 則返回運行時異常。	String	否
wsdlLocation	指定描述要調用的 Web Service 的 WSDL 文件。如果不指定此特性，客戶端 Web Service 則使用 clientgen Ant 任務從中創建了要調用 Web Service 的 JAX-RPC Service 實現的 WSDL 文件。	String	否
endpointAddress	指定要調用 Web Service 的端點地址。如果不指定此特性，客戶端 Web Service 則使用 WSDL 文件中指定的端點地址。	String	否

示例

下列 JWS 文件節選顯示瞭如何在客戶端 Web Service 中使用 @ServiceClient 批註來批註帶有要調用 Web Service（名爲 ReliableHelloWorldService，其 WSDL 位於 URL http://localhost:7001/ReliableHelloWorld/ReliableHelloWorld?WSDL）的 JAX-RPC 存根控件的字段 (port)；僅顯示了該示例的相關部分：

package examples.webservices.reliable;

import javax.jws.WebService;

...

import weblogic.jws.ServiceClient;

import examples.webservices.reliable.ReliableHelloWorldPortType;

@WebService(...

public class ReliableClientImpl

{

@ServiceClient(

     wsdlLocation="http://localhost:7001/ReliableHelloWorld/ReliableHelloWorld?WSDL",
     serviceName="ReliableHelloWorldService",
     portName="ReliableHelloWorldServicePort")

private ReliableHelloWorldPortType port;

@WebMethod

public void callHelloWorld(String input, String serviceUrl)

throws RemoteException {

port.helloWorld(input);

System.out.println(" Invoked the ReliableHelloWorld.helloWorld operation reliably." );

}

weblogic.jws.StreamAttachments

描述

目標：類

指定 WebLogic Web Service 運行時在讀取 Web Service 的所有方法的參數時使用流 API。這樣會增強 Web Service 操作調用的性能，尤其當參數較大（如圖像）時更是如此。

如果在同一 Web Service 中使用下列功能則不能使用此批註：

對話
可靠消息傳送
JMS 傳輸
客戶端應用程序和它調用的 Web Service 之間的代理服務器

@StreamAttachments 批註沒有任何特性。

示例

下列簡單的 JWS 文件顯示瞭如何指定 @StreamAttachments 批註；唯一的方法 echoAttachment() 只是採用 DataHandler 參數，並將其回送回調用該 Web Service 操作的客戶端應用程序。WebLogic Web Service 運行時在讀取 DataHandler 內容時使用流。

package examples.webservices.stream_attach;

import javax.jws.WebMethod;
import javax.jws.WebService;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.StreamAttachments;

import javax.activation.DataHandler;

import java.rmi.RemoteException;

@WebService(name="StreamAttachPortType",
serviceName="StreamAttachService",
targetNamespace="http://example.org")

@WLHttpTransport(contextPath="stream_attach",
serviceUri="StreamAttachService",
portName="StreamAttachServicePort")

@StreamAttachments

/**
* 流附件示例
*/

public class StreamAttachImpl {

@WebMethod()
public DataHandler echoAttachment(DataHandler dh) throws RemoteException {

return dh;

}
}

weblogic.jws.Transactional

描述

目標：類、方法

指定批註的操作或 JWS 文件中的所有操作（在類級別指定該批註時）是否在事務內運行。默認情況下，操作不在事務內運行。

特性

表 B-22 weblogic.jws.Transactional JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
value	指定操作（在方法級別使用時）或 Web Service 的所有操作（在類級別指定時）是否在事務內運行。有效值爲 true 和 false。默認值爲 false。	boolean	否
timeout	指定當前事務的超時值（秒）。此特性的默認值爲 30 秒。	int	否

示例

下列示例顯示瞭如何使用 @Transactional 批註來指定 Web Service 的操作作爲事務的一部分執行：

package examples.webservices.transactional;

import javax.jws.WebMethod;
import javax.jws.WebService;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Transactional;

@WebService(name="TransactionPojoPortType",
serviceName="TransactionPojoService",
targetNamespace="http://example.org")

@WLHttpTransport(contextPath="transactionsPojo",
serviceUri="TransactionPojoService",
portName="TransactionPojoPort")

/**
* 此 JWS 文件形成了帶有下列單個操作的簡單 WebLogic
* Web Service 的基礎：sayHello。此操作作爲事務的一部分
* 執行。
*
* @作者版權所有 (c) 2004，BEA Systems。保留所有權利。
*/

public class TransactionPojoImpl {

@WebMethod()
@Transactional(value=true)

public String sayHello(String message) {
System.out.println("sayHello:" + message);
return "Here is the message: '" + message + "'";
}

}

weblogic.jws.Types

描述

目標：方法、參數

指定返回類型或參數的備用數據類型的完全限定 Java 類名稱的逗號分隔列表。這些備用數據類型必須擴展方法簽名中指定的數據類型；如果不擴展，當您將 JWS 文件編譯到 Web Service 中時，jwsc Ant 任務則會返回驗證錯誤。

例如，假設您創建了 Address 基本數據類型，然後創建了擴展此基本類型的 USAAddress 和 CAAddress。如果方法簽名指定它採用 Address 參數，則可以使用 @Types 批註來對該參數進行批註，以指定公共操作除了基本數據類型 Address 之外還採用 USAAddress 和 CAAddress 作爲參數。

您還可以使用此批註來限制可包含在集合數據類型（如 java.util.Collection 或 java.util.List）的參數或返回值中的數據類型。通過限制允許的包含數據類型，生成的 WSDL 是特定的並且是明確的，當客戶端應用程序調用 Web Service 操作時，Web Service 運行時在限定參數方面將具有更高的性能。

如果在方法級別指定此批註，它則只應用於返回值。如果希望該批註應用於參數，則必須在每個相關參數的參數級別指定該批註。

特性

表 B-23 weblogic.jws.Types JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
value	可代替原始數據類型使用的備用數據類型或者包含在集合類型參數或返回值中的允許數據類型的完全限定類名稱的逗號分隔列表。	String[]	是

示例

下列示例顯示了一個使用 @Types 批註的簡單 JWS 文件，相關 Java 代碼以粗體顯示：

package examples.webservices.types;

import javax.jws.WebMethod;
import javax.jws.WebService;

import weblogic.jws.WLHttpTransport;
import weblogic.jws.Types;

import examples.webservices.types.BasicStruct;

@WebService(serviceName="TypesService",
name="TypesPortType",
targetNamespace="http://example.org")

@WLHttpTransport(contextPath="types",
serviceUri="TypesService",
portName="TypesServicePort")

public class TypesImpl {

@WebMethod()
@Types({"examples.webservices.types.ExtendedStruct"})
public BasicStruct echoStruct(
     @Types({"examples.webservices.types.ExtendedStruct"}) BasicStruct struct)
{
    System.out.println("echoStruct called");
    return struct;
}

}

在該示例中，echoStruct() 方法的簽名顯示它採用 BasicStruct 值同時作爲參數和返回值。但是，因爲該方法和 struct 參數都使用 @Types 批註進行了批註，所以調用 echoStruct 的客戶端應用程序還可以向其傳遞數據類型爲 ExtendedStruct 的參數；在這裏，該操作還會返回 ExtendedStruct 值。該示例假設 ExtendedStruct 擴展 BasicStruct。

weblogic.jws.WildcardBinding

描述

目標：類

指定通配符類（如 javax.xml.soap.SOAPElement 或 org.apache.xmlbeans.XmlObject）綁定到的 XML Schema 數據類型。默認情況下，這些 Java 數據類型綁定到 <xsd:any> XML Schema 數據類型。通過使用此類級別批註，可以指定通配符類綁定到 <xsd:anyType>。

特性

表 B-24 weblogic.jws.WildcardBinding JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
className	指定此綁定應用於的通配符類的完全限定名稱。常用值爲 javax.xml.soap.SOAPElement 和 org.apache.xmlbeans.XmlObject。	String	是
binding	指定通配符類應該綁定到的 XML Schema 數據類型。您可以指定下列值之一： § WildcardParticle.ANY WildcardParticle.ANYTYPE	enum	是

示例

下列示例顯示如何使用 @WildcardBinding 批註來指定 Apache XMLBean 數據類型 XMLObject 應該綁定到此 Web Service 的 <xsd:any> XML Schema 數據類型：

@WildcardBindings({
    @WildcardBinding(className="org.apache.xmlbeans.XmlObject",
                      binding=WildcardParticle.ANY),
    @WildcardBinding(className="org.apache.xmlbeans.XmlObject[]",
                      binding=WildcardParticle.ANY)})
public class SimpleImpl {

...

weblogic.jws.WildcardBindings

描述

目標：類

指定 @weblogic.jws.WildcardBinding 批註數組。

此 JWS 批註沒有任何特性。

有關示例，請參閱 weblogic.jws.WildcardBinding。

weblogic.jws.WLHttpTransport

描述

目標：類

指定用於通過 HTTP 傳輸調用 Web Service 的 URL 的上下文路徑和服務 URI 部分，以及生成的 WSDL 中的端口名。

在一個 JWS 文件中只能指定一次（最多）此批註。

特性

表 B-25 weblogic.jws.WLHttpTransport JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
contextPath	Web Service 的上下文路徑。您在調用 Web Service 的 URL 中使用此值。例如，假設您將某個 Web Service 的上下文路徑設置爲了 financial；部署的該 WebLogic Web Service 的 WSDL 的 URL 可能如下所示： http://hostname:7001/financial/GetQuote?WSDL 此特性的默認值爲 JWS 文件的名稱，不帶其擴展名。例如，如果 JWS 文件的名稱爲 HelloWorldImpl.java，則其 contextPath 的默認值爲 HelloWorldImpl。	String	否
serviceUri	URL 的 Web Service URI 部分。您在調用 Web Service 的 URL 中使用此值。例如，假設您將此特性設置爲了 GetQuote；則該服務的部署 WSDL 的 URL 可能如下所示： http://hostname:7001/financial/GetQuote?WSDL 此特性的默認值爲 JWS 文件的名稱，不帶其擴展名。例如，如果 JWS 文件的名稱爲 HelloWorldImpl.java，則其 serviceUri 的默認值爲 HelloWorldImpl。	String	否
portName	所生成 WSDL 中端口的名稱。此特性映射到 WSDL 中 <port> 元素的 name 特性。此特性的默認值基於 JWS 文件的 @javax.jws.WebService 批註。具體來說，默認 portName 爲 @WebService 批註的 name 特性值加上實際文本 SoapPort。例如，如果 @WebService.name 設置爲了 MyService，則默認 portName 爲 MyServiceSoapPort。	String	否

示例

@WLHttpTransport(contextPath="complex",
serviceUri="ComplexService",
portName="ComplexServicePort")

weblogic.jws.WLHttpsTransport

描述

目標：類

警告：	截止到 9.2 版本的 WebLogic Server，將不贊成使用 @weblogic.jws.WLHttpsTransport 批註。您應該使用 @weblogic.jws.WLHttpTransport 批註來代替，因爲它現在同時支持 HTTP 和 HTTPS 協議。如果希望客戶端應用程序僅使用 HTTPS 協議訪問 Web Service，則必須在 JWS 文件中指定 @weblogic.jws.security.UserDataConstraint JWS 批註。

指定用於通過 HTTPS 傳輸調用 Web Service 的 URL 的上下文路徑和服務 URI 部分，以及生成的 WSDL 中的端口名。

在一個 JWS 文件中只能指定一次（最多）此批註。

特性

表 B-26 weblogic.jws.WLHttpsTransport JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
contextPath	Web Service 的上下文路徑。您在調用 Web Service 的 URL 中使用此值。例如，假設您將某個 Web Service 的上下文路徑設置爲了 financial；部署的該 WebLogic Web Service 的 WSDL 的 URL 可能如下所示： https://hostname:7001/financial/GetQuote?WSDL 此特性的默認值爲 JWS 文件的名稱，不帶其擴展名。例如，如果 JWS 文件的名稱爲 HelloWorldImpl.java，則其 contextPath 的默認值爲 HelloWorldImpl。	String	否
serviceUri	URL 的 Web Service URI 部分。您在調用 Web Service 的 URL 中使用此值。例如，假設您將此特性設置爲了 GetQuote；則該服務的部署 WSDL 的 URL 可能如下所示： https://hostname:7001/financial/GetQuote?WSDL 此特性的默認值爲 JWS 文件的名稱，不帶擴展名。例如，如果 JWS 文件的名稱爲 HelloWorldImpl.java，則其 serviceUri 的默認值爲 HelloWorldImpl。	String	否
portName	所生成 WSDL 中端口的名稱。此特性映射到 WSDL 中 <port> 元素的 name 特性。此特性的默認值基於 JWS 文件的 @javax.jws.WebService 批註。具體來說，默認 portName 爲 @WebService 批註的 name 特性值加上實際文本 SoapPort。例如，如果 @WebService.name 設置爲了 MyService，則默認 portName 爲 MyServiceSoapPort。	String	否

示例

@WLHttpsTransport(portName="helloSecurePort",
contextPath="secure",
serviceUri="SimpleSecureBean")

weblogic.jws.WLJmsTransport

描述

目標：類

指定用於通過 JMS 傳輸調用 Web Service 的 URL 的上下文路徑和服務 URI 部分，以及生成的 WSDL 中的端口名。使用此批註還可以指定 WebLogic Server 將來自操作調用的請求消息排入到的 JMS 隊列。

在一個 JWS 文件中只能指定一次（最多）此批註。

特性

表 B-27 weblogic.jws.WLJmsTransport JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
contextPath	Web Service 的上下文根。您在調用 Web Service 的 URL 中使用此值。	String	否
serviceUri	調用 Web Service 的客戶端應用程序使用的 URL 的 Web Service URI 部分。	String	否
queue	已爲 JMS 傳輸配置的 JMS 隊列的 JNDI 名稱。有關使用 JMS 傳輸的詳細信息，請參閱使用 JMS 傳輸作爲連接協議。如果不指定，則此特性的默認值爲 weblogic.wsee.DefaultQueue。您仍然必須在要部署 Web Service 的 WebLogic Server 實例中創建此 JMS 隊列。	String	否
portName	所生成 WSDL 中端口的名稱。此特性映射到 WSDL 中 <port> 元素的 name 特性。如果不指定此特性，jwsc 則會根據實現該 Web Service 的類的名稱生成默認名稱。	String	否
connectionFactory	已爲 JMS 傳輸配置的 JMS 連接工廠的 JNDI 名稱。有關使用 JMS 傳輸的詳細信息，請參閱使用 JMS 傳輸作爲連接協議。	String	是

示例

下列示例顯示瞭如何指定 JWS 文件實現使用 JMS 傳輸調用的 Web Service。WebLogic Server 將來自服務操作調用的 SOAP 消息請求排入到的 JMS 隊列爲 JMSTransportQueue；該示例假設已經爲 WebLogic Server 配置此 JMS 隊列。

WLJmsTransport(contextPath="transports",
                serviceUri="JMSTransport",
                queue="JMSTransportQueue",
                portName="JMSTransportServicePort")

weblogic.jws.WSDL

描述

目標：類

指定是否公開部署的 WebLogic Web Service 的 WSDL。

默認情況下，WSDL 在下列 URL 公開：

http://[host]:[port]/[contextPath]/[serviceUri]?WSDL

其中：

host 指運行 WebLogic Server 的計算機。
port 指 WebLogic Server 監聽的端口號（默認值爲 7001）。
contextPath 和 serviceUri 分別指實現 Web Service 的 JWS 文件的 @WLHttpTransport JWS 批註的 contextPath 和 serviceUri 特性。

例如，假設您使用了下列 @WLHttpTransport 批註：

@WLHttpTransport(portName="helloPort",
contextPath="hello",
serviceUri="SimpleImpl")

可查看該 Web Service 的 WSDL 的 URL 爲（假設該服務在名爲 ariel 的主機上運行）：

http://ariel:7001/hello/SimpleImpl?WSDL

特性

表 B-28 weblogic.jws.WSDL JWS 批註標記的特性

名稱

描述

數據類型

是否必需？

exposed

指定是否公開部署的 Web Service 的 WSDL。

有效值爲 true 和 false。默認值爲 true，即默認情況下公開 WSDL。

boolean

否

示例

@WSDL 批註的下列用法顯示瞭如何指定不公開部署的 Web Service 的 WSDL；只顯示了相關的 Java 代碼：

package examples.webservices;

import....

@WebService(name="WsdlAnnotationPortType",
serviceName="WsdlAnnotationService",
targetNamespace="http://example.org")

@WSDL(exposed=false)

public class WsdlAnnotationImpl {

...

}

weblogic.jws.security.CallbackRolesAllowed

描述

目標：方法、字段

指定 @SecurityRole JWS 批註數組，該數組列出了允許調用 Web Service 的回調方法的角色。映射到未指定角色的用戶或者根本未映射任何角色的用戶不允許調用回調方法。

如果在字段級別使用此批註，則允許指定的角色調用 Web Service 的所有回調操作。如果在方法級別使用此批註，則允許指定的角色只調用該回調方法。如果在兩個級別都指定此批註，則在沒有衝突的情況下該方法值替換字段值。

特性

表 B-29 weblogic.jws.security.CallbackRolesAllowed JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
value	列出允許調用回調方法的角色的 @weblogic.jws.security.RolesAllowed 數組。	String[]	是

示例

下列示例顯示瞭如何在方法級別使用 @CallbackRolesAllowed 批註來指定允許角色 engineer 調用回調方法：

@CallbackMethod(target="port", operation="callbackOperation")
@CallbackRolesAllowed(@SecurityRole(role="engineer", mapToPrincipals="shackell"))
public void callbackHandler(String msg) {

System.out.println (msg);

}

weblogic.jws.security.RolesAllowed

描述

目標：類、方法

用於爲 Web Service 啓用基本身份驗證的 JWS 批註。具體來說，它指定 @SecurityRole JWS 批註數組，這些批註描述允許調用 Web Service 的角色列表。映射到未指定角色的用戶或者根本未映射任何角色的用戶不允許調用該 Web Service。

如果在類級別使用此批註，則允許指定的角色調用 Web Service 的所有操作。要只爲某個特定的操作集指定角色，請在操作級別指定該批註。

特性

表 B-30 weblogic.jws.security.RolesAllowed JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
value	列出允許調用 Web Service 方法的角色的 @weblogic.jws.security.RolesAllowed 數組。	String[]	是

示例

package examples.webservices.security_roles;

...

import weblogic.jws.security.RolesAllowed;
import weblogic.jws.security.SecurityRole;

@WebService(name="SecurityRolesPortType",
serviceName="SecurityRolesService",
targetNamespace="http://example.org")

@RolesAllowed ( {
    @SecurityRole (role="manager",
                   mapToPrincipals={ "juliet","amanda" }),
    @SecurityRole (role="vp")
} )

public class SecurityRolesImpl {

...

在該示例中，只允許角色 manager 和 vp 調用該 Web Service。在該 Web Service 的上下文中，用戶 juliet 和 amanda 被分配了 manager 角色。但是，角色 vp 不包括 mapToPrincipals 特性，這就暗示着用戶已經外部映射到了此角色。該示例假設您已經向 WebLogic Server 安全領域添加了兩個用戶（juliet 和 amanda）。

weblogic.jws.security.RolesReferenced

描述

目標：類

用於指定角色名列表的 JWS 批註，這些角色名引用允許調用該 Web Service 的實際角色。具體來說，它指定 @SecurityRoleRef JWS 批註數組，其中每個批註都描述被引用的角色名和 @SecurityRole 批註定義的實際角色之間的鏈接。

此 JWS 批註沒有任何特性。

示例

package examples.webservices.security_roles;

...

import weblogic.jws.security.RolesAllowed;
import weblogic.jws.security.SecurityRole;
import weblogic.jws.security.RolesReferenced;
import weblogic.jws.security.SecurityRoleRef;

@WebService(name="SecurityRolesPortType",
serviceName="SecurityRolesService",
targetNamespace="http://example.org")

@RolesAllowed ( {
    @SecurityRole (role="manager",
                   mapToPrincipals={ "juliet","amanda" }),
    @SecurityRole (role="vp")
} )

@RolesReferenced (
@SecurityRoleRef (role="mgr", link="manager")
)

public class SecurityRolesImpl {

...

在該示例中，角色 mgr 與角色 manager 相鏈接，該角色允許調用該 Web Service。這就表示也允許被分配了 mgr 角色的任何用戶調用該 Web Service。

weblogic.jws.security.RunAs

描述

目標：類

指定在 WebLogic Server 中實際運行該 Web Service 的角色和用戶標識。

例如，假設 @RunAs 批註指定 roleA 角色和 userA 委託人。這就表示，即使該 Web Service 是由 userB（映射到 roleB）調用的，相關操作實際也作爲 userA 在內部執行。

特性

表 B-31 weblogic.jws.security.RunAs JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
role	指定該 Web Service 應該作爲其運行的角色。	String	是
mapToPrincipal	指定映射到該角色的委託人用戶。假設您已經將指定的委託人（用戶）配置爲了有效的 WebLogic Server 用戶（通常使用管理控制檯完成此操作）。有關詳細信息，請參閱創建用戶。	String	是

示例

package examples.webservices.security_roles;

import weblogic.jws.security.RunAs;

...

@WebService(name="SecurityRunAsPortType",
serviceName="SecurityRunAsService",
targetNamespace="http://example.org")

@RunAs (role="manager", mapToPrincipal="juliet")

public class SecurityRunAsImpl {

...

該示例顯示瞭如何指定該 Web Service 總是作爲映射到 manager 角色的用戶 juliet 運行，而不管哪個用戶真正調用該 Web Service。

weblogic.jws.security.SecurityRole

描述

目標：類、方法

指定允許調用 Web Service 的角色名稱。此批註在 JWS 文件中總是指定爲 @RolesAllowed 數組的成員。

當客戶端應用程序調用受保護的 Web Service 時，它會作爲其基本身份驗證的一部分指定用戶和密碼。假設管理員已經使用管理控制檯將該用戶配置爲了有效 WebLogic Server 用戶，有關詳細信息，請參閱創建用戶。

要調用該 Web Service 的用戶也必須映射到相關角色。您可以下列兩種方式之一執行此任務：

使用管理控制檯將用戶映射到角色。這種情況下，不指定 @SecurityRole 批註的 mapToPrincipals 特性。有關詳細信息，請參閱將用戶添加到角色中。
使用 mapToPrincipals 特性指定一個或多個用戶，從而將該用戶映射到僅位於該 Web Service 上下文中的角色。

要指定允許多個角色調用 Web Service，請在 @RolesAllowed 批註中包括多個 @SecurityRole 批註。

特性

表 B-32 weblogic.jws.security.SecurityRole JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
role	允許調用 Web Service 的角色的名稱。	String	是
mapToPrincipals	映射到該角色的用戶名數組。如果不指定此特性，則假設您在外部定義了用戶和該角色之間的映射（通常使用管理控制檯完成該操作）。	String[]	否

示例

package examples.webservices.security_roles;

...

import weblogic.jws.security.RolesAllowed;
import weblogic.jws.security.SecurityRole;

@WebService(name="SecurityRolesPortType",
serviceName="SecurityRolesService",
targetNamespace="http://example.org")

@RolesAllowed ( {
    @SecurityRole (role="manager",
                   mapToPrincipals={ "juliet","amanda" }),
    @SecurityRole (role="vp")
} )

public class SecurityRolesImpl {

...

weblogic.jws.security.SecurityRoleRef

描述

目標：類

指定鏈接到允許調用該 Web Service 的已指定角色的角色名引用。

只要被引用的角色已在該 Web Service 的 @RolesAllowed 批註中指定，映射到該角色引用的用戶就可以調用該 Web Service。

特性

表 B-33 weblogic.jws.security.SecurityRoleRef JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
role	角色引用的名稱。	String	是
link	允許調用該 Web Service 的已指定角色的名稱。此特性的值與同一 JWS 文件中指定的 @SecurityRole annotation的 role 特性的值相對應。	String	是

示例

package examples.webservices.security_roles;

...

import weblogic.jws.security.RolesAllowed;
import weblogic.jws.security.SecurityRole;
import weblogic.jws.security.RolesReferenced;
import weblogic.jws.security.SecurityRoleRef;

@WebService(name="SecurityRolesPortType",
serviceName="SecurityRolesService",
targetNamespace="http://example.org")

@RolesAllowed ( {
    @SecurityRole (role="manager",
                   mapToPrincipals={ "juliet","amanda" }),
    @SecurityRole (role="vp")
} )

@RolesReferenced (
@SecurityRoleRef (role="mgr", link="manager")
)

public class SecurityRolesImpl {

...

在該示例中，角色 mgr 與角色 manager 相鏈接，該角色允許調用該 Web Service。這就表示也允許被分配了 mgr 角色的任何用戶調用該 Web Service。

weblogic.jws.security.UserDataConstraint

描述

目標：類

指定在調用 Web Service 時是否需要客戶端使用 HTTPS 傳輸。

如果在實現該 Web Service 的 JWS 文件中，此批註的 transport 特性設置爲 Transport.INTEGRAL 或 Transport.CONFIDENTIAL，WebLogic Server 則會在客戶端和 Web Service 之間建立安全套接字層 (SSL) 連接。

如果在 JWS 文件中指定此批註，則還必須指定 weblogic.jws.WLHttpTransport 批註（或 jwsc Ant 任務的 <WLHttpTransport> 元素）以確保在 WSDL 文件中由 jwsc Ant 任務生成 HTTPS 綁定。

特性

表 B-34 weblogic.jws.security.UserDataConstraint JWS 批註標記的特性

名稱

描述

數據類型

是否必需？

transport

指定在調用 Web Service 時是否需要客戶端使用 HTTPS 傳輸。

有效值爲：

§ Transport.NONE - 指定該 Web Service 不需要任何傳輸保證。
Transport.INTEGRAL - 指定該 Web Service 需要客戶端和 Web Service 之間以無法在傳輸中更改的方式發送數據。
Transport.CONFIDENTIAL - 指定該 Web Service 需要數據以防止其他實體觀察到傳輸內容的方式進行傳輸。

默認值爲 Transport.NONE。

enum

否

示例

package examples.webservices.security_https;

import weblogic.jws.security.UserDataConstraint;

...

@WebService(name="SecurityHttpsPortType",
serviceName="SecurityHttpsService",
targetNamespace="http://example.org")

@UserDataConstraint(
transport=UserDataConstraint.Transport.CONFIDENTIAL)

public class SecurityHttpsImpl {

...

weblogic.jws.security.WssConfiguration

描述

目標：類

指定您希望 Web Service 使用的 Web Service 安全配置的名稱。如果在 JWS 文件中不指定此批註，並且存在默認安全配置的話，該 Web Service 則與該默認安全配置（名爲 default_wss）相關聯。

只有您的 Web Service 是爲消息級別安全（加密和數字簽名）配置的情況下，@WssConfiguration 批註纔有意義。與使用此批註的 Web Service 相關聯的安全配置指定如對於標識是否使用 X.509 證書、是否使用密碼摘要、要用於加密和數字簽名的密鑰存儲等信息。

WebLogic Web Service 不一定必須與安全配置相關聯；如果 Web Service 安全運行時的默認行爲足夠，則不需要任何其他配置。但是，如果 Web Service 需要不同於默認行爲的其他行爲（如將 X.509 證書而不是默認的用戶名/密碼標記用於標識），則 Web Service 必須與安全配置相關聯。

必須首先使用管理控制檯創建安全配置，才能成功調用指定該安全配置的 Web Service。有關詳細信息，請參閱創建 Web Service 安全配置。有關消息級別安全的一般信息，請參閱配置消息級安全（數字簽名和加密）。

特性

表 B-35 weblogic.jws.security.WssConfiguration JWS 批註標記的特性

名稱

描述

數據類型

是否必需？

value

指定與此 Web Service 相關聯的 Web Service 安全配置的名稱。默認配置名爲 default_wss。

必須首先使用管理控制檯創建安全配置（甚至默認的安全配置），才能成功調用該 Web Service。

String

是

示例

下列示例顯示瞭如何指定 Web Service 與 my_security_configuration 安全配置相關聯；只顯示了相關的 Java 代碼：

package examples.webservices.wss_configuration;

import javax.jws.WebService;
...

import weblogic.jws.security.WssConfiguration;

@WebService(...
...

@WssConfiguration(value="my_security_configuration")

public class WssConfigurationImpl {

...

weblogic.jws.soap.SOAPBinding

描述

目標：方法

指定 Web Service 操作到 SOAP 消息協議的映射。

此批註與 @javax.jws.soap.SOAPBinding 相似，只是它應用於方法而不是類。例如，使用此批註您可以指定一個 Web Service 操作使用 RPC 編碼的 SOAP 綁定，同一個 Web Service 中的另一個操作使用 document-literal-wrapped SOAP 綁定。

注意：	因爲 @weblogic.jws.soap.SOAPBinding 和 @javax.jws.soap.SOAPBinding 具有相同的類名，所以將其用於 JWS 文件中時要注意指的是哪個批註。

特性

表 B-36 weblogic.jws.soap.SOAPBinding JWS 批註標記的特性

名稱

描述

數據類型

是否必需？

style

指定被調用的批註操作的請求和響應 SOAP 消息的消息樣式。

有效值爲：

§ SOAPBinding.Style.RPC
SOAPBinding.Style.DOCUMENT。

默認值爲 SOAPBinding.Style.DOCUMENT。

enum

否

use

指定被調用的批註操作的請求和響應 SOAP 消息的格式設置樣式。

有效值爲：

§ SOAPBinding.Use.LITERAL
SOAPBinding.Use.ENCODED

默認值爲 SOAPBinding.Use.LITERAL。

enum

否

parameterStyle

確定方法參數是否表示整個消息正文，或者這些參數是否爲包裝在根據該操作命名的頂級元素中的元素。

有效值爲：

§ SOAPBinding.ParameterStyle.BARE
SOAPBinding.ParameterStyle.WRAPPED

默認值爲 SOAPBinding.ParameterStyle.WRAPPED

注意：	此特性僅適用於 document-literal 樣式的 Web Service。換句話說，只有也將 style 特性設置爲 SOAPBinding.Style.DOCUMENT、use 特性設置爲 SOAPBinding.Use.LITERAL 的情況下才能指定此特性。

enum

否

示例

下列簡單的 JWS 文件顯示瞭如何指定 Web Service 的操作在默認情況下使用 document-literal-wrapped SOAP 綁定；通過在類級別使用 @javax.jws.soap.SOAPBinding 批註可以指定此內容。然後，該示例顯示瞭如何通過在方法級別使用 @weblogic.jws.soap.SOAPBinding 批註，從而爲各個方法指定不同的 SOAP 綁定。具體來說，sayHelloDocLitBare() 方法使用 document-literal-bare SOAP 綁定，sayHelloRPCEncoded() 方法使用 RPC 編碼的 SOAP 綁定。

package examples.webservices.soap_binding_method;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;

import weblogic.jws.WLHttpTransport;

@WebService(name="SoapBindingMethodPortType",
serviceName="SoapBindingMethodService",
targetNamespace="http://example.org")

@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

@WLHttpTransport(contextPath="soap_binding_method",
serviceUri="SoapBindingMethodService",
portName="SoapBindingMethodServicePort")

/**
* 說明如何爲方法指定 soap 綁定的 JWS 示例。
*/

public class SoapBindingMethodImpl {

@WebMethod()
@weblogic.jws.soap.SOAPBinding(
               style=SOAPBinding.Style.DOCUMENT,
               use=SOAPBinding.Use.LITERAL,
               parameterStyle=SOAPBinding.ParameterStyle.BARE)

public String sayHelloDocLitBare(String message) {
System.out.println("sayHelloDocLitBare" + message);
return "Here is the message: '" + message + "'";
}

@WebMethod()
@weblogic.jws.soap.SOAPBinding(
style=SOAPBinding.Style.RPC,
use=SOAPBinding.Use.ENCODED)

public String sayHelloRPCEncoded (String message) {
System.out.println("sayHelloRPCEncoded" + message);
return "Here is the message: '" + message + "'";
}
}

weblogic.jws.security.SecurityRoles（不贊成使用）

描述

目標：類、方法

注意：	@weblogic.security.jws.SecurityRoles JWS 批註在 WebLogic Server 9.0 中開始不贊成使用。

指定允許訪問該 Web Service 的操作的角色。

如果在類級別使用此批註，則指定的角色適用於該 Web Service 的所有公共操作。如果希望將不同的角色與同一 Web Service 的不同操作相關聯，則還可以在方法級別指定角色列表。

注意：	@SecurityRoles 批註僅在 EJB 實現的 Web Service 的上下文中受支持。因此，只能在明確實現 javax.ejb.SessionBean 的 JWS 文件內指定此批註。有關確保對於 EJB 的訪問安全的意義的概念信息，請參閱確保 Enterprise JavaBean (EJB) 安全。有關在 JWS 文件中明確實現 EJB 的信息，請參閱是否要實現無狀態會話 EJB？

特性

表 B-37 weblogic.jws.security.SecurityRoles JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
rolesAllowed	指定允許訪問該 Web Service 的角色列表。此批註等同於實現該 Web Service 的無狀態會話 EJB 的 ejb-jar.xml 部署描述符中的 <method-permission> 元素。	String 數組	否
rolesReferenced	指定該 Web Service 引用的角色列表。該 Web Service 可以使用列出角色的憑據訪問其他資源。此批註等同於實現該 Web Service 的無狀態會話 EJB 的 ejb-jar.xml 部署描述符中的 <security-role-ref> 元素。	String 數組	否

示例

下列示例顯示瞭如何在類級別指定該 Web Service 只能由 Admin 角色調用；只顯示了示例的相關部分：

package examples.webservices.security_roles;

import javax.ejb.SessionBean;
import javax.ejb.SessionContext;

import weblogic.ejbgen.Session;

import javax.jws.WebService;

...

import weblogic.jws.security.SecurityRoles;

@Session(ejbName="SecurityRolesEJB")

@WebService(...

// 指定可以調用整個 Web Service 的角色

@SecurityRoles(rolesAllowed="Admnin")

public class SecurityRolesImpl implements SessionBean {

...

weblogic.jws.security.SecurityIdentity (deprecated)

描述

目標：類

注意：	@weblogic.security.jws.SecurityIdentity JWS 批註在 WebLogic Server 9.1 中開始不贊成使用。

指定調用 Web Service 時它所採用的標識。

除非指定了其他內容，否則 Web Service 採用已經過身份驗證的調用者的標識。此批註使得開發人員能夠替換此行爲，以便作爲某個特定的角色執行該 Web Service。該角色必須映射到 WebLogic Server 安全領域中的用戶或組。

注意：	@SecurityIdentity 批註僅在 EJB 實現的 Web Service 的上下文中有意義。因此，只能在明確實現 javax.ejb.SessionBean 的 JWS 文件內指定此批註。有關確保對於 EJB 的訪問安全的意義的概念信息，請參閱確保 Enterprise JavaBean (EJB) 安全。有關在 JWS 文件中明確實現 EJB 的信息，請參閱是否要實現無狀態會話 EJB？

特性

表 B-38 weblogic.jws.security.SecurityIdentity JWS 批註標記的特性
名稱	描述	數據類型	是否必需？
value	指定調用該 Web Service 時它採用的角色。該角色必須映射到 WebLogic Server 安全領域中的用戶或組。	String	是

示例

下列示例顯示瞭如何指定在調用 Web Service 時該 Web Service 作爲 Admin 角色運行：

package examples.webservices.security_roles;

import javax.ejb.SessionBean;
import javax.ejb.SessionContext;

import weblogic.ejbgen.Session;

import javax.jws.WebService;

...

import weblogic.jws.security.SecurityIdentity;

@Session(ejbName="SecurityRolesEJB")

@WebService(...

// 指定以 Admin 角色運行 Web Service

@SecurityIdentity( value="Admin")

public class SecurityRolesImpl implements SessionBean {

...

JWS 批註參考WebService註解

The method xxx of type xxx must override or implement a supertype

如何在google被封的情況下登陸stackoverflow賬號？

JWS 批註參考WebService註解

Java Card Applet Development——環境搭建及基礎概念(JCDK v2.2.2&v3.0.0.5)

CVS，GIT，Mercurial和SVN比較

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結