diff --git a/extensions/webservices/docs/Soap_Scripts_in_Mozilla.html b/extensions/webservices/docs/Soap_Scripts_in_Mozilla.html index 0bdb8b1be8c..f702f9b18d7 100644 --- a/extensions/webservices/docs/Soap_Scripts_in_Mozilla.html +++ b/extensions/webservices/docs/Soap_Scripts_in_Mozilla.html @@ -1,276 +1,415 @@ - + 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.  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 tight binding to the natural data of Javascript so that the script -can simply use the data instead of tediously encoding and extracting the -data from the XML.
- + +
Microsoft and others have advocated + SOAP as a way to encode and exchange public data structures between agents + on the web.  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 tight binding +to the natural data of Javascript so that the script can simply use the +data instead of tediously encoding and extracting the data from the XML.
+

SOAP Services

- There are a number of sources for services available on the web being - set up, such as XMethods. Apache supports modules for SOAP that this author - has used to author services for purposes of testing 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 + There are a number of sources for services available on the web being + set up, such as XMethods. Apache supports modules for SOAP that this author + has used to author services for purposes of testing 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.
- +

SOAP Blocks

- +

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 + + 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. 
- +

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.
- + + 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.
+

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 the data within + + 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 the data within each block.
- +

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 + 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.
- -

Conventions
-

- Names or short description in angle brackets represent values or objects - of the named type which may be literal, constructed via "new", or a variable. -  Occasionally the same syntax with a longer description represents script - performing an operation.  Quoted angle brackets indicate a string of - the described form.
-
- 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.
-

Basic Operations
+

Conventions

- For basic SOAP operations is all most users need to do.
+ Names or short description in angle brackets represent values or objects + of the named type which may be literal, constructed via "new", or a variable. +  Occasionally the same syntax with a longer description represents +script performing an operation.  Quoted angle brackets indicate a string +of the described form.
+
+ 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.
+ +

Basic Operations
+

+ 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(<SOAPPerameter> [,...]);
    • +
  • // 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>
    • +
  • }
    • + +
+
+ +

+ 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 much less frequently, but they need to be there +for  cases where they are needed.  The casual reader may skip the +remaining tables of operations in this section, or scan for features of interest.
+ +

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.

- - - - - - - + + + + - - - - - - - - - - - - - - - - @@ -278,735 +417,280 @@ of result>
Basic Operation
+ 		Header Operation
 How to Do It
Create a parameter block, setting the Javascript - value and name for rpc-style call
+ 		Create a Header Block
 +
    -
  • <SOAPParameter> -= new SOAPParameter(<any value or object> -, "<name>");
    • -
  •  // or
    • -
  • <SOAPParameter> -= new SOAPParameter();
    • -
  • <SOAPParameter>.value -= <any value or object> ;
    • -
  • <SOAPParameter> -.name = "<name>";
    • - +
  • <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> + ";
    • +
Set parameters in a Javascript array
+ 		Establish non-default role of a header block
 +
    -
  • <SOAPParameter array> - = new Array(<SOAPPerameter> [,...]);
    • -
  • // or
    • -
  • <SOAPParameter array> - = new Array();
    • -
  • <SOAPParameter array> -[0] = <SOAPParameter> ;
    • -
  • [...]
    • - +
  • <SOAPHeaderBlock> + .actorURI = "<actorURI> ";
    • +
  • <SOAPHeaderBlock> + .mustUnderstand = <true or false> + ;
    • +
