CXF之JAX-WS Provider and CXF之JAX-WS Dispatch API

Provider API

1 Messaging Modes(消息模型)

继承了Provider接口的对象可以使用两个消息模型：

--消息模型

--消息负载模型

.  消息模型

当使用消息模型时，Provider的实现使用完整的消息。完整的消息包含任意绑定，header,包装。

你指定Provider的实现使用消息模型，它的值是java.xml.ws.Service.Mode.MESSAGE,它由javax.xml.ws.ServiceMode注解提供.

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

 

消息负载模型

在消息负载模型下，Provider实现使用消息负载，如例，Provider实现仅使用SOAP消息的body部分。

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

 如果你不提供@ServiceMode注解，Provider实现将默认使用消息负载(PAYLOAD)模型。

2 数据类型(Data Types)

.  概述

Provider实现，因为他们是低级别的对象，不能使用由相同JAXB生成的高级别的消费者API类型。Provider实现使用下列类型：

--javax.xml.transform.Source

--javax.xml.soap.SOAPMessage

--javax.activetion.DataSource

.  使用Source对象

Provider实现能接受与返回从javax.xml.transform.Source接口派生的对象。Source对象是低级别的拥有xml文档的对象。

每个Source实现类提供方法访问存储的xml文档并操纵它的内容。下面的对象实现了Source接口：

--DOMSource容纳一个DOM树的xml消息。xml消息存储在Mode对象集中，并能通过getNode()方法访问它们。节点能

使用setNode()方法被添加或增加到DOM树。

--SAXSource容纳一个SAX对象的xml消息。SAX对象包含一个InputSource对象，它包含原数据和解析原数据的XMLReader对象。

--StreamSource容纳一个数据流的xml消息。这个数据流能像其它任何数据流一样操作。

注意：当使用Source对象的时候，开发人员负责确保所有必须的绑定具体包装被添加到消息上。

.  使用SOAPMessage对象

Provider实现能使用javax.xml.soap.SOAPMessage对象，当下面条件为真时：

--Provider实现正使用SOAP绑定。

--Provider实现正使用消息模型。

SOAPMessage对象，顾名思义，拥有一个SOAP消息。他包含一个SOAPPart对象和零到多个AttachmentPart对象。

SOAPPart对象包含SOAP的具体部分，包含：soap信封，soap头和soap消息主体。AttachmentPart对象包含作为附件

通过的二进制数据。

.  使用DataSource对象

Provider实现能使用实现了javax.activation.DataSource接口的对象，当下面条件为真时：

--这实现类正使用HTTP 绑定。

--这实现类正在消息模型。

DataSource对象提供了一个使用MIME类型数据的机制，它来源于URLs,files,字节数组。

3 实现Provider对象

Provider接口是比较容易实现的。它仅有一个方法，invoke(),它必须被实现，它还有三个简单的要求：

--必须有@WebServiceProvider注解。

--必须有默认的public构造函数

--必须实现Provider接口的类型版本。换而言之，你不能实现Provider<T>接口。你必须实现使用一个具体数据类型

的接口的版本。如例，你能实现Provider<SAXSource>接口。

.  working with messages

与高级别的SEI服务实现不同，Provider实现接受原xml数据的请求和发送必须的原xml数据响应。

.  实现invoke()方法

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;
    }
    ...
  }
}

 

下面这个例子，Provider实现在负载模型下使用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;
  }
}

 

 

JAX-WS Dispatch API

Dispatch对象有两个使用模型：

--消息模型

--负载模型

.  消息模型

在消息模型中，一个Dispatch对象要使用一个完整的消息。完整的消息包括头与包装器.

你为Despatch对象指定使用消息模型，当你创建Dispatch对象时，要提供java.xml.Service.Mode.MESSAGE值。

.  负载模型

在负载模型中，Dispatch对象仅使用消息负载(消息体body)。

你为Despatch对象指定使用负载模型，当你创建Dispatch对象时，要提供java.xml.ws.Service.Mode.PAYLOAD值.

2 Data Types(数据类型)

Dispatch对象，因为它们是低级别的对象，使用相同的JAXB生成的高级别的消费者API是不被优化的。

Dispatch对象使用下面几个类型：

--javax.xml.transform.Source

--javax.xml.soap.SOAPMessage

--javax.activation.DataSource

--JAXB

.  使用Source对象

