diff --git a/extensions/webservices/docs/Soap_Scripts_in_Mozilla.html b/extensions/webservices/docs/Soap_Scripts_in_Mozilla.html index 7ffa77dac32..6f32107f2e7 100644 --- a/extensions/webservices/docs/Soap_Scripts_in_Mozilla.html +++ b/extensions/webservices/docs/Soap_Scripts_in_Mozilla.html @@ -1,1190 +1,1369 @@ - + Soap Scripts in Mozilla - -
+ +

SOAP Scripts in Mozilla

- February 16, 2002
- + February 16, 2002
+

Ray Whitmer

- +

Abstract

- -
Microsoft and others have advocated - SOAP as a way to encode and exchange public data structures between agents - on the web, which is now becoming a web standard at W3C (see the multiple -submissions and working documents related to SOAP in the list of -W3C current drafts -). 
-
-The browser client is the most universal web agent in existence, and Javascript -is the standard, interoperable way of scripting browsers.  Scriptable -SOAP in browsers gives clients and servers more to say to each other through -existing http-xml services, providing scripts with persistence, database, -and access to other web services not tied to the request and response -cycles of the HTML-based user interface.  Web data structures, exchanged - in a platform-neutral way, should become as fundamental to web agents as -web content is today.  The key to this is a very natural binding to -the data of Javascript so that the script can simply use the data instead -of tediously encoding and extracting the data from the XML.
- -

1 SOAP Services

- There are a number of sources for services available on the web -being set up, such as the XMethods -website - which the Mozilla implementation has used for some of our tests and use - cases.  Apache supports modules for SOAP that have been used to author - services for purposes of testing the Mozilla implementation (and entertainment).  - Once it is set up, it is as simple as writing a function in Javascript, - Java, or any other of a number of supported languages and then writing -a simple service description in XML or submitting a form to deploy the -service.  There are toolkits available from Microsoft and other webserver -providers for authoring such services as well.
- -

2 SOAP Blocks

- -

2.1 Parameters
-

- SOAP-based services exchange message envelopes which contain blocks - of XML data roughly corresponding to the parameters of a service call.  - When an rpc-style message is exchanged, blocks representing the regular - parameter blocks are placed inside an element which identifies the object - and method being invoked, which is placed inside the body.  In a -non-RPC message, the blocks are placed directly inside the body instead -of under the method element. 
- -

2.2 Header Blocks
-

- If there are blocks which are optional or independently added or processed, - these are carried in the header with an assigned role and marked if the - recipient is required to understand them.
- -

2.3 Encodings
-

- Interpretation of each block depends upon the encoding that was used, - which is clearly specified in the message.  If the standard SOAP encoding - is used, then XML Schema types control the interpretation of the data within - each block.
- -

3 Using the Low-Level SOAP API

- To use the low-level API, the user creates a SOAPCall object, encodes - the function call with a list of headers and regular parameters, and invokes - the call, which returns a response which contains the results of the service - call including a fault generated by the service which processed the message, - output parameters, and/or header blocks.  If the call is invoked -asynchronously, then a function is given which receives the response -when it arrives from the remote service.
-
- Besides Javascript, the below-described operations should also generally - work for other xpconnect-supported languages in Mozilla such as C++/XPCOM - and Python, because language-independent cross-platform interfaces were - used.
- -

3.1 Conventions Used Below in Operations
-

- Names or descriptions in angle brackets represent values or objects - matching the name or description.  These may be literal, constructed - via "new", or variables.  Occasionally the same syntax with a longer - description represent mores script performing an operation.  Quoted - angle brackets indicate a string of the described type.
-
- So the following operation:
- -
    -
  • <Foo> = new Foo( - <FooFact> );
    • -
  • <Foo>.bar = - <any value or object>;
    • -
  • <Baz> = - <Foo>.find("<name> - ");
    • -
  • <find out what you have>
    • - -
- might be replaced in a real Javascript program with
-
- var myFoo = new Foo(new FooFact("always","Great","Baz"));
- myFoo.bar = 3.14159265;
- var myGreatBaz = myFoo.find("Great");
- if (checkBaz(myGreatBaz)) {
-   alert(myGreatBaz.description);
- }
-
- where "myFoo" is a variable holding an object of type Foo and myGreatBaz - is a variable holding an object of type Baz.
- -

3.2 Basic Operations of SOAP
-

- For basic SOAP operations is all most users need to do.
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Basic Operation
- 		How to Do It
-
Create a parameter block, setting the Javascript - value and name for rpc-style call
- 		- -
    -
  • <SOAPParameter> - = new SOAPParameter(<any value or object> - , "<name>");
    • -
  •  // or
    • -
  • <SOAPParameter> - = new SOAPParameter();
    • -
  • <SOAPParameter> - .value = <any value or object> - ;
    • -
  • <SOAPParameter> - .name = "<name>";
    • - -
-
Set parameters in a Javascript array
- 		- -
    -
  • <SOAPParameter array> - = new Array(<SOAPParameter> - [,...]);
    • -
  • // or
    • -
  • <SOAPParameter array> - = new Array();
    • -
  • <SOAPParameter array> - [0] = <SOAPParameter> ;
    • -
  • [...]
    • - -
-
Create and encode the parameters in a basic - SOAP 1.1 rpc-style message
- 		- -
    -
  • <SOAPCall> = -new SOAPCall();
    • -
  • <SOAPCall>.transportURI - = "<http-based service URI>"
    • -
  • <SOAPCall>.encode(0, - "<method name> ", " - <service namespace>", 0, null, - <SOAPParameter array> .length, - <SOAPParameter array>);
    • - -
-
Invoke  call (send call message and receive - response message)
- 		- -
    -
  • <SOAPResponse> - = <SOAPCall>.invoke();
    • -
  • <process the response -- see - below>
    • -
  • // or
    • -
  • <SOAPCall>.asyncInvoke( - <SOAPResponseListener> );
    • - -
-
Handle completion of async SOAP call.
- 		- -
    -
  • function <SOAPResponseListener - name>(<SOAPResponse> - , <SOAPCall>, - <error>)
    • -
  • {
    • -
  •   if (error != 0) {
    • -
  •      <action - to be taken on failure to transport message>
    • -
  •   }
    • -
  •   <process the response - -- see below>
    • -
  • }
    • - -
-
Get service's failure, if any.
- 		- -
    -
  • <SOAPFault> -= <SOAPResponse>.fault;
    • -
  • if (<SOAPFault> - != null) {
    • -
  •   <namespace URI string> - = <SOAPFault> .faultNamespace;
    • -
  •   <name string> - = <SOAPFault> .faultCode;
    • -
  •   <summary string> - = <SOAPFault> .faultString;
    • -
  •   <actor URI string> - = <SOAPFault> .actorURI;
    • -
  •   <action to be taken -in case of fault>
    • -
  • }
    • - -
-
Get returned parameters from rpc-style response
- 		- -
    -
  • <SOAPParameter array> - = <SOAPResponse> .getParameters(true, - {});
    • - -
-
Process Javascript values, etc. of returned - parameters
- 		- -
    -
  • for (i = 0; i != <SOAPParameter - array>.length; i++)
    • -
  • {
    • -
  •   <SOAPParameter> - = <SOAPParameter array>[i];
    • -
  •   <value or object> - = <SOAPParameter> .value;
    • -
  •   <name string> - = <SOAPParameter> .name;
    • -
  •   <checking and processing - of result>
    • -
  • }
    • - -
-
- -

- -

3.3 Beyond Basic Operations
-

- The above operations are what every user of the lowlevel SOAP toolkit needs -to invoke service requests and interpret the responses, as is easily seen -by looking at some of the samples.  The bulk of the operations that follow -will generally be used less frequently, but they need to be there for  cases -where they are needed.  The casual reader may wish to skip the remaining -tables of operations in this section, or scan for features of interest.
- -

3.4 Header Operations

- For additional information, the user can send or receive header blockss. -  Sending and receiving header blocks is not very different from sending - and receiving parameters as described above.
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Header Operation
- 		How to Do It
-
Create a Header Block
- 		- -
    -
  • <SOAPHeaderBlock> - = new SOAPHeaderBlock(<any value or object> - , "<name>", " - <namespaceURI> ");
    • -
  •  // or
    • -
  • <SOAPHeaderBlock> - = new SOAPHeaderBlock();
    • -
  • <SOAPHeaderBlock> - .value = <any value or object> - ;
    • -
  • <SOAPHeaderBlock> - .name = "<name> ";
    • -
  • <SOAPHeaderBlock> - .namespaceURI = "<namespaceURI> - ";
    • - -
-
Establish non-default role of a header block
- 		- -
    -
  • <SOAPHeaderBlock> - .actorURI = "<actorURI> ";
    • -
  • <SOAPHeaderBlock> - .mustUnderstand = <true or false> - ;
    • - -
-
Set header blocks in a Javascript array
- 		- -
    -
  • <SOAPHeaderBlock array> - = new Array(<SOAPHeaderBlock> - [,...]);
    • -
  • // or
    • -
  • <SOAPHeaderBlock array> - = new Array();
    • -
  • <SOAPHeaderBlock array> - [0] = <SOAPHeaderBlock> ;
    • -
  • [...]
    • - -
-
Encode the headers in a SOAP 1.1 rpc-style -message
- 		- -
    -
  • <SOAPCall>.encode(0, - "<method name> ", " - <service namespace>", <SOAPHeaderBlock - array> .length, <SOAPHeaderBlock - array>, <SOAPParameter array> - .length, <SOAPParameter array> - );
    • - -
-
Get returned headers
- 		- -
    -
  • <SOAPHeaderBlock array> - = <SOAPResponse> .getHeaderBlocks(true, - {});
    • - -
-
Process Javascript values, etc. of returned -headers
- 		- -
    -
  • for (i = 0; i != <SOAPHeaderBlock - array>.length; i++)
    • -
  • {
    • -
  •   <SOAPHeaderBlock> - = <SOAPHeaderBlock array>[i];
    • -
  •   <value or object> - = <SOAPHeaderBlock> .value;
    • -
  •   <name string> - = <SOAPHeaderBlock> .name;
    • -
  •   <namespace URI string> - = <SOAPHeaderBlock> .namespaceURI;
    • -
  •   <actor URI string> - = <SOAPHeaderBlock> .actorURI;
    • -
  •   <must understand boolean> - = <SOAPHeaderBlock> .mustUnderstand;
    -
    • -
  •   <checking and processing - of result>
    • -
  • }
    • - -
-
- -

3.5 Non-RPC Operations

- For messages that are not intended to model RPC calls, there is no -method name or target object URI, and the parameters generally have namespaceURIs. -  Otherwise, the basic operations are the same.
-
- - - - - - - - - - - - - - - - - - - - - -
Non-RPC Operation
- 		How to Do It
-
Setting the namespaceURI of a non-RPC parameter
- 		- -
    -
  • <SOAPParameter> - = new SOAPHeaderBlock(<any value or object> - , "<name>", " - <namespaceURI> ");
    • -
  •  // or
    • -
  • <SOAPParameter> - .namespaceURI = "<namespaceURI> - ";
    • - -
-
Encode a SOAP 1.1 non-rpc-style message
- 		- -
    -
  • <SOAPCall>.encode(0, - "", "", <header block array>.length, - <header block array>, - <parameter array>.length, <parameter - array>)
    • - -
-
Get returned parameters from non-rpc-style -response
- 		- -
    -
  • <SOAPParameter array> - = <SOAPResponse> .getParameters(false, - {});
    • - -
-
- -

3.6 SOAPBlock and SOAPMessage Supertypes

- In the following operations, SOAPHeaderBlock and SOAPParameter may be referred -to collectively as SOAPBlock objects.
-
- Also, SOAPCall and SOAPResponse may be referred to collectively as SOAPMessage -objects.
- -

3.7 More Operations

- The following table contains less-common operations.
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Operation
- 		How to Do It
-
Set or get an actionURI carried for the message - in the HTTP header
- 		- -
    -
  • <SOAPMessage> - .actionURI = "<action URI> ";
    • -
  • // or
    -
    • -
  • <action URI string> - = <SOAPMessage> .actionURI;
    -
    • - -
-
Directly set the DOM element to represent the - block's encoded content, bypassing encoding of the value on the block
- 		- -
    -
  • <SOAPBlock>.element - = <DOM Element> ;
    -
    • - -
-
-
Directly get the DOM element that represents - the block's encoded content, bypassing decoding of the value on the block
- 		- -
    -
  • <DOM Element> - = <SOAPBlock>.element;
    -
    • - -
-
Directly get the DOM element containing the -SOAP envelope , header, or body of an encoded message
- 		- -
    -
  • <DOM Element> - = <SOAPMessage>.envelope;
    • -
  • // OR
    • -
  • <DOM Element> - = <SOAPMessage>.header;
    • -
  • // or
    • -
  • <DOM Element> - = <SOAPMessage>.body;
    -
    • - -
-
Directly set the DOM document to represent -the message's entire encoded content, bypassing encoding.
- 		- -
    -
  • <SOAPMessage> - .message = <DOM Document> ;
    -
    • - -
-
-
Directly get the DOM document of an encoded -message, bypassing encoding.
- 		- -
    -
  • <DOM Document> - = <SOAPMessage>.message;
    -
    • - -
-
-
Get the method name and object URI, if any, -of the message.
- 		<method name string> - = <SOAPMessage> .method;
-
Get the actual SOAP version of an encoded message - -- 0 for SOAP 1.1 and 1 for SOAP 1.2.
- 		- -
    -
  • <version integer> - = <SOAPMessage> .version;
    • - -
-
Encode a SOAP 1.2 message.
- 		- -
    -
  • <SOAPCall>.encode(1, - "<method name> ", " - <service namespace>", <SOAPHeaderBlock - array> .length, <SOAPHeaderBlock - array>, <SOAPParameter array> - .length, <SOAPParameter array> - );
    • - -
-
Abort an in-progress async call -- this does - not necessarily cause the message not to be processed, but the API stops - listening for it to complete.
- 		- -
    -
  • <SOAPCallCompletion> - = <SOAPCall> .asyncInvoke( - <SOAPResponseListener>);
    • -
  • [...]
    • -
  • <SOAPCallCompletion> - .abort();
    -
    • - -
-
Get the encoding (style) used to encode or -decode message.  Not available on an unencoded call unless explicitly -set -- use following operation instead.
- 		- -
    -
  • <SOAPEncoding> - = <SOAPMessage>.encoding;
    • - -
