Axis2 Web服务配置文件services.xml详解

  在Axis1中部署服务时，咱们使用service.wsdd文件来配置服务。在Axis2中，再也不使用service.wsdd文件来配置服务，改用services.xml了。这两个配置文件的语法是大相径庭的。

    本文涵盖了services.xml文件的语法和使用说明。在Apache Axis2/Java中，同一个服务包文件既能够用于部署单个服务，也能够部署多个服务。不论以何种方式部署服务，一个有效的服务包文件必须包含services.xml文件。随着咱们部署服务的方式不一样，services.xml文件的语法也不一样。Services.xml文件主要有两种：一种用于部署单个服务，一种用于部署服务组。

编写用于部署单个服务的services.xml文件

    用于部署单个服务的services.xml文件的根节点是 service,整个文件看起来就像这样：

<service>
......
</service>

    咱们用服务包部署单个服务时，若是咱们没有给service节点指定name属性，那么服务包文件名称就是服务名称。例如假设服务包文件名是foo.aar，那么服务名就是foo。咱们也能够给service节点添加name属性来指定不一样的服务名称。以下所述：服务名

<service name="foo">
......
</service>

    服务编写者可使用description元素来描述该服务。在Axis2 Web管理控制台中查看服务时，咱们只能看到服务名和服务描述。若是咱们不给services.xml文件添加description元素，则服务描述栏会显示服务名称。对于那些访问该服务的用户来讲，服务描述是很是有用的。添加服务描述信息很是简单，给services.xml文件添加一个可选的description节点就能够了。该节点的值既能够是纯文本，也能够是HTML代码片断。服务描述

<service>
<description>计算矩形面积</description>
......
</service>

也能够写成这样：

<service>
<description><b>计算矩形面积</b></description>
......
</service>

注：description节点是可选节点

服务级参数

    在services.xml文件中，咱们能够直接在service节点下定义参数，这些参数供消息上下文(在运行时)、AxisService或者AxisOperation访问。参数有一个必选参数和可选参数：参数名称是必选参数，locked 属性是可选参数。

    locked属性指明了是否容许参数值被子节点覆盖。举例来讲，若是咱们在axis2.xml文件中添加了一个locked属性值为true的参数，那么若是服务试图在services.xml文件中定义同名参数，是会抛出异常的。

    举例来讲，假设axis2.xml文件中定义了一个名叫foo的参数，该参数locked属性为true,而services.xml文件也有一个同名参数，那么部署时会抛出异常。若是参数的locked属性为true，则不能在子节点中覆盖父节点中定义的参数。

    参数值能够是任何东西，它既能够是纯文本也能够是XML片断。要添加服务级参数，请参考下文：

<service>
.....
<parameter name=location>Colombo , Sri Lanka</parameter>
.....
</service>

服务类

    在Axis2中，Web服务并不强制要求指定服务实现类！Axis2架构容许编写没有服务实现类的Web服务，这是由于消息接收器容许这样作。Axis2中，一旦请求交予消息接收器处理，Axis2引擎就认为本身的事情作完了，剩余工做都是消息接收器的了。所以，services.xml并不强制要求提供服务实现类。可是绝大多数状况下，咱们仍是须要服务类的，咱们能够在services.xml文件中添加ServiceClass参数来指定服务类。该参数的值是服务类的全路径名。示例以下：
服务级消息接收器

<parameter name="ServiceClass" locked="false">org.apache.Foo</parameter>

    Axis2中消息接收器是特殊的处理器，是In路径（请求路径）中的最后一个处理器。Web服务中的每一个操做都有他本身的消息接收器，并且不一样的操做能够有不一样的消息接收器。消息接收器是依赖于消息交换模式的,因此咱们必须为不一样的消息交换模式指定不一样的消息接收器。

    怎样才能给全部的操做指定相同的消息接收器呢？只要添加服务级消息接收器便可。如此咱们就没必要在操做级别指定消息接收器了。咱们要作的是指定服务级消息接收器。而在部署时，Axis2会自动给操做选择正确的消息接收器。
使用模块

<messageReceivers>

<messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only" class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/>

<messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out" class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>

</messageReceivers>

    在一些状况下，若是不使用WS-Security模块，咱们就不该该运行该服务。这时咱们只需往services.xml文件中添加module标签，就能使用该模块了。须要注意的是，若是模块不可用会致使服务变成有错误的服务而没法使用。
服务会话范围

<service>

<module ref=foo/>

</service>

    Axis2中Web服务有四种会话范围。若是不指定，则默认为 request 会话范围。咱们能够经过给 service 节点添加一个可选的 scope参数来指定会话范围，会话范围共有以下四种：

1. application : 应用级别。生命周期和Axis2引擎生命周期相同。
2. soapsession : 使用addressing headers中的自定义引用属性来管理会话。
3. transportsession : 使用transport cookies来管理会话，生命周期和底层的transport相同。
4. request :生命周期很短，和请求处理周期相同。

<service scope="application">

......

</service>

Service目标名字空间

    服务目标名字空间仅仅在WSDL生成过程当中起做用。在运行时，若是有人试图使用?wsdl来查看WSDL，那么生成的WSDL文件中的目标名字空间就是services.xml文件中指定的值。同时，咱们为了使用自定义的WSDL文件，把WSDL文件放到META-INF目录中，这种状况下要覆盖原有的目标名字空间，也是经过往services.xml文件中添加目标名字空间来实现的。目标名字空间的缺省值是http://ws.apache.org/axis2。

    要指定目标名字空间，咱们须要给service节点添加可选的targetNamespace属性，示例以下

