学步园

使用 JMS 传输作为连接协议

通常情况下，客户端应用程序在调用 WebLogic Web Service 时使用 HTTP/S 作为连接协议。但是，您可以对 WebLogic Web Service 进行配置，以便客户端应用程序可以改用 JMS 作为传输。请按照后面部分中的描述使用 JWS 批注或 jwsc Ant 任务的子元素配置传输。

将 WebLogic Web Service 配置为使用 JMS 进行连接传输时，为 Web Service 的已生成 WSDL 中的对应端口指定的端点地址在其 URL 中使用 jms:// 而不是 http://。下面是 JMS 端点地址的示例：

jms://myHost:7001/transports/JMSTransport?URI=JMSTransportQueue

URL 的 URI=JMSTransportQueue 部分指定已经为 JMS 传输功能配置的 JMS 队列。虽然无法使用 HTTP 调用 Web Service，但可以使用 HTTP 查看它的 WSDL，这就是 clientgen 为什么仍旧能够为 Web Service 生成 JAX-RPC 存根控件。

对于您指定的每个传输，WebLogic Server 都会在 WSDL 中生成一个附加端口。因此，如果要为客户端应用程序提供传输选项以供它们在调用 Web Service 时使用（JMS、HTTP 或 HTTPS），应使用适当的 JWS 批注或 jwsc 的子元素明确添加传输。

使用 JMS 传输：主要步骤

以下过程描述如何指定可使用 JMS 传输调用 Web Service。

它假设您已经创建了一个实现 Web Service 的基本 JWS 文件，并且您想要配置该 Web Service 以使用 JMS 对其进行调用。它还假设您设置了一个基于 Ant 的开发环境并且您有一个有效的 build.xml 文件，该文件包括用于运行 jwsc Ant 任务和部署服务的目标。有关详细信息，请参阅 WebLogic Web Service 的迭代开发 和 JWS 文件编程。

有关更新客户端应用程序以使用 JMS 传输调用 Web Service 的信息，请参阅使用 JMS 传输调用 WebLogic Web Service。

使用 @WLJmsTransport JWS 批注

如果您在为 JWS 文件编程时知道您希望客户端应用程序使用 JMS 传输（而不是 HTTP/S）调用 Web Service，可以使用 @WLJmsTransport 指定调用的详细信息。以后在生成时，可以通过指定 jwsc Ant 任务的 <WLJmsTransport> 子元素（如使用 jwsc Ant 任务的 <WLJmsTransport> 子元素中所述）来替代 JWS 文件中的批注并添加其他 JMS 传输规范。

使用 @WLJmsTranport 批注时，请遵循下列原则：

以下示例显示了一个使用 @WLJmsTransport 批注的简单 JWS 文件，相关代码以粗体显示：

package examples.webservices.jmstransport;

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

import weblogic.jws.WLJmsTransport;

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

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

// WebLogic 特定的 JWS 批注，用于指定生成 Web Service 
// 的 URI 所使用的上下文路径和服务 URI 为
// “transports/JMSTransport”

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

/**
 * 此 JWS 文件形成了带有下列单个操作的简单 Java 类实现的 WebLogic
 * Web Service 的基础：sayHello
 *
 * @作者版权所有 (c) 2005，BEA Systems。保留所有权利。
*/

public class JMSTransportImpl {

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

使用 jwsc Ant 任务的 <WLJmsTransport> 子元素

您也可以在生成时使用 jwsc Ant 任务的 <jws> 元素的 <WLJmsTransport> 子元素指定 JMS 传输。在生成时指定传输的原因包括：

如果为 jwsc Ant 任务指定一种传输，则该传输优先于 JWS 文件中的任何传输批注。

以下示例说明如何为 jwsc Ant 任务指定传输：

  <target name="build-service">

    <jwsc
      srcdir="src"
      destdir="${ear-dir}">
      <jws file="examples/webservices/jmstransport/JMSTransportImpl.java">

        <WLJmsTransport
                contextPath="transports" 
                serviceUri="JMSTransport"
                portName="JMSTransportServicePort"
               queue="JMSTransportQueue"/>

      </jws>

    </jwsc>

