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,整個檔案看起來就像這樣:
1 2 3 |
< service >
...............
</ service >
|
服務名
我們用服務包部署單個服務時,如果我們沒有給service節點指定name屬性,那麼服務包檔名稱就是服務名稱。例如假設服務包檔名是foo.aar,那麼服務名就是foo。我們也可以給service節點新增name屬性來指定不同的服務名稱。如下所述:
1 2 3 |
< service name = "foo" >
...............
</ service >
|
服務描述
服務編寫者可以使用description元素來描述該服務。在Axis2 Web管理控制檯中檢視服務時,我們只能看到服務名和服務描述。如果我們不給services.xml檔案新增description元素,則服務描述欄會顯示服務名稱。對於那些訪問該服務的使用者來說,服務描述是非常有用的。新增服務描述資訊非常簡單,給services.xml檔案新增一個可選的description節點就可以了。該節點的值既可以是純文字,也可以是HTML程式碼片段。
1 2 3 4 |
< service >
< description >計算矩形面積</ description >
……
</ service >
|
也可以寫成這樣:
1 2 3 4 |
< 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片段。要新增服務級引數,請參考下文:
1 2 3 4 5 |
< 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會自動給操作選擇正確的訊息接收器。
1 2 3 4 |
< messageReceivers >
< messageReceiver mep = class = "org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver" />
< messageReceiver mep = class = "org.apache.axis2.rpc.receivers.RPCMessageReceiver" />
</ messageReceivers >
|
使用模組
在一些情況下,如果不使用WS-Security模組,我們就不應該執行該服務。這時我們只需往services.xml檔案中新增module標籤,就能使用該模組了。需要注意的是,如果模組不可用會導致服務變成有錯誤的服務而無法使用。
1 2 3 |
< service >
< module ref = foo />
</ service >
|
服務會話範圍
Axis2中Web服務有四種會話範圍。如果不指定,則預設為 request 會話範圍。我們可以通過給 service 節點新增一個可選的 scope引數來指定會話範圍,會話範圍共有如下四種:
- application : 應用級別。生命週期和Axis2引擎生命週期相同。
- soapsession : 使用addressing headers中的自定義引用屬性來管理會話。
- transportsession : 使用transport cookies來管理會話,生命週期和底層的transport相同。
- request :生命週期很短,和請求處理週期相同。
1 2 3 |
< service scope = "application" >
......
</ service >
|
Service目標名字空間
服務目標名字空間僅僅在WSDL生成過程中起作用。在執行時,如果有人試圖使用?wsdl來檢視WSDL,那麼生成的WSDL檔案中的目標名字空間就是services.xml檔案中指定的值。同時,我們為了使用自定義的WSDL檔案,把WSDL檔案放到META-INF目錄中,這種情況下要覆蓋原有的目標名字空間,也是通過往services.xml檔案中新增目標名字空間來實現的。目標名字空間的預設值是http://ws.apache.org/axis2。
要指定目標名字空間,我們需要給service節點新增可選的targetNamespace屬性,示例如下:
1 2 3 |
< 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檔案中新增下述節點即可。
1 2 3 |
< 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標籤,如下所述:
1 2 3 |
< transports >
< transport >https</ transport >
</ transports >
|
操作和操作相關元素
上一節描述了會影響服務中所有操作的服務級配置。例如,我們在服務級使用模組,這是會影響服務中所有操作的。但是有時我們希望在操作中覆寫這些配置或者新增新配置。
注:如果服務實現類是用Java編寫的,那麼服務類中的所有public方法,預設都是要暴露出去的。如果服務類使用其它語言編寫的,那麼我們必須指定要釋出的操作,否則預設是不暴露出去的。
覆寫操作
上面提到了我們想在操作中覆寫服務級配置。要覆寫服務級引數,我們需要新增operation標籤:
1 2 3 4 5 6 |
< 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標籤
1 2 3 |
< operation name = doSmt >
< messageReceiver class = "org.apache.axis2.MyMessageReceiver" />
</ operation >
|
新增actionMapping
actionMapping相當於操作的別名。我們可以為操作新增任意數量的別名。我們可以根據ActionMapping來過濾請求,也可以為不同的action mapping 執行不同的處理邏輯。客戶端請求訊息中通過指定SOAPAction或者wsa:action來發送action mapping。這樣Axis2的分發器就可以把請求訊息分發給正確的操作。
1 2 3 4 |
< operation name = doSmt >
< actionMapping >mapping1</ actionMapping >
< actionMapping actionMapping >
</ operation >
|
使用模組
就像我們在服務中使用模組,我們也可以在操作中使用模組。舉例來說,如果我們只希望在指定的操作上提供安全訪問,最好的方法是在這些操作中使用模組。
要使用模組,只需要在operation元素中新增module元素即可。
1 2 3 |
< operation name = doSmt >
< module ref = "foo" />
</ operation >
|
排除操作
Axis2預設會暴露實現類中的所有public方法(如果是用Java實現的)。如果我們把.wsdl檔案放到META-INF目錄中,而由不希望釋出檔案中的所有操作,那麼我們可以新增excludeOperations標籤來排除那些不希望暴露的操作。
1 2 3 |
< excludeOperations >
< operation >op1</ operation >
</ excludeOperations >
|
編寫用於部署服務組的services.xml檔案
要在單個服務包檔案中部署多個服務,服務組是一個便捷方法。當然,這些服務之間應該存在邏輯關係。用於服務組的services.xml檔案和用於單個服務的,它們之間唯一的區別就是根元素。用於服務組的,根元素是serviceGroup,我們可以在serviceGroup元素內部定義多個service元素。
1 2 3 4 5 6 7 8 |
< serviceGroup >
< service name = service1 >
......
< service >
< service name = service2 >
..........
</ service >
</ serviceGroup >
|
注:在這種情況下,服務包檔名成了服務組的名稱。Service元素的name屬性成了必選屬性,而且在整個伺服器中必須保證唯一。系統不允許兩個服務同名。
一旦我們瞭解瞭如何編寫用於單個服務的services.xml檔案,那編寫用於服務組的services.xml檔案就很容易了。就像上面提到的一樣,服務組只是服務元素的集合,前面提到的所有語法在服務組中是一樣的。