-
Set the encoding style (and associated styles) - used to encode a message.
- 		- -
    -
  • <SOAPEncoding> - = new SOAPEncoding();
    • -
  • <SOAPEncoding> - = <SOAPEncoding>.getAssociatedEncoding(" - <style URI>",<true to -create> );
    • -
  • [...]<customize encodings>
    -
    • -
  • <SOAPMessage> - .encoding = <SOAPEncoding> ;
    • - -
-
Specify the specific style used to encode or - decode specific blocks
- 		- -
    -
  • <SOAPEncoding> - = <SOAPEncoding>.getAssociatedEncoding(" - <style URI>",<true to -create> );
    • -
  • <SOAPBlock>.encoding - = <SOAPEncoding> ;
    • - -
-
- -

- -

3.8 Using Schema Types

- The default SOAP encodings implement most XML built-in types, as -well as the basic SOAP types.  In the absence of a specified type, -native values and objects will typically be correctly identified and mapped -to a corresponding schema type.  Many types do not match, and so they -will be mapped to a close type.  Providing specific schema types can -help the encoding produce the desired results.  For example, multidimensional - arrays must be decoded as nested arrays because Javascript only supports - single-dimensional arrays.  f no schema type is given that identifies - the array as multidimensional, then a multidimensional array will be encoded - as a nested array.  An accurate schema type can also help when encoding - or decoding of other complex objects such as SOAP structs.
-
- Schema types may be attached to blocks before encoding or before accessing - the value of a returned object to better control the encoding and decoding. -  All schema types which are used to control the encoding and decoding - should come from the schema collection available through any associated - encoding.
-
- - - - - - - - - - - - - - - - - - - - - -
Schema Operation
- 		How to Do It
-
Get the schema collection of all associated -encodings.
- 		- -
    -
  • <SchemaCollection> - = <SOAPEncoding> .schemaCollection;
    • - -
-
Load additional schema types from XML Schema - files into the schema collection.
-
- 		- -
    -
  • <SchemaLoader> - = <SchemaCollection> - ;
    • -
  • // and then
    -
    • -
  • <SchemaLoader> - .load(" <schema file URI> ");
    • -
  • //  or
    -
    • -
  • <SchemaLoader> - .loadAsync(" <schemaURI> ", - <load completion function> -);
    • - -
-
Specify the XML Schema type to be used when -encoding or decoding a block -- decoding a block occurs when you get its -value if it came from an encoded message such as a SOAPResponse. - -
    -
  • <SchemaType> - = <SchemaCollection> - .getType(" <name> ", " - <namespaceURI> ");
    • -
  • if (<schemaType != null) {
    -
    • -
  •   - <SOAPBlock> .schemaType = <SchemaType> - ;
    • -
  • }
    • -     -
-
- -

- -

- -

3.9 Customization of Encodings

- A specific encoding must have encoders and decoders to function.  Encoding - or decoding of data always begins with a default encoder or decoder, which - then may lookup additional encoders or decoders by a string key as required. -  For either the 1.1 or 1.2 version of the default SOAP encoding, the - default encoder and decoder use the schema type's namespaceURI and name, - seperated by "#" to look up additional decoders for specific schema types. -  Additional encoders and decoders registered within the default encodings - will automatically be invoked as an object identified as the corresponding - type is processed.  Other encodings can use any scheme for looking -up additional encoders and decoders, or none at all if all the work is done - by the default encoder and decoder for that encoding style.  Encodings - which are registered with the system, such as the default SOAP 1.1 or 1.2 - encodings, automatically come with encoders and decoders built-in, whereas - new encodings have none.  Custom encodings may also reuse existing -encoders, and decoders, but there is no guarantee which are present, since -the mapping may vary when handling an infinite set of types with a finite -set of encoders and decoders.
-
- Also, there has been a proliferation of variant schema types with -different URIs, which may be improperly intermixed in usage, but expected -to function properly.  Most notably, the SOAP 1.1 specification used -unofficial XML Schema URIs and SOAP encoding schema URIs not compatible -with those which are in the W3C XML Schema and drafts for SOAP 1.2 specifications. - It is not uncommon to send and receive messages using the URIs specified -in the SOAP 1.1 specification, but described by WSDL using XML Schema that -uses the official, correct URIs.  To solve these problems, the encoding -permits schema URIs to be aliased, both on input and on output, so that -only the SOAP 1.2 and official XMLSchema types are used internally, while -supporting the other URIs.  Mappings of this type are built-in for -encodings which are registered with the system, such as the default encodings - of SOAP 1.1 and 1.2.  The default URI mappings in the default encoding - of SOAP 1.1 may be manipulated, for example, to output the official XML -Schema URIs, without having to rewrite any encoders or decoders.
-
- - - - - - - - - - - - - - - - - - - - - - - - - -
Encoding Customization Operation
- 		How to Do It
-
Create a custom encoder. - -
    -
  • function <New DOM Element> - = <SOAPEncoder name>( - <SOAPEncoding>, <value> - , <namespaceURI> , - <name>, <SchemaType> - , <SOAPAttachments> , - <Parent DOM Element> )
    • -
  • {
    • -
  • [...]
    • -
  • <DOM Element> - = <Parent DOM Element> - .ownerDocument.createElementNS(namespaceURI,name);
    -
    • -
  • [...]
    • -
  •   <Parent DOM Element> - .appendChild(<DOM Element>);
    -
    • -
  •   return <DOM Element> - ;
    -
    • -
  • }
    • -
  • // and
    • -
  • <SOAPEncoding> - .defaultEncoder = <SOAPEncoder> - ;
    • -
  • // or
    • -
  • <SOAPEncoding> - .setEncoder(" <namespaceURI> - # <name> ", - <SOAPEncoder> );
    • - -
-
-
Create a custom decoder.
- 		- -
    -
  • function <New DOM Element> - = <SOAPDecoder name>( - <SOAPEncoding>, <DOM Element> - , <SchemaType>, - <SOAPAttachments>)
    • -
  • {
    • -
  • [...]
    • -
  •   return <value or object> - ;
    -
    • -
  • }
    • -
  • // and
    • -
  • <SOAPEncoding> - .defaultDecoder = <SOAPDecoder> - ;
    • -
  • // or
    • -
  • <SOAPEncoding> - .setDecoder(" <namespaceURI> - # <name> ", - <SOAPDecoder> );
    • - -
-
-
Map or unmap schema  URI aliases
- 		- -
    -
  • <SOAPEncoding> - .mapSchemaURI(" <external URI> - ", "<internal URI>", - <true to alias output> );
    • -
  • // or
    • -
  • <SOAPEncoding> - .unmapSchemaURI(" <external URI> - ");
    • - -
-
Register modified or alternative encodings, -making them automatically available to all SOAP scripts in the system
- 		Install an appropriate registerable encoding - in components/<new encoding> - .js
-
- -

3.10 Security Operations

- In browsers, the risk of allowing an externally-loaded untrusted script - to request information within a firewall and send it elsewhere has lead - to very tight sandbox restrictions, only permitting external browser scripts - to request xml data and services on the same domain from which the script - was loaded.  This same restriction applies by default to SOAP requests - executed within the browser.  This means that an externally-loaded - script cannot, for example, call other external services unless they are - in the same domain from which the page was loaded.  Even if the page - was loaded from the user's own hard disk, the script must ask for permission - to make SOAP calls.  A browser enhancement is planned to permit more-precise - control of trust between scripts and specific available services.
-
- Since SOAP permits headers to be added to messages that require interpretation - by the recipient, this API can request a header to warn the recipient that - it was sent by an untrusted script loaded from a specific sourceURI, and - no good SOAP service will unintentionally disregard the warning.  If - the envelope is verified and the header is added, then the browser can -allow the script less=-restricted access to services outside of its source - domain.  Accepting this header permits SOAP services that really do -want to be universally available to allow access without forcing the user -to risk breach of the firewall protections or requiring user intervention -at all.
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Security Operation
- 		How to Do It
-
Mark the call with a verifySourceHeader, if -the server permits it, so the browser can make the call with less privilege - and risk.
- 		- -
    -
  • <SOAPCall>.verifySourceHeader - = true;
    • - -
-
Request risky privileges within a local or -signed script to make an unverified SOAP calls to other domains.
- 		- -
    -
  • netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead")
    • - -
-
Modify the security settings in the preferences - file, allowing scripts from some domain to make risky SOAP calls to any - other domain, which is disabled by default.Add the setting in default/pref/all.js - :
- -
    -
  • pref("<some domain prefix> - .SOAPCall.invoke","allAccess");
    • - -
-
Modify the security settings in the preferences - file to disallow calls made with the verifySource header, which is generally - enabled by default.
- 		Change the setting in default/pref/all.js - :
- -
    -
  • pref("capability.policy.default.SOAPCall.invokeVerifySourceHeader","none");
    • - -
-
Register alternative transport mechanisms, -making available alternative transports to all scripts and perhaps creating - alternative security models for protocols besides http(s).
- 		Install an appropriate registerable encoding - in components/<new transport> - .js.
-
- -

- -

4 Future Features

- -

4.1 Access to SOAP as Proxies

- Although a SOAP call can generally be accomplished using this low-level - API in a few dozen lines, WSDL is a standard that contains enough information -to enable this to occur with no manual argument and type setup required. - An implementation is under development that instantiates web service -proxies complete with appropriate xpconnect interfaces by simply loading -and using information out of a WSDL file that describes the service.  The -proxy's interface has dynamically-generated methods named appropriately -to match the services described in the WSDL file which accept arguments of -the appropriate data types and calls the appropriate low-level SOAP functions -with the appropriate type information, making it even simpler not only -to invoke services from Javascript code, but to associate appropriate schema -types loaded from the WSDL file with the arguments.  This higher level -is not available in the first release.  When it is available, invoking -WSDL-described features gets even easier and more reliable.
- -

- -

4.2 Arbitrary Graphs of Data

- The SOAP specification allows objects to be passed as arguments which - may have originally referenced other objects that are not owned in a pure - hierarchy.  This is represented by using an href attribute.  Due - to the problems with leaking reference counts in COM objects with cyclic - references, this has not been implemented yet.  Also, the output of - a cyclicly-referencing set of objects has not been implemented.  Incoming - objects that do not reference cyclicly currently create separate copies - for each reference to an object, and with cycles will probably never complete. -  On input, hrefs are currently ignored.  In the future it may -be possible to solve this and transmit and receive arbitrarily-referencing -objects, but the solution is more complex than just using weak references.
- -

4.3 SOAP With Attachments

- Many clients and servers now support automatically transmitting large - Mime with a SOAP message by encapsulating it in MIME, DIME, or other enveloping - formats.  This has been anticipated in the APIs, but the SOAPAttachments - API is currently a placeholder for this future feature which is not yet - implemented.
- -

4.4 New Transports and Local Services

- Obvious new transports that would be useful include e-mail -- permitting - a SOAP exchange to occur as an email exchange --, instant messenger for - peer to peer, and a local manager with a controlled security model but -without the size limitations, enabling SOAP to save and restore arbitrary -Javascript application data on the client.  These services require -a framework, already being planned, for permitting the browser to host -services as well as being a good client.  There are obviously security -issues to be solved to make these successful.
- -

4.5 Standards

- The interfaces to the objects of this API were designed to be as simple - and universal as possible.  We believe that we should submit a note -describing them and sponser a W3C proposal to standardize an API for invoking -this type of service from web clients.  In such an effort, changes would -be inevitable and welcomed as the price for interoperability within web clients. - Part of this API are incomplete, specifically the SOAPAttachments object, -which will be defined to allow encoders and decoders to control uniqueness - and referencing, both for resolving arbitrary graphs of data (as described -above in "Arbitrary Graphs of Data") as well as for automatically resolving -references to attached objects carried with the message in an external encapsulation -(as described above in "SOAP With Attachments").
- -

4.6 Samples and Testing

- Some samples or tests have been created, but these commonly only use -the basic operations.  Some of the higher-level features are being -tested by the prosy code (as described above in "Access to SOAP as Proxies"). - While most of the methods of this API are well-exercized internally - during even basic invocation, we need samples that test and demonstrate -external access to the functions.  What exists today is mozilla/extensions/xmlextras/tests - /soap*.html.  We welcome the contribution of tests by other parties. - Most samples work but at least one (soapcall.html) is no longer correctly -configured to talk to a server -- but it genrates interesting messages anyway.
+ +
Microsoft and others have advocated + SOAP as a way to encode and exchange public data structures between agents + on the web, which is now becoming a web standard at W3C (see the multiple + submissions and working documents related to SOAP in the list of + W3C current drafts + ). 
+
+ The browser client is the most universal web agent in existence, and + Javascript is the standard, interoperable way of scripting browsers.  + Scriptable SOAP in browsers gives clients and servers more to say to +each other through existing http-xml request services, providing scripts + with persistence, database, and access to other web services not tied +to the request and response cycles of the HTML-based user interface.  + Web data structures, exchanged in a platform-neutral way, should become +as fundamental to web agents as web content is today.  The key to this +is a very natural binding to the data of Javascript so that the script can +simply use the data instead of tediously encoding and extracting the data +from the XML.

- To test the services, it is currently required to compile Mozilla with the -environment variable MOZ_SOAP=1 (if you already have a build, you only need -to do a clean rebuild of the xmlextras directory).  It is also interesting -to turn on MOZ_DEBUG=1, because even if you do not debug the program, this -causes the exchanged SOAP messages to be displayed on the standard output -if you run from a command shell where this is visible.
-
- A SOAP service server has been set up at ray.dsl.xmission.com where additional -services may be deployed to help test and demo the features for scripting - SOAP in Mozilla.  No home page describes the Apache Jakarta server -on port 8080 which is the test facility, but this is currently used in two -tests in the previously-mentioned directory: soapisprimenumber.html and soapunscramble.html. - Adding services is as easy as writing functions in Javascript, Java, -or other supported languages and describing the deployment in XML.  Disclaimer: -as this is merely an end-subscriber DSL service, if the server becomes too -widely published, it may have to be shut down.
-
- Bugs should be reported as usual.
+ +

+ 0 Table of Contents

