使用Spring WS创建合同优先的Web服务

1引言

本文介绍了如何使用来实现和测试SOAP Web服务
Spring Web Services项目。本示例使用JAXB2进行（取消）编组。为了开发服务，我将使用合同优先的方法，该方法首先定义服务合同，然后基于该合同实施服务。

本文分为以下几节：

2解释申请
3实施服务
3.1创建合同
3.2生成Java类
3.3实现SOAP端点
3.4配置应用程序
4测试服务
5附加信息
5.1实施客户
5.2内部运作方式

2解释申请

示例应用程序处理订单。我们有一个前端控制器（messageDispatcher servlet），它将处理订单请求，调用服务以处理订单并返回结果。

Aplicacio

您可以在github上获取源代码。

3实施服务

3.1创建合同

由于我们将使用合同优先的方法，因此创建合同的最简单方法是首先定义示例xml文档，然后我们将使用工具生成合同。以下是示例xml文档：

client-request.xml

<clientDataRequest xmlns="http://www.xpadro.spring.samples.com/orders"clientId="A-123"productId="C5FH"quantity="5" />

client-response.xml

<clientDataResponse xmlns="http://www.xpadro.spring.samples.com/orders" confirmationId="7890B"orderDate="2013-09-22"amount="15.50" />

为了创建模式，我们可以使用Trang，这是一个开放源代码工具，将允许我们从xml文档中生成xsd模式。我已经将该库包含到项目构建路径中（可以从Trang 网站获得此jar），并且我已经创建了一个Ant任务来执行转换：

generate-schema.xml

<project name="Ant-Generate-Schema-With-Trang" default="generate" basedir="."><property name="src.dir" location="src" /><property name="trang.dir" location="lib" /><property name="source.dir" location="${src.dir}/main/webapp/WEB-INF/schemas/samples" /><property name="schema.dir" location="${src.dir}/main/webapp/WEB-INF/schemas/xsd" /><target name="generate" description="generates order schema"><delete dir="${schema.dir}" /><mkdir dir="${schema.dir}" /><java jar="${trang.dir}/trang.jar" fork="true"><arg value="${source.dir}/client-request.xml" /><arg value="${schema.dir}/client-request.xsd" /></java><java jar="${trang.dir}/trang.jar" fork="true"><arg value="${source.dir}/client-response.xml" /><arg value="${schema.dir}/client-response.xsd" /></java></target>
</project>

一旦执行了Ant任务，它将生成架构。由于模式是自动生成的，因此我们可能需要进行一些修改以使其适应我们的需求。让我们来看看：

客户端请求

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://www.xpadro.spring.samples.com/orders" xmlns:orders="http://www.xpadro.spring.samples.com/orders"><xs:element name="clientDataRequest"><xs:complexType><xs:attribute name="clientId" use="required" type="xs:NCName"/><xs:attribute name="productId" use="required" type="xs:NCName"/><xs:attribute name="quantity" use="required" type="xs:integer"/></xs:complexType></xs:element>
</xs:schema>

客户端响应

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://www.xpadro.spring.samples.com/orders" xmlns:orders="http://www.xpadro.spring.samples.com/orders"><xs:element name="clientDataResponse"><xs:complexType><xs:attribute name="amount" use="required" type="xs:decimal"/><xs:attribute name="confirmationId" use="required" type="xs:NMTOKEN"/><xs:attribute name="orderDate" use="required" type="xs:NMTOKEN"/></xs:complexType></xs:element>
</xs:schema>

我们可以向这些架构添加不同的验证，但是在本示例中，我将仅修改几种类型，例如clientId，productId和ConfirmationId（xs：string）和orderDate（xs：date）。 XML数据类型到Java类型的映射是由JAXB完成的。您可以检查提供了哪些映射
在这里。

为了完成该架构，我们将把response元素复制到请求架构中。我用响应和请求创建了第三个模式：

客户端服务

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"elementFormDefault="qualified" targetNamespace="http://www.xpadro.spring.samples.com/orders"xmlns:orders="http://www.xpadro.spring.samples.com/orders"><xs:element name="clientDataRequest"><xs:complexType><xs:attribute name="clientId" use="required" type="xs:string" /><xs:attribute name="productId" use="required" type="xs:string" /><xs:attribute name="quantity" use="required" type="xs:integer" /></xs:complexType></xs:element><xs:element name="clientDataResponse"><xs:complexType><xs:attribute name="amount" use="required" type="xs:decimal" /><xs:attribute name="confirmationId" use="required" type="xs:string" /><xs:attribute name="orderDate" use="required" type="xs:date" /></xs:complexType></xs:element>
</xs:schema>

