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文件就很容易了。就像上面提到的同樣，服務組只是服務元素的集合，前面提到的全部語法在服務組中是同樣的。