Create and encode the parameters in a basic SOAP - 1.1 rpc-style message
+ 		Set header blocks in a Javascript array
 +
    -
  • <SOAPCall> = new -SOAPCall();
    • -
  • <SOAPCall>.transportURI -= "<http-based service URI>"
    • -
  • <SOAPCall>.encode(0, +
  • <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>", 0, null, -<SOAPParameter array> .length, -<SOAPParameter array>);
    • - + <service namespace>", <SOAPHeaderBlock +array> .length, <SOAPHeaderBlock + array>, <SOAPParameter array> + .length, <SOAPParameter array> + ); +
Invoke  call (send call message and receive - response message)
+ 		Get returned headers
 +
    -
  • <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, +
  • <SOAPHeaderBlock array> + = <SOAPResponse> .getHeaderBlocks(true, {});
    • - +
Process Javascript values, etc. of returned parameters
+ 		Process Javascript values, etc. of returned headers
 +
    -
  • for (i = 0; i != <SOAPParameter +
  • for (i = 0; i != <SOAPHeaderBlock array>.length; i++)
    • -
  • {
    • -
  •   <SOAPParameter> - = <SOAPParameter array>[i];
    • -
  •   <value or object> - = <SOAPParameter> .value;
    • -
  •   <name string> - = <SOAPParameter> .name;
    • -
  •   <checking and processing +
  • {
    • +
  •   <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>
    • -
  • }
    • - +
  • }
    • +
-

- 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 much less frequently, but they need to -be there for  cases where they are needed.  The casual reader may -skip the remaining tables of operations in this section, or scan for features -of interest.
-

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>
    • -
  • }
    • - -
-
-

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. + 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, - {});
    • - -
-
- -

SOAP Supertypes

-Header blocks and rpc-style and non-rpc-style parameters are similar.  In -the following sections, these will usually be referred to collectively as -SOAPBlock objects..
-
-SOAPCall and SOAPResponse objects are also fairly similar as messages consisting -of blocks.  In the following sections, calls and responses will usually -be referred to collectively as SOAPMessage objects.
- -

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> ;
    • - -
-
- -

- -

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> ;
    • -
  • }
    • -     -
-
- -

- -

- -

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 may be automatically 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
-
- -

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.
+ 		Non-RPC Operation
 + How to Do It
+
Setting the namespaceURI of a non-RPC parameter
+
    -
  • <SOAPCall>.verifySourceHeader -= true;
    • - +
  • <SOAPParameter> + = new SOAPHeaderBlock(<any value or object> + , "<name>", " + <namespaceURI> ");
    • +
  •  // or
    • +
  • <SOAPParameter> +.namespaceURI = "<namespaceURI> + ";
    • +
Request risky privileges within a local or signed - script to make an unverified SOAP calls to other domains.
+ 		Encode a SOAP 1.1 non-rpc-style message
 +
    -
  • netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead")
    • - +
  • <SOAPCall>.encode(0, +"", "", <header block array>.length, + <header block array>, + <parameter array>.length, <parameter + array>)
    • +
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 - :
- + 		Get returned parameters from non-rpc-style response
+
    -
  • pref("<some domain prefix> -.SOAPCall.invoke","allAccess");
    • - +
  • <SOAPParameter array> + = <SOAPResponse> .getParameters(false, + {});
    • + +
+
+ +

SOAP Supertypes

+ Header blocks and rpc-style and non-rpc-style parameters are similar.  In +the following sections, these will usually be referred to collectively as +SOAPBlock objects..
+
+ SOAPCall and SOAPResponse objects are also fairly similar as messages consisting +of blocks.  In the following sections, calls and responses will usually +be referred to collectively as SOAPMessage objects.
+ +

More Operations

+ The following table contains less-common operations.
+
+ + + + + + + + + + - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -1014,85 +698,422 @@ security models for protocols besides http(s).
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;
    +
    • +
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).
+ 		Directly set the DOM element to represent the +block's encoded content, bypassing encoding of the value on the block
Install an appropriate registerable encoding in - components/<new transport> -.js.
+ 		+
    +
  • <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> ;
    • + +

- + +

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> + ;
    • +
  • }
    • +     +
+
+ +

+ +

+ +

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 may be automatically +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
+
+ +

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.
+
+ +

+

Future Features

- +

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 describes how all of -this could occur with no manual type and argument 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.  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.
- + Although a SOAP call can generally be accomplished using this low-level +API in a few dozen lines, WSDL is a standard that describes how all of +this could occur with no manual type and argument 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.  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.
+

- +

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.
- + 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.
+

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 + 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.
- +

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.
+ 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.
+

Standards