  </target>

上面的示例说明如何将在使用 @WLJmsTransport JWS 批注中显示的 JWS 文件中指定的值指定给 URL 和 JMS 队列。

有关使用 jwsc Ant 任务的详细信息，请参阅 jwsc。

使用 JMS 传输调用 WebLogic Web Service

可编写客户端应用程序以使用 JMS 传输调用 Web Service，方式与编写使用 HTTP 传输的客户端应用程序一样。唯一区别是：必须确保已经创建了 JMS 队列（由 @WLJmsTransport 批注或 jwsc 任务的<WLJmsTransport> 子元素指定）和其他 JMS 对象。有关详细信息，请参阅使用 JMS 传输：主要步骤。

虽然无法使用 HTTP 调用 JMS 传输配置的 Web Service，但可以使用 HTTP 查看它的 WSDL，因此 clientgen Ant 任务仍旧能够为 Web Service 创建 JAX-RPC 存根控件。例如，此部分中显示的 Web Service 的 WSDL 的 URL 将会是：

http://host:port/transports/JMSTransport?WSDL

但是，因为已部署的 Web Service 的 WSDL 中的端点地址使用 jms:// 而不是 http://，并且该地址包括限定符 ?URI=JMS_QUEUE，所以 clientgen Ant 任务会在调用 Web Service 时自动创建使用 JMS 传输所需的存根控件，并且客户端应用程序不需要执行不同于平常的操作。下面是 JMS 端点地址的示例：

jms://host:port/transports/JMSTransport?URI=JMSTransportQueue

有关调用 Web Service 的常规信息，请参阅调用 Web Service。

替代默认服务地址 URL

如果编写的客户端应用程序使用 clientgen 生成的 JAX-RPC 存根控件调用 Web Service，则 Web Service 的默认服务地址 URL 是在 Service 构造方法的 WSDL 文件参数的 <address> 元素中指定的 URL。

但是，有时可能需要替代该地址，尤其是在调用的 WebLogic Web Service 部署到某个群集并且您想要指定群集地址或群集中受管服务器的地址列表时。可能还需要使用 t3 协议调用 Web Service。要在使用 JMS 传输时替代此服务端点 URL，请使用 weblogic.wsee.jaxrpc.WLStub.JMS_TRANSPORT_JNDI_URL 存根控件属性，如以下示例所示：

package examples.webservices.jmstransport.client;

import weblogic.wsee.jaxrpc.WLStub;

import java.rmi.RemoteException;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;

/**
 * 这是一个简单的独立客户端应用程序，用以调用
 * JMSTransport Web service 中的 <code>sayHello</code> 操作。
*
 * @作者版权所有 (c) 2004，BEA Systems。保留所有权利。
*/

public class Main {

  public static void main(String[] args)
      throws ServiceException, RemoteException{

    JMSTransportService service = new JMSTransportService_Impl(args[0] + "?WSDL" );
    JMSTransportPortType port = service.getJMSTransportServicePort();

    Stub stub = (Stub) port;

    stub._setProperty(WLStub.JMS_TRANSPORT_JNDI_URL,
                      "t3://shackell01.amer.bea.com:7001");
    try {
      String result = null;

      result = port.sayHello("Hi there!");

      System.out.println( "Got JMS result: " + result );

    } catch (RemoteException e) {
      throw e;
    }
  }
}

有关其他存根控件属性的参考文档，请参阅 WLStub。

使用 JMS BytesMessage 而不是默认的 TextMessage

使用 JMS 传输时，Web Service 运行时默认使用 javax.jms.TextMessage 对象发送该消息。对于大多数客户端应用程序，这通常足够了，但有时可能需要发送二进制数据而不是普通文本，在这种情况下，必须请求 Web Service 运行时改用 javax.jms.BytesMessage。要这样做，请使用客户端应用程序中的 WLStub.JMS_TRANSPORT_MESSAGE_TYPE 存根控件属性并将它的值设置为WLStub.JMS_BYTESMESSAGE，如以下示例所示：

