一般情況下,WS.Call 只是 XMLHttpRequest 之上的一層薄包裝,負責一些簡化處理,例如設定 SOAP 1.1 規範要求的 SOAPAction HTTP 標頭。
這個函式庫的 API 相當直覺。SOAP.* 物件(SOAP.Element、SOAP.Envelope、SOAP.Header、SOAP.Body)提供建構與讀取 SOAP 信封的方法,把底層 XML DOM 的細節順利抽象掉。
以下片段示範組出一個 SOAP 信封:
var envelope = new SOAP.Envelope();
var body = envelope.create_body();
var el = body.create_child(new WS.QName('method', 'urn:foo'));
el.create_child(new WS.QName('param', 'urn:foo')).set_value('bar');
產生的 SOAP 信封大致如下:
<envelope xmlns="https://schemas.xmlsoap.org">
<body>
<method xmlns="urn:foo">
<param>bar</param>
</method>
</body>
</envelope>
若 SOAP 信封代表一個 RPC 樣式請求,SOAP.Body 提供了一個便利方法 set_rpc,能一次組出完整的 RPC 請求,包含操作名稱、輸入參數陣列與 SOAP 編碼樣式 URI:
var envelope = new SOAP.Envelope();
var body = envelope.create_body();
body.set_rpc(
new WS.QName('param', 'urn:foo'),
new Array(
{ name: 'param', value: 'bar' }
),
SOAP.NOENCODING
);
每個參數都作為一個 JavaScript 物件結構傳遞,可帶有以下屬性:
舉例來說,若參數名為「abc」、命名空間為「urn:foo」、xsi:type 為「int」、值為「3」,寫法就是:
new Array({
name: new WS.QName('abc', 'urn:foo'),
value: 3,
xsitype: new WS.QName('int', 'https://www.w3.org/2000/10/XMLSchema')
})
組好 SOAP.Envelope 後,把它傳進 WS.Call 的 invoke 方法即可呼叫信封內編碼的方法:
(new WS.Call(service_uri)).invoke(envelope, callback);
另一條路是手動組信封,把參數 WS.QName、參數陣列與編碼樣式傳給 invoke_rpc:
var call = new WS.Call(serviceURI);
var nsuri = 'urn:foo';
var qn_op = new WS.QName('method', nsuri);
var qn_op_resp = new WS.QName('methodResponse', nsuri);
call.invoke_rpc(
qn_op,
new Array(
{ name: 'param', value: 'bar' }
),
SOAP.NOENCODING,
function(call, envelope) {
// envelope 是回應的 SOAP.Envelope
// 回應的 XML 文字在 arguments[2]
}
);
呼叫 invoke 或 invoke_rpc 時,WS.Call 會建立一個基本的 XMLHttpRequest 物件、傳入含 SOAP 信封的 XML 元素、接收並解析回應,然後呼叫你提供的回呼函式。
為了擴充 SOAP 訊息的前置與後置處理,WS.Call 允許註冊一組 WS.Handler 物件。對於呼叫週期內的每個請求、每個回應與每個錯誤,都會呼叫這些物件。新的處理器只要繼承 WS.Handler 即可:
var MyHandler = Class.create();
MyHandler.prototype = (new WS.Handler()).extend({
on_request : function(envelope) {
// 前置處理
},
on_response : function(call, envelope) {
// 回應後、回呼前的處理
},
on_error : function(call, envelope) {
}
});
var call = new WS.Call(...);
call.add_handler(new MyHandler());
處理器最適合插入或取出正在傳遞的 SOAP 信封中的資訊。舉例來說,你可以設想一個處理器自動把適當的 Web 服務定址(WS-Addressing)元素插進 SOAP Header:
var WSAddressingHandler = Class.create();
WSAddressingHandler.prototype = (new WS.Handler()).extend({
on_request : function(call, envelope) {
envelope.create_header().create_child(
new WS.QName('Action', 'https://ws-addressing', 'wsa')
).set_value('https://www.example.com');
}
});
WS.Binder 負責 SOAP.Element 物件的自訂序列化與反序列化,實作時必須提供兩個方法:
var MyBinding = Class.create();
MyBinding.prototype = (new WS.Binding()).extend({
to_soap_element : function(value, element) {
...
},
to_value_object : function(element) {
...
}
});