-The interfaces to the objects of this API were designed to be as simple and -universal as possible.  We believe that we should sponser a W3C proposal -to standardize an API for invoking this type of service from web clients. - We recognize that in such an effort, changes would be inevitable and -welcomed.  Certain parts of the API are incomplete, especially the SOAPAttachments -object, which will serve to allow encoders and decoders to control uniqueness -and referencing both for resolving arbitrary graphs of data (when that is -implemented) as well as references to attached objects carried with the message -in an external encapsulation such as MIME or DIME (when that is implemented).
- + The interfaces to the objects of this API were designed to be as simple +and universal as possible.  We believe that we should sponser a W3C +proposal to standardize an API for invoking this type of service from web +clients.  We recognize that in such an effort, changes would be inevitable +and welcomed.  Certain parts of the API are incomplete, especially the +SOAPAttachments object, which will serve to allow encoders and decoders to +control uniqueness and referencing both for resolving arbitrary graphs of +data (when that is implemented) as well as references to attached objects +carried with the message in an external encapsulation such as MIME or DIME +(when that is implemented).
+

Samples and Tests

-Some samples or tests have been created, but these commonly only test the -basic operations.  Most work but a few still predate the current SOAP -interfaces, and are located within the mozilla/extensions/xmlextras/tests -directory of the mozilla build.  We welcome the contribution of tests + Some samples or tests have been created, but these commonly only use the +basic operations.  While most of the methods are exercized internally +during even basic invocation, we need samples that show and test external +access to the functions.  Most samples work but a few still predate +the current SOAP interfaces.  They are located within the mozilla/extensions/xmlextras/tests +directory of the mozilla build.  We welcome the contribution of tests by other parties.
-
-A test server has been set up outside the firewall at ray.dsl.xmission.com -where services may be deployed to help test and demo the features for scripting +
+ A test server has been set up outside the firewall at ray.dsl.xmission.com +where services may be deployed to help test and demo the features for scripting SOAP in Mozilla.  This is a Tomcat server running the Apache SOAP code.
-
-Bugs should be reported as usual for the mozilla or derived product you are -using.
+
+ Bugs should be reported as usual for the mozilla or derived product you +are using.
+

Object Interfaces

-
+
+

-
-
- +
+
+ diff --git a/extensions/xmlextras/docs/Soap_Scripts_in_Mozilla.html b/extensions/xmlextras/docs/Soap_Scripts_in_Mozilla.html index 0bdb8b1be8c..f702f9b18d7 100644 --- a/extensions/xmlextras/docs/Soap_Scripts_in_Mozilla.html +++ b/extensions/xmlextras/docs/Soap_Scripts_in_Mozilla.html @@ -1,276 +1,415 @@ - + 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.  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 tight binding to the natural data of Javascript so that the script -can simply use the data instead of tediously encoding and extracting the -data from the XML.
- + +
Microsoft and others have advocated + SOAP as a way to encode and exchange public data structures between agents + on the web.  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 tight binding +to the natural data of Javascript so that the script can simply use the +data instead of tediously encoding and extracting the data from the XML.
+

SOAP Services

- There are a number of sources for services available on the web being - set up, such as XMethods. Apache supports modules for SOAP that this author - has used to author services for purposes of testing 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 + There are a number of sources for services available on the web being + set up, such as XMethods. Apache supports modules for SOAP that this author + has used to author services for purposes of testing 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.
- +

SOAP Blocks

- +

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 + + 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. 
- +

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.
- + + 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.
+

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 the data within + + 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 the data within each block.
- +

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 + 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.
- -

Conventions
-

- Names or short description in angle brackets represent values or objects - of the named type which may be literal, constructed via "new", or a variable. -  Occasionally the same syntax with a longer description represents script - performing an operation.  Quoted angle brackets indicate a string of - the described form.
-
- 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.
-

Basic Operations
+

Conventions

- For basic SOAP operations is all most users need to do.
+ Names or short description in angle brackets represent values or objects + of the named type which may be literal, constructed via "new", or a variable. +  Occasionally the same syntax with a longer description represents +script performing an operation.  Quoted angle brackets indicate a string +of the described form.
+
+ 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.
+ +

Basic Operations
+

+ 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(<SOAPPerameter> [,...]);
    • +
  • // 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>
    • +
  • }
    • + +
+
+ +