    stub._setProperty(WLStub.JMS_TRANSPORT_MESSAGE_TYPE,
                      WLStub.JMS_BYTESMESSAGE);

Web Service 运行时会使用与请求相同的消息数据类型传回响应。

有关可在其中设置此属性的客户端应用程序的完整示例，请参阅替代默认服务地址 URL。有关其他存根控件属性的参考文档，请参阅 WLStub。

禁用对 WSDL 文件进行 HTTP 访问

如 使用 JMS 传输调用 WebLogic Web Service 中所述，默认情况下，部署的 Web Service 的 WSDL 仍可使用 HTTP 进行访问。如果要禁用对 WSDL 文件进行访问，特别是禁用从防火墙外访问 Web Service，则您可以执行下列操作之一：

创建和使用 SOAP 消息处理程序

有些 Web Service 需要访问 SOAP 消息，对于 SOAP 消息，可为其创建 SOAP 消息处理程序。

SOAP 消息处理程序提供在 Web Service 的请求和响应中截获 SOAP 消息的机制。您可以同时在 Web Service 本身或调用该 Web Service 的客户端应用程序中创建处理程序。

访问 SOAP 消息头部分中的信息就是使用处理程序的简单示例。您可以使用 SOAP 头存储 Web Service 特定的信息，然后使用处理程序操作它。

也可以使用 SOAP 消息处理程序提高 Web Service 的性能。在将 Web Service 部署了一段时间后，您可能会发现许多使用者使用相同的参数来调用它。通过缓存 Web Service 的常见调用的结果（假设结果是静态的）并在适当时立即返回这些结果（而不需要先调用实现 Web Service 的后端组件），可以提高 Web Service 的性能。通过使用处理程序检查请求 SOAP 消息以查看其中是否包含常见参数，可以实现此性能改进。

下表列出了可在 JWS 文件中用于指定配置了处理程序链的 Web Service 的 JWS 批注；后面的部分更加详细地讨论如何使用这些批注。有关其他信息，请参阅 Web Services MetaData for the Java Platform (JSR-181) specification。

下表描述 javax.xml.rpc.handler API 的主要类和接口，其中一些可在创建处理程序本身时使用。后面的部分详细讨论了这些 API。有关这些 API 的其他信息，请参阅 JAX-RPC 1.1 specification。

将 SOAP 消息处理程序添加到 Web Service：主要步骤

以下过程描述用于将 SOAP 消息处理程序添加到 Web Service 的高级步骤。

它假设您已经创建了一个实现某 Web Service 的基本 JWS 文件，并且您想要通过添加 SOAP 消息处理程序和处理程序链来更新该 Web Service。它还假设您设置了一个基于 Ant 的开发环境并且您有一个有效的 build.xml 文件，该文件包括用于运行 jwsc Ant 任务的目标。有关详细信息，请参阅 WebLogic Web Service 的迭代开发 和 JWS 文件编程。

有关创建客户端 SOAP 消息处理程序和处理程序链的信息，请参阅创建并使用客户端 SOAP 消息处理程序。

设计 SOAP 消息处理程序和处理程序链

设计 SOAP 消息处理程序和处理程序链时，必须确定：

处理程序链中的每个处理程序都有一个用于处理请求 SOAP 消息的方法和一个用于处理响应 SOAP 消息的方法。一组有序处理程序被称为“处理程序链”。请指定某 Web Service 上附加有一个处理程序链，而该处理程序链使用以下两个 JWS 批注之一附加到其上：@HandlerChain 或 @SOAPMessageHandler。后面的部分讨论何时使用哪个批注。

调用 Web Service 时，WebLogic Server 按照如下方式执行处理程序：

例如，假设您要在 JWS 文件中使用 @HandlerChain JWS 批注指定外部配置文件，并且该配置文件定义一个名为 SimpleChain 的处理程序链（该程序链包含三个处理程序），如以下示例所示：

<jwshc:handler-config xmlns:jwshc="http://www.bea.com/xml/ns/jws"
   xmlns:soap1="http://HandlerInfo.org/Server1"
   xmlns:soap2="http://HandlerInfo.org/Server2"
   xmlns="http://java.sun.com/xml/ns/j2ee" >

   <jwshc:handler-chain>

     <jwshc:handler-chain-name>SimpleChain</jwshc:handler-chain-name>

     <jwshc:handler>
       <handler-name>handlerOne</handler-name>
       <handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler1</handler-class>
     </jwshc:handler>

     <jwshc:handler>
       <handler-name>handlerTwo</handler-name>
       <handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler2</handler-class>
     </jwshc:handler>

     <jwshc:handler>
       <handler-name>handlerThree</handler-name>
       <handler-class>examples.webservices.soap_handlers.global_handler.ServerHandler3</handler-class>
     </jwshc:handler>

