WSO2 ESB XML定义语法（1）

1.(基于Apache Synapse的WSO2 ESB实现)参考文件位置： http://synapse.apache.org/userguide/config.html

　　基于Apache Synapse的WSO2 ESB实现,使用基于XML的配置语言进行配置。这是由Synapse社区创建和维护的域特定语言（DSL）。该语言设计简单，直观且易于学习。此语言中的所有XML元素（标记）必须使用命名空间URL http://ws.apache.org/ns/synapse进行命名空间限定。如下图：

2.配置语法

　　1.registry 配置

　　<registry>元素用于定义运行时使用的注册表适配器。注册表提供程序为正在使用的注册表指定实现类，并且可选地指定特定注册表实现可能需要的许多配置参数。下面给出了概要配置。

<registry provider="string"/> 
    <parameter name="string">text | xml</parameter>* 
</registry>

实例：

<registry provider="org.apache.synapse.registry.url.SimpleURLRegistry"> 
<parameter name="root">file:./repository/conf/sample/resources/</parameter> 
<parameter name="cachableDuration">15000</parameter> 
</registry>

'root'参数指定已加载资源的注册表的根URL。SimpleURLRegistry键是路径片段，当与根前缀组合时，将形成引用资源的完整URL。

'cachableDuration'参数指定应缓存从注册表加载的资源的毫秒数。更高级的注册表实现允许为不同的资源指定不同的可缓存持续时间，或者将某些资源标记为永不过期。（例如，检查基于Apache Synapse的WSO2 ESB实现）

2.Local Entry (Local Registry) Configuration

　　Local Entry提供了将各种外部配置工件导入Synapse runtime的便捷方法。这包括WSDL，策略，XSLT文件和脚本。在服务器启动时解析本地条目定义，并将引用的配置加载到内存中，直到服务器关闭为止。其他功能组件（如序列，端点和代理服务）可以使用Local Entry引用这些本地定义的内存中配置元素。

<localEntry>元素用于声明Synapse实例的本地注册表项。

<localEntry key="string" [src="url"]>text | xml</localEntry>

　　Local Entry可能包含指定为内联内容的静态文本或静态XML。

<localEntry key="version">0.1</localEntry> 

<localEntry key="validate_schema"> 
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
... 
</xs:schema> 
</localEntry>

　　请注意包含一些静态XML架构内容的validate_schema 的Local Entry。诸如validate mediator之类的中介可以引用此Local Entry来加载其XML模式定义。

　　Local Entry还可以指向可以从中加载内容的远程URL（使用'src'属性指定）。这样，用户无需在Synapse配置中指定所有外部配置。所需的工件可以保存在文件系统上或托管在Web服务器上，Synapse可以使用Local Entry定义从中获取它们。以下示例显示如何配置Local Entry以从本地文件系统加载XSLT文件。

<localEntry key =“xslt-key-req”src =“file：repository / conf / sample / resources / transform / transform.xslt”/>

　　值得注意的是，Synapse仅在服务器启动期间加载Local Entry内容（即使使用远程URL定义它们）。因此，在重新启动服务器之前，对远程工件所做的任何更改都不会反映在Synapse上。这与远程注册表的行为形成对比，在远程注册表中，一旦缓存周期到期，Synapse就会重新加载配置工件。

3.Sequence配置

　　Sequence类似于Synapse中的消息流，由一组调解器组成。

　　<sequence>元素用于定义Synapse配置中的Sequence。

　　可以使用名称定义Sequence，以便可以在Synapse配置中重复使用它们。名为“main”和“fault”的序列在Synapse配置中具有特殊意义。'main'序列处理' Message Mediation '接受的任何消息”。如果Synapse遇到故障，则调用'fault'序列，并且不通过其'onError'属性为序列指定自定义错误处理程序。如果“主”或“故障”序列未在本地定义或未在注册表中找到，则Synapse auto会在初始化时生成合适的默认值。

　　可以通过指定对注册表项的密钥引用来定义动态Sequence。随着远程注册表项的更改，将根据指定的缓存持续时间和到期动态更新Sequence。如果对Sequence启用了跟踪，则通过Sequence处理的所有消息都会通过每个中介步骤将跟踪信息写入通过log4j.properties配置配置的“trace.log”文件。

下面给出了序列定义的语法概要。

<sequence name="string" [onError="string"] [key="string"] [trace="enable"] [statistics="enable"]>

 mediator* 