+
1 SOAP Services +
+
+ 2 SOAP Blocks +
+
2.1 Parameters +
+ 2.2 Header Blocks +
+ 2.3 Encodings +
+
+ 3 Using the Mozilla +Low-Level SOAP API +
+
3.1 Conventions Used +Below in +
+ 3.2 Basic Operations of SOAP +
+ 3.3 Beyond Basic Operations +
+ 3.4 Header Operations +
+ 3.5 Non-RPC Operations +
+ 3.6 SOAPBlock and +SOAPMessage Supertypes +
+ 3.7 More Operations +
+ 3.8 Using Schema Types +
+ 3.9 Customization of Encodings +
+ 3.10 Security Operations +
+
+ 4 Future Features +
+
4.1 Access to SOAP +as Proxies +
+ 4.2 Arbitrary Graphs of Data +
+ 4.3 SOAP With Attachments +
+ 4.4 New Transports +and Local Services +
+ 4.5 Standards +
+
+ 5 Samples and Testing +
+
+ 6 Object Interfaces +
+

+ 1 SOAP Services

+ There are a number of sources for services available on the web + being set up, such as the XMethods +website + which the Mozilla implementation has used for some tests and use +cases.  Apache also provides modules for SOAP that have been used to +author services for purposes of testing the Mozilla implementation (and +entertainment).  Once it is set up, it is as simple as writing +a service function in Javascript, Java, or any other of a number of supported +languages and then writing a service description in XML to deploy the service.  + There are toolkits available from Microsoft and other webserver providers + for authoring such services as well.
+ +

+ 2 SOAP Blocks

+ +

+ 2.1 Parameters
+

+ SOAP-based services exchange message envelopes which contain blocks + of XML data roughly corresponding to the parameters of a service call.  + When an rpc-style message is exchanged, blocks representing the regular + parameter blocks are placed inside an element which identifies the object + and method being invoked, which is placed inside the body.  In a +non-RPC message, the blocks are placed directly inside the body instead +of under the method element. 
+ +

+ 2.2 Header Blocks
+

+ If there are blocks which are optional or independently added or + processed, these are carried in the header with an assigned role and +marked if the recipient is required to understand them before trying to +process the message.
+ +

+ 2.3 Encodings
+

+ Interpretation of each block depends upon the encoding that was + used, which is clearly specified in the message.  If the standard + SOAP encoding is used, then XML Schema types control the interpretation + of the data within each block.
+ +

+ 3 Using the Mozilla Low-Level SOAP API

+ To use the low-level API, the user creates a SOAPCall object, +encodes the function call with a list of headers and regular parameters, +and invokes the call, which returns a response which contains the results +of the service call including a fault generated by the service which processed + the message if it failed, output parameters, and/or header blocks.  +If the call is invoked asynchronously, then a function is supplied by +the caller which receives the response when it arrives from the remote +service.
+
+ Besides Javascript, the below-described operations should also +generally work for other xpconnect-supported languages in Mozilla such +as C++/XPCOM and Python, because language-independent cross-platform +interfaces and architectures were used.
+ +

+ 3.1 Conventions Used Below in Descriptions of Operations
+

+ Names or descriptions in angle brackets represent values or objects + matching the name or description.  These may be literal, constructed + via "new", or variables.  Occasionally the same syntax may represent +script performing an operation.  Quoted angle brackets indicate a +character string of the described type.
+
+ So the following sample operation:
+ +
    +
  • <Foo> = new Foo( + <FooFact> );
    • +
  • <Foo>.bar = + <any value or object>;
    • +
  • <Baz> = + <Foo>.find("<name> + ");
    • +
  • <find out what you have>
    • + +
+ might be replaced in a real Javascript program:
+
+ var myFoo = new Foo(new FooFact("always","Great","Baz"));
+ myFoo.bar = 3.14159265;
+ var myGreatBaz = myFoo.find("Great");
+ if (checkBaz(myGreatBaz)) {
+   alert(myGreatBaz.description);
+ }
+
+ where "myFoo" is a variable holding an object of type Foo and myGreatBaz + is a variable holding an object of type Baz.
+ +

+ 3.2 Basic Operations of SOAP
+

+ The following basic SOAP operations is nearly all that most users +of SOAP need to do.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Basic Operation
+ 		How to Do It
+
Create a parameter block, setting the Javascript + value and name for rpc-style call.
+ 		+ +
    +
  • <SOAPParameter> + = new SOAPParameter(<any value or object> + , "<name>");
    • +
  •  // or
    • +
  • <SOAPParameter> + = new SOAPParameter();
    • +
  • <SOAPParameter> + .value = <any value or object> + ;
    • +
  • <SOAPParameter> + .name = "<name>";
    • + + +
+
Set parameters in a Javascript array.
+ 		+ +
    +
  • <SOAPParameter array> + = new Array(<SOAPParameter> + <,...>);
    • +
  • // or
    • +
  • <SOAPParameter array> + = new Array();
    • +
  • <SOAPParameter array> + [0] = <SOAPParameter> ;
    • +
  • <...>
    • + + +
+
Create and encode the parameters in a basic + SOAP 1.1 rpc-style message.
+ 		+ +
    +
  • <SOAPCall> + = new SOAPCall();
    • +
  • <SOAPCall> + .transportURI = "<http-based service URI> + "
    • +
  • <SOAPCall> + .encode(0, "<method name> ", +" <target object namespaceURI> + ", 0, null, <SOAPParameter array> + .length, <SOAPParameter array> + );
    • + + +
+
Invoke  call (send call message and + receive response message).
+ 		+ +
    +
  • <SOAPResponse> + = <SOAPCall>.invoke();
    • +
  • <process the response -- + see below>
    • +
  • // or
    • +
  • <SOAPCall> + .asyncInvoke( <SOAPResponseListener> + );
    • + + +
+
Handle completion of async SOAP call.
+ 		+ +
    +
  • function <SOAPResponseListener + name>(<SOAPResponse> + , <SOAPCall>, + <error>)
    • +
  • {
    • +
  •   if (error != 0) {
    • +
  •      <action + to be taken on failure to transport message>
    • +
  •   }
    • +
  •   <process the response + -- see below>
    • +
  • }
    • + + +
+
Get service's failure, if any.
+ 		+ +
    +
  • <SOAPFault> + = <SOAPResponse> + .fault;
    • +
  • if (<SOAPFault> + != null) {
    • +
  •   <namespace URI string> + = <SOAPFault> .faultNamespace;
    • +
  •   <name string> + = <SOAPFault> .faultCode;
    • +
  •   <summary string> + = <SOAPFault> .faultString;
    • +
  •   <actor URI string> + = <SOAPFault> .actorURI;
    • +
  •   <action to be taken + in case of fault>
    • +
  • }
    • + + +
+
Get returned parameters from rpc-style +response .
+ 		+ +
    +
  • <SOAPParameter array> + = <SOAPResponse> .getParameters(true, + {});
    • + + +
+
Process Javascript values, etc. of returned + parameters.
+ 		+ +
    +
  • for (i = 0; i != <SOAPParameter + array>.length; i++)
    • +
  • {
    • +
  •   <SOAPParameter> + = <SOAPParameter array> +[i];
    • +
  •   <value or object> + = <SOAPParameter> .value;
    • +
  •   <name string> + = <SOAPParameter> .name;
    • +
  •   <checking and processing + of result>
    • +
  • }
    • + + +
+
+ +

-

5 Object Interfaces

-
+

+ 3.3 Beyond Basic Operations
+

+ The above operations are what every user of the lowlevel SOAP toolkit + needs to invoke service requests and interpret the responses, as is easily + seen by looking at some of the samples (see +section 5 +).  The bulk of the operations that follow will be used less frequently, +but they need to be there for certain cases.  The casual reader may +wish to skip the remaining tables of operations in this section, or scan +for features of interest.
+ +

+ 3.4 Header Operations

+ The user can send or receive header blocks for information not carried in +the body of the message.  Sending and receiving header blocks is not +very different from sending and receiving parameters as described above.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Header Operation
+ 		How to Do It
+
Create a Header Block.
+ 		+ +
    +
  • <SOAPHeaderBlock> + = new SOAPHeaderBlock(<any value or object> + , "<name>", " + <namespaceURI> ");
    • +
  •  // or
    • +
  • <SOAPHeaderBlock> + = new SOAPHeaderBlock();
    • +
  • <SOAPHeaderBlock> + .value = <any value or object> + ;
    • +
  • <SOAPHeaderBlock> + .name = "<name> ";
    • +
  • <SOAPHeaderBlock> + .namespaceURI = "<namespaceURI> + ";
    • + + +
+
Establish non-default role of a header block +.
+ 		+ +
    +
  • <SOAPHeaderBlock> + .actorURI = "<actorURI> +";
    • +
  • <SOAPHeaderBlock> + .mustUnderstand = <true or false> + ;
    • + + +
+
Set header blocks in a Javascript array.
+ 		+ +
    +
  • <SOAPHeaderBlock array> + = new Array(<SOAPHeaderBlock> + <,...>);
    • +
  • // or
    • +
  • <SOAPHeaderBlock array> + = new Array();
    • +
  • <SOAPHeaderBlock array> + [0] = <SOAPHeaderBlock> +;
    • +
  • <...>
    • + + +
+
Encode the headers in a SOAP 1.1 rpc-style + message.
+ 		+ +
    +
  • <SOAPCall> + .encode(0, "<method name> ", +" <target object namespaceURI> + ", <SOAPHeaderBlock array> +.length, <SOAPHeaderBlock array> + , <SOAPParameter array> +.length, <SOAPParameter array> + );
    • + + +
+
Get returned headers.
+ 		+ +
    +
  • <SOAPHeaderBlock array> + = <SOAPResponse> .getHeaderBlocks(true, + {});
    • + + +
+
Process Javascript values, etc. of returned + headers.
+ 		+ +
    +
  • for (i = 0; i != <SOAPHeaderBlock + array>.length; i++)
    • +
  • {
    • +
  •   <SOAPHeaderBlock> + = <SOAPHeaderBlock array> + [i];
    • +
  •   <value or object> + = <SOAPHeaderBlock> .value;
    • +
  •   <name string> + = <SOAPHeaderBlock> .name;
    • +
  •   <namespace URI string> + = <SOAPHeaderBlock> .namespaceURI;
    • +
  •   <actor URI string> + = <SOAPHeaderBlock> .actorURI;
    • +
  •   <must understand +boolean> = <SOAPHeaderBlock> + .mustUnderstand;
    +
    • +
  •   <checking and processing + of result>
    • +
  • }
    • + + +
+
+ +

+ 3.5 Non-RPC Operations

+ For messages that are not intended to model RPC calls, there is +no method name or target object URI, and the parameters generally have +namespaceURIs.  Otherwise, the basic operations are the same.
+
+ + + + + + + + + + + + + + + + + + + + + +
Non-RPC Operation
+ 		How to Do It
+
Setting the namespaceURI of a non-RPC parameter +.
+ 		+ +
    +
  • <SOAPParameter> + = new SOAPHeaderBlock(<any value or object> + , "<name>", " + <namespaceURI> ");
    • +
  •  // or
    • +
  • <SOAPParameter> + .namespaceURI = "<namespaceURI> + ";
    • + + +
+
Encode a SOAP 1.1 non-rpc-style message.
+ 		+ +
    +
  • <SOAPCall> + .encode(0, "", "", <header block array> + .length, <header block array> + , <parameter array>.length, + <parameter array> + )
    • + + +
+
Get returned parameters from non-rpc-style + response.
+ 		+ +
    +
  • <SOAPParameter array> + = <SOAPResponse> .getParameters(false, + {});
    • + + +
+
+ +

+ 3.6 SOAPBlock and SOAPMessage Supertypes

+ In the following operations, SOAPHeaderBlock and SOAPParameter may be + referred to collectively as SOAPBlock objects.
+
+ Also, SOAPCall and SOAPResponse may be referred to collectively as SOAPMessage + objects.
+ +

+ 3.7 More Operations

+ The following table contains less-common operations.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Operation
+ 		How to Do It
+
Set or get an actionURI carried for the +message in the HTTP header.
+ 		+ +
    +
  • <SOAPMessage> + .actionURI = "<action URI> + ";
    • +
  • // or
    +
    • +
  • <action URI string> + = <SOAPMessage> .actionURI;
    +
    • + + +
+
Directly set the DOM element to represent + the block's encoded content, bypassing encoding of the value on the +block .
+ 		+ +
    +
  • <SOAPBlock> + .element = <DOM Element> ;
    +
    • + + +
+
+
Directly get the DOM element that represents + the block's encoded content, bypassing decoding of the value on the block +.
+ 		+ +
    +
  • <DOM Element> + = <SOAPBlock>.element;
    +
    • + + +
+
Directly get the DOM element containing +the SOAP envelope , header, or body of an encoded message.
+ 		+ +
    +
  • <DOM Element> + = <SOAPMessage> +.envelope;
    • +
  • // OR
    • +
  • <DOM Element> + = <SOAPMessage> +.header;
    • +
  • // or
    • +
  • <DOM Element> + = <SOAPMessage> +.body;
    +
    • + + +
+
Directly set the DOM document to represent + the message's entire encoded content, bypassing encoding.
+ 		+ +
    +
  • <SOAPMessage> + .message = <DOM Document> +;
    +
    • + + +
+
+
Directly get the DOM document of an encoded + message, bypassing encoding.
+ 		+ +
    +
  • <DOM Document> + = <SOAPMessage> +.message;
    +
    • + + +
+
+
Get the method name and target object URI, +if any, of the message.
+ 		+
    +
  • <method name string> + = <SOAPMessage> .methodName;
    • +
  • <object URI string> + = <SOAPMessage> .targetObjectURI;
    • -

    - - - - - +
+
Get the actual SOAP version of an encoded + message -- 0 for SOAP 1.1 and 1 for SOAP 1.2.
+ 		+ +
    +
  • <version integer> + = <SOAPMessage> .version;
    • + + +
+
Encode a SOAP 1.2 message.
+ 		+ +
    +
  • <SOAPCall> + .encode(1, "<method name> ", +" <target object namespaceURI> + ", <SOAPHeaderBlock array> +.length, <SOAPHeaderBlock array> + , <SOAPParameter array> +.length, <SOAPParameter array> + );
    • + + +
