41.2. 在服务提供商中使用 XML

实现提供程序接口的对象有两个 消息传递模式 ：

您指定的消息传递模式决定了传递给您的实施的消息传递详情级别。

在使用 消息模式 时，提供程序实施将适用于完整的消息。完整的消息包括任何绑定特定标头和打包程序。例如，一个使用 SOAP 绑定的提供程序实现会接收请求，作为完全指定的 SOAP 信息。从实施返回的所有响应都必须是完全指定的 SOAP 消息。

要指定 Provider 实施使用消息模式，方法是提供 java.xml.ws.Service.Mode.MESSAGE 作为 javax.xml.ws.ServiceMode 注解的值，如 例 41.9 “指定提供程序实施使用消息模式” 所示。

@WebServiceProvider
@ServiceMode(value=Service.Mode.MESSAGE)
public class stockQuoteProvider implements Provider<SOAPMessage>
{
  ...
}

在 有效负载模式中，Provider 实施只用于消息有效负载。例如，在有效负载模式中工作的供应商实施只适用于 SOAP 消息的正文。绑定层处理任何绑定级别打包程序和标头。

在使用不使用特殊打包程序的绑定时，如 Apache CXF XML 绑定、有效负载模式和消息模式提供相同的结果。

要指定 Provider 实施使用有效负载模式，方法是提供 java.xml.ws.Service.Mode.PAYLOAD 作为 javax.xml.ws.ServiceMode 注解的值，如 例 41.10 “指定提供程序实施使用 Payload Mode” 所示。

@WebServiceProvider
@ServiceMode(value=Service.Mode.PAYLOAD)
public class stockQuoteProvider implements Provider<DOMSource>
{
  ...
}

如果没有为 @ServiceMode 注释提供值，则 Provider 实施会使用有效负载模式。

由于它们是低级对象，因此提供商实施无法使用与更高级别的消费者 API 相同的 JAXB 生成的类型。提供程序实现用于以下类型的对象：

提供程序实施可以接受并返回从 javax.xml.transform.Source 接口派生的对象。源对象是存放 XML 文档的低级别对象。每个 Source 实施都提供了访问存储的 XML 文档和操作其内容的方法。以下对象实施 Source 接口：

如果您创建您的 Provider 对象使其使用通用源对象，Apache CXF 会将消息返回为 SAXSource 对象。

可以使用端点的 source-preferred-format 属性来更改此行为。有关配置 Apache CXF 运行时的详情，请参考 第 IV 部分 “配置 Web 服务端点”。

在以下情况下，供应商实施可以使用 javax.xml.SOAPMessage 对象：

SOAPMessage 对象包含 SOAP 消息。它们包含一个 SOAPPart 对象和零个或多个 AttachmentPart 对象。SOAPPart 对象包含 SOAP 消息的特定部分，包括 SOAP envelope、任何 SOAP 标头和 SOAP 消息正文。AttachmentPart 对象包含作为附件传递的二进制数据。

当以下条件满足时，提供程序实施可以使用实现 javax.activation.DataSource 接口的对象：

数据源对象提供了一种机制，用于处理各种来源中的数据，包括 URL、文件和字节数组。

提供程序接口相对容易实现。它只有一个方法 调用（），必须实现。另外，它有三个简单要求：

实施提供程序接口的复杂性是在处理请求消息和构建正确响应的逻辑中。

与基于 SEI 的更高级别的服务实现不同，提供商实现将请求接收为原始 XML 数据，并且必须发送响应作为原始 XML 数据。这要求开发人员对所实施服务所使用的消息的了解。这些详细信息通常可在描述该服务的 WSDL 文档中找到。

WS-I 基本 配置集提供有关服务使用的信息，包括：

为了被 JAX-WS 认可为服务实施，提供程序实施必须与 @WebServiceProvider 注释进行解码。

表 41.2 “@WebServiceProvider Properties” 描述可以为 @WebServiceProvider 注释设置的属性。