   </jwshc:handler-chain>

</jwshc:handler-config>

下图显示 WebLogic Server 执行每个处理程序的 handleRequest() 和 handleResponse() 方法的顺序。

每个 SOAP 消息处理程序都有一个单独的方法来处理请求和响应 SOAP 消息，原因是：对于入站和出站消息，通常必须进行相同类型的处理。例如，可以设计一种加密处理程序，其 handleRequest() 方法为 SOAP 请求中的安全数据解密，handleResponse() 方法为 SOAP 响应加密。

但是，可以设计只处理 SOAP 请求而不对响应进行等同处理的处理程序。

也可以选择不调用处理程序链中的下一个处理程序，并随时向客户端应用程序发送即时响应。

创建 GenericHandler 类

SOAP 消息处理程序类应该扩展 javax.rpc.xml.handler.GenericHandler 抽象类，而该抽象类本身实现 javax.rpc.xml.handler.Handler 接口。

GenericHandler 类是便于编写处理程序的便利抽象类。该类提供生命周期方法 init() 和 destroy() 以及 Handler 接口的各种 handleXXX() 方法的默认实现。编写处理程序类时，只替代需要作为Handler 实现类的一部分自定义的那些方法。

尤其是，处理程序接口包含下列可在扩展 GenericHandler 的处理程序类中实现的方法：

有时，可能需要从处理程序中直接查看或更新 SOAP 消息，尤其是在处理附件（如图像）时。在这种情况下，请使用 javax.xml.soap.SOAPMessage 抽象类，该类是 SOAP With Attachments API for Java 1.1 (SAAJ) 规范的一部分。有关详细信息，请参阅使用 SAAJ 直接操作 SOAP 请求和响应消息。

以下示例说明了一个简单的 SOAP 消息处理程序，该处理程序将 SOAP 请求和响应消息输出到 WebLogic Server 日志文件中：

package examples.webservices.soap_handlers.global_handler;

import javax.xml.namespace.QName;
import javax.xml.rpc.handler.HandlerInfo;
import javax.xml.rpc.handler.GenericHandler;
import javax.xml.rpc.handler.MessageContext;
import javax.xml.rpc.handler.soap.SOAPMessageContext;
import javax.xml.rpc.JAXRPCException;

import weblogic.logging.NonCatalogLogger;

/**
 * 此类实现处理程序链内的某个处理程序，用于访问 SOAP
 * 请求及响应消息。
* <p>
 * 在实现 Web Service 本身的后端
 * Java 类处理消息之前，此类将扩展 <code>javax.xml.rpc.handler.GenericHandler</code>
 * 抽象类，并只将 SOAP 请求和响应消息输出到
 * 服务器日志文件。
*/

public class ServerHandler1 extends GenericHandler {

  private NonCatalogLogger log;

  private HandlerInfo handlerInfo;

  /**
   *  初始化处理程序实例。创建 nonCatalogLogger
   *  以记录消息。
*/

  public void init(HandlerInfo hi) {

    log = new NonCatalogLogger("WebService-LogHandler");
    handlerInfo = hi;

  }

  /**
   * 指定在将消息发送至实现 Web Service 的 Java 类之前，
   * 将 SOAP 请求消息记录到日志文件。
*/

  public boolean handleRequest(MessageContext context) {

   SOAPMessageContext messageContext = (SOAPMessageContext) context;

   System.out.println("** Request: "+messageContext.getMessage().toString());
   log.info(messageContext.getMessage().toString());
   return true;

  }

  /**
   * 指定在将消息发送回至
   *调用 Web Service 的客户端应用程序之前，
   * 将 SOAP 响应消息记录到日志文件。
*/

  public boolean handleResponse(MessageContext context) {

    SOAPMessageContext messageContext = (SOAPMessageContext) context;

    System.out.println("** Response: "+messageContext.getMessage().toString());
    log.info(messageContext.getMessage().toString());
    return true;

  }

  /**
   * 指定在处理程序实例引发 SOAP 错误的情况下，
   *将消息记录到日志文件。
*/

  public boolean handleFault(MessageContext context) {

   SOAPMessageContext messageContext = (SOAPMessageContext) context;

   System.out.println("** Fault: "+messageContext.getMessage().toString());
   log.info(messageContext.getMessage().toString());
       return true;

  }

  public QName[] getHeaders() {

    return handlerInfo.getHeaders();

  }

}

实现 Handler.init() 方法

调用 Handler.init() 方法可创建 Handler 对象的实例并启用该实例以将它本身初始化。它的签名是：

  public void init(HandlerInfo config) throws JAXRPCException {}

HandlerInfo 对象包含 SOAP 消息处理程序的相关信息，尤其是初始化参数。使用 HandlerInfo.getHandlerConfig() 方法可获取这些参数；该方法返回包含名称-值对的 java.util.Map 对象。

如果需要处理初始化参数，或者如果有其他初始化任务需要执行，请实现 init() 方法。

初始化参数的示例用法有：打开或关闭调试，指定要在其中写入消息或错误的日志文件的名称，等等。

实现 Handler.destroy() 方法

调用 Handler.destroy() 方法可破坏 Handler 对象的实例。它的签名是：