Dispatch对象能接收与返回派生自javax.xml.transform.Source接口的对象。 Source对象是保存xml文档的低级别对象。

每个Source实现提供方法，访问存储的xml文档并操纵它的内容。

下面的对象实现了Source接口：

--DOMSource

--SAXSource

--StreamSource

注意：当使用Source对象时，开发者要负责确保所有必须的且具体的绑定包装都添加到了消息上。

例如，当一个服务期待SOAP消息交互时，开发人员必须确保所需的SOAP信封添加到传出的请求

并且SOAP信封的内容是正确的。

.  使用SOAPMessage对象

当下面条件为真时，Dispatch对象能使用javax.xml.soap.SOAPMessage对象。

--Dispatch对象正使用SOAP binding.

--Dispatch对象正使用message mode(消息模型).

.  使用DataSource对象

Dispatch对象能使用实现了javax.activation.DataSource接口的对象，当下面条件为真时：

--Dispatch对象正使用HTTP binding.

--Dispatch对象正使用message mode(消息模型)

DataSource对象提供了一个可以用MIME类型数据的机制，可以来自URL,文件和字节数组。

.  使用JAXB对象

虽然Dispatch对象本意是低级别的API, 允许你使用原消息。他们也允许你使用JAXB对象。若要使用

JAXB对象，Dispatch对象必须通过JAXBContext, JAXBContext知道在使用中怎么编组和解组JAXB对象。

Dispatch对象被创建时通过JAXBContext。

JAXBContext理解你能通过JAXB对象作为invoke()方法的参数。你也能放返回消息进JAXB对象，JAXBContext

对象能理解。

3 使用Dispatch对象

使用Dispatch对象调用一个远程服务，你要做以下几点：

--创建一个Dispatch对象

--构建一个请求消息

--调用合适的invoke()方法

--解析响应消息

.  创建一个Dispatch对象

创建一个Dispatch对象要做以下几步：

--创建一个Service对象，它代表wsdl:service元素定义的服务

--使用Service对象的createDispatch()方法创建Dispatch对象

public Dispatch<T> createDispatch(QName portName,java.lang.Class<T> type,Service.Mode mode)

throws WebServiceException;

如果你使用JAXB对象的createDispatch()方法的签名就是：

public Dispatch<T> createDispatch(QName portName,javax.xml.bind.JAXBContext context,Service.Mode mode)

throws WebServiceException;

下表描述createDispatch()方法的参数：

parameter description

partName wsdl:port元素的指定的QName,它代表Dispatch对象调用上的服务提供者。

type 指定Dispatch对象使用的指定对象的数据类型

mode 指定Dispatch对象的消息使用模型。

下面代码是创建一个Dispatch对象并在消息负载模型下使用DOMSource对象：

...
QName serviceName = new QName("http://org.apache.cxf","stockQuoteReporter");
Service s = Service.create(serviceName);
QName portName = new QName("http://org.apache.cxf","stockQuoteReporterPort");
Dispatch<DomSource> dispatch = s.createDispatch(portName,DOMSource.class,Service.Mode.PAYLOAD);
...

.  构建请求消息(略)

.  同步调用

为消费者生成一个同步调用的响应，你使用Dispatch对象的invoke()方法。

T invoke(T msg) throws WebServiceException;

同步的例子：

...
DocumentBuilder db = DocumentBuilderFactory.newDocumentBuilder();
Document requestDoc = db.newDocument();
Element root = requestDoc.createElementNS("http://org.apache.cxf/stockExample","getStockPrice");
root.setNodeValue("DOW");
DOMSource request = new DOMSource(requestDoc);
DOMSource response = disp.invoke(request);
...

 .  异步调用

Dispatch对象支持异步调用. Dispatch对象可以使用轮询与回调两种方式处理异步。

当使用轮询方式的invokeAsync()方法时，返回一个Response<T>对象，可以定期轮询它，看看response是否返回。

Response<T> invokeAsync(T msg) throws WebServiceException;

当使用回调方式的invokeAsync()方法时，它接受一个AsyncHandler的实现，当response返回时处理它。

Future<?> invokeAsync(T msg,AsyncHandler<T> handler) throws WebServiceException;

.  单向调用(OneWay)

当一个请求不需要一个响应的时候，你的远程调用可以使用Dispatch对象上的invokeOneWay()方法。

void invokeOneWay(T msg) throws WebServiceException;