+
Abort an in-progress async call -- this +does not necessarily cause the message not to be processed, but the API +stops listening for it to complete.
+ 		+ +
    +
  • <SOAPCallCompletion> + = <SOAPCall> .asyncInvoke( + <SOAPResponseListener>);
    • +
  • <...>
    • +
  • <SOAPCallCompletion> + .abort();
    +
    • + + +
+
Get the encoding (style) used to encode +or decode message.  Not available on an unencoded call unless explicitly + set -- use following operation instead.
+ 		+ +
    +
  • <SOAPEncoding> + = <SOAPMessage> +.encoding;
    • + + +
+
Set the primary encoding style used to +encode a message.  A new SOAPEncoding objects (created by new) starts +a different set of associated encodings, which are only reached (or created) +in association by calling getAssociatedEncoding().
+ 		+ +
    +
  • <SOAPEncoding> + = new SOAPEncoding();
    • +
  • <SOAPEncoding> + = <SOAPEncoding> + .getAssociatedEncoding(" <style URI> + ",<true to create> );
    • +
  • <customize encodings>
    +
    • +
  • <SOAPMessage> + .encoding = <SOAPEncoding> + ;
    • + + +
+
Specify the encoding style used to encode + or decode specific blocks.
+ 		+ +
    +
  • <SOAPEncoding> + = <SOAPEncoding> + .getAssociatedEncoding(" <style URI> + ",<true to create> );
    • +
  • <SOAPBlock> + .encoding = <SOAPEncoding> +;
    • + + +
+
+ +

+ +

+ 3.8 Using Schema Types

+ The default SOAP encodings implement most XML built-in types, +as well as the basic SOAP types.  In the absence of a specified +type, native values and objects will typically be correctly identified +and mapped to a corresponding schema type.  There may be no perfect +correspondance between Javascript and XML Schema types, so they will be +mapped to a close corresponding type.
+
+ Providing specific schema types can help the encoding produce the desired +results.  For example, multidimensional arrays must be decoded as +nested arrays because Javascript only supports single-dimensional arrays. + If no schema type is given that identifies the array as multidimensional, + then a multidimensional array will be encoded as a nested array.  An + accurate schema type can also help when encoding or decoding of other +complex objects such as SOAP structs.
+
+ Schema types may be attached to blocks before encoding or before + accessing the value of a returned object to better control the encoding + and decoding.  All schema types which are used to control the encoding + and decoding should come from the schema collection available through + the encoding (associated encodings share the same collection).
+
+ + + + + + + + + + + + + + + + + + + + + +
Schema Operation
+ 		How to Do It
+
Get the schema collection of all associated + encodings.
+ 		+ +
    +
  • <SchemaCollection> + = <SOAPEncoding> .schemaCollection;
    • + + +
+
Load additional schema types from XML Schema + files into the schema collection.
+
+ 		+ +
    +
  • <SchemaLoader> + = <SchemaCollection> + ;
    • +
  • // and then
    +
    • +
  • <SchemaLoader> + .load(" <schema file URI> + ");
    • +
  • //  or
    +
    • +
  • <SchemaLoader> + .loadAsync(" <schemaURI> +", <load completion function> + );
    • + + +
+
Specify the XML Schema type to be used when + encoding or decoding a block.  Note: decoding a block occurs when +you get its value, so after getting a block from an XML-encoded message such +as a SOAPResponse, attaching type info affects evaluation of the value. + +
    +
  • <SchemaType> + = <SchemaCollection> + .getType(" <name> ", " + <namespaceURI> ");
    • +
  • if (<schemaType != null) + {
    +
    • +
  •   + <SOAPBlock> .schemaType = + <SchemaType> ;
    • +
  • }
    • +     + +
+
+ +

+ +

+ +

+ 3.9 Customization of Encodings

+ A specific encoding must have encoders and decoders to function. +  Encoding or decoding of data always begins with a default encoder + or decoder, which then may lookup additional encoders or decoders by +a string key as required.  For either the 1.1 or 1.2 version of +the default SOAP encoding, the default encoder and decoder use the schema +type's namespaceURI and name, seperated by "#" to look up additional decoders +for specific schema types.  Additional encoders and decoders registered + within the default encodings will automatically be invoked as an object + identified as the corresponding type is processed.  Other encodings + can use any scheme for looking up additional encoders and decoders, or +none at all if all the work is done by the default encoder and decoder +for that encoding.  Encodings which are registered with the system, +such as the default SOAP 1.1 or 1.2 encodings, automatically come with encoders +and decoders built-in, whereas new encodings have none.  Custom encodings + may also reuse existing encoders and decoders, but there is no guarantee + which are present, since the mapping may vary when handling an infinite +set of types with a finite set of encoders and decoders.
+
+ Also, there has been a proliferation of different schema URIs +to describe the same types, which may often even be intermixed in usage, but +expected to function properly.  Most notably, the SOAP 1.1 specification +used unofficial XML Schema URIs and SOAP encoding schema URIs not compatible + with those which are in the W3C XML Schema and drafts for SOAP 1.2 specifications. +  It is not uncommon to send and receive messages using the URIs +specified in the SOAP 1.1 specification, but described by WSDL using XML +Schema that uses the official, correct URIs.  To solve these problems, +the encoding permits schema URIs to be aliased, both on input and on +output, so that only the SOAP 1.2 and official XMLSchema types are used +internally, while supporting the other URIs.  Mappings of this type +are built-in for encodings which are registered with the system, such as +the default encodings of SOAP 1.1 and 1.2.  The default URI mappings +may be manipulated, for example, to output SOAP 1.1 but with the official +XML Schema URIs, without having to rewrite any encoders or decoders.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
Encoding Customization Operation
+ 		How to Do It
+
Create a custom encoder. + +
    +
  • function <New DOM Element> + = <SOAPEncoder name>( + <SOAPEncoding>, <value> + , <namespaceURI> , + <name>, <SchemaType> + , <SOAPAttachments> , + <Parent DOM Element> )
    • +
  • {
    • +
  • <...>
    +
    • +
  • <DOM Element> + = <Parent DOM Element> + .ownerDocument.createElementNS(namespaceURI,name);
    +
    • +
  • <...>
    +
    • +
  •   <Parent DOM Element> + .appendChild(<DOM Element> + );
    +
    • +
  •   return <DOM Element> + ;
    +
    • +
  • }
    • +
  • // and
    • +
  • <SOAPEncoding> + .defaultEncoder = <SOAPEncoder> + ;
    • +
  • // or
    • +
  • <SOAPEncoding> + .setEncoder(" <namespaceURI> + # <name> ", + <SOAPEncoder> );
    • + + +
+
+
Create a custom decoder.
+ 		+ +
    +
  • function <New DOM Element> + = <SOAPDecoder name>( + <SOAPEncoding>, <DOM +Element> , <SchemaType> + , <SOAPAttachments>)
    • +
  • {
    • +
  • <...>
    • +
  •   return <value or object> + ;
    +
    • +
  • }
    • +
  • // and
    • +
  • <SOAPEncoding> + .defaultDecoder = <SOAPDecoder> + ;
    • +
  • // or
    • +
  • <SOAPEncoding> + .setDecoder(" <namespaceURI> + # <name> ", + <SOAPDecoder> );
    • + + +
+
+
Map or unmap schema  URI aliases
+ 		+ +
    +
  • <SOAPEncoding> + .mapSchemaURI(" <external URI> + ", "<internal URI>", + <true to alias output> );
    • +
  • // or
    • +
  • <SOAPEncoding> + .unmapSchemaURI(" <external URI> + ");
    • + + +
+
Register modified or alternative encodings, + making them automatically available to all SOAP scripts in the system
+ 		Install an appropriate registerable encoding + in components/<new encoding> + .js
+
+ +

+ 3.10 Security Operations

+ In browsers, the risk of allowing an externally-loaded untrusted + script to request information within a firewall and send it elsewhere +has lead to very tight sandbox restrictions, permitting external browser +scripts to only request xml data and services on the same domain from +which the script was loaded.  This same restriction applies by default +to SOAP requests executed within the browser.  This means that an +externally-loaded script cannot, for example, call other external services +unless they are in the same domain from which the page was loaded.  Even +if the page was loaded from the user's own hard disk, the script must ask +for permission to make SOAP calls.  A browser enhancement is planned +to permit more-precise control of trust between scripts and specific available +services.
+
+ Since SOAP permits headers to be added to messages that require +interpretation by the recipient, this API can request a header to warn +the recipient that it was sent by an untrusted script loaded from a specific + sourceURI, and no good SOAP service will unintentionally disregard the warning. +  If the envelope is verified and the header is added, then the browser + can allow the script less-restricted access to services outside of its +source domain.  Accepting this header permits SOAP services that +really do want to be universally available to allow access without forcing +the user to risk breach of the firewall protections and/or request user +permission.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Security Operation
+ 		How to Do It
+
Mark the call with a verifySourceHeader +so, if the service permits it, the browser can make the call with less +privilege and risk.
+ 		+ +
    +
  • <SOAPCall> + .verifySourceHeader = true;
    • + + +
+
Request risky privileges within a local +or signed script to make an unverified SOAP calls to other domains.
+ 		+ +
    +
  • netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead")
    • + + +
+
Modify the security settings in the preferences + file, allowing scripts from some domain to make risky SOAP calls to +any other domain, which is disabled by default.Add the setting in default/pref/all.js + :
+ + +
    +
  • pref("<some domain prefix> + .SOAPCall.invoke","allAccess");
    • + + +
+
Modify the security settings in the preferences + file to disallow even dross-domain calls made with verifySource header, +which is generally permitted by default.
+ 		Remove or comment out the setting in +default/pref/all.js :
+ +
    +
  • pref("capability.policy.default.SOAPCall.invokeVerifySourceHeader","allAccess");
    • + +
+
Register alternative transport mechanisms, + making available alternative transports to all scripts and perhaps creating + alternative security models for protocols besides http(s).  See + +the futures section + for more info on possible transports.
+ 		Install an appropriate registerable encoding + in components/<new transport> + .js.
+
+ +

+ +

+ 4 Future Features

+ +

+ 4.1 Access to SOAP as Proxies

+ Although a SOAP call can generally be accomplished using this +low-level API in a few dozen lines, WSDL is a standard that contains +enough information to enable this to occur with no manual argument and +type setup required.  An implementation is under development that + instantiates web service proxies complete with appropriate xpconnect interfaces + by simply loading and using information out of a WSDL file that describes +the service.  The proxy's interface has dynamically-generated methods +named appropriately to match the services described in the WSDL file which +accept arguments of the appropriate data types and calls the appropriate + low-level SOAP functions with the appropriate type information, making +it even simpler not only to invoke services from Javascript code, but to +associate appropriate schema types loaded from the WSDL file with the arguments. + This higher level is not available in the first release.  When +it is available, invoking WSDL-described features gets even easier and more +reliable.
+ +

+ +

+ 4.2 Arbitrary Graphs of Data

+ The SOAP specification allows objects to be passed as arguments + which may have originally referenced other objects that are not owned + in a pure hierarchy.  This is represented by using an href attribute. +  Due to the problems with leaking reference counts in COM objects + with cyclic references, this has not been implemented yet.  Also, + the output of a cyclicly-referencing set of objects has not been implemented. +  Outgoing objects that do not reference cyclicly currently create + separate copies for each reference to an object, and with cycles output + may never complete.  On input, hrefs are currently ignored.  In + the future it may be possible to solve this and transmit and receive arbitrarily-referencing + objects, but the solution is more complex than just using weak references.
+ +

+ 4.3 SOAP With Attachments

+ Many clients and servers now support automatically transmitting + large Mime with a SOAP message by encapsulating it in MIME, DIME, or +other enveloping formats.  This has been anticipated in the APIs, +but the SOAPAttachments API is currently a placeholder for this future +feature which is not yet implemented.
+ +

+ 4.4 New Transports and Local Services

+ Obvious new transports that would be useful include e-mail -- permitting + a SOAP exchange to occur as an email exchange --, instant messenger for + peer to peer, and a local manager with a controlled security model but +without the size limitations, enabling SOAP to save and restore arbitrary +Javascript application data on the client.  These services require +a framework, already being planned, for permitting the browser to host +services as well as being a good client.  There are obviously security +issues to be solved to make these successful.
+ +

+ 4.5 Standards

+ The interfaces to the objects of this API were designed to be as simple + and universal as possible.  We believe that we should submit a note + describing them and sponser a W3C proposal to standardize an API for invoking + this type of service from web clients.  In such an effort, changes +would be inevitable and welcomed as the price for interoperability within +web clients.  Part of this API are incomplete, specifically the SOAPAttachments + object, which will be defined to allow encoders and decoders to control +uniqueness and referencing, both for resolving arbitrary graphs of data +(as described above in "Arbitrary Graphs of Data") as well as for automatically +resolving references to attached objects carried with the message in an +external encapsulation (as described above in "SOAP With Attachments").
+ +

+ 5 Samples and Testing

+ Some samples or tests have been created, but these commonly only use + the basic operations.  Some of the higher-level features are being + tested by the prosy code (as described above in "Access to SOAP as Proxies"). +  While most of the methods of this API are well-exercized internally + during even basic invocation, we need samples that test and demonstrate +external access to the functions.  What exists today is mozilla/extensions/xmlextras/tests + /soap*.html.  We welcome the contribution of tests by other parties. +  Most samples work but at least one (soapcall.html) is no longer correctly + configured to talk to a server -- but it genrates interesting messages +anyway.
+
+ To test the services, it is currently required to compile Mozilla with + the environment variable MOZ_SOAP=1 (if you already have a build, you only + need to do a clean rebuild of the xmlextras directory).  It is also + interesting to turn on MOZ_DEBUG=1, because even if you do not debug the + program, this causes the exchanged SOAP messages to be displayed on the +standard output if you run from a command shell where this is visible.
+
+ A SOAP service server has been set up at ray.dsl.xmission.com where + additional services may be deployed to help test and demo the features +for scripting SOAP in Mozilla.  No home page describes the Apache +Jakarta server on port 8080 which is the test facility, but this is currently +used in two tests in the previously-mentioned directory: soapisprimenumber.html + and soapunscramble.html.  Adding services is as easy as writing functions + in Javascript, Java, or other supported languages and describing the deployment + in XML.  Disclaimer: as this is merely an end-subscriber DSL service, + if the server becomes too widely published, it may have to be shut down.
+
+ Bugs should be reported as usual.
+ +

+ 6 Object Interfaces

+
+ +