+ 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 much less frequently, but they need to be there +for  cases where they are needed.  The casual reader may skip the +remaining tables of operations in this section, or scan for features of interest.
+ +

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.

- - - - - - - + + + + - - - - - - - - - - - - - - - - @@ -278,735 +417,280 @@ of result>
Basic Operation
+ 		Header Operation
 How to Do It
Create a parameter block, setting the Javascript - value and name for rpc-style call
+ 		Create a Header Block
 +
    -
  • <SOAPParameter> -= new SOAPParameter(<any value or object> -, "<name>");
    • -
  •  // or
    • -
  • <SOAPParameter> -= new SOAPParameter();
    • -
  • <SOAPParameter>.value -= <any value or object> ;
    • -
  • <SOAPParameter> -.name = "<name>";
    • - +
  • <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> + ";
    • +
Set parameters in a Javascript array
+ 		Establish non-default role of a header block
 +
    -
  • <SOAPParameter array> - = new Array(<SOAPPerameter> [,...]);
    • -
  • // or
    • -
  • <SOAPParameter array> - = new Array();
    • -
  • <SOAPParameter array> -[0] = <SOAPParameter> ;
    • -
  • [...]
    • - +
  • <SOAPHeaderBlock> + .actorURI = "<actorURI> ";
    • +
  • <SOAPHeaderBlock> + .mustUnderstand = <true or false> + ;
    • +
Create and encode the parameters in a basic SOAP - 1.1 rpc-style message
+ 		Set header blocks in a Javascript array
 +
    -
  • <SOAPCall> = new -SOAPCall();
    • -
  • <SOAPCall>.transportURI -= "<http-based service URI>"
    • -
  • <SOAPCall>.encode(0, +
  • <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>", 0, null, -<SOAPParameter array> .length, -<SOAPParameter array>);
    • - + <service namespace>", <SOAPHeaderBlock +array> .length, <SOAPHeaderBlock + array>, <SOAPParameter array> + .length, <SOAPParameter array> + ); +
Invoke  call (send call message and receive - response message)
+ 		Get returned headers
 +
    -
  • <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, +
  • <SOAPHeaderBlock array> + = <SOAPResponse> .getHeaderBlocks(true, {});
    • - +
Process Javascript values, etc. of returned parameters
+ 		Process Javascript values, etc. of returned headers
 +
    -
  • for (i = 0; i != <SOAPParameter +
  • for (i = 0; i != <SOAPHeaderBlock array>.length; i++)
    • -
  • {
    • -
  •   <SOAPParameter> - = <SOAPParameter array>[i];
    • -
  •   <value or object> - = <SOAPParameter> .value;
    • -
  •   <name string> - = <SOAPParameter> .name;
    • -
  •   <checking and processing +
  • {
    • +
  •   <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>
    • -
  • }
    • - +
  • }
    • +
-

- 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 much less frequently, but they need to -be there for  cases where they are needed.  The casual reader may -skip the remaining tables of operations in this section, or scan for features -of interest.
-

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>
    • -
  • }
    • - -
-
-

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. + 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, - {});
    • - -
-
- -

SOAP Supertypes

-Header blocks and rpc-style and non-rpc-style parameters are similar.  In -the following sections, these will usually be referred to collectively as -SOAPBlock objects..
-
-SOAPCall and SOAPResponse objects are also fairly similar as messages consisting -of blocks.  In the following sections, calls and responses will usually -be referred to collectively as SOAPMessage objects.
- -

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> ;
    • - -
-
- -

- -

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> ;
    • -
  • }
    • -     -
-
- -

- -

- -

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 may be automatically 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
-
- -

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.
+ 		Non-RPC Operation
 + How to Do It
+
Setting the namespaceURI of a non-RPC parameter
+
    -
  • <SOAPCall>.verifySourceHeader -= true;
    • - +
  • <SOAPParameter> + = new SOAPHeaderBlock(<any value or object> + , "<name>", " + <namespaceURI> ");
    • +
  •  // or
    • +
  • <SOAPParameter> +.namespaceURI = "<namespaceURI> + ";
    • +
