Axis2 Web服務組態檔services.xml詳解，axis2services.xml

Axis2 Web服務組態檔services.xml詳解，axis2services.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,整個檔案看起來就像這樣：

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

服務名

    我們用服務包部署單個服務時，如果我們沒有給service節點指定name屬性，那麼服務包檔案名稱就是服務名稱。例如假設服務包檔案名稱是foo.aar，那麼服務名就是foo。我們也可以給service節點添加name屬性來指定不同的服務名稱。如下所述：

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

服務描述

    服務編寫者可以使用description元素來描述該服務。在Axis2 Web管理主控台中查看服務時，我們只能看到服務名和服務描述。如果我們不給services.xml檔案添加description元素，則服務描述列會顯示服務名稱。對於那些訪問該服務的使用者來說，服務描述是非常有用的。添加服務描述資訊非常簡單，給services.xml檔案添加一個可選的description節點就可以了。該節點的值既可以是純文字，也可以是HTML程式碼片段。

1234	<service><description>計算矩形面積</description>……</service>

也可以寫成這樣：

1234	<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片段。要添加服務級參數，請參考下文：

12345

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

服務類

    在Axis2中，Web服務並不強制要求指定服務實作類別！Axis2架構允許編寫沒有服務實作類別的Web服務，這是因為訊息接收器允許這樣做。Axis2中，一旦請求交予訊息接收器處理，Axis2引擎就認為自己的事情做完了，剩餘工作都是訊息接收器的了。因此，services.xml並不強制要求提供服務實作類別。但是絕大多數情況下，我們還是需要服務類的，我們可以在services.xml檔案中添加ServiceClass參數來指定服務類。該參數的值是服務類的全路徑名。樣本如下：

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

服務級訊息接收器

    Axis2中訊息接收器是特殊的處理器，是In路徑（請求路徑）中的最後一個處理器。Web服務中的每個操作都有他自己的訊息接收器，而且不同的操作可以有不同的訊息接收器。訊息接收器是依賴於訊息交換模式的,所以我們必須為不同的訊息交換模式指定不同的訊息接收器。

    怎樣才能給所有的操作指定相同的訊息接收器呢？只要添加服務級訊息接收器即可。如此我們就不必在操作層級指定訊息接收器了。我們要做的是指定服務級訊息接收器。而在部署時，Axis2會自動給操作選擇正確的訊息接收器。

1234	<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標籤，就能使用該模組了。需要注意的是，如果模組不可用會導致服務變成有錯誤的服務而無法使用。

123	<service><module ref=foo/></service>

服務會話範圍

    Axis2中Web服務有四種會話範圍。如果不指定，則預設為 request 會話範圍。我們可以通過給 service 節點添加一個可選的 scope參數來指定會話範圍，會話範圍共有如下四種：

1. application : 應用層級。生命週期和Axis2引擎生命週期相同。
2. soapsession : 使用addressing headers中的自訂引用屬性來管理會話。
3. transportsession : 使用transport cookies來管理會話，生命週期和底層的transport相同。
4. request :生命週期很短，和請求處理周期相同。

123	<service scope="application">......</service>

Service目標名字空間

    服務目標名字空間僅僅在WSDL產生過程中起作用。在運行時，如果有人試圖使用?wsdl來查看WSDL，那麼產生的WSDL檔案中的目標名字空間就是services.xml檔案中指定的值。同時，我們為了使用自訂的WSDL檔案，把WSDL檔案放到META-INF目錄中，這種情況下要覆蓋原有的目標名字空間，也是通過往services.xml檔案中添加目標名字空間來實現的。目標名字空間的預設值是http://ws.apache.org/axis2。

    要指定目標名字空間，我們需要給service節點添加可選的targetNamespace屬性，樣本如下：

123	<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檔案中添加下述節點即可。

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