<service targetNamespace=http://foo.org>
......
</service>

Schema目标名字空间

    当生成WSDL文件（运行时）或者生成schema（部署时）的时候，若是在META-INF目录中找不到WSDL文件，则能够经过往services.xml文件中添加schema节点来指定自定义的schema目标名字空间。

    在部署的时候，若是不指定schema目标名字空间，则根据服务实现类的全路径名来生成目标名字空间。例如，若是服务类的全路径名是org.apache.axis2.FooService，那生成的schema名字空间是http://FooService.axis2.apache.org/xsd

    若是你想使用自定义值，只须要在services.xml文件中添加下述节点便可。

<service>

<schema schemaNamespace=http://foo.org/xsd/>

</service>

WSDL中的elementFormDefault值

    在使用Java类生成WSDL文件时，WSDL文件中schema定义中的elementFormDefault默认是设置为qualified。若是qualified为true，则响应消息中的全部元素都是受限的。可是有些时候咱们并不须要这种行为，咱们但愿把elementFormDefault设置为unqualified。这时咱们只须要在services.xml文件中添加下述条目便可。

<schema elementFormDefaultQualified="false"/>

注：咱们还能够同时指定schemaNamespace属性。

在指定的传输通道上暴露服务

    Axis2能够在多种传输通道上暴露服务，这是经过Lister Manager完成的。例如，使用Listener Manager你能够在HTTP和TCP上暴露服务。

    因为Axis2支持多种传输通道，因此咱们能够在选定的传输通道上暴露服务。好比说系统管理服务，咱们但愿该服务只在支持SSL的通道上暴露，这样才能保证系统管理的安全性。

    当服务端支持多种传输通道时，全部的服务都是在全部的通道上暴露的。若是只但愿在选定的通道上暴露服务，咱们须要在services.xml文件中添加transport标签，以下所述：

<transports>

<transport>https</transport>

</transports>

操做和操做相关元素

    上一节描述了会影响服务中全部操做的服务级配置。例如，咱们在服务级使用模块，这是会影响服务中全部操做的。可是有时咱们但愿在操做中覆写这些配置或者添加新配置。

注：若是服务实现类是用Java编写的，那么服务类中的全部public方法，默认都是要暴露出去的。若是服务类使用其它语言编写的，那么咱们必须指定要发布的操做，不然默认是不暴露出去的。

覆写操做

    上面提到了咱们想在操做中覆写服务级配置。要覆写服务级参数，咱们须要添加operation标签：

<service>

<parameter name=location locked=false>Colombo , Sri Lanka </parameter>

<operation name=doSmt>

<parameter name=location locked=false>California ,USA</parameter>

</operation>

</service>

Operation 级消息接收器

    前文描述了如何指定服务级消息接收器。可是，咱们也能够为不一样的操做指定不一样的消息接收器，这须要在operation中指定messageReceiver标签

<operation name=doSmt>

<messageReceiver class="org.apache.axis2.MyMessageReceiver"/>

</operation>

添加actionMapping

    actionMapping至关于操做的别名。咱们能够为操做添加任意数量的别名。咱们能够根据ActionMapping来过滤请求，也能够为不一样的action mapping 执行不一样的处理逻辑。客户端请求消息中经过指定SOAPAction或者wsa:action来发送action mapping。这样Axis2的分发器就能够把请求消息分发给正确的操做。

<operation name=doSmt>

<actionMapping>mapping1</actionMapping>

<actionMapping>http://foo.org/doSmt</actionMapping>

</operation>

使用模块

    就像咱们在服务中使用模块，咱们也能够在操做中使用模块。举例来讲，若是咱们只但愿在指定的操做上提供安全访问，最好的方法是在这些操做中使用模块。

    要使用模块，只须要在operation元素中添加module元素便可。
排除操做

<operation name=doSmt>

<module ref="foo"/>

</operation>

    Axis2默认会暴露实现类中的全部public方法（若是是用Java实现的）。若是咱们把.wsdl文件放到META-INF目录中，而由不但愿发布文件中的全部操做，那么咱们能够添加excludeOperations标签来排除那些不但愿暴露的操做。

<excludeOperations>

<operation>op1</operation>

</excludeOperations>

编写用于部署服务组的services.xml文件

    要在单个服务包文件中部署多个服务，服务组是一个便捷方法。固然，这些服务之间应该存在逻辑关系。用于服务组的services.xml文件和用于单个服务的，它们之间惟一的区别就是根元素。用于服务组的，根元素是serviceGroup，咱们能够在serviceGroup元素内部定义多个service元素。

<serviceGroup>

<service name=service1>

......

<service>

<service name=service2>

..........

</service>

</serviceGroup>

注：在这种状况下，服务包文件名成了服务组的名称。Service元素的name属性成了必选属性，并且在整个服务器中必须保证惟一。系统不容许两个服务同名。

    一旦咱们了解了如何编写用于单个服务的services.xml文件，那编写用于服务组的services.xml文件就很容易了。就像上面提到的同样，服务组只是服务元素的集合，前面提到的全部语法在服务组中是同样的。