+
+
+ + + diff --git a/extensions/xmlextras/docs/Soap_Scripts_in_Mozilla.html b/extensions/xmlextras/docs/Soap_Scripts_in_Mozilla.html index 7ffa77dac32..6f32107f2e7 100644 --- a/extensions/xmlextras/docs/Soap_Scripts_in_Mozilla.html +++ b/extensions/xmlextras/docs/Soap_Scripts_in_Mozilla.html @@ -1,1190 +1,1369 @@ - + Soap Scripts in Mozilla - -
+ +

SOAP Scripts in Mozilla

- February 16, 2002
- + February 16, 2002
+

Ray Whitmer

- +

Abstract

- -
Microsoft and others have advocated - SOAP as a way to encode and exchange public data structures between agents - on the web, which is now becoming a web standard at W3C (see the multiple -submissions and working documents related to SOAP in the list of -W3C current drafts -). 
-
-The browser client is the most universal web agent in existence, and Javascript -is the standard, interoperable way of scripting browsers.  Scriptable -SOAP in browsers gives clients and servers more to say to each other through -existing http-xml services, providing scripts with persistence, database, -and access to other web services not tied to the request and response -cycles of the HTML-based user interface.  Web data structures, exchanged - in a platform-neutral way, should become as fundamental to web agents as -web content is today.  The key to this is a very natural binding to -the data of Javascript so that the script can simply use the data instead -of tediously encoding and extracting the data from the XML.
- -

1 SOAP Services

- There are a number of sources for services available on the web -being set up, such as the XMethods -website - which the Mozilla implementation has used for some of our tests and use - cases.  Apache supports modules for SOAP that have been used to author - services for purposes of testing the Mozilla implementation (and entertainment).  - Once it is set up, it is as simple as writing a function in Javascript, - Java, or any other of a number of supported languages and then writing -a simple service description in XML or submitting a form to deploy the -service.  There are toolkits available from Microsoft and other webserver -providers for authoring such services as well.
- -

2 SOAP Blocks

- -

2.1 Parameters
-

- SOAP-based services exchange message envelopes which contain blocks - of XML data roughly corresponding to the parameters of a service call.  - When an rpc-style message is exchanged, blocks representing the regular - parameter blocks are placed inside an element which identifies the object - and method being invoked, which is placed inside the body.  In a -non-RPC message, the blocks are placed directly inside the body instead -of under the method element. 
- -

2.2 Header Blocks
-

- If there are blocks which are optional or independently added or processed, - these are carried in the header with an assigned role and marked if the - recipient is required to understand them.
- -

2.3 Encodings
-

- Interpretation of each block depends upon the encoding that was used, - which is clearly specified in the message.  If the standard SOAP encoding - is used, then XML Schema types control the interpretation of the data within - each block.
- -

3 Using the Low-Level SOAP API

- To use the low-level API, the user creates a SOAPCall object, encodes - the function call with a list of headers and regular parameters, and invokes - the call, which returns a response which contains the results of the service - call including a fault generated by the service which processed the message, - output parameters, and/or header blocks.  If the call is invoked -asynchronously, then a function is given which receives the response -when it arrives from the remote service.
-
- Besides Javascript, the below-described operations should also generally - work for other xpconnect-supported languages in Mozilla such as C++/XPCOM - and Python, because language-independent cross-platform interfaces were - used.
- -

3.1 Conventions Used Below in Operations
-

- Names or descriptions in angle brackets represent values or objects - matching the name or description.  These may be literal, constructed - via "new", or variables.  Occasionally the same syntax with a longer - description represent mores script performing an operation.  Quoted - angle brackets indicate a string of the described type.
-
- So the following operation:
- -
    -
  • <Foo> = new Foo( - <FooFact> );
    • -
  • <Foo>.bar = - <any value or object>;
    • -
  • <Baz> = - <Foo>.find("<name> - ");
    • -
  • <find out what you have>
    • - -
- might be replaced in a real Javascript program with
-
- var myFoo = new Foo(new FooFact("always","Great","Baz"));
- myFoo.bar = 3.14159265;
- var myGreatBaz = myFoo.find("Great");
- if (checkBaz(myGreatBaz)) {
-   alert(myGreatBaz.description);
- }
-
- where "myFoo" is a variable holding an object of type Foo and myGreatBaz - is a variable holding an object of type Baz.
- -

3.2 Basic Operations of SOAP
-

- For basic SOAP operations is all most users need to do.
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Basic Operation
- 		How to Do It
-
Create a parameter block, setting the Javascript - value and name for rpc-style call
- 		- -
    -
  • <SOAPParameter> - = new SOAPParameter(<any value or object> - , "<name>");
    • -
  •  // or
    • -
  • <SOAPParameter> - = new SOAPParameter();
    • -
  • <SOAPParameter> - .value = <any value or object> - ;
    • -
  • <SOAPParameter> - .name = "<name>";
    • - -
-
Set parameters in a Javascript array
- 		- -
    -
  • <SOAPParameter array> - = new Array(<SOAPParameter> - [,...]);
    • -
  • // or
    • -
  • <SOAPParameter array> - = new Array();
    • -
  • <SOAPParameter array> - [0] = <SOAPParameter> ;
    • -
  • [...]
    • - -
-
Create and encode the parameters in a basic - SOAP 1.1 rpc-style message
- 		- -
    -
  • <SOAPCall> = -new SOAPCall();
    • -
  • <SOAPCall>.transportURI - = "<http-based service URI>"
    • -
  • <SOAPCall>.encode(0, - "<method name> ", " - <service namespace>", 0, null, - <SOAPParameter array> .length, - <SOAPParameter array>);
    • - -
-
Invoke  call (send call message and receive - response message)
- 		- -
    -
  • <SOAPResponse> - = <SOAPCall>.invoke();
    • -
  • <process the response -- see - below>
    • -
  • // or
    • -
  • <SOAPCall>.asyncInvoke( - <SOAPResponseListener> );
    • - -
-
Handle completion of async SOAP call.
- 		- -
    -
  • function <SOAPResponseListener - name>(<SOAPResponse> - , <SOAPCall>, - <error>)
    • -
  • {
    • -
  •   if (error != 0) {
    • -
  •      <action - to be taken on failure to transport message>
    • -
  •   }
    • -
  •   <process the response - -- see below>
    • -
  • }
    • - -
-
Get service's failure, if any.
- 		- -
    -
  • <SOAPFault> -= <SOAPResponse>.fault;
    • -
  • if (<SOAPFault> - != null) {
    • -
  •   <namespace URI string> - = <SOAPFault> .faultNamespace;
    • -
  •   <name string> - = <SOAPFault> .faultCode;
    • -
  •   <summary string> - = <SOAPFault> .faultString;
    • -
  •   <actor URI string> - = <SOAPFault> .actorURI;
    • -
  •   <action to be taken -in case of fault>
    • -
  • }
    • - -
-
Get returned parameters from rpc-style response
- 		- -
    -
  • <SOAPParameter array> - = <SOAPResponse> .getParameters(true, - {});
    • - -
-
Process Javascript values, etc. of returned - parameters
- 		- -
    -
  • for (i = 0; i != <SOAPParameter - array>.length; i++)
    • -
  • {
    • -
  •   <SOAPParameter> - = <SOAPParameter array>[i];
    • -
  •   <value or object> - = <SOAPParameter> .value;
    • -
  •   <name string> - = <SOAPParameter> .name;
    • -
  •   <checking and processing - of result>
    • -
  • }
    • - -
-
- -

- -

3.3 Beyond Basic Operations
-

- The above operations are what every user of the lowlevel SOAP toolkit needs -to invoke service requests and interpret the responses, as is easily seen -by looking at some of the samples.  The bulk of the operations that follow -will generally be used less frequently, but they need to be there for  cases -where they are needed.  The casual reader may wish to skip the remaining -tables of operations in this section, or scan for features of interest.
- -

3.4 Header Operations

- For additional information, the user can send or receive header blockss. -  Sending and receiving header blocks is not very different from sending - and receiving parameters as described above.
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Header Operation
- 		How to Do It
-
Create a Header Block
- 		- -
    -
  • <SOAPHeaderBlock> - = new SOAPHeaderBlock(<any value or object> - , "<name>", " - <namespaceURI> ");
    • -
  •  // or
    • -
  • <SOAPHeaderBlock> - = new SOAPHeaderBlock();
    • -
  • <SOAPHeaderBlock> - .value = <any value or object> - ;
    • -
  • <SOAPHeaderBlock> - .name = "<name> ";
    • -
  • <SOAPHeaderBlock> - .namespaceURI = "<namespaceURI> - ";
    • - -
-
Establish non-default role of a header block
- 		- -
    -
  • <SOAPHeaderBlock> - .actorURI = "<actorURI> ";
    • -
  • <SOAPHeaderBlock> - .mustUnderstand = <true or false> - ;
    • - -
-
Set header blocks in a Javascript array
- 		- -
    -
  • <SOAPHeaderBlock array> - = new Array(<SOAPHeaderBlock> - [,...]);
    • -
  • // or
    • -
  • <SOAPHeaderBlock array> - = new Array();
    • -
  • <SOAPHeaderBlock array> - [0] = <SOAPHeaderBlock> ;
    • -
  • [...]
    • - -
-
Encode the headers in a SOAP 1.1 rpc-style -message
- 		- -
    -
  • <SOAPCall>.encode(0, - "<method name> ", " - <service namespace>", <SOAPHeaderBlock - array> .length, <SOAPHeaderBlock - array>, <SOAPParameter array> - .length, <SOAPParameter array> - );
    • - -
-
Get returned headers
- 		- -
    -
  • <SOAPHeaderBlock array> - = <SOAPResponse> .getHeaderBlocks(true, - {});
    • - -
-
Process Javascript values, etc. of returned -headers
- 		- -
    -
  • for (i = 0; i != <SOAPHeaderBlock - array>.length; i++)
    • -
  • {
    • -
  •   <SOAPHeaderBlock> - = <SOAPHeaderBlock array>[i];
    • -
  •   <value or object> - = <SOAPHeaderBlock> .value;
    • -
  •   <name string> - = <SOAPHeaderBlock> .name;
    • -
  •   <namespace URI string> - = <SOAPHeaderBlock> .namespaceURI;
    • -
  •   <actor URI string> - = <SOAPHeaderBlock> .actorURI;
    • -
  •   <must understand boolean> - = <SOAPHeaderBlock> .mustUnderstand;
    -
    • -
  •   <checking and processing - of result>
    • -
  • }
    • - -
-
- -

3.5 Non-RPC Operations

- For messages that are not intended to model RPC calls, there is no -method name or target object URI, and the parameters generally have namespaceURIs. -  Otherwise, the basic operations are the same.
-
- - - - - - - - - - - - - - - - - - - - - -
Non-RPC Operation
- 		How to Do It
-
Setting the namespaceURI of a non-RPC parameter
- 		- -
    -
  • <SOAPParameter> - = new SOAPHeaderBlock(<any value or object> - , "<name>", " - <namespaceURI> ");
    • -
  •  // or
    • -
  • <SOAPParameter> - .namespaceURI = "<namespaceURI> - ";
    • - -
-
Encode a SOAP 1.1 non-rpc-style message
- 		- -
    -
  • <SOAPCall>.encode(0, - "", "", <header block array>.length, - <header block array>, - <parameter array>.length, <parameter - array>)
    • - -
-
Get returned parameters from non-rpc-style -response
- 		- -
    -
  • <SOAPParameter array> - = <SOAPResponse> .getParameters(false, - {});
    • - -
-
- -

3.6 SOAPBlock and SOAPMessage Supertypes

- In the following operations, SOAPHeaderBlock and SOAPParameter may be referred -to collectively as SOAPBlock objects.
-
- Also, SOAPCall and SOAPResponse may be referred to collectively as SOAPMessage -objects.
- -

3.7 More Operations

- The following table contains less-common operations.
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Operation
- 		How to Do It
-
Set or get an actionURI carried for the message - in the HTTP header
- 		- -
    -
  • <SOAPMessage> - .actionURI = "<action URI> ";
    • -
  • // or
    -
    • -
  • <action URI string> - = <SOAPMessage> .actionURI;
    -
    • - -
-
Directly set the DOM element to represent the - block's encoded content, bypassing encoding of the value on the block
- 		- -
    -
  • <SOAPBlock>.element - = <DOM Element> ;
    -
    • - -
-
-
Directly get the DOM element that represents - the block's encoded content, bypassing decoding of the value on the block
- 		- -
    -
  • <DOM Element> - = <SOAPBlock>.element;
    -
    • - -
-
Directly get the DOM element containing the -SOAP envelope , header, or body of an encoded message
- 		- -
    -
  • <DOM Element> - = <SOAPMessage>.envelope;
    • -
  • // OR
    • -
  • <DOM Element> - = <SOAPMessage>.header;
    • -
  • // or
    • -
  • <DOM Element> - = <SOAPMessage>.body;
    -
    • - -
-
Directly set the DOM document to represent -the message's entire encoded content, bypassing encoding.
- 		- -
    -
  • <SOAPMessage> - .message = <DOM Document> ;
    -
    • - -
-
-
Directly get the DOM document of an encoded -message, bypassing encoding.
- 		- -
    -
  • <DOM Document> - = <SOAPMessage>.message;
    -
    • - -
-
-
Get the method name and object URI, if any, -of the message.
- 		<method name string> - = <SOAPMessage> .method;
-
Get the actual SOAP version of an encoded message - -- 0 for SOAP 1.1 and 1 for SOAP 1.2.
- 		- -
    -
  • <version integer> - = <SOAPMessage> .version;
    • - -
-
Encode a SOAP 1.2 message.
- 		- -
    -
  • <SOAPCall>.encode(1, - "<method name> ", " - <service namespace>", <SOAPHeaderBlock - array> .length, <SOAPHeaderBlock - array>, <SOAPParameter array> - .length, <SOAPParameter array> - );
    • - -
-
Abort an in-progress async call -- this does - not necessarily cause the message not to be processed, but the API stops - listening for it to complete.
- 		- -
    -
  • <SOAPCallCompletion> - = <SOAPCall> .asyncInvoke( - <SOAPResponseListener>);
    • -
  • [...]
    • -
  • <SOAPCallCompletion> - .abort();
    -
    • - -
