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

描述

目标：类

指定实现 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

注意：

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 {

...

posted @ 2013-04-19 13:19 wanggd_blog 阅读(20851) 评论(0) 编辑收藏举报

刷新页面返回顶部

JWS 批注参考WebService注解

公告