JWS 批注參考WebService注解
下列部分提供了有關標准 (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
- javax.jws.WebMethod
- javax.jws.Oneway
- javax.jws.WebParam
- javax.jws.WebResult
- javax.jws.HandlerChain
- javax.jws.soap.SOAPBinding
- javax.jws.soap.SOAPMessageHandler
- javax.jws.soap.InitParam
- javax.jws.soap.SOAPMessageHandlers
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 文件，並且會返回錯誤。
|
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，則該參數的數據類型必須為 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.DOCUMENT。 |
enum |
否 |
||
| use |
指定請求和響應 SOAP 消息的格式設置樣式。 有效值為：
默認值為 SOAPBinding.Use.LITERAL。 |
enum |
否 |
||
| parameterStyle |
確定方法參數是否表示整個消息正文，或者這些參數是否為包裝在根據該操作命名的頂級元素中的元素。 有效值為：
默認值為 SOAPBinding.ParameterStyle.WRAPPED
|
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
- weblogic.jws.AsyncResponse
- weblogic.jws.Binding
- weblogic.jws.BufferQueue
- weblogic.jws.Callback
- weblogic.jws.CallbackMethod
- weblogic.jws.CallbackService
- weblogic.jws.Context
- weblogic.jws.Conversation
- weblogic.jws.Conversational
- weblogic.jws.MessageBuffer
- weblogic.jws.Policies
- weblogic.jws.Policy
- weblogic.jws.ReliabilityBuffer
- weblogic.jws.ReliabilityErrorHandler
- weblogic.jws.ServiceClient
- weblogic.jws.StreamAttachments
- weblogic.jws.Transactional
- weblogic.jws.Types
- weblogic.jws.WildcardBinding
- weblogic.jws.WildcardBindings
- weblogic.jws.WLHttpTransport
- weblogic.jws.WLHttpsTransport
- weblogic.jws.WLJmsTransport
- weblogic.jws.WSDL
- weblogic.jws.security.CallbackRolesAllowed
- weblogic.jws.security.RolesAllowed
- weblogic.jws.security.RolesReferenced
- weblogic.jws.security.RunAs
- weblogic.jws.security.SecurityRole
- weblogic.jws.security.SecurityRoleRef
- weblogic.jws.security.UserDataConstraint
- weblogic.jws.security.WssConfiguration
- weblogic.jws.soap.SOAPBinding
- weblogic.jws.security.SecurityRoles（不贊成使用）
- weblogic.jws.security.SecurityIdentity (不贊成使用)
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。 |
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 |
指定批注的方法實現的對話階段。 可能的值有：
指定該方法啟動一個新對話。調用此方法會創建新的對話 ID 和上下文，還會重置其空閑計時器和期限計時器。
指定該方法是正在進行的某個對話的一部分。調用此方法會重置空閑計時器。此方法必須總是在啟動方法之后、完成方法之前調用。
指定該方法明確完成正在進行的對話。 默認值為 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 定義。 有效值為數字並帶有下列單位之一：
例如，要指定最長空閑時間為十分鍾，請按照下列方式指定該批注： @Conversational(maxIdleTime="10 minutes") 如果指定零長度值（如 0 seconds 或 0 minutes 等），則由於不活動該對話永遠不會超時。 默認值為 0 seconds。 |
String |
否 |
| maxAge |
指定對話在由 WebLogic Server 完成之前可以保持活動狀態的時間長度。 有效值為數字並帶有下列單位之一：
例如，要指定最長期限為三天，請按照下列方式指定該批注： @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 實現之間進行。 有效值為數字並帶有下列單位之一：
例如，要指定重試延遲為兩天，請指定： @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。 |
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 實現之間進行。 有效值為數字並帶有下列單位之一：
例如，要指定重試延遲為兩天，請指定： @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 數據類型。 您可以指定下列值之一：
|
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 {
...
在該示例中，只允許角色 manager 和 vp 調用該 Web Service。在該 Web Service 的上下文中，用戶 juliet 和 amanda 被分配了 manager 角色。但是，角色 vp 不包括 mapToPrincipals 特性，這就暗示着用戶已經外部映射到了此角色。該示例假設您已經向 WebLogic Server 安全領域添加了兩個用戶（juliet 和 amanda）。
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。 |
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.DOCUMENT。 |
enum |
否 |
||
| use |
指定被調用的批注操作的請求和響應 SOAP 消息的格式設置樣式。 有效值為：
默認值為 SOAPBinding.Use.LITERAL。 |
enum |
否 |
||
| parameterStyle |
確定方法參數是否表示整個消息正文，或者這些參數是否為包裝在根據該操作命名的頂級元素中的元素。 有效值為：
默認值為 SOAPBinding.ParameterStyle.WRAPPED
|
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 {
...