WSDL中的elementFormDefault值

    在使用Java類產生WSDL檔案時，WSDL檔案中schema定義中的elementFormDefault預設是設定為qualified。如果qualified為true，則響應訊息中的所有元素都是受限的。但是有些時候我們並不需要這種行為，我們希望把elementFormDefault設定為unqualified。這時我們只需要在services.xml檔案中添加下述條目即可。

1	<schema elementFormDefaultQualified="false"/>

註：我們還可以同時指定schemaNamespace屬性。

在指定的傳輸通道上暴露服務

    Axis2可以在多種傳輸通道上暴露服務，這是通過Lister Manager完成的。例如，使用Listener Manager你可以在HTTP和TCP上暴露服務。

    由於Axis2支援多種傳輸通道，所以我們可以在選定的傳輸通道上暴露服務。比如說系統管理服務，我們希望該服務只在支援SSL的通道上暴露，這樣才能保證系統管理的安全性。

    當服務端支援多種傳輸通道時，所有的服務都是在所有的通道上暴露的。如果只希望在選定的通道上暴露服務，我們需要在services.xml檔案中添加transport標籤，如下所述：

123	<transports><transport>https</transport></transports>

操作和操作相關元素

    上一節描述了會影響服務中所有操作的服務級配置。例如，我們在服務級使用模組，這是會影響服務中所有操作的。但是有時我們希望在操作中覆寫這些配置或者添加新配置。

註：如果服務實作類別是用Java編寫的，那麼服務類中的所有public方法，預設都是要暴露出去的。如果服務類使用其它語言編寫的，那麼我們必須指定要發布的操作，否則預設是不暴露出去的。

覆寫操作

    上面提到了我們想在操作中覆寫服務級配置。要覆寫服務級參數，我們需要添加operation標籤：

123456

<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標籤

123	<operation name=doSmt><messageReceiver class="org.apache.axis2.MyMessageReceiver"/></operation>

添加actionMapping

    actionMapping相當於操作的別名。我們可以為操作添加任意數量的別名。我們可以根據ActionMapping來過濾請求，也可以為不同的action mapping 執行不同的處理邏輯。用戶端請求訊息中通過指定SOAPAction或者wsa:action來發送action mapping。這樣Axis2的分發器就可以把請求訊息分發給正確的操作。

1234	<operation name=doSmt><actionMapping>mapping1</actionMapping><actionMapping>http://foo.org/doSmt</actionMapping></operation>

使用模組

    就像我們在服務中使用模組，我們也可以在操作中使用模組。舉例來說，如果我們只希望在指定的操作上提供安全訪問，最好的方法是在這些操作中使用模組。

    要使用模組，只需要在operation元素中添加module元素即可。

123	<operation name=doSmt><module ref="foo"/></operation>

排除操作

    Axis2預設會暴露實作類別中的所有public方法（如果是用Java實現的）。如果我們把.wsdl檔案放到META-INF目錄中，而由不希望發布檔案中的所有操作，那麼我們可以添加excludeOperations標籤來排除那些不希望暴露的操作。

123	<excludeOperations><operation>op1</operation></excludeOperations>

編寫用於部署服務組的services.xml檔案

    要在單個服務包檔案中部署多個服務，服務組是一個便捷方法。當然，這些服務之間應該存在邏輯關係。用於服務組的services.xml檔案和用於單個服務的，它們之間唯一的區別就是根項目。用於服務組的，根項目是serviceGroup，我們可以在serviceGroup元素內部定義多個service元素。

12345678

<serviceGroup><service name=service1>......<service><service name=service2>..........</service></serviceGroup>

註：在這種情況下，服務包檔案名稱成了服務組的名稱。Service元素的name屬性成了必選屬性，而且在整個伺服器中必須保證唯一。系統不允許兩個服務同名。

    一旦我們瞭解了如何編寫用於單個服務的services.xml檔案，那編寫用於服務組的services.xml檔案就很容易了。就像上面提到的一樣，服務組只是服務元素的集合，前面提到的所有文法在服務組中是一樣的。