所有这些属性都是可选的，默认情况下为空。如果您将其留空，Apache CXF 将使用实施类中的信息创建值。

Provider 接口只有一个方法，即 调用（），必须实现。invoke（） 方法接收发送到所实施提供程序接口类型声明的传入请求，并返回将响应消息打包为同一类型对象。例如，一个 Provider<SOAPMessage> 接口的实现会将请求接收为 SOAPMessage 对象，并返回响应作为 SOAPMessage 对象。

Provider 实施使用的消息传递模式决定了请求和响应消息包含的绑定特定信息的数量。使用消息模式实现的实现会接收所有绑定特定打包程序和标头以及请求。它们还必须将所有绑定特定打包程序和标头添加到响应消息中。使用有效负载模式实现的实施仅接收请求的正文。使用有效负载模式实现的 XML 文档被放入请求消息的正文中。

例 41.11 “provider<SOAPMessage> 实现” 显示一个提供程序实施，它适用于消息模式下的 SOAPMessage 对象。

import javax.xml.ws.Provider;
import javax.xml.ws.Service;
import javax.xml.ws.ServiceMode;
import javax.xml.ws.WebServiceProvider;

@WebServiceProvider(portName="stockQuoteReporterPort"
                    serviceName="stockQuoteReporter")
@ServiceMode(value="Service.Mode.MESSAGE")
public class  stockQuoteReporterProvider implements Provider<SOAPMessage>
{
public stockQuoteReporterProvider()
  {
  }

public SOAPMessage invoke(SOAPMessage request)
  {
  SOAPBody requestBody = request.getSOAPBody();
  if(requestBody.getElementName.getLocalName.equals("getStockPrice"))
    {
    MessageFactory mf = MessageFactory.newInstance();
      SOAPFactory sf = SOAPFactory.newInstance();

    SOAPMessage response = mf.createMessage();
      SOAPBody respBody = response.getSOAPBody();
      Name bodyName = sf.createName("getStockPriceResponse");
      respBody.addBodyElement(bodyName);
      SOAPElement respContent = respBody.addChildElement("price");
      respContent.setValue("123.00");
      response.saveChanges();
    return response;
    }
    ...
  }
}

例 41.11 “provider<SOAPMessage> 实现” 中的代码执行以下操作：

指定以下类实施一个由 wsdl:service 元素命名为 stockQuoteReporter 的服务的 Provider 对象，其 wsdl:port 元素名为 stockQuoteReporterPort。

指定此提供者实施使用消息模式。

提供所需的默认公共构造器。

提供 调用（）方法的 实施，它采用 SOAPMessage 对象并返回 SOAPMessage 对象。

从传入 SOAP 消息正文中提取请求消息。

检查请求消息的根元素，以确定如何处理请求。

创建构建响应所需的因素。

为响应构建 SOAP 消息。

将响应返回为 SOAPMessage 对象。

例 41.12 “provider<DOMSource> 实现” 演示了在有效负载模式中使用 DOMSource 对象的提供程序实现示例。

import javax.xml.ws.Provider;
import javax.xml.ws.Service;
import javax.xml.ws.ServiceMode;
import javax.xml.ws.WebServiceProvider;

@WebServiceProvider(portName="stockQuoteReporterPort" serviceName="stockQuoteReporter")
@ServiceMode(value="Service.Mode.PAYLOAD")
public class  stockQuoteReporterProvider implements Provider<DOMSource>
public stockQuoteReporterProvider()
  {
  }

public DOMSource invoke(DOMSource request)
  {
    DOMSource response = new DOMSource();
    ...
    return response;
  }
}

例 41.12 “provider<DOMSource> 实现” 中的代码执行以下操作：

指定类实现实现服务的 Provider 对象，其 wsdl:service 元素命名为 stockQuoteReporter，其 wsdl:port 元素名为 stockQuoteReporterPort。

指定此提供程序的实现使用有效负载模式。

提供所需的默认公共构造器。

提供 调用（） 方法的实施，它采用 DOMSource 对象并返回 DOMSource 对象。