-
Get the encoding (style) used to encode or -decode message.  Not available on an unencoded call unless explicitly -set -- use following operation instead.
- 		- -
    -
  • <SOAPEncoding> - = <SOAPMessage>.encoding;
    • - -
-
Set the encoding style (and associated styles) - used to encode a message.
- 		- -
    -
  • <SOAPEncoding> - = new SOAPEncoding();
    • -
  • <SOAPEncoding> - = <SOAPEncoding>.getAssociatedEncoding(" - <style URI>",<true to -create> );
    • -
  • [...]<customize encodings>
    -
    • -
  • <SOAPMessage> - .encoding = <SOAPEncoding> ;
    • - -
-
Specify the specific style used to encode or - decode specific blocks
- 		- -
    -
  • <SOAPEncoding> - = <SOAPEncoding>.getAssociatedEncoding(" - <style URI>",<true to -create> );
    • -
  • <SOAPBlock>.encoding - = <SOAPEncoding> ;
    • - -
-
- -

- -

3.8 Using Schema Types

- The default SOAP encodings implement most XML built-in types, as -well as the basic SOAP types.  In the absence of a specified type, -native values and objects will typically be correctly identified and mapped -to a corresponding schema type.  Many types do not match, and so they -will be mapped to a close type.  Providing specific schema types can -help the encoding produce the desired results.  For example, multidimensional - arrays must be decoded as nested arrays because Javascript only supports - single-dimensional arrays.  f no schema type is given that identifies - the array as multidimensional, then a multidimensional array will be encoded - as a nested array.  An accurate schema type can also help when encoding - or decoding of other complex objects such as SOAP structs.
-
- Schema types may be attached to blocks before encoding or before accessing - the value of a returned object to better control the encoding and decoding. -  All schema types which are used to control the encoding and decoding - should come from the schema collection available through any associated - encoding.
-
- - - - - - - - - - - - - - - - - - - - - -
Schema Operation
- 		How to Do It
-
Get the schema collection of all associated -encodings.
- 		- -
    -
  • <SchemaCollection> - = <SOAPEncoding> .schemaCollection;
    • - -
-
Load additional schema types from XML Schema - files into the schema collection.
-
- 		- -
    -
  • <SchemaLoader> - = <SchemaCollection> - ;
    • -
  • // and then
    -
    • -
  • <SchemaLoader> - .load(" <schema file URI> ");
    • -
  • //  or
    -
    • -
  • <SchemaLoader> - .loadAsync(" <schemaURI> ", - <load completion function> -);
    • - -
-
Specify the XML Schema type to be used when -encoding or decoding a block -- decoding a block occurs when you get its -value if it came from an encoded message such as a SOAPResponse. - -
    -
  • <SchemaType> - = <SchemaCollection> - .getType(" <name> ", " - <namespaceURI> ");
    • -
  • if (<schemaType != null) {
    -
    • -
  •   - <SOAPBlock> .schemaType = <SchemaType> - ;
    • -
  • }
    • -     -
-
- -

- -

- -

3.9 Customization of Encodings

- A specific encoding must have encoders and decoders to function.  Encoding - or decoding of data always begins with a default encoder or decoder, which - then may lookup additional encoders or decoders by a string key as required. -  For either the 1.1 or 1.2 version of the default SOAP encoding, the - default encoder and decoder use the schema type's namespaceURI and name, - seperated by "#" to look up additional decoders for specific schema types. -  Additional encoders and decoders registered within the default encodings - will automatically be invoked as an object identified as the corresponding - type is processed.  Other encodings can use any scheme for looking -up additional encoders and decoders, or none at all if all the work is done - by the default encoder and decoder for that encoding style.  Encodings - which are registered with the system, such as the default SOAP 1.1 or 1.2 - encodings, automatically come with encoders and decoders built-in, whereas - new encodings have none.  Custom encodings may also reuse existing -encoders, and decoders, but there is no guarantee which are present, since -the mapping may vary when handling an infinite set of types with a finite -set of encoders and decoders.
-
- Also, there has been a proliferation of variant schema types with -different URIs, which may be improperly intermixed in usage, but expected -to function properly.  Most notably, the SOAP 1.1 specification used -unofficial XML Schema URIs and SOAP encoding schema URIs not compatible -with those which are in the W3C XML Schema and drafts for SOAP 1.2 specifications. - It is not uncommon to send and receive messages using the URIs specified -in the SOAP 1.1 specification, but described by WSDL using XML Schema that -uses the official, correct URIs.  To solve these problems, the encoding -permits schema URIs to be aliased, both on input and on output, so that -only the SOAP 1.2 and official XMLSchema types are used internally, while -supporting the other URIs.  Mappings of this type are built-in for -encodings which are registered with the system, such as the default encodings - of SOAP 1.1 and 1.2.  The default URI mappings in the default encoding - of SOAP 1.1 may be manipulated, for example, to output the official XML -Schema URIs, without having to rewrite any encoders or decoders.
-
- - - - - - - - - - - - - - - - - - - - - - - - - -
Encoding Customization Operation
- 		How to Do It
-
Create a custom encoder. - -
    -
  • function <New DOM Element> - = <SOAPEncoder name>( - <SOAPEncoding>, <value> - , <namespaceURI> , - <name>, <SchemaType> - , <SOAPAttachments> , - <Parent DOM Element> )
    • -
  • {
    • -
  • [...]
    • -
  • <DOM Element> - = <Parent DOM Element> - .ownerDocument.createElementNS(namespaceURI,name);
    -
    • -
  • [...]
    • -
  •   <Parent DOM Element> - .appendChild(<DOM Element>);
    -
    • -
  •   return <DOM Element> - ;
    -
    • -
  • }
    • -
  • // and
    • -
  • <SOAPEncoding> - .defaultEncoder = <SOAPEncoder> - ;
    • -
  • // or
    • -
  • <SOAPEncoding> - .setEncoder(" <namespaceURI> - # <name> ", - <SOAPEncoder> );
    • - -
-
-
Create a custom decoder.
- 		- -
    -
  • function <New DOM Element> - = <SOAPDecoder name>( - <SOAPEncoding>, <DOM Element> - , <SchemaType>, - <SOAPAttachments>)
    • -
  • {
    • -
  • [...]
    • -
  •   return <value or object> - ;
    -
    • -
  • }
    • -
  • // and
    • -
  • <SOAPEncoding> - .defaultDecoder = <SOAPDecoder> - ;
    • -
  • // or
    • -
  • <SOAPEncoding> - .setDecoder(" <namespaceURI> - # <name> ", - <SOAPDecoder> );
    • - -
-
-
Map or unmap schema  URI aliases
- 		- -
    -
  • <SOAPEncoding> - .mapSchemaURI(" <external URI> - ", "<internal URI>", - <true to alias output> );
    • -
  • // or
    • -
  • <SOAPEncoding> - .unmapSchemaURI(" <external URI> - ");
    • - -
-
Register modified or alternative encodings, -making them automatically available to all SOAP scripts in the system
- 		Install an appropriate registerable encoding - in components/<new encoding> - .js
-
- -

3.10 Security Operations

- In browsers, the risk of allowing an externally-loaded untrusted script - to request information within a firewall and send it elsewhere has lead - to very tight sandbox restrictions, only permitting external browser scripts - to request xml data and services on the same domain from which the script - was loaded.  This same restriction applies by default to SOAP requests - executed within the browser.  This means that an externally-loaded - script cannot, for example, call other external services unless they are - in the same domain from which the page was loaded.  Even if the page - was loaded from the user's own hard disk, the script must ask for permission - to make SOAP calls.  A browser enhancement is planned to permit more-precise - control of trust between scripts and specific available services.
-
- Since SOAP permits headers to be added to messages that require interpretation - by the recipient, this API can request a header to warn the recipient that - it was sent by an untrusted script loaded from a specific sourceURI, and - no good SOAP service will unintentionally disregard the warning.  If - the envelope is verified and the header is added, then the browser can -allow the script less=-restricted access to services outside of its source - domain.  Accepting this header permits SOAP services that really do -want to be universally available to allow access without forcing the user -to risk breach of the firewall protections or requiring user intervention -at all.
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Security Operation
- 		How to Do It
-
Mark the call with a verifySourceHeader, if -the server permits it, so the browser can make the call with less privilege - and risk.
- 		- -
    -
  • <SOAPCall>.verifySourceHeader - = true;
    • - -
-
Request risky privileges within a local or -signed script to make an unverified SOAP calls to other domains.
- 		- -
    -
  • netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead")
    • - -
-
Modify the security settings in the preferences - file, allowing scripts from some domain to make risky SOAP calls to any - other domain, which is disabled by default.Add the setting in default/pref/all.js - :
- -
    -
  • pref("<some domain prefix> - .SOAPCall.invoke","allAccess");
    • - -
-
Modify the security settings in the preferences - file to disallow calls made with the verifySource header, which is generally - enabled by default.
- 		Change the setting in default/pref/all.js - :
- -
    -
  • pref("capability.policy.default.SOAPCall.invokeVerifySourceHeader","none");
    • - -
-
Register alternative transport mechanisms, -making available alternative transports to all scripts and perhaps creating - alternative security models for protocols besides http(s).
- 		Install an appropriate registerable encoding - in components/<new transport> - .js.
-
- -

- -

4 Future Features

- -

4.1 Access to SOAP as Proxies

- Although a SOAP call can generally be accomplished using this low-level - API in a few dozen lines, WSDL is a standard that contains enough information -to enable this to occur with no manual argument and type setup required. - An implementation is under development that instantiates web service -proxies complete with appropriate xpconnect interfaces by simply loading -and using information out of a WSDL file that describes the service.  The -proxy's interface has dynamically-generated methods named appropriately -to match the services described in the WSDL file which accept arguments of -the appropriate data types and calls the appropriate low-level SOAP functions -with the appropriate type information, making it even simpler not only -to invoke services from Javascript code, but to associate appropriate schema -types loaded from the WSDL file with the arguments.  This higher level -is not available in the first release.  When it is available, invoking -WSDL-described features gets even easier and more reliable.
- -

- -

4.2 Arbitrary Graphs of Data

- The SOAP specification allows objects to be passed as arguments which - may have originally referenced other objects that are not owned in a pure - hierarchy.  This is represented by using an href attribute.  Due - to the problems with leaking reference counts in COM objects with cyclic - references, this has not been implemented yet.  Also, the output of - a cyclicly-referencing set of objects has not been implemented.  Incoming - objects that do not reference cyclicly currently create separate copies - for each reference to an object, and with cycles will probably never complete. -  On input, hrefs are currently ignored.  In the future it may -be possible to solve this and transmit and receive arbitrarily-referencing -objects, but the solution is more complex than just using weak references.
- -

4.3 SOAP With Attachments

- Many clients and servers now support automatically transmitting large - Mime with a SOAP message by encapsulating it in MIME, DIME, or other enveloping - formats.  This has been anticipated in the APIs, but the SOAPAttachments - API is currently a placeholder for this future feature which is not yet - implemented.
- -

4.4 New Transports and Local Services

- Obvious new transports that would be useful include e-mail -- permitting - a SOAP exchange to occur as an email exchange --, instant messenger for - peer to peer, and a local manager with a controlled security model but -without the size limitations, enabling SOAP to save and restore arbitrary -Javascript application data on the client.  These services require -a framework, already being planned, for permitting the browser to host -services as well as being a good client.  There are obviously security -issues to be solved to make these successful.
- -

4.5 Standards

- The interfaces to the objects of this API were designed to be as simple - and universal as possible.  We believe that we should submit a note -describing them and sponser a W3C proposal to standardize an API for invoking -this type of service from web clients.  In such an effort, changes would -be inevitable and welcomed as the price for interoperability within web clients. - Part of this API are incomplete, specifically the SOAPAttachments object, -which will be defined to allow encoders and decoders to control uniqueness - and referencing, both for resolving arbitrary graphs of data (as described -above in "Arbitrary Graphs of Data") as well as for automatically resolving -references to attached objects carried with the message in an external encapsulation -(as described above in "SOAP With Attachments").
- -

4.6 Samples and Testing

- Some samples or tests have been created, but these commonly only use -the basic operations.  Some of the higher-level features are being -tested by the prosy code (as described above in "Access to SOAP as Proxies"). - While most of the methods of this API are well-exercized internally - during even basic invocation, we need samples that test and demonstrate -external access to the functions.  What exists today is mozilla/extensions/xmlextras/tests - /soap*.html.  We welcome the contribution of tests by other parties. - Most samples work but at least one (soapcall.html) is no longer correctly -configured to talk to a server -- but it genrates interesting messages anyway.
+ +
Microsoft and others have advocated + SOAP as a way to encode and exchange public data structures between agents + on the web, which is now becoming a web standard at W3C (see the multiple + submissions and working documents related to SOAP in the list of + W3C current drafts + ). 
+
+ The browser client is the most universal web agent in existence, and + Javascript is the standard, interoperable way of scripting browsers.  + Scriptable SOAP in browsers gives clients and servers more to say to +each other through existing http-xml request services, providing scripts + with persistence, database, and access to other web services not tied +to the request and response cycles of the HTML-based user interface.  + Web data structures, exchanged in a platform-neutral way, should become +as fundamental to web agents as web content is today.  The key to this +is a very natural binding to the data of Javascript so that the script can +simply use the data instead of tediously encoding and extracting the data +from the XML.

- To test the services, it is currently required to compile Mozilla with the -environment variable MOZ_SOAP=1 (if you already have a build, you only need -to do a clean rebuild of the xmlextras directory).  It is also interesting -to turn on MOZ_DEBUG=1, because even if you do not debug the program, this -causes the exchanged SOAP messages to be displayed on the standard output -if you run from a command shell where this is visible.
-
- A SOAP service server has been set up at ray.dsl.xmission.com where additional -services may be deployed to help test and demo the features for scripting - SOAP in Mozilla.  No home page describes the Apache Jakarta server -on port 8080 which is the test facility, but this is currently used in two -tests in the previously-mentioned directory: soapisprimenumber.html and soapunscramble.html. - Adding services is as easy as writing functions in Javascript, Java, -or other supported languages and describing the deployment in XML.  Disclaimer: -as this is merely an end-subscriber DSL service, if the server becomes too -widely published, it may have to be shut down.
-
- Bugs should be reported as usual.
+ +

+ 0 Table of Contents