</sequence>

'onError'属性可用于定义自定义错误处理程序序列。可以通过在序列上将“statistics”属性设置为“enable”来激活统计信息收集。在此模式下，序列将跟踪处理的消息数量及其处理时间。然后可以通过Synapse统计API检索此统计信息。

sequence元素的所有直接子元素必须是有效的调解器。以下示例显示了由三个子调解器组成的序列配置。

<sequence name =“main”onError =“errorHandler”> 
<log /> 
<property name =“test” value =“test value”/> 
<send /> 
</ sequence>

sequence还可以将消息移交给其他序列。在这个意义上，sequence类似于较大程序中的过程。在许多编程语言中，过程可以调用其他过程。请参阅以下示例sequence配置。

<sequence name =“foo”>
<log /> 
<property name =“test”value =“test value”/> 
<sequence key =“other_sequence”/> 
<send /> 
</ sequence>

注意如何使用'sequence'元素将消息传递给名为'other_sequence'的序列。'key'属性可以指向另一个命名序列，本地条目或远程注册表项。

4.Endpoint配置

<endpoint>元素定义传出消息的目标。可以在Synapse配置中定义几种类型的Endpoint。

Address endpoint
WSDL endpoint
Load balance endpoint
Fail-over endpoint
Default endpoint
Recipient list endpoint

这些Endpoint类型的配置语法和运行时语义彼此不同。但是，Endpoint定义的高级配置语法采用以下形式。

<endpoint [name="string"] [key="string"]> 

address-endpoint | default-endpoint | wsdl-endpoint | 
load-balanced-endpoint | fail-over-endpoint | recipient-list-endpoint 

</endpoint>

　　请注意Endpoint定义始终以“endpoint”元素开头。此顶级“Endpoint”元素的直接子元素确定Endpoint的类型。以上所有Endpoint类型都可以具有“name”属性，并且这些命名Endpoint可以通过key属性由其他Endpoint引用。例如，如果存在名为“foo”的Endpoint，则可以在任何需要使用“foo”的地方使用以下Endpoint。

<endpoint key="foo"/>

这提供了一种在Synapse配置中重用Endpoint定义的简单机制。

'trace'属性打开发送到Endpoint的消息的详细跟踪信息。这些将在通过log4j.properties文件配置的“trace.log”文件中提供。

4.1 Address Endpoint

<address uri="endpoint address" [format="soap11|soap12|pox|get"] [optimize="mtom|swa"] 
　　
　　[encoding="charset encoding"] [statistics="enable|disable"] [trace="enable|disable"]> 

<enableSec [policy="key"]/>? 

<enableAddressing [version="final|submission"] [separateListener="true|false"]/>? 

　　<timeout> 

　　　　<duration>timeout duration in milliseconds</duration> 

　　　　<responseAction>discard|fault</responseAction> 

　　</timeout>? 

<markForSuspension> 

　　[<errorCodes>xxx,yyy</errorCodes>]
 
　　<retriesBeforeSuspension>m</retriesBeforeSuspension> 

　　<retryDelay>d</retryDelay>

</markForSuspension>

<suspendOnFailure> 
　　[<errorCodes>xxx,yyy</errorCodes>] 

　　<initialDuration>n</initialDuration> 

　　<progressionFactor>r</progressionFactor> 

　　<maximumDuration>l</maximumDuration> 

</suspendOnFailure> 

</address>

地址Endpoint是通过在配置中直接指定端点的EPR和其他属性来定义的Endpoint。address元素的'uri'属性包含目标端点的EPR。端点的消息格式和优化附件的方法可分别在'format'和'optimize'属性中指定。可以在“enableSec”元素的policy属性中指定端点的安全策略。通过使用'enableAddressing'元素，可以使用WS-Addressing发送到端点的消息。

端点配置的“timeout”元素用于为端点设置特定的套接字超时。默认情况下，此值设置为1分钟（60秒）。当与后端服务集成时，需要更长时间来响应超时持续时间应相应增加。

'responseAction'元素表示在超时时间段过去后收到响应时应采取的操作。Synapse可以“丢弃”延迟响应或将其注入“故障”处理程序。

Synapse端点是状态机。在任何给定的时间点，它可以处于四种状态之一 - 活动，超时，暂停和切换。端点如何以及何时更改其状态可通过Synapse配置进行配置。处于挂起或关闭状态的端点不能用于发送消息。这样的尝试会产生运行时错误。

