Microsoft and others have advocated
       SOAP as a way to encode and exchange public data structures between
 agents      on the web, which is now becoming a web standard at W3C (see
the multiple  submissions and working documents related to SOAP in the list
of    W3C current drafts
      ).  
      
      The browser client is the most universal web agent in   existence,
 and   Javascript is the standard, interoperable way of scripting   browsers.  
   Scriptable SOAP in browsers gives clients and servers more   to say to 
each   other through existing http-xml request services, providing scripts 
  with persistence,  database, and access to other web services not tied to
  the request and response  cycles of the HTML-based user interface.  
 Web data structures, exchanged  in a platform-neutral way, should become 
as fundamental to web agents as web content is today.  The key to this 
is a very natural binding to the data of Javascript so that the script can 
simply use the data instead  of tediously encoding and extracting the data 
from the XML.
    
       
    0 Table of Contents
     
  1 SOAP Services
    
     
     2 SOAP Blocks
    
           
  2.1 Parameters
    
       2.2 Header Blocks
    
       2.3 Encodings
    
       
       3 Using the Mozilla 
 Low-Level SOAP API
    
                 
    3.1 Conventions
Used Below in
    
         3.2 Basic Operations of
SOAP
    
         3.3 Beyond Basic Operations
    
         3.4 Header Operations
    
         3.5 Non-RPC Operations
    
         3.6 SOAPBlock
 and SOAPMessage Supertypes
    
         3.7 More Operations
    
         3.8 Using Schema Types
    
         3.9 Customization of Encodings
    
         3.10 Security Operations
    
         
         4 Future Features
    
                       
      4.1 Access to
SOAP as Proxies
    
           4.2 Arbitrary Graphs of
 Data
    
           4.3 SOAP With Attachments
    
           4.4 New Transports 
 and Local Services
    
           4.5 Standards
    
           
           5 Samples and Testing
    
           
           6 Object Interfaces
                        
                             
        
    1 SOAP Services
               There are a number of sources for services available on the
 web   being    set  up, such as the 
XMethods
  website
         which the Mozilla implementation has used for some tests and use 
  cases.  Apache also provides modules for SOAP that have been used to
 author   services for purposes of testing the Mozilla implementation (and
 entertainment).       Once it is set up, it is as simple as writing 
a service function in Javascript,    Java,  or any other of a number of supported 
 languages and then writing  a  service description in XML to deploy the service. 
    There are toolkits available from Microsoft and other webserver providers
     for authoring such services as well.
                                                   
        
    2 SOAP Blocks
                                                   
        
    2.1 Parameters
              
              SOAP-based services exchange message envelopes which contain
 blocks    of  XML  data roughly corresponding to the parameters of a service
 call.       When  an rpc-style message is exchanged, blocks representing
 the regular     parameter  blocks are placed inside an element which identifies
 the object     and method  being invoked, which is placed inside the body.
  In a  non-RPC   message,  the blocks are placed directly inside the
 body instead  of under   the method  element.  
                                                   
        
    2.2 Header Blocks
              
             If there are blocks which are optional or independently added
 or  processed,     these are carried in the header with an assigned role
and marked if the   recipient  is required to understand them before trying
to process the message.
                                                   
        
    2.3 Encodings
              
              Interpretation of each block depends upon the encoding that 
was   used,    which  is clearly specified in the message.  If the standard 
  SOAP encoding   is used, then XML Schema types control the interpretation 
  of the data within   each block.
                                                   
        
    3 Using the Mozilla Low-Level SOAP API
              To use the low-level API, the user creates a SOAPCall object, 
 encodes     the   function call with a list of headers and regular parameters, 
 and  invokes    the call, which returns a response which contains the results 
 of the service    call including a fault generated by the service which processed
  the message if it failed,    output parameters, and/or header blocks. 
 If the call is invoked asynchronously,     then a function is supplied by
 the caller which receives the response when it arrives from     the remote
 service.
              
              Besides Javascript, the below-described operations should also
  generally      work for other xpconnect-supported languages in Mozilla
such   as C++/XPCOM      and Python, because language-independent cross-platform
  interfaces and architectures were    used.
                                                 
        
    3.1 Conventions Used Below in Descriptions of Operations
             
             Names or descriptions in angle brackets represent values or