Request risky privileges within a local or signed - script to make an unverified SOAP calls to other domains.
+ 		Encode a SOAP 1.1 non-rpc-style message
 +
    -
  • netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead")
    • - +
  • <SOAPCall>.encode(0, +"", "", <header block array>.length, + <header block array>, + <parameter array>.length, <parameter + array>)
    • +
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 - :
- + 		Get returned parameters from non-rpc-style response
+
    -
  • pref("<some domain prefix> -.SOAPCall.invoke","allAccess");
    • - +
  • <SOAPParameter array> + = <SOAPResponse> .getParameters(false, + {});
    • + +
+
+ +

SOAP Supertypes

+ Header blocks and rpc-style and non-rpc-style parameters are similar.  In +the following sections, these will usually be referred to collectively as +SOAPBlock objects..
+
+ SOAPCall and SOAPResponse objects are also fairly similar as messages consisting +of blocks.  In the following sections, calls and responses will usually +be referred to collectively as SOAPMessage objects.
+ +

More Operations

+ The following table contains less-common operations.
+
+ + + + + + + + + + - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -1014,85 +698,422 @@ security models for protocols besides http(s).
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;
    +
    • +
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).
+ 		Directly set the DOM element to represent the +block's encoded content, bypassing encoding of the value on the block
Install an appropriate registerable encoding in - components/<new transport> -.js.
+ 		+
    +
  • <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> ;
    • + +

- + +

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> + ;
    • +
  • }
    • +     +
+
+ +

+ +

+ +

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 may be automatically +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
+
+ +

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.
+
+ +

+

Future Features

- +

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 describes how all of -this could occur with no manual type and argument 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.  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.
- + Although a SOAP call can generally be accomplished using this low-level +API in a few dozen lines, WSDL is a standard that describes how all of +this could occur with no manual type and argument 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.  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.
+

- +

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.
- + 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.
+

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 + 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.
- +

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.
+ 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.
+

Standards

-The interfaces to the objects of this API were designed to be as simple and -universal as possible.  We believe that we should sponser a W3C proposal -to standardize an API for invoking this type of service from web clients. - We recognize that in such an effort, changes would be inevitable and -welcomed.  Certain parts of the API are incomplete, especially the SOAPAttachments -object, which will serve to allow encoders and decoders to control uniqueness -and referencing both for resolving arbitrary graphs of data (when that is -implemented) as well as references to attached objects carried with the message -in an external encapsulation such as MIME or DIME (when that is implemented).
- + The interfaces to the objects of this API were designed to be as simple +and universal as possible.  We believe that we should sponser a W3C +proposal to standardize an API for invoking this type of service from web +clients.  We recognize that in such an effort, changes would be inevitable +and welcomed.  Certain parts of the API are incomplete, especially the +SOAPAttachments object, which will serve to allow encoders and decoders to +control uniqueness and referencing both for resolving arbitrary graphs of +data (when that is implemented) as well as references to attached objects +carried with the message in an external encapsulation such as MIME or DIME +(when that is implemented).
+

Samples and Tests

-Some samples or tests have been created, but these commonly only test the -basic operations.  Most work but a few still predate the current SOAP -interfaces, and are located within the mozilla/extensions/xmlextras/tests -directory of the mozilla build.  We welcome the contribution of tests + Some samples or tests have been created, but these commonly only use the +basic operations.  While most of the methods are exercized internally +during even basic invocation, we need samples that show and test external +access to the functions.  Most samples work but a few still predate +the current SOAP interfaces.  They are located within the mozilla/extensions/xmlextras/tests +directory of the mozilla build.  We welcome the contribution of tests by other parties.
-
-A test server has been set up outside the firewall at ray.dsl.xmission.com -where services may be deployed to help test and demo the features for scripting +
+ A test server has been set up outside the firewall at ray.dsl.xmission.com +where services may be deployed to help test and demo the features for scripting SOAP in Mozilla.  This is a Tomcat server running the Apache SOAP code.
-
-Bugs should be reported as usual for the mozilla or derived product you are -using.
+
+ Bugs should be reported as usual for the mozilla or derived product you +are using.
+

Object Interfaces

-
+
+

-
-
- +
+
+