+
1 SOAP Services +
+
+ 2 SOAP Blocks +
+
2.1 Parameters +
+ 2.2 Header Blocks +
+ 2.3 Encodings +
+
+ 3 Using the Mozilla +Low-Level SOAP API +
+
3.1 Conventions Used +Below in +
+ 3.2 Basic Operations of SOAP +
+ 3.3 Beyond Basic Operations +
+ 3.4 Header Operations +
+ 3.5 Non-RPC Operations +
+ 3.6 SOAPBlock and +SOAPMessage Supertypes +
+ 3.7 More Operations +
+ 3.8 Using Schema Types +
+ 3.9 Customization of Encodings +
+ 3.10 Security Operations +
+
+ 4 Future Features +
+
4.1 Access to SOAP +as Proxies +
+ 4.2 Arbitrary Graphs of Data +
+ 4.3 SOAP With Attachments +
+ 4.4 New Transports +and Local Services +
+ 4.5 Standards +
+
+ 5 Samples and Testing +
+
+ 6 Object Interfaces +
+

+ 1 SOAP Services

+ There are a number of sources for services available on the web + being set up, such as the XMethods +website + which the Mozilla implementation has used for some tests and use +cases.  Apache also provides modules for SOAP that have been used to +author services for purposes of testing the Mozilla implementation (and +entertainment).  Once it is set up, it is as simple as writing +a service function in Javascript, Java, or any other of a number of supported +languages and then writing a service description in XML to deploy the service.  + There are toolkits available from Microsoft and other webserver providers + for authoring such services as well.
+ +

+ 2 SOAP Blocks

+ +

+ 2.1 Parameters
+

+ SOAP-based services exchange message envelopes which contain blocks + of XML data roughly corresponding to the parameters of a service call.  + When an rpc-style message is exchanged, blocks representing the regular + parameter blocks are placed inside an element which identifies the object + and method being invoked, which is placed inside the body.  In a +non-RPC message, the blocks are placed directly inside the body instead +of under the method element. 
+ +

+ 2.2 Header Blocks
+

+ If there are blocks which are optional or independently added or + processed, these are carried in the header with an assigned role and +marked if the recipient is required to understand them before trying to +process the message.
+ +

+ 2.3 Encodings
+

+ Interpretation of each block depends upon the encoding that was + used, which is clearly specified in the message.  If the standard + SOAP encoding is used, then XML Schema types control the interpretation + of the data within each block.
+ +

+ 3 Using the Mozilla Low-Level SOAP API

+ To use the low-level API, the user creates a SOAPCall object, +encodes the function call with a list of headers and regular parameters, +and invokes the call, which returns a response which contains the results +of the service call including a fault generated by the service which processed + the message if it failed, output parameters, and/or header blocks.  +If the call is invoked asynchronously, then a function is supplied by +the caller which receives the response when it arrives from the remote +service.
+
+ Besides Javascript, the below-described operations should also +generally work for other xpconnect-supported languages in Mozilla such +as C++/XPCOM and Python, because language-independent cross-platform +interfaces and architectures were used.
+ +

+ 3.1 Conventions Used Below in Descriptions of Operations
+

+ Names or descriptions in angle brackets represent values or objects + matching the name or description.  These may be literal, constructed + via "new", or variables.  Occasionally the same syntax may represent +script performing an operation.  Quoted angle brackets indicate a +character string of the described type.
+
+ So the following sample operation:
+ +
    +
  • <Foo> = new Foo( + <FooFact> );
    • +
  • <Foo>.bar = + <any value or object>;
    • +
  • <Baz> = + <Foo>.find("<name> + ");
    • +
  • <find out what you have>
    • + +
+ might be replaced in a real Javascript program:
+
+ var myFoo = new Foo(new FooFact("always","Great","Baz"));
+ myFoo.bar = 3.14159265;
+ var myGreatBaz = myFoo.find("Great");
+ if (checkBaz(myGreatBaz)) {
+   alert(myGreatBaz.description);
+ }
+
+ where "myFoo" is a variable holding an object of type Foo and myGreatBaz + is a variable holding an object of type Baz.
+ +

+ 3.2 Basic Operations of SOAP
+

+ The following basic SOAP operations is nearly all that most users +of SOAP need to do.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Basic Operation
+ 		How to Do It
+
Create a parameter block, setting the Javascript + value and name for rpc-style call.
+ 		+ +
    +
  • <SOAPParameter> + = new SOAPParameter(<any value or object> + , "<name>");
    • +
  •  // or
    • +
  • <SOAPParameter> + = new SOAPParameter();
    • +
  • <SOAPParameter> + .value = <any value or object> + ;
    • +
  • <SOAPParameter> + .name = "<name>";
    • + + +
+
Set parameters in a Javascript array.
+ 		+ +
    +
  • <SOAPParameter array> + = new Array(<SOAPParameter> + <,...>);
    • +
  • // or
    • +
  • <SOAPParameter array> + = new Array();
    • +
  • <SOAPParameter array> + [0] = <SOAPParameter> ;
    • +
  • <...>
    • + + +
+
Create and encode the parameters in a basic + SOAP 1.1 rpc-style message.
+ 		+ +
    +
  • <SOAPCall> + = new SOAPCall();
    • +
  • <SOAPCall> + .transportURI = "<http-based service URI> + "
    • +
  • <SOAPCall> + .encode(0, "<method name> ", +" <target object namespaceURI> + ", 0, null, <SOAPParameter array> + .length, <SOAPParameter array> + );
    • + + +
+
Invoke  call (send call message and + receive response message).
+ 		+ +
    +
  • <SOAPResponse> + = <SOAPCall>.invoke();
    • +
  • <process the response -- + see below>
    • +
  • // or
    • +
  • <SOAPCall> + .asyncInvoke( <SOAPResponseListener> + );
    • + + +
+
Handle completion of async SOAP call.
+ 		+ +
    +
  • function <SOAPResponseListener + name>(<SOAPResponse> + , <SOAPCall>, + <error>)
    • +
  • {
    • +
  •   if (error != 0) {
    • +
  •      <action + to be taken on failure to transport message>
    • +
  •   }
    • +
  •   <process the response + -- see below>
    • +
  • }
    • + + +
+
Get service's failure, if any.
+ 		+ +
    +
  • <SOAPFault> + = <SOAPResponse> + .fault;
    • +
  • if (<SOAPFault> + != null) {
    • +
  •   <namespace URI string> + = <SOAPFault> .faultNamespace;
    • +
  •   <name string> + = <SOAPFault> .faultCode;
    • +
  •   <summary string> + = <SOAPFault> .faultString;
    • +
  •   <actor URI string> + = <SOAPFault> .actorURI;
    • +
  •   <action to be taken + in case of fault>
    • +
  • }
    • + + +
+
Get returned parameters from rpc-style +response .
+ 		+ +
    +
  • <SOAPParameter array> + = <SOAPResponse> .getParameters(true, + {});
    • + + +
+
Process Javascript values, etc. of returned + parameters.
+ 		+ +
    +
  • for (i = 0; i != <SOAPParameter + array>.length; i++)
    • +
  • {
    • +
  •   <SOAPParameter> + = <SOAPParameter array> +[i];
    • +
  •   <value or object> + = <SOAPParameter> .value;
    • +
  •   <name string> + = <SOAPParameter> .name;
    • +
  •   <checking and processing + of result>
    • +
  • }
    • + + +
+
+ +

-

5 Object Interfaces

-
+

+ 3.3 Beyond Basic Operations
+

+ The above operations are what every user of the lowlevel SOAP toolkit + needs to invoke service requests and interpret the responses, as is easily + seen by looking at some of the samples (see +section 5 +).  The bulk of the operations that follow will be used less frequently, +but they need to be there for certain cases.  The casual reader may +wish to skip the remaining tables of operations in this section, or scan +for features of interest.
+ +

+ 3.4 Header Operations

+ The user can send or receive header blocks for information not carried in +the body of the message.  Sending and receiving header blocks is not +very different from sending and receiving parameters as described above.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Header Operation
+ 		How to Do It
+
Create a Header Block.
+ 		+ +
    +
  • <SOAPHeaderBlock> + = new SOAPHeaderBlock(<any value or object> + , "<name>", " + <namespaceURI> ");
    • +
  •  // or
    • +
  • <SOAPHeaderBlock> + = new SOAPHeaderBlock();
    • +
  • <SOAPHeaderBlock> + .value = <any value or object> + ;
    • +
  • <SOAPHeaderBlock> + .name = "<name> ";
    • +
  • <SOAPHeaderBlock> + .namespaceURI = "<namespaceURI> + ";
    • + + +
+
Establish non-default role of a header block +.
+ 		+ +
    +
  • <SOAPHeaderBlock> + .actorURI = "<actorURI> +";
    • +
  • <SOAPHeaderBlock> + .mustUnderstand = <true or false> + ;
    • + + +
+
Set header blocks in a Javascript array.
+ 		+ +
    +
  • <SOAPHeaderBlock array> + = new Array(<SOAPHeaderBlock> + <,...>);
    • +
  • // or
    • +
  • <SOAPHeaderBlock array> + = new Array();
    • +
  • <SOAPHeaderBlock array> + [0] = <SOAPHeaderBlock> +;
    • +
  • <...>
    • + + +
+
Encode the headers in a SOAP 1.1 rpc-style + message.
+ 		+ +
    +
  • <SOAPCall> + .encode(0, "<method name> ", +" <target object namespaceURI> + ", <SOAPHeaderBlock array> +.length, <SOAPHeaderBlock array> + , <SOAPParameter array> +.length, <SOAPParameter array> + );
    • + + +
+
Get returned headers.
+ 		+ +
    +
  • <SOAPHeaderBlock array> + = <SOAPResponse> .getHeaderBlocks(true, + {});
    • + + +
+
Process Javascript values, etc. of returned + headers.
+ 		+ +
    +
  • for (i = 0; i != <SOAPHeaderBlock + array>.length; i++)
    • +
  • {
    • +
  •   <SOAPHeaderBlock> + = <SOAPHeaderBlock array> + [i];
    • +
  •   <value or object> + = <SOAPHeaderBlock> .value;
    • +
  •   <name string> + = <SOAPHeaderBlock> .name;
    • +
  •   <namespace URI string> + = <SOAPHeaderBlock> .namespaceURI;
    • +
  •   <actor URI string> + = <SOAPHeaderBlock> .actorURI;
    • +
  •   <must understand +boolean> = <SOAPHeaderBlock> + .mustUnderstand;
    +
    • +
  •   <checking and processing + of result>
    • +
  • }
    • + + +
+
+ +

+ 3.5 Non-RPC Operations

+ For messages that are not intended to model RPC calls, there is +no method name or target object URI, and the parameters generally have +namespaceURIs.  Otherwise, the basic operations are the same.
+
+ + + + + + + + + + + + + + + + + + + + + +
Non-RPC Operation
+ 		How to Do It
+
Setting the namespaceURI of a non-RPC parameter +.
+ 		+ +
    +
  • <SOAPParameter> + = new SOAPHeaderBlock(<any value or object> + , "<name>", " + <namespaceURI> ");
    • +
  •  // or
    • +
  • <SOAPParameter> + .namespaceURI = "<namespaceURI> + ";
    • + + +
+
Encode a SOAP 1.1 non-rpc-style message.
+ 		+ +
    +
  • <SOAPCall> + .encode(0, "", "", <header block array> + .length, <header block array> + , <parameter array>.length, + <parameter array> + )
    • + + +
+
Get returned parameters from non-rpc-style + response.
+ 		+ +
    +
  • <SOAPParameter array> + = <SOAPResponse> .getParameters(false, + {});
    • + + +
+
+ +

+ 3.6 SOAPBlock and SOAPMessage Supertypes

+ In the following operations, SOAPHeaderBlock and SOAPParameter may be + referred to collectively as SOAPBlock objects.
+
+ Also, SOAPCall and SOAPResponse may be referred to collectively as SOAPMessage + objects.
+ +

+ 3.7 More Operations

+ The following table contains less-common operations.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Operation
+ 		How to Do It
+
Set or get an actionURI carried for the +message in the HTTP header.
+ 		+ +
    +
  • <SOAPMessage> + .actionURI = "<action URI> + ";
    • +
  • // or
    +
    • +
  • <action URI string> + = <SOAPMessage> .actionURI;
    +
    • + + +
+
Directly set the DOM element to represent + the block's encoded content, bypassing encoding of the value on the +block .
+ 		+ +
    +
  • <SOAPBlock> + .element = <DOM Element> ;
    +
    • + + +
+
+
Directly get the DOM element that represents + the block's encoded content, bypassing decoding of the value on the block +.
+ 		+ +
    +
  • <DOM Element> + = <SOAPBlock>.element;
    +
    • + + +
+
Directly get the DOM element containing +the SOAP envelope , header, or body of an encoded message.
+ 		+ +
    +
  • <DOM Element> + = <SOAPMessage> +.envelope;
    • +
  • // OR
    • +
  • <DOM Element> + = <SOAPMessage> +.header;
    • +
  • // or
    • +
  • <DOM Element> + = <SOAPMessage> +.body;
    +
    • + + +
+
Directly set the DOM document to represent + the message's entire encoded content, bypassing encoding.
+ 		+ +
    +
  • <SOAPMessage> + .message = <DOM Document> +;
    +
    • + + +
+
+
Directly get the DOM document of an encoded + message, bypassing encoding.
+ 		+ +
    +
  • <DOM Document> + = <SOAPMessage> +.message;
    +
    • + + +
+
+
Get the method name and target object URI, +if any, of the message.
+ 		+
    +
  • <method name string> + = <SOAPMessage> .methodName;
    • +
  • <object URI string> + = <SOAPMessage> .targetObjectURI;
    • -

    - - - - - +
+
Get the actual SOAP version of an encoded + message -- 0 for SOAP 1.1 and 1 for SOAP 1.2.
+ 		+ +
    +
  • <version integer> + = <SOAPMessage> .version;
    • + + +
+
Encode a SOAP 1.2 message.
+ 		+ +
    +
  • <SOAPCall> + .encode(1, "<method name> ", +" <target object namespaceURI> + ", <SOAPHeaderBlock array> +.length, <SOAPHeaderBlock array> + , <SOAPParameter array> +.length, <SOAPParameter array> + );
    • + + +