objects      matching the name or description.  These may be literal,
constructed     via "new", or variables.    Occasionally the same syntax
may represent   script  performing an operation.  Quoted   angle brackets
indicate a  character string of  the described type.
             
             So the following sample operation:
                                                 
        
               - <Foo> = new
Foo(          <FooFact> );
- <Foo>.bar =
                      <any value or object>
;
- <Baz> = 
          <Foo>.find("<name>
           ");
- <find out what you have>
             might be replaced in a real Javascript program:
             
             
var myFoo = new Foo(new FooFact("always","Great","Baz"));
             myFoo.bar = 3.14159265;
             var myGreatBaz = myFoo.find("Great");
             if (checkBaz(myGreatBaz)) {
               alert(myGreatBaz.description);
             }
             
             where "myFoo" is a variable holding an object of type Foo and
 myGreatBaz      is a variable holding an object of type Baz.
                                                   
        
    3.2 Basic Operations of SOAP
              
              The following basic SOAP operations is nearly all that most 
users  of SOAP need to do.
              
                                                   
        
                
                  
                    | Basic Operation 
 | How to Do It 
 | 
                  
                    | Create a parameter block, setting the
 Javascript      value and name for rpc-style call. 
 | 
                     <SOAPParameter>
          = new SOAPParameter(<any value or object>
          ,  "<name>");  // or <SOAPParameter>
          = new SOAPParameter();<SOAPParameter>
         .value = <any value or object>
         ; <SOAPParameter>
          .name = "<name>"; | 
                  
                    | Set parameters in a Javascript array. 
 | 
                     <SOAPParameter array>
           = new Array(<SOAPParameter>
     <,...>); // or<SOAPParameter array>
           = new Array();<SOAPParameter array>
          [0] = <SOAPParameter>
 ;<...> | 
                  
                    | Create and encode the parameters in
a  basic    SOAP   1.1 rpc-style message. 
 | 
                     <SOAPCall>
     =  new  SOAPCall();<SOAPCall>
    .transportURI    = "<http-based service URI>
    "<SOAPCall>
    .encode(0,    "<method name>
  ",  "      <target object  namespaceURI>
    ", 0, null,       <SOAPParameter array>
     .length,       <SOAPParameter  array>
    ); | 
                  
                    | Invoke  call (send call message 
and   receive     response message). 
 | 
                     <SOAPResponse>
         =           <SOAPCall>
.invoke();<process the response
 --  see   below> // or <SOAPCall>
     .asyncInvoke(     <SOAPResponseListener>
      ); | 
                  
                   | Handle completion of async SOAP call. 
 | 
                     function <SOAPResponseListener
     name>(<SOAPResponse>
           , <SOAPCall>, 
          <error>){  if (error != 0) {     <action
    to  be taken on failure to transport  message>  }  <process the
response     -- see below>} | 
                 
                    | Get service's failure, if any. 
 | 
                     <SOAPFault>
      =              <SOAPResponse>
    .fault;if (<SOAPFault>
          != null) {  <namespace URI
 string>         = <SOAPFault>
   .faultNamespace;  <name string>
           = <SOAPFault> .faultCode;  <summary string>
           = <SOAPFault> .faultString;  <actor URI string>
           = <SOAPFault> .actorURI;  <action to be 
taken    in  case of fault>} | 
                  
                    | Get returned parameters from rpc-style 
 response . 
 | 
                     <SOAPParameter array>
           = <SOAPResponse> .getParameters(true,
      {}); | 
                  
                    | Process Javascript values, etc. of returned
    parameters. 
 | 
                     for (i = 0; i != <SOAPParameter
     array>.length; i++){  <SOAPParameter>
           = <SOAPParameter array>
   [i];  <value or object>
           = <SOAPParameter> .value;  <name string>
           = <SOAPParameter> .name;  <checking and 
processing     of result>} | 
                                                                        
      
                                                
        
                                                   
        
                                     
        
    3.3 Beyond Basic Operations
       
       The above operations are what every user of the lowlevel SOAP toolkit
   needs  to invoke service requests and interpret the responses, as is easily 
   seen  by looking at some of the samples (see 
   section 5
   ).  The bulk of the operations that follow will be used less frequently, 
 but they need to be there for certain cases.  The casual reader may 
wish to  skip the remaining tables of operations in this section, or scan 
for features   of interest.
                                           
        
    3.4 Header Operations
    The user can send or receive header blocks for information not carried
 in  the body of the message.     Sending and receiving header blocks
 is not very different from sending    and receiving parameters as described
 above.
             
                                                 
        
               
                 
                   | Header Operation 
 | How to Do It 
 | 
                 
                   | Create a Header Block. 
 | 
                     <SOAPHeaderBlock>
           = new SOAPHeaderBlock(<any value or
 object>        , "<name>
  ", "        <namespaceURI> ");   // or  <SOAPHeaderBlock>
           = new SOAPHeaderBlock(); <SOAPHeaderBlock>
          .value = <any value or object>
         ;  <SOAPHeaderBlock>
          .name = "<name> ";  <SOAPHeaderBlock>
          .namespaceURI = "<namespaceURI>
           "; | 
                 
                   | Establish non-default role of a header
 block  . 
 | 
                     <SOAPHeaderBlock>
          .actorURI = "<actorURI>
   ";<SOAPHeaderBlock>
          .mustUnderstand = <true or false>
          ; | 
                 
                   | Set header blocks in a Javascript array. 
 | 
                     <SOAPHeaderBlock array>
           = new Array(<SOAPHeaderBlock>
          <,...>);  // or <SOAPHeaderBlock array>
           = new Array(); <SOAPHeaderBlock array>
          [0] = <SOAPHeaderBlock>
   ; <...> | 
                 
                   | Encode the headers in a SOAP 1.1 rpc-style
   message. 
 | 
                     <SOAPCall>
    .encode(0,    "<method name>
  ",  "      <target object  namespaceURI>
    ", <SOAPHeaderBlock    array>
   .length,           <SOAPHeaderBlock     array>
    , <SOAPParameter array>   
   .length,           <SOAPParameter array>
          ); | 
                 
                   | Get returned headers. 
 | 
                     <SOAPHeaderBlock array>
           = <SOAPResponse> .getHeaderBlocks(true,
      {}); | 
                 
                   | Process Javascript values, etc. of returned 
   headers. 
 | 
                     for (i = 0; i != <SOAPHeaderBlock
     array>.length; i++){  <SOAPHeaderBlock>
           = <SOAPHeaderBlock array>
     [i];  <value or object>
           = <SOAPHeaderBlock>
.value;  <name string>
           = <SOAPHeaderBlock>
.name;  <namespace URI
 string>         = <SOAPHeaderBlock>
   .namespaceURI;  <actor URI string>
           = <SOAPHeaderBlock>
.actorURI;  <must understand
  boolean>       = <SOAPHeaderBlock>
     .mustUnderstand;
  <checking and 
processing     of result>} | 
                                                                        
  
                                               
        
                                                 
        
    3.5 Non-RPC Operations
             For messages that are not intended to model RPC calls, there 
is  no  method    name or target object URI, and the parameters generally 
have  namespaceURIs.      Otherwise, the basic operations are the same.
             
                                                 
        
               
                 
                   | Non-RPC Operation 
 | How to Do It 
 | 
                 
                   | Setting the namespaceURI of a non-RPC 
parameter  . 
 | 
                     <SOAPParameter>
          = new SOAPHeaderBlock(<any value or 
 object>        , "<name>
  ", "        <namespaceURI> ");   // or <SOAPParameter>
         .namespaceURI = "<namespaceURI>
          "; | 
                 
                   | Encode a SOAP 1.1 non-rpc-style message. 
 | 
                     <SOAPCall>
    .encode(0,    "", "", <header block array>
    .length,     <header block array>
    ,       <parameter array>.length,
             <parameter    array>
    ) | 
                 
                   | Get returned parameters from non-rpc-style
   response. 
 | 
                     <SOAPParameter array>
           = <SOAPResponse> .getParameters(false,
      {}); | 
                                                                        
  
                                               
        
                                                 
        
    3.6 SOAPBlock and SOAPMessage Supertypes
       In  the following operations, SOAPHeaderBlock and SOAPParameter may
 be  referred  to collectively as  SOAPBlock objects.
             
       Also, SOAPCall and SOAPResponse may be referred to collectively as 
SOAPMessage    objects.
                                                 
        
    3.7 More Operations
             The following table contains less-common operations.
             
                                                 
        
               
                 
                   | Operation 
 | How to Do It 
 | 
                        
                   | Set or get an actionURI carried for the 
 message    in  the HTTP header. 
 | 
                     <SOAPMessage>
       .actionURI  = "<action URI>
    ";// or
<action URI string>
           = <SOAPMessage> .actionURI;
 | 
                 
                   | Directly set the DOM element to represent 
  the   block's   encoded content, bypassing encoding of the value on the 
block . 
 | 
                     <SOAPBlock>
     .element   = <DOM Element>
 ;
 
 | 
                 
                   | Directly get the DOM element that represents
    the   block's encoded content, bypassing decoding of the value on the
block  . 
 | 
                     <DOM Element>
        =            <SOAPBlock>
 .element;
 | 
                 
                   | Directly get the DOM element containing 
 the   SOAP   envelope , header, or body of an encoded message. 
 | 
                     <DOM Element>
        =            <SOAPMessage>
   .envelope;// OR<DOM Element>
        =            <SOAPMessage>
   .header;// or<DOM Element>
        =            <SOAPMessage>
   .body;
 | 
                 
                   | Directly set the DOM document to represent
   the   message's  entire encoded content, bypassing encoding. 
 | 
                     <SOAPMessage>
       .message  = <DOM Document>
   ;
 
 | 
                 
                   | Directly get the DOM document of an encoded 
   message,    bypassing encoding. 
 | 
                     <DOM Document>
         =           <SOAPMessage>
   .message;
 
 | 
                 
                   | Get the method name and target object 
URI,  if any,  of  the  message. 
 | 
            <method name string>
           = <SOAPMessage> .methodName;<object URI string>
           = <SOAPMessage> .targetObjectURI; | 
                 
                   | Get the actual SOAP version of an encoded 
  message     -- 0 for SOAP 1.1 and 1 for SOAP 1.2. 
 | 
                     <version integer>
           = <SOAPMessage> .version; | 
                 
                   | Encode a SOAP 1.2 message. 
 | 
                     <SOAPCall>
    .encode(1,    "<method name>
  ",  "      <target object namespaceURI>
    ", <SOAPHeaderBlock    array>
   .length,           <SOAPHeaderBlock     array>
    , <SOAPParameter array>   
   .length,           <SOAPParameter array>
          ); | 
                 
                   | Abort an in-progress async call -- this 
 does   not   necessarily cause the message not to be processed, but the API
 stops   listening   for it to complete. 
 | 
                     <SOAPCallCompletion>
           = <SOAPCall> .asyncInvoke(
          <SOAPResponseListener>);<...><SOAPCallCompletion>
          .abort();
 | 
                 
                   | Get the encoding (style) used to encode 
 or  decode    message.  Not available on an unencoded call unless explicitly
   set  --  use following operation instead. 
 | 
                     <SOAPEncoding>
         =           <SOAPMessage>
   .encoding; | 
                 
                   | Set the primary encoding style used 
to  encode a message.  A new SOAPEncoding objects (created by new) starts 
 a different set of associated encodings, which are only reached (or created) 
 in association by calling getAssociatedEncoding(). 
 | 
                     <SOAPEncoding>
         = new SOAPEncoding();<SOAPEncoding>
         =           <SOAPEncoding>
    .getAssociatedEncoding("       <style  URI>
    ",<true to  create>    );<customize encodings>
<SOAPMessage>
       .encoding  = <SOAPEncoding>
    ; | 
                 
                   | Specify the encoding style used to encode 
  or  decode   specific blocks. 
 | 
                     <SOAPEncoding>
         =           <SOAPEncoding>
    .getAssociatedEncoding("       <style  URI>
    ",<true to  create>    );<SOAPBlock>
     .encoding   = <SOAPEncoding>
   ; | 
                                                                        
  
                                               
        
                                                 
        
                                                 
        
    3.8 Using Schema Types
              The default SOAP encodings implement most XML built-in types, 
 as  well   as  the basic SOAP types.  In the absence of a specified 
type,  native   values  and objects will typically be correctly identified 
and mapped  to  a corresponding  schema type.  There may be no perfect 
correspondence between Javascript and XML Schema types, so they  will be mapped
to  a close corresponding type.
    
    Providing specific schema types can  help the encoding  produce the desired
  results.  For example, multidimensional    arrays must  be decoded
as  nested arrays because Javascript only supports    single-dimensional
 arrays.   If no schema type is given that identifies    the array as
multidimensional,   then a multidimensional array will be encoded    as a
nested array.  An   accurate schema type can also help when encoding
   or decoding of other  complex  objects such as SOAP structs.
             
             Schema types may be attached to blocks before encoding or before 
  accessing     the value of a returned object to better control the encoding 
  and decoding.      All schema types which are used to control the encoding
  and decoding     should come from the schema collection available through
  the encoding (associated encodings share the same collection).
             
                                                 
        
               
                 
                   | Schema Operation 
 | How to Do It 
 | 
                 
                   | Get the schema collection of all associated 
   encodings. 
 | 
                     <SchemaCollection>
           = <SOAPEncoding> .schemaCollection; | 
                 
                   | Load additional schema types from XML 
Schema    files   into the schema collection. 
 
 | 
                     <SchemaLoader>
         =           <SchemaCollection>
         ;// and then
<SchemaLoader>
        .load("  <schema file URI>
    ");//  or
<SchemaLoader>
        .loadAsync("  <schemaURI>
   ",              <load  completion  function>
      ); | 
                 
                   | Specify the XML Schema type to be used
 when   encoding    or decoding a block.  Note: decoding a block occurs
 when  you get its  value, so after getting a block from an XML-encoded message
 such as a SOAPResponse, attaching type info affects evaluation of the value. | 
                     <SchemaType>
       =             <SchemaCollection>
        .getType("  <name> ", 
"       <namespaceURI>  ");if (<schemaType != null) 
  {
  
         <SOAPBlock> .schemaType = 
    <SchemaType>      ;} | 
                                                                        
  
                                               
        
                                                 
        
                                                 
        
                                                 
        
    3.9 Customization of Encodings
             A specific encoding must have encoders and decoders to function. 
   Encoding     or decoding of data always begins with a default encoder 
  or decoder, which     then may lookup additional encoders or decoders by 
 a string key as required.      For either the 1.1 or 1.2 version of 
the default SOAP encoding, the    default encoder and decoder use the schema 
type's namespaceURI and name,   seperated by "#" to look up additional decoders 
for specific schema types.    Additional encoders and decoders registered 
  within the default encodings   will automatically be invoked as an object 
  identified as the corresponding   type is processed.  Other encodings 
  can use any scheme for looking up  additional encoders and decoders, or 
none  at all if all the work is done  by the default encoder and decoder for
that  encoding.  Encodings  which are registered with the system, such
as the default SOAP 1.1 or 1.2  encodings, automatically come with encoders 
and decoders built-in, whereas  new encodings have none.  Custom encodings 
  may also reuse existing encoders  and decoders, but there is no guarantee 
  which are present, since the mapping  may vary when handling an infinite 
 set of types with a finite set of encoders  and decoders.
             
             Also, there has been a proliferation of different    schema
URIs   to describe the same types, which may often even be intermixed in
usage,  but expected  to function    properly.  Most notably, the SOAP
1.1 specification   used  unofficial   XML Schema URIs and SOAP encoding
schema URIs not compatible    with those which   are in the W3C XML Schema
and drafts for SOAP 1.2 specifications.     It   is not uncommon to
send and receive messages using the URIs specified   in  the SOAP 1.1 specification,
but described by WSDL using XML Schema that   uses  the official, correct
URIs.  To solve these problems, the encoding   permits   schema URIs
to be aliased, both on input and on output, so that   only the  SOAP 1.2
and official XMLSchema types are used internally, while   supporting  the
other URIs.  Mappings of this type are built-in  for  encodings which
are registered with the system, such as the default encodings    of SOAP
1.1 and 1.2.  The default URI mappings may be manipulated, for example,
to output SOAP 1.1 but with the official XML  Schema  URIs, without having
to rewrite any encoders or decoders.
             
                                                 
        
               
                 
                   | Encoding Customization Operation 
 | How to Do It 
 | 
                 
                   | Create a custom encoder. | 
                     function <New DOM Element>
           = <SOAPEncoder name>
(          <SOAPEncoding>,  
<value>          , <namespaceURI>
 ,           <name>, 
<SchemaType>          , <SOAPAttachments>
 ,                            <Parent DOM  Element>
   ){<...>
<DOM Element>
        =            <Parent DOM Element>
         .ownerDocument.createElementNS(namespaceURI,name);
<...>
  <Parent DOM Element>
          .appendChild(<DOM Element>
     );
  return <DOM Element>
          ;
}// and<SOAPEncoding>
        .defaultEncoder  = <SOAPEncoder>
         ;// or <SOAPEncoding>
         .setEncoder(" <namespaceURI>
       #  <name> ",
       <SOAPEncoder>  ); 
 | 
                 
                   | Create a custom decoder. 
 | 
                     function <New DOM Element>
           = <SOAPDecoder name>
(          <SOAPEncoding>,  
<DOM   Element>      ,  <SchemaType>
    ,       <SOAPAttachments>){<...>  return <value or 
object>         ;
}// and<SOAPEncoding>
        .defaultDecoder  = <SOAPDecoder>
         ;// or <SOAPEncoding>
         .setDecoder(" <namespaceURI>
       #  <name> ",
       <SOAPDecoder>  ); 
 | 
                 
                   | Map or unmap schema  URI aliases 
 | 
                     <SOAPEncoding>
        .mapSchemaURI("  <external URI>
         ", "<internal   URI>", 
                         <true to alias output>
   ); // or <SOAPEncoding>
         .unmapSchemaURI(" <external URI>
         "); | 
                 
                   | Register modified or alternative encodings, 
   making    them automatically available to all SOAP scripts in the system 
 | Install an appropriate registerable encoding
    in   components/<new encoding>
          .js
 | 
                                                                        
  
                                               
        
                                                 
        
    3.10 Security Operations
             In browsers, the risk of allowing an externally-loaded untrusted 
  script    to request information within a firewall and send it elsewhere 
 has lead  to  very tight sandbox restrictions, permitting external browser 
 scripts    to only request xml data and services on the same domain from 
which the script    was loaded.  This same restriction applies by default 
to SOAP requests    executed within the browser.  This means that an 
externally-loaded  script  cannot, for example, call other external services 
unless they are  in the same domain from which the page was loaded.  Even 
if the page  was loaded from the user's own hard disk, the script must ask 
for permission  to make SOAP calls.  A browser enhancement is planned 
to permit more-precise   control of trust between scripts and specific available 
services.
             
             Since SOAP permits headers to be added to messages that require
  interpretation     by the recipient, this API can request a header to warn
  the recipient that    it was sent by an untrusted script loaded from a
specific    sourceURI, and  no good SOAP service will unintentionally disregard
the  warning.   If    the envelope is verified and the header is added,
then  the browser  can  allow  the script less-restricted access to services
outside  of its source   domain.   Accepting this header permits SOAP
services  that really do  want to be universally available to allow access
without forcing the user  to risk breach of the firewall protections and/or
request user permission.
             
                                                    
        
                
                  
                   | Security Operation 
 | How to Do It 
 | 
                 
                   | Mark the call with a verifySourceHeader 
 so, if  the  service  permits it, the browser can make the call with less 
 privilege    and risk. 
 | 
                     <SOAPCall>
    .verifySourceHeader    = true; | 
                  
                    | Request risky privileges within a local
  or  signed    script to make an unverified SOAP calls to other domains. 
 | 
                     netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead") | 
                  
                    | Modify the security settings in the
preferences      file,  allowing scripts from some domain to make risky SOAP
calls to any    other domain, which is disabled by default. | Add the setting in default/pref/all.js:
 
                     pref("<some domain prefix>
          .SOAPCall.invoke","allAccess"); | 
                  
                | Modify the security settings in the preferences
     file to disallow even dross-domain calls made with verifySource header,
  which is generally permitted by default. 
 | Remove or comment out the setting in 
   default/pref/all.js:
 
                  pref("capability.policy.default.SOAPCall.invokeVerifySourceHeader","allAccess"); | 
              
                    | Register alternative transport mechanisms, 
   making  available alternative transports  to all scripts and perhaps creating 
    alternative  security models for protocols besides http(s).  See 
               the futures
 section
    for more info on possible transports. 
 | Install an appropriate registerable
encoding     in components/<new transport>
          .js.
 | 
                                                                        
      
                                                
        
                                                   
        
                                                 
        
    4 Future Features
                                                   
        
    4.1 Access to SOAP as Proxies
              Although a SOAP call can generally be accomplished using this 
 low-level    API in a  few  dozen lines, WSDL   is a standard that contains 
 enough information  to enable this to occur with no manual  argument and 
type setup required.   An  implementation is under development that 
instantiates web service  proxies  complete with appropriate xpconnect interfaces 
 by simply loading  and using  information out of a WSDL file that describes
  the service.  The  proxy's  interface has dynamically-generated  methods
  named appropriately  to match the services described in the WSDL file 
which   accept arguments of the appropriate  data types and calls the appropriate
   low-level SOAP functions with the appropriate   type information, making
  it even simpler not only to invoke services from   Javascript code, but
to  associate appropriate schema types loaded from the   WSDL file with the
arguments.   This higher level is not available in the first release.
 When  it is available, invoking WSDL-described features gets even easier
and more  reliable.
                                                   
        
 
                                                   
        
    4.2 Arbitrary Graphs of Data
              The SOAP specification allows objects to be passed as arguments 
  which    may  have originally referenced other objects that are not owned 
  in a pure    hierarchy.   This is represented by using an href attribute. 
   Due    to the problems  with leaking reference counts in COM objects 
  with cyclic    references, this  has not been implemented yet.  Also, 
  the output of   a cyclic-referencing  set of objects has not been implemented. 
   Outputting    of objects that do not have cyclic  references currently
creates   separate copies   for each reference to  an object, and with cycles
output   may never complete.     On input, hrefs are currently ignored.
 In   the future it may  be  possible to solve this and transmit and
receive arbitrarily-referencing    objects,  but the solution  is more complex
than just using weak references.
                                                   
        
    4.3 SOAP With Attachments
              Many clients and servers now support automatically transmitting 
  large    Mime  with a SOAP message by encapsulating it in MIME, DIME, or 
 other enveloping     formats.  This has been anticipated in the APIs, 
 but the SOAPAttachments     API is currently a place holder for this future 
 feature which is not yet   implemented.
                                                 
        
    4.4 New Transports and Local Services
             Obvious new transports that would be useful include e-mail --
 permitting     a SOAP exchange  to occur as an email exchange --, instant
 messenger for    peer to peer, and  a local manager with a controlled security
 model but  without   the size limitations, enabling SOAP to save and restore
 arbitrary  Javascript   application data on the client.  These services
 require  a framework,   already being planned, for  permitting the browser
 to host  services as well   as being a good client.   There are obviously
 security  issues to be  solved to make these successful.
                                           
        
    4.5 Standards
          The interfaces to the objects of this API were designed to be as
 simple    and universal as possible.  We believe that we should submit
 a note   describing them and sponsor a W3C proposal to standardize an API
 for invoking   this type of service from web clients.  In such an effort,
 changes would  be inevitable and welcomed as the price for interoperability
 within web clients.   Part of this API are incomplete, specifically
the SOAPAttachments  object,  which will be defined to allow encoders and
decoders to control uniqueness  and referencing, both for resolving arbitrary
graphs of data (as described  above in "Arbitrary Graphs of Data") as well
as for automatically resolving  references to attached objects carried with
the message in an external encapsulation  (as described above in "SOAP With
Attachments").
                                                   
        
    5 Samples and Testing
  Tests and samples exist today can be found in the mozilla tree at 
  mozilla/extensions/xmlextras/tests/soap*.html.  We welcome the
contribution of tests and samples by other parties.  Please note that
these files do not work in the linked location due to js files being shown 
as HTML cross-referenced files, so they must be copied from the current 
mozilla tree to the client's local harddrive or some web server before 
testing them.
       
       To test the services, it is   interesting  to turn on MOZ_DEBUG=1, 
because even if you do not debug the program, this  causes the exchanged 
SOAP messages to be displayed on the standard output  if you run from a command 
shell where this is visible.
          
          A SOAP service server has been set up at ray.dsl.xmission.com where 
  additional  services may be deployed to help test and demo the features 
for  scripting   SOAP in Mozilla.  No home page describes the Apache 
Jakarta  server  on port 8080 which is the test facility, but this is currently 
used  in two  tests in the previously-mentioned directory: soapisprimenumber.html 
  and soapunscramble.html.   Adding services is as easy as writing functions 
  in Javascript, Java,  or other supported languages and describing the deployment 
  in XML.  Disclaimer:  as this is merely an end-subscriber DSL service, 
  if the server becomes too  widely published, it may have to be shut down.
          
SOAP Bugs should be reported using bugzilla.mozilla.org, as a new bug on
Browser, specifying the XML component, and assigned to 
rayw@netscape.com
, which is the email address you can use to contact me directly if you have
an issue that cannot be solved in the newsgroup 
netscape.public.mozilla.xml
 or by filing a bug.
        
          6 Object Interfaces