默认情况下，端点处于“活动”状态。只要处于此状态，端点将继续转发请求。如果活动端点在尝试发送消息时遇到错误（例如：连接失败），则端点可能会被推入“超时”状态或“暂停”状态。通常，大多数错误会使端点直接进入“暂停”状态。连接超时（错误代码101504）和连接关闭错误（101505）是唯一不会直接挂起端点的错误。

使用'suspendOnFailure'中的'errorCodes'元素配置一可以明确定义应该挂起端点的错误。类似地，'markForSuspension'配置中的'errorCodes'元素可用于定义应将端点推入'Timeout'状态的错误。

“超时”状态的端点可用于发送消息。但是在此状态下的任何连续错误都可以将端点推入“暂停”状态。可以使用'markForSuspension'配置中的'retriesBeforeSuspension'元素配置可以挂起端点的连续错误数。'retryDelay'用于指定端点在将其移至'Timeout'状态后无法立即使用的持续时间。此持续时间应以毫秒为单位指定。

处于“已暂停”状态的端点不能用于发送消息。但暂停只是暂时的。可以使用'initialDuration'元素配置挂起持续时间。当此时间段到期时，暂停的端点可再次使用。但是，任何重复出现的错误都可能使端点返回“Suspended”状态。这种连续的暂停也可以逐渐增加由'progressionFactor'元素配置的端点的暂停持续时间。但暂停持续时间永远不会超过'maximumDuration'元素中配置的时间段。请注意'initialDuration'

下面给出一些示例地址端点配置。请注意通信协议如何用作后缀来指示传出传输。

4.3 Default 端点配置

　　默认端点是为端点添加QoS和其他配置而定义的端点，该端点是从消息上下文的“To”地址解析的。所有配置（例如端点的消息格式，优化附件的方法以及端点的安全策略）都可以像地址端点一样指定。此端点仅与“uri”属性中的地址端点不同，后者不会出现在此端点中。以下部分描述了默认端点的配置。

<default [format="soap11|soap12|pox|get"] [optimize="mtom|swa"] [encoding="charset encoding"] 

[statistics="enable|disable"] [trace="enable|disable"]> 

<enableSec [policy="key"]/>? 

<enableAddressing [version="final|submission"] [separateListener="true|false"]/>? 

<timeout> 

　　<duration>timeout duration in milliseconds</duration> 

　　<responseAction>discard|fault</responseAction> 

</timeout>? 

<markForSuspension>

　　[<errorCodes>xxx,yyy</errorCodes>] 

　　<retriesBeforeSuspension>m</retriesBeforeSuspension> 

　　<retryDelay>d</retryDelay> 

</markForSuspension> 

<suspendOnFailure> 

　　[<errorCodes>xxx,yyy</errorCodes>] 

　　<initialDuration>n</initialDuration> 

　　<progressionFactor>r</progressionFactor> 

　　<maximumDuration>l</maximumDuration> 

</suspendOnFailure> 

</default>

4.4 WSDL Endpoint

WSDL端点是基于指定的WSDL文档的端点定义。可以将WSDL文档指定为URI或配置中的内联定义。包含目标EPR的服务和端口名称必须分别使用“service”和“port”（或“endpoint”）属性指定。“enableSec”，“enableAddressing”，“suspendOnFailure”和“timeout”等元素与地址端点相同。

<wsdl [uri="wsdl-uri"] service="qname" port/endpoint="qname"> 

<wsdl:definition>...</wsdl:definition>? 

<wsdl20:description>...</wsdl20:description>? 

<enableSec [policy="key"]/>? 

<enableAddressing/>? 

<timeout>

 　 <duration>timeout duration in milliseconds</duration> 

　　<responseAction>discard|fault</responseAction> 

</timeout>? 

<markForSuspension>

　　[<errorCodes>xxx,yyy</errorCodes>] 

　　<retriesBeforeSuspension>m</retriesBeforeSuspension> 

　　<retryDelay>d</retryDelay> 

</markForSuspension> 

<suspendOnFailure> 

[<errorCodes>xxx,yyy</errorCodes>] 

<initialDuration>n</initialDuration>

<progressionFactor>r</progressionFactor>

<maximumDuration>l</maximumDuration>

</suspendOnFailure> 

</wsdl>