  public void destroy() throws JAXRPCException {}

实现 destroy() 方法可释放在处理程序的整个生命周期获取的所有资源。

实现 Handler.getHeaders() 方法

Handler.getHeaders() 方法获取可由此 Handler 实例处理的头块。它的签名是：

  public QName[] getHeaders() {}

实现 Handler.handleRequest() 方法

调用 Handler.handleRequest() 方法可在后端组件处理 SOAP 消息请求前将其截获。它的签名是：

  public boolean handleRequest(MessageContext mc) 
          throws JAXRPCException,SOAPFaultException  {}

实现此方法可执行一些任务，如在后端组件处理 SOAP 消息前将其中的数据解密，等等。

MessageContext 对象将 SOAP 消息处理程序处理的消息上下文抽象化。MessageContext 属性允许处理程序链中的处理程序共享处理状态。

使用 MessageContext 的 SOAPMessageContext 子接口可处理或更新 SOAP 消息请求的内容。SOAP 消息请求本身存储在 javax.xml.soap.SOAPMessage 对象中。有关此对象的详细信息，请参阅使用 SAAJ 直接操作 SOAP 请求和响应消息。

SOAPMessageContext 类定义了两种用于处理 SOAP 请求的方法：

在为 SOAP 请求的所有处理编码之后，请为以下场景之一编码：

实现 Handler.handleResponse() 方法

调用 Handler.handleResponse() 方法可在后端组件处理 SOAP 消息响应后，但将其传回到调用 Web Service 的客户端应用程序前将其截获。它的签名是：

  public boolean handleResponse(MessageContext mc) throws JAXRPCException {}

实现此方法可执行一些任务，如在将 SOAP 消息传回到客户端应用程序前将其中的数据解密以便进一步处理返回值，等等。

MessageContext 对象将 SOAP 消息处理程序处理的消息上下文抽象化。MessageContext 属性允许处理程序链中的处理程序共享处理状态。

使用 MessageContext 的 SOAPMessageContext 子接口可处理或更新 SOAP 消息响应的内容。SOAP 消息响应本身存储在 javax.xml.soap.SOAPMessage 对象中。请参阅使用 SAAJ 直接操作 SOAP 请求和响应消息。

SOAPMessageContext 类定义了两种用于处理 SOAP 响应的方法：

在为 SOAP 响应的所有处理编码之后，请为以下场景之一编码：

实现 Handler.handleFault() 方法

Handler.handleFault() 方法根据 SOAP 消息处理模式处理 SOAP 错误。它的签名是：

    public boolean handleFault(MessageContext mc) throws JAXRPCException  {}

实现此方法可处理由 handleResponse() 和 handleRequest() 方法生成的任何 SOAP 错误以及由后端组件生成的错误。

MessageContext 对象将 SOAP 消息处理程序处理的消息上下文抽象化。MessageContext 属性允许处理程序链中的处理程序共享处理状态。

使用 MessageContext 的 SOAPMessageContext 子接口可处理或更新 SOAP 消息的内容。SOAP 消息本身存储在 javax.xml.soap.SOAPMessage 对象中。请参阅使用 SAAJ 直接操作 SOAP 请求和响应消息。

SOAPMessageContext 类定义了下面两种用于处理 SOAP 消息的方法：

在为 SOAP 错误的所有处理编码之后，请为以下场景之一编码：

使用 SAAJ 直接操作 SOAP 请求和响应消息

javax.xml.soap.SOAPMessage 抽象类是 SOAP With Attachments API for Java 1.1 (SAAJ) 规范的一部分。创建 SOAP 消息处理程序时，使用该类可操作请求和响应 SOAP 消息。本部分描述SOAPMessage 对象的基本结构以及可用于查看和更新 SOAP 消息的一些方法。

SOAPMessage 对象包含 SOAPPart 对象（该对象包含实际的 SOAP XML 文档）以及零个或多个附件。

有关 SOAPMessage 类的完整描述，请参阅 SAAJ Javadocs。有关 SAAJ 的详细信息，请转至 http://java.sun.com/xml/saaj/index.html。

SOAPPart 对象

SOAPPart 对象在 SOAPEnvelope 对象内包含 XML SOAP 文档。使用此对象可获取实际的 SOAP 头和正文。

以下示例 Java 代码说明如何从 Handler 类提供的 MessageContext 对象检索 SOAP 消息并处理它的各部分：

SOAPMessage soapMessage =  messageContext.getMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();
SOAPEnvelope soapEnvelope = soapPart.getEnvelope();
SOAPBody soapBody = soapEnvel