最后一步是写合同，通常用WSDL文件表示。如果您不想手动创建它，Spring-ws项目为我们提供了一种从XSD模式生成此文件的方法。您将在配置应用程序部分中看到第二种方法。

3.2生成Java类

我们将使用JAXB2生成请求和响应对象。 JAXB的XJC编译器将负责从我们之前生成的XSD架构转换这些对象。它将作为Ant任务执行：

<project name="Ant-Generate-Classes-With-JAXB2" default="generate" basedir="."><property name="src.dir" location="src" /><property name="java.dir" location="src/main/java" /><property name="schema.dir" location="${src.dir}/main/webapp/WEB-INF/schemas/xsd" /><target name="generate"><exec executable="xjc"><arg line=" -d ${java.dir} -p xpadro.spring.ws.types ${schema.dir}/client-service.xsd" /></exec></target>
</project>

该任务将在xpadro.spring.ws.types包中创建Java类（您可能需要刷新项目）。

3.3实现SOAP端点

端点接收未编组的消息有效负载，并使用此数据来调用订单服务。然后它将返回服务响应，该响应将由端点适配器编组：

@Endpoint
public class OrderEndpoint {@Autowiredprivate OrderService orderService;@PayloadRoot(localPart="clientDataRequest", namespace="http://www.xpadro.spring.samples.com/orders")public @ResponsePayload ClientDataResponse order(@RequestPayload ClientDataRequest orderData) {OrderConfirmation confirmation = orderService.order(orderData.getClientId(), orderData.getProductId(), orderData.getQuantity().intValue());ClientDataResponse response = new ClientDataResponse();response.setConfirmationId(confirmation.getConfirmationId());BigDecimal amount = new BigDecimal(Float.toString(confirmation.getAmount()));response.setAmount(amount);response.setOrderDate(convertDate(confirmation.getOrderDate()));return response;}//date conversion
}

这是端点使用的注释的简短描述：

@Endpoint ：将类注册为组件。这样，将通过组件扫描检测到该类。

@PayloadRoot ：将端点方法注册为请求的处理程序。该注释将定义该方法可以处理的请求消息类型。在我们的示例中，它将接收消息，其中其有效负载根元素具有与我们创建的XSD架构中定义的名称空间相同的名称空间，并且其本地名称是为请求定义的名称（clientDataRequest）。

@RequestPayload ：指示请求消息的有效负载作为参数传递给方法。

@ResponsePayload ，指示将返回值用作响应消息的有效负载。

3.4配置应用程序

web.xml
应用程序配置（如数据源，transactionManager…）

<context-param><param-name>contextConfigLocation</param-name><param-value>classpath:xpadro/spring/ws/config/root-config.xml</param-value>
</context-param>

加载应用程序上下文

<listener><listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>

这是一个Servlet，它将充当处理所有SOAP调用的前端控制器。它的功能是将传入的XML消息派生到端点，就像Spring MVC的DispatcherServlet一样。

<servlet><servlet-name>orders</servlet-name><servlet-class>org.springframework.ws.transport.http.MessageDispatcherServlet</servlet-class><init-param><param-name>contextConfigLocation</param-name><param-value>classpath:xpadro/spring/ws/config/servlet-config.xml</param-value></init-param><load-on-startup>1</load-on-startup>
</servlet><servlet-mapping><servlet-name>orders</servlet-name><url-pattern>/orders/*</url-pattern>
</servlet-mapping>

servlet-config.xml
此配置包含Web服务基础结构bean。

<!-- Detects @Endpoint since it is a specialization of @Component -->
<context:component-scan base-package="xpadro.spring.ws"/><!-- detects @PayloadRoot -->
<ws:annotation-driven/><ws:dynamic-wsdl id="orderDefinition" portTypeName="Orders" locationUri="http://localhost:8081/spring-ws"><ws:xsd location="/WEB-INF/schemas/xsd/client-service.xsd"/>
</ws:dynamic-wsdl>

在动态wsdl中，将什么值放在locationUri属性中都没有关系，因为它将由MessageDispatcherServlet处理。因此，wsdl将在以下位置可用：

http：// localhost：8081 / spring-ws / orders / whatever / orderDefinition.wsdl

4测试服务

下面的示例创建一个模拟客户端，该客户端将访问Web服务：

@ContextConfiguration("classpath:xpadro/spring/ws/test/config/test-server-config.xml")
@RunWith(SpringJUnit4ClassRunner.class)
public class TestWebService {@AutowiredApplicationContext context;private MockWebServiceClient mockClient;@Testpublic void testValidOrderRequest() {Source requestPayload = new StringSource("<clientDataRequest xmlns='http://www.xpadro.spring.samples.com/orders' " +"clientId='123' productId='XA-55' quantity='5'/>");Source responsePayload = new StringSource("<clientDataResponse xmlns='http://www.xpadro.spring.samples.com/orders' " +"amount='55.99' confirmationId='GHKG34L' orderDate='2013-10-26+02:00'/>");RequestCreator creator = RequestCreators.withPayload(requestPayload);mockClient = MockWebServiceClient.createClient(context);mockClient.sendRequest(creator).andExpect(ResponseMatchers.payload(responsePayload));}@Testpublic void testInvalidOrderRequest() {Source requestPayload = new StringSource("<clientDataRequest xmlns='http://www.xpadro.spring.samples.com/orders' " +"clientId='456' productId='XA-55' quantity='5'/>");Source responsePayload = new StringSource("<SOAP-ENV:Fault xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>" +"<faultcode>SOAP-ENV:Server</faultcode><faultstring xml:lang='en'>Client [456] not found</faultstring></SOAP-ENV:Fault>");RequestCreator creator = RequestCreators.withPayload(requestPayload);mockClient = MockWebServiceClient.createClient(context);mockClient.sendRequest(creator).andExpect(ResponseMatchers.payload(responsePayload));}
}

此测试中使用的配置文件非常简单，仅包含对服务组件的扫描：

<context:component-scan base-package="xpadro.spring.ws"/>
<ws:annotation-driven/>

5附加信息

5.1实施客户

为了方便客户端访问Web服务，Spring为我们提供了WebServiceTemplate类。此类包含用于发送和接收消息的方法，并且它还使用转换器对（取消）编组对象。

我创建了一个充当服务客户端的测试：

@ContextConfiguration("classpath:xpadro/spring/ws/test/config/client-config.xml")
@RunWith(SpringJUnit4ClassRunner.class)
public class TestClient {@Autowired WebServiceTemplate wsTemplate;@Testpublic void invokeOrderService() throws Exception {ClientDataRequest request = new ClientDataRequest();request.setClientId("123");request.setProductId("XA-55");request.setQuantity(new BigInteger("5", 10));ClientDataResponse response = (ClientDataResponse) wsTemplate.marshalSendAndReceive(request);assertNotNull(response);assertEquals(new BigDecimal("55.99"), response.getAmount());assertEquals("GHKG34L", response.getConfirmationId());}
}

配置测试文件包含WebServiceTemplate配置：

<oxm:jaxb2-marshaller id="marshaller" contextPath="xpadro.spring.ws.types"/><bean class="org.springframework.ws.client.core.WebServiceTemplate"><property name="marshaller" ref="marshaller" /><property name="unmarshaller" ref="marshaller" /><property name="defaultUri" value="http://localhost:8081/spring-ws/orders" /> 
</bean>

只需记住在执行此测试之前使用已部署的Web服务应用程序启动服务器即可。

5.2内部运作方式

如果您只想实现Web服务，则本文在上一节中完成。对于那些对它如何真正起作用感到好奇的人，我将尝试解释如何将请求映射到端点，这比到目前为止的解释要低一些。

当请求到达MessageDispatcher时，它依赖于两个组件：

它询问EndpointMapping哪个是适当的端点。
利用从映射接收到的信息，它使用端点适配器来调用端点。适配器还支持参数解析器和返回类型处理程序。

端点映射

MessageDispatcher包含一个端点映射列表，每个映射都包含一个先前注册的方法端点的映射。在我们的例子中，JAXB映射PayloadRootAnnotationMethodEndpointMapping已注册所有带有@PayloadRoot注释的方法。如果消息的有效负载的合格名称解析为注册方法，则它将被返回给MessageDispatcher。如果我们不注释我们的方法，它将无法处理请求。
序列1
端点适配器