+
Abort an in-progress async call -- this +does not necessarily cause the message not to be processed, but the API +stops listening for it to complete.
+ 		+ +
    +
  • <SOAPCallCompletion> + = <SOAPCall> .asyncInvoke( + <SOAPResponseListener>);
    • +
  • <...>
    • +
  • <SOAPCallCompletion> + .abort();
    +
    • + + +
+
Get the encoding (style) used to encode +or decode message.  Not available on an unencoded call unless explicitly + set -- use following operation instead.
+ 		+ +
    +
  • <SOAPEncoding> + = <SOAPMessage> +.encoding;
    • + + +
+
Set the primary encoding style used to +encode a message.  A new SOAPEncoding objects (created by new) starts +a different set of associated encodings, which are only reached (or created) +in association by calling getAssociatedEncoding().
+ 		+ +
    +
  • <SOAPEncoding> + = new SOAPEncoding();
    • +
  • <SOAPEncoding> + = <SOAPEncoding> + .getAssociatedEncoding(" <style URI> + ",<true to create> );
    • +
  • <customize encodings>
    +
    • +
  • <SOAPMessage> + .encoding = <SOAPEncoding> + ;
    • + + +
+
Specify the encoding style used to encode + or decode specific blocks.
+ 		+ +
    +
  • <SOAPEncoding> + = <SOAPEncoding> + .getAssociatedEncoding(" <style URI> + ",<true to create> );
    • +
  • <SOAPBlock> + .encoding = <SOAPEncoding> +;
    • + + +
+
+ +

+ +

+ 3.8 Using Schema Types

+ The default SOAP encodings implement most XML built-in types, +as well as the basic SOAP types.  In the absence of a specified +type, native values and objects will typically be correctly identified +and mapped to a corresponding schema type.  There may be no perfect +correspondance between Javascript and XML Schema types, so they will be +mapped to a close corresponding type.
+
+ Providing specific schema types can help the encoding produce the desired +results.  For example, multidimensional arrays must be decoded as +nested arrays because Javascript only supports single-dimensional arrays. + If no schema type is given that identifies the array as multidimensional, + then a multidimensional array will be encoded as a nested array.  An + accurate schema type can also help when encoding or decoding of other +complex objects such as SOAP structs.
+
+ Schema types may be attached to blocks before encoding or before + accessing the value of a returned object to better control the encoding + and decoding.  All schema types which are used to control the encoding + and decoding should come from the schema collection available through + the encoding (associated encodings share the same collection).
+
+ + + + + + + + + + + + + + + + + + + + + +
Schema Operation
+ 		How to Do It
+
Get the schema collection of all associated + encodings.
+ 		+ +
    +
  • <SchemaCollection> + = <SOAPEncoding> .schemaCollection;
    • + + +
+
Load additional schema types from XML Schema + files into the schema collection.
+
+ 		+ +
    +
  • <SchemaLoader> + = <SchemaCollection> + ;
    • +
  • // and then
    +
    • +
  • <SchemaLoader> + .load(" <schema file URI> + ");
    • +
  • //  or
    +
    • +
  • <SchemaLoader> + .loadAsync(" <schemaURI> +", <load completion function> + );
    • + + +
+
Specify the XML Schema type to be used when + encoding or decoding a block.  Note: decoding a block occurs when +you get its value, so after getting a block from an XML-encoded message such +as a SOAPResponse, attaching type info affects evaluation of the value. + +
    +
  • <SchemaType> + = <SchemaCollection> + .getType(" <name> ", " + <namespaceURI> ");
    • +
  • if (<schemaType != null) + {
    +
    • +
  •   + <SOAPBlock> .schemaType = + <SchemaType> ;
    • +
  • }
    • +     + +
+
+ +

+ +

+ +

+ 3.9 Customization of Encodings

+ A specific encoding must have encoders and decoders to function. +  Encoding or decoding of data always begins with a default encoder + or decoder, which then may lookup additional encoders or decoders by +a string key as required.  For either the 1.1 or 1.2 version of +the default SOAP encoding, the default encoder and decoder use the schema +type's namespaceURI and name, seperated by "#" to look up additional decoders +for specific schema types.  Additional encoders and decoders registered + within the default encodings will automatically be invoked as an object + identified as the corresponding type is processed.  Other encodings + can use any scheme for looking up additional encoders and decoders, or +none at all if all the work is done by the default encoder and decoder +for that encoding.  Encodings which are registered with the system, +such as the default SOAP 1.1 or 1.2 encodings, automatically come with encoders +and decoders built-in, whereas new encodings have none.  Custom encodings + may also reuse existing encoders and decoders, but there is no guarantee + which are present, since the mapping may vary when handling an infinite +set of types with a finite set of encoders and decoders.
+
+ Also, there has been a proliferation of different schema URIs +to describe the same types, which may often even be intermixed in usage, but +expected to function properly.  Most notably, the SOAP 1.1 specification +used unofficial XML Schema URIs and SOAP encoding schema URIs not compatible + with those which are in the W3C XML Schema and drafts for SOAP 1.2 specifications. +  It is not uncommon to send and receive messages using the URIs +specified in the SOAP 1.1 specification, but described by WSDL using XML +Schema that uses the official, correct URIs.  To solve these problems, +the encoding permits schema URIs to be aliased, both on input and on +output, so that only the SOAP 1.2 and official XMLSchema types are used +internally, while supporting the other URIs.  Mappings of this type +are built-in for encodings which are registered with the system, such as +the default encodings of SOAP 1.1 and 1.2.  The default URI mappings +may be manipulated, for example, to output SOAP 1.1 but with the official +XML Schema URIs, without having to rewrite any encoders or decoders.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
Encoding Customization Operation
+ 		How to Do It
+
Create a custom encoder. + +
    +
  • function <New DOM Element> + = <SOAPEncoder name>( + <SOAPEncoding>, <value> + , <namespaceURI> , + <name>, <SchemaType> + , <SOAPAttachments> , + <Parent DOM Element> )
    • +
  • {
    • +
  • <...>
    +
    • +
  • <DOM Element> + = <Parent DOM Element> + .ownerDocument.createElementNS(namespaceURI,name);
    +
    • +
  • <...>
    +
    • +
  •   <Parent DOM Element> + .appendChild(<DOM Element> + );
    +
    • +
  •   return <DOM Element> + ;
    +
    • +
  • }
    • +
  • // and
    • +
  • <SOAPEncoding> + .defaultEncoder = <SOAPEncoder> + ;
    • +
  • // or
    • +
  • <SOAPEncoding> + .setEncoder(" <namespaceURI> + # <name> ", + <SOAPEncoder> );
    • + + +
+
+
Create a custom decoder.
+ 		+ +
    +
  • function <New DOM Element> + = <SOAPDecoder name>( + <SOAPEncoding>, <DOM +Element> , <SchemaType> + , <SOAPAttachments>)
    • +
  • {
    • +
  • <...>
    • +
  •   return <value or object> + ;
    +
    • +
  • }
    • +
  • // and
    • +
  • <SOAPEncoding> + .defaultDecoder = <SOAPDecoder> + ;
    • +
  • // or
    • +
  • <SOAPEncoding> + .setDecoder(" <namespaceURI> + # <name> ", + <SOAPDecoder> );
    • + + +
+
+
Map or unmap schema  URI aliases
+ 		+ +
    +
  • <SOAPEncoding> + .mapSchemaURI(" <external URI> + ", "<internal URI>", + <true to alias output> );
    • +
  • // or
    • +
  • <SOAPEncoding> + .unmapSchemaURI(" <external URI> + ");
    • + + +
+
Register modified or alternative encodings, + making them automatically available to all SOAP scripts in the system
+ 		Install an appropriate registerable encoding + in components/<new encoding> + .js
+
+ +

+ 3.10 Security Operations

+ In browsers, the risk of allowing an externally-loaded untrusted + script to request information within a firewall and send it elsewhere +has lead to very tight sandbox restrictions, permitting external browser +scripts to only request xml data and services on the same domain from +which the script was loaded.  This same restriction applies by default +to SOAP requests executed within the browser.  This means that an +externally-loaded script cannot, for example, call other external services +unless they are in the same domain from which the page was loaded.  Even +if the page was loaded from the user's own hard disk, the script must ask +for permission to make SOAP calls.  A browser enhancement is planned +to permit more-precise control of trust between scripts and specific available +services.
+
+ Since SOAP permits headers to be added to messages that require +interpretation by the recipient, this API can request a header to warn +the recipient that it was sent by an untrusted script loaded from a specific + sourceURI, and no good SOAP service will unintentionally disregard the warning. +  If the envelope is verified and the header is added, then the browser + can allow the script less-restricted access to services outside of its +source domain.  Accepting this header permits SOAP services that +really do want to be universally available to allow access without forcing +the user to risk breach of the firewall protections and/or request user +permission.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Security Operation
+ 		How to Do It
+
Mark the call with a verifySourceHeader +so, if the service permits it, the browser can make the call with less +privilege and risk.
+ 		+ +
    +
  • <SOAPCall> + .verifySourceHeader = true;
    • + + +
+
Request risky privileges within a local +or signed script to make an unverified SOAP calls to other domains.
+ 		+ +
    +
  • netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead")
    • + + +
+
Modify the security settings in the preferences + file, allowing scripts from some domain to make risky SOAP calls to +any other domain, which is disabled by default.Add the setting in default/pref/all.js + :
+ + +
    +
  • pref("<some domain prefix> + .SOAPCall.invoke","allAccess");
    • + + +
+
Modify the security settings in the preferences + file to disallow even dross-domain calls made with verifySource header, +which is generally permitted by default.
+ 		Remove or comment out the setting in +default/pref/all.js :
+ +
    +
  • pref("capability.policy.default.SOAPCall.invokeVerifySourceHeader","allAccess");
    • + +
+
Register alternative transport mechanisms, + making available alternative transports to all scripts and perhaps creating + alternative security models for protocols besides http(s).  See + +the futures section + for more info on possible transports.
+ 		Install an appropriate registerable encoding + in components/<new transport> + .js.
+
+ +

+ +

+ 4 Future Features

+ +

+ 4.1 Access to SOAP as Proxies

+ Although a SOAP call can generally be accomplished using this +low-level API in a few dozen lines, WSDL is a standard that contains +enough information to enable this to occur with no manual argument and +type setup required.  An implementation is under development that + instantiates web service proxies complete with appropriate xpconnect interfaces + by simply loading and using information out of a WSDL file that describes +the service.  The proxy's interface has dynamically-generated methods +named appropriately to match the services described in the WSDL file which +accept arguments of the appropriate data types and calls the appropriate + low-level SOAP functions with the appropriate type information, making +it even simpler not only to invoke services from Javascript code, but to +associate appropriate schema types loaded from the WSDL file with the arguments. + This higher level is not available in the first release.  When +it is available, invoking WSDL-described features gets even easier and more +reliable.
+ +

+ +

+ 4.2 Arbitrary Graphs of Data

+ The SOAP specification allows objects to be passed as arguments + which may have originally referenced other objects that are not owned + in a pure hierarchy.  This is represented by using an href attribute. +  Due to the problems with leaking reference counts in COM objects + with cyclic references, this has not been implemented yet.  Also, + the output of a cyclicly-referencing set of objects has not been implemented. +  Outgoing objects that do not reference cyclicly currently create + separate copies for each reference to an object, and with cycles output + may never complete.  On input, hrefs are currently ignored.  In + the future it may be possible to solve this and transmit and receive arbitrarily-referencing + objects, but the solution is more complex than just using weak references.
+ +

+ 4.3 SOAP With Attachments

+ Many clients and servers now support automatically transmitting + large Mime with a SOAP message by encapsulating it in MIME, DIME, or +other enveloping formats.  This has been anticipated in the APIs, +but the SOAPAttachments API is currently a placeholder for this future +feature which is not yet implemented.
+ +

+ 4.4 New Transports and Local Services

+ Obvious new transports that would be useful include e-mail -- permitting + a SOAP exchange to occur as an email exchange --, instant messenger for + peer to peer, and a local manager with a controlled security model but +without the size limitations, enabling SOAP to save and restore arbitrary +Javascript application data on the client.  These services require +a framework, already being planned, for permitting the browser to host +services as well as being a good client.  There are obviously security +issues to be solved to make these successful.
+ +

+ 4.5 Standards

+ The interfaces to the objects of this API were designed to be as simple + and universal as possible.  We believe that we should submit a note + describing them and sponser a W3C proposal to standardize an API for invoking + this type of service from web clients.  In such an effort, changes +would be inevitable and welcomed as the price for interoperability within +web clients.  Part of this API are incomplete, specifically the SOAPAttachments + object, which will be defined to allow encoders and decoders to control +uniqueness and referencing, both for resolving arbitrary graphs of data +(as described above in "Arbitrary Graphs of Data") as well as for automatically +resolving references to attached objects carried with the message in an +external encapsulation (as described above in "SOAP With Attachments").
+ +

+ 5 Samples and Testing

+ Some samples or tests have been created, but these commonly only use + the basic operations.  Some of the higher-level features are being + tested by the prosy code (as described above in "Access to SOAP as Proxies"). +  While most of the methods of this API are well-exercized internally + during even basic invocation, we need samples that test and demonstrate +external access to the functions.  What exists today is mozilla/extensions/xmlextras/tests + /soap*.html.  We welcome the contribution of tests by other parties. +  Most samples work but at least one (soapcall.html) is no longer correctly + configured to talk to a server -- but it genrates interesting messages +anyway.
+
+ To test the services, it is currently required to compile Mozilla with + the environment variable MOZ_SOAP=1 (if you already have a build, you only + need to do a clean rebuild of the xmlextras directory).  It is also + interesting to turn on MOZ_DEBUG=1, because even if you do not debug the + program, this causes the exchanged SOAP messages to be displayed on the +standard output if you run from a command shell where this is visible.
+
+ A SOAP service server has been set up at ray.dsl.xmission.com where + additional services may be deployed to help test and demo the features +for scripting SOAP in Mozilla.  No home page describes the Apache +Jakarta server on port 8080 which is the test facility, but this is currently +used in two tests in the previously-mentioned directory: soapisprimenumber.html + and soapunscramble.html.  Adding services is as easy as writing functions + in Javascript, Java, or other supported languages and describing the deployment + in XML.  Disclaimer: as this is merely an end-subscriber DSL service, + if the server becomes too widely published, it may have to be shut down.
+
+ Bugs should be reported as usual.
+ +

+ 6 Object Interfaces

+
+ +

+
+
+ + +