Web 服务支持
Web 服务支持
本章介绍了 Spring 集成对 Web 服务的支持,包括:
您需要将此依赖项包含在您的项目中:
<dependency>
<groupId>org.springframework.integration</groupId>
<artifactId>spring-integration-ws</artifactId>
<version>6.1.9</version>
</dependency>
compile "org.springframework.integration:spring-integration-ws:6.1.9"
出站 Web 服务网关
要在向通道发送消息时调用 Web 服务,您有两个选项,这两个选项都基于 Spring Web 服务项目构建:SimpleWebServiceOutboundGateway
和MarshallingWebServiceOutboundGateway
.
前者接受String
或javax.xml.transform.Source
作为消息负载。
后者支持Marshaller
和Unmarshaller
接口。
两者都需要 Spring Web 服务DestinationProvider
来确定要调用的 Web 服务的 URI。
以下示例显示了调用 Web 服务的两个选项:
simpleGateway = new SimpleWebServiceOutboundGateway(destinationProvider);
marshallingGateway = new MarshallingWebServiceOutboundGateway(destinationProvider, marshaller);
当使用命名空间支持(稍后介绍)时,您只需设置一个 URI。
在内部,解析器配置一个固定的 URIDestinationProvider 实现。
但是,如果您需要在运行时动态解析 URI,则DestinationProvider 可以提供从注册表中查找 URI 等行为。
请参阅 Spring Web 服务DestinationProvider Javadoc 了解有关此策略的更多信息。 |
从版本 5.0 开始,您可以提供SimpleWebServiceOutboundGateway
和MarshallingWebServiceOutboundGateway
使用外部WebServiceTemplate
实例,您可以为任何自定义属性配置该实例,包括checkConnectionForFault
(这允许您的应用程序处理不合格的服务)。
入站 Web 服务网关
要在收到 Web 服务调用时向通道发送消息,您同样有两个选项:SimpleWebServiceInboundGateway
和MarshallingWebServiceInboundGateway
.
前者提取javax.xml.transform.Source
从WebServiceMessage
并将其设置为 Message payload。
后者支持实现Marshaller
和Unmarshaller
接口。
如果传入的 Web 服务消息是 SOAP 消息,则 SOAP作标头将添加到Message
转发到 Request 通道。
以下示例显示了这两个选项:
simpleGateway = new SimpleWebServiceInboundGateway();
simpleGateway.setRequestChannel(forwardOntoThisChannel);
simpleGateway.setReplyChannel(listenForResponseHere); //Optional
marshallingGateway = new MarshallingWebServiceInboundGateway(marshaller);
//set request and optionally reply channel
这两个网关都实现了 Spring Web 服务MessageEndpoint
接口,因此它们可以配置一个MessageDispatcherServlet
根据标准 Spring Web 服务配置。
有关如何使用这些组件的更多详细信息,请参见 Spring Web 服务参考指南中介绍创建 Web 服务的章节。 介绍 Object/XML 映射的章节也同样适用。
要添加SimpleWebServiceInboundGateway
和MarshallingWebServiceInboundGateway
配置添加到 Spring WS 基础结构中,您应该添加EndpointMapping
定义MessageDispatcherServlet
和目标MessageEndpoint
实现,就像你对普通的 Spring WS 应用程序所做的那样。
为此(从 Spring 集成的角度来看),Spring WS 提供了以下方便的EndpointMapping
实现:
-
o.s.ws.server.endpoint.mapping.UriEndpointMapping
-
o.s.ws.server.endpoint.mapping.PayloadRootQNameEndpointMapping
-
o.s.ws.soap.server.endpoint.mapping.SoapActionEndpointMapping
-
o.s.ws.server.endpoint.mapping.XPathPayloadEndpointMapping
您必须在应用程序上下文中为这些类指定 bean,并引用SimpleWebServiceInboundGateway
和/或MarshallingWebServiceInboundGateway
根据 WS 映射算法的 bean 定义。
有关更多信息,请参阅终端节点映射。
Web 服务命名空间支持
要配置出站 Web 服务网关,请使用outbound-gateway
元素ws
namespace 中,如下例所示:
<int-ws:outbound-gateway id="simpleGateway"
request-channel="inputChannel"
uri="https://example.org"/>
此示例不提供 'reply-channel'。
如果 Web 服务返回非空响应,则Message 包含该响应的响应将发送到请求消息的REPLY_CHANNEL 页眉。
如果这不可用,则会引发 channel resolution 异常。
如果要将回复发送到另一个通道,请在 'outbound-gateway' 元素上提供 'reply-channel' 属性。 |
默认情况下,当您调用在对请求使用 String 负载后返回空响应的 Web 服务时Message ,没有回复Message 已发送。
因此,你不需要设置 'reply-channel' 或有一个REPLY_CHANNEL 标头Message .
如果您确实希望以Message ,您可以将 'ignore-empty-responses' 属性设置为false .
这样做仅适用于String 对象,因为使用Source 或Document object 导致 null 响应,因此永远不会生成回复Message . |
要设置入站 Web Service Gateway,请使用inbound-gateway
元素,如下例所示:
<int-ws:inbound-gateway id="simpleGateway"
request-channel="inputChannel"/>
要使用 Spring OXM 编组器或解组器,必须提供 bean 引用。 以下示例说明如何为出站编组网关提供 Bean 引用:
<int-ws:outbound-gateway id="marshallingGateway"
request-channel="requestChannel"
uri="https://example.org"
marshaller="someMarshaller"
unmarshaller="someUnmarshaller"/>
下面的示例展示了如何为入站编组网关提供 Bean 引用:
<int-ws:inbound-gateway id="marshallingGateway"
request-channel="requestChannel"
marshaller="someMarshaller"
unmarshaller="someUnmarshaller"/>
最Marshaller implementation 还会实现Unmarshaller 接口。
当使用这样的Marshaller ,则只有marshaller 属性是必需的。
即使使用Marshaller ,您还可以为request-callback 在出站网关上。 |
对于任一出站网关类型,您都可以指定destination-provider
属性而不是uri
(恰好需要其中之一)。
然后,您可以引用任何 Spring Web 服务DestinationProvider
实现(例如,在运行时从注册表中查找 URI)。
对于任一出站网关类型,message-factory
属性也可以配置对任何 Spring Web 服务的引用WebServiceMessageFactory
实现。
对于简单入站网关类型,您可以设置extract-payload
属性设置为false
转发整个WebServiceMessage
而不仅仅是其 payload 作为Message
添加到请求通道。
这样做可能很有用,例如,当自定义转换器与WebServiceMessage
径直。
从版本 5.0 开始,web-service-template
reference 属性允许您将WebServiceTemplate
具有任何可能的自定义属性。
Web 服务 Java DSL 支持
以下代码段显示了 Web 服务命名空间支持中显示的网关的等效配置:
@Bean
IntegrationFlow inbound() {
return IntegrationFlow.from(Ws.simpleInboundGateway()
.id("simpleGateway"))
...
.get();
}
@Bean
IntegrationFlow outboundMarshalled() {
return f -> f.handle(Ws.marshallingOutboundGateway()
.id("marshallingGateway")
.marshaller(someMarshaller())
.unmarshaller(someUnmarshalller()))
...
}
@Bean
IntegrationFlow inboundMarshalled() {
return IntegrationFlow.from(Ws.marshallingInboundGateway()
.marshaller(someMarshaller())
.unmarshaller(someUnmarshalller())
.id("marshallingGateway"))
...
.get();
}
其他属性可以以流畅的方式在终端节点规范上设置(属性取决于外部WebServiceTemplate
已为出站网关提供)。
例子:
.from(Ws.simpleInboundGateway()
.extractPayload(false))
.handle(Ws.simpleOutboundGateway(template)
.uri(uri)
.sourceExtractor(sourceExtractor)
.encodingMode(DefaultUriBuilderFactory.EncodingMode.NONE)
.headerMapper(headerMapper)
.ignoreEmptyResponses(true)
.requestCallback(requestCallback)
.uriVariableExpressions(uriVariableExpressions)
.extractPayload(false))
)
.handle(Ws.marshallingOutboundGateway()
.destinationProvider(destinationProvider)
.marshaller(marshaller)
.unmarshaller(unmarshaller)
.messageFactory(messageFactory)
.encodingMode(DefaultUriBuilderFactory.EncodingMode.VALUES_ONLY)
.faultMessageResolver(faultMessageResolver)
.headerMapper(headerMapper)
.ignoreEmptyResponses(true)
.interceptors(interceptor)
.messageSenders(messageSender)
.requestCallback(requestCallback)
.uriVariableExpressions(uriVariableExpressions))
.handle(Ws.marshallingOutboundGateway(template)
.uri(uri)
.encodingMode(DefaultUriBuilderFactory.EncodingMode.URI_COMPONENT)
.headerMapper(headerMapper)
.ignoreEmptyResponses(true)
.requestCallback(requestCallback)
.uriVariableExpressions(uriVariableExpressions))
)
出站 URI 配置
对于 Spring Web 服务支持的所有 URI 方案(参见 URI 和传输) <uri-variable/>
提供了 substitution 。
以下示例显示了如何定义它:
<ws:outbound-gateway id="gateway" request-channel="input"
uri="https://springsource.org/{thing1}-{thing2}">
<ws:uri-variable name="thing1" expression="payload.substring(1,7)"/>
<ws:uri-variable name="thing2" expression="headers.x"/>
</ws:outbound-gateway>
<ws:outbound-gateway request-channel="inputJms"
uri="jms:{destination}?deliveryMode={deliveryMode}&priority={priority}"
message-sender="jmsMessageSender">
<ws:uri-variable name="destination" expression="headers.jmsQueue"/>
<ws:uri-variable name="deliveryMode" expression="headers.deliveryMode"/>
<ws:uri-variable name="priority" expression="headers.jms_priority"/>
</ws:outbound-gateway>
如果您提供DestinationProvider
,则不支持变量替换,如果提供变量,则会发生配置错误。
控制 URI 编码
默认情况下,URL 字符串是编码的(请参阅UriComponentsBuilder
) 添加到 URI 对象。
在某些具有非标准 URI 的方案中,不需要执行编码。
这<ws:outbound-gateway/>
元素提供了一个encoding-mode
属性。
要禁用 URL 编码,请将此属性设置为NONE
(默认情况下,它是TEMPLATE_AND_VALUES
).
如果您希望对某些 URL 进行部分编码,可以使用expression
在<uri-variable/>
,如下例所示:
<ws:outbound-gateway url="https://somehost/%2f/fooApps?bar={param}" encoding-mode="NONE">
<http:uri-variable name="param"
expression="T(org.apache.commons.httpclient.util.URIUtil)
.encodeWithinQuery('Hello World!')"/>
</ws:outbound-gateway>
如果您将DestinationProvider ,encoding-mode 被忽略。 |
WS 消息头
Spring 集成 Web 服务网关会自动映射 SOAP作头。
默认情况下,它与 Spring 集成之间相互复制MessageHeaders
通过使用DefaultSoapHeaderMapper
.
您可以传入自己的特定于 SOAP 的头映射器的实现,因为网关具有支持这样做的属性。
除非requestHeaderNames
或replyHeaderNames
的属性DefaultSoapHeaderMapper
,则不会将任何用户定义的 SOAP 标头复制到 SOAP 消息或从 SOAP 消息复制任何用户定义的 SOAP 标头。
当您使用 XML 命名空间进行配置时,您可以使用mapped-request-headers
和mapped-reply-headers
属性,您可以通过设置header-mapper
属性。
映射用户定义的 Headers 时,值还可以包含简单的通配符模式(例如myheader* 或myheader ).
例如,如果需要复制所有用户定义的标头,则可以使用通配符: . |
从版本 4.1 开始,AbstractHeaderMapper
(一个DefaultSoapHeaderMapper
superclass) 允许NON_STANDARD_HEADERS
token 的requestHeaderNames
和replyHeaderNames
属性(除了现有的STANDARD_REQUEST_HEADERS
和STANDARD_REPLY_HEADERS
) 映射所有用户定义的标头。
我们建议使用以下组合,而不是使用通配符 ():* STANDARD_REPLY_HEADERS, NON_STANDARD_HEADERS .
这样做可以避免映射request headers 添加到回复中。 |
从版本 4.3 开始,您可以通过在模式前面加上!
.
否定模式获得优先级,因此STANDARD_REQUEST_HEADERS,thing1,thing*,!thing2,!thing3,qux,!thing1
不映射thing1
,thing2
或thing3
.
它确实映射了标准标头,thing4
和qux
.
(请注意,thing1
以非否定和否定形式包含。
因为否定的值优先,所以thing1
未映射。
如果您有一个以! ,则可以使用 进行转义,如下所示:\ STANDARD_REQUEST_HEADERS,\!myBangHeader .
一个!myBangHeader 然后映射。 |
入站 SOAP 标头(入站网关的请求标头和出站网关的回复标头)映射为SoapHeaderElement
对象。
您可以通过访问Source
:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<auth>
<username>user</username>
<password>pass</password>
</auth>
<bar>BAR</bar>
<baz>BAZ</baz>
<qux>qux</qux>
</soapenv:Header>
<soapenv:Body>
...
</soapenv:Body>
</soapenv:Envelope>
如果mapped-request-headers
是auth, ca*
这auth
,cat
和can
headers 被映射,但qux
未映射。
以下示例演示如何获取名为user
从名为auth
:
...
SoapHeaderElement header = (SoapHeaderElement) headers.get("auth");
DOMSource source = (DOMSource) header.getSource();
NodeList nodeList = source.getNode().getChildNodes();
assertEquals("username", nodeList.item(0).getNodeName());
assertEquals("user", nodeList.item(0).getFirstChild().getNodeValue());
...
从版本 5.0 开始,DefaultSoapHeaderMapper
支持用户定义的标头类型javax.xml.transform.Source
并将它们填充为<soapenv:Header>
.
以下示例显示了如何执行此作:
Map<String, Object> headers = new HashMap<>();
String authXml =
"<auth xmlns='http://test.auth.org'>"
+ "<username>user</username>"
+ "<password>pass</password>"
+ "</auth>";
headers.put("auth", new StringSource(authXml));
...
DefaultSoapHeaderMapper mapper = new DefaultSoapHeaderMapper();
mapper.setRequestHeaderNames("auth");
上述示例的结果是以下 SOAP 信封:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<auth xmlns="http://test.auth.org">
<username>user</username>
<password>pass</password>
</auth>
</soapenv:Header>
<soapenv:Body>
...
</soapenv:Body>
</soapenv:Envelope>
MTOM 支持
编组入站和出站 Web 服务网关直接通过编组程序的内置功能(例如,Jaxb2Marshaller
提供mtomEnabled
选项)。
从版本 5.0 开始,简单 Web 服务网关可以直接使用入站和出站进行作MimeMessage
实例,这些实例具有用于作附件的 API。
当您需要发送带有附件的 Web 服务消息(来自服务器的回复或客户端请求)时,您应该使用WebServiceMessageFactory
直接发送WebServiceMessage
将附件作为payload
添加到网关的请求或回复通道。
以下示例显示了如何执行此作:
WebServiceMessageFactory messageFactory = new SaajSoapMessageFactory(MessageFactory.newInstance());
MimeMessage webServiceMessage = (MimeMessage) messageFactory.createWebServiceMessage();
String request = "<test>foo</test>";
TransformerFactory transformerFactory = TransformerFactory.newInstance();
Transformer transformer = transformerFactory.newTransformer();
transformer.transform(new StringSource(request), webServiceMessage.getPayloadResult());
webServiceMessage.addAttachment("myAttachment", new ByteArrayResource("my_data".getBytes()), "plain/text");
this.webServiceChannel.send(new GenericMessage<>(webServiceMessage));