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
correspondance between Javascript and XML Schema types, so they  will be
mapped to  a close corresponding type.
 
 Providing specific schema types can  help the encoding  produce the desired 
results.  For example, multidimensional    arrays must  be decoded as 
nested arrays because Javascript only supports    single-dimensional  arrays. 
 If no schema type is given that identifies    the array as multidimensional, 
 then a multidimensional array will be encoded    as a nested array.  An 
 accurate schema type can also help when encoding    or decoding of other 
complex  objects such as SOAP structs.
          
          Schema types may be attached to blocks before encoding or before
 accessing     the value of a returned object to better control the encoding
 and decoding.      All schema types which are used to control the encoding
 and decoding     should come from the schema collection available through
 the encoding (associated encodings share the same collection).
          
                   
        
            
              
                | Schema Operation 
 | How to Do It 
 | 
              
                | Get the schema collection of all associated
  encodings. 
 | 
                  <SchemaCollection>
        = <SOAPEncoding> .schemaCollection; | 
              
                | Load additional schema types from XML Schema 
  files   into the schema collection. 
 
 | 
                  <SchemaLoader>
      =           <SchemaCollection>
      ;// and then
<SchemaLoader>
     .load("  <schema file URI>
 ");//  or
<SchemaLoader>
     .loadAsync("  <schemaURI>
",              <load  completion  function>
   ); | 
              
                | Specify the XML Schema type to be used when
  encoding    or decoding a block.  Note: decoding a block occurs when 
you get its  value, so after getting a block from an XML-encoded message such
as a SOAPResponse, attaching type info affects evaluation of the value. | 
                  <SchemaType>
    =             <SchemaCollection>
     .getType("  <name> ",  "
    <namespaceURI>  ");if (<schemaType != null)
 {
  
      <SOAPBlock> .schemaType = 
 <SchemaType>      ;} | 
                                       
                    
        
                   
        
                   
        
                   
        
 3.9 Customization of Encodings
          A specific encoding must have encoders and decoders to function.
  Encoding     or decoding of data always begins with a default encoder
 or decoder, which     then may lookup additional encoders or decoders by
a string key as required.      For either the 1.1 or 1.2 version of
the default SOAP encoding, the    default encoder and decoder use the schema
type's namespaceURI and name,   seperated by "#" to look up additional decoders
for specific schema types.    Additional encoders and decoders registered
 within the default encodings   will automatically be invoked as an object
 identified as the corresponding   type is processed.  Other encodings
 can use any scheme for looking up  additional encoders and decoders, or
none  at all if all the work is done  by the default encoder and decoder
for that  encoding.  Encodings  which are registered with the system,
such as the default SOAP 1.1 or 1.2  encodings, automatically come with encoders
and decoders built-in, whereas  new encodings have none.  Custom encodings
 may also reuse existing encoders  and decoders, but there is no guarantee
 which are present, since the mapping  may vary when handling an infinite
set of types with a finite set of encoders  and decoders.
          
          Also, there has been a proliferation of different    schema URIs 
to describe the same types, which may often even be intermixed in usage, but
expected  to function    properly.  Most notably, the SOAP 1.1 specification 
used  unofficial   XML Schema URIs and SOAP encoding schema URIs not compatible 
 with those which   are in the W3C XML Schema and drafts for SOAP 1.2 specifications.
   It   is not uncommon to send and receive messages using the URIs
specified   in  the SOAP 1.1 specification, but described by WSDL using XML
Schema that   uses  the official, correct URIs.  To solve these problems,
the encoding   permits   schema URIs to be aliased, both on input and on
output, so that   only the  SOAP 1.2 and official XMLSchema types are used
internally, while   supporting  the other URIs.  Mappings of this type
are built-in  for  encodings which are registered with the system, such as
the default encodings    of SOAP 1.1 and 1.2.  The default URI mappings
may be manipulated, for example, to output SOAP 1.1 but with the official
XML  Schema  URIs, without having to rewrite any encoders or decoders.
          
                   
        
            
              
                | Encoding Customization Operation 
 | How to Do It 
 | 
              
                | Create a custom encoder. | 
                  function <New DOM Element>
        = <SOAPEncoder name>(
       <SOAPEncoding>,  <value>
       , <namespaceURI> , 
       <name>, <SchemaType>
       , <SOAPAttachments> ,  
       <Parent DOM  Element> ){<...>
<DOM Element>
     =            <Parent DOM Element>
      .ownerDocument.createElementNS(namespaceURI,name);
<...>
  <Parent DOM Element>
       .appendChild(<DOM Element>
  );
  return <DOM Element>
       ;
}// and<SOAPEncoding>
     .defaultEncoder  = <SOAPEncoder>
      ;// or <SOAPEncoding>
      .setEncoder(" <namespaceURI>
    #  <name> ",
    <SOAPEncoder>  ); 
 | 
              
                | Create a custom decoder. 
 | 
                  function <New DOM Element>
        = <SOAPDecoder name>(
       <SOAPEncoding>,  <DOM 
Element>      ,  <SchemaType>
 ,       <SOAPAttachments>){<...>  return <value or object>
       ;
}// and<SOAPEncoding>
     .defaultDecoder  = <SOAPDecoder>
      ;// or <SOAPEncoding>
      .setDecoder(" <namespaceURI>
    #  <name> ",
    <SOAPDecoder>  ); 
 | 
              
                | Map or unmap schema  URI aliases 
 | 
                  <SOAPEncoding>
     .mapSchemaURI("  <external URI>
      ", "<internal   URI>", 
     <true to alias output>  ); // or <SOAPEncoding>
      .unmapSchemaURI(" <external URI>
      "); | 
              
                | Register modified or alternative encodings,
  making    them automatically available to all SOAP scripts in the system 
 | Install an appropriate registerable encoding 
  in   components/<new encoding>
       .js
 | 
                                       
                    
        
                   
        
 3.10 Security Operations
          In browsers, the risk of allowing an externally-loaded untrusted
 script    to request information within a firewall and send it elsewhere
has lead  to  very tight sandbox restrictions, permitting external browser
scripts    to only request xml data and services on the same domain from
which the script    was loaded.  This same restriction applies by default
to SOAP requests    executed within the browser.  This means that an
externally-loaded  script  cannot, for example, call other external services
unless they are  in the same domain from which the page was loaded.  Even
if the page  was loaded from the user's own hard disk, the script must ask
for permission  to make SOAP calls.  A browser enhancement is planned
to permit more-precise   control of trust between scripts and specific available
services.
          
          Since SOAP permits headers to be added to messages that require 
interpretation     by the recipient, this API can request a header to warn 
the recipient that    it was sent by an untrusted script loaded from a specific 
 sourceURI, and  no good SOAP service will unintentionally disregard the warning.
  If    the envelope is verified and the header is added, then the browser
 can  allow  the script less-restricted access to services outside of its
source   domain.   Accepting this header permits SOAP services that
really do  want to be universally available to allow access without forcing
the user  to risk breach of the firewall protections and/or request user
permission.
          
                      
        
             
               
                | Security Operation 
 | How to Do It 
 | 
              
                | Mark the call with a verifySourceHeader
so, if  the  service  permits it, the browser can make the call with less
privilege    and risk. 
 | 
                  <SOAPCall>
 .verifySourceHeader    = true; | 
               
                 | Request risky privileges within a local 
or  signed    script to make an unverified SOAP calls to other domains. 
 | 
                  netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead") | 
               
                 | Modify the security settings in the preferences
    file,  allowing scripts from some domain to make risky SOAP calls to
any    other domain, which is disabled by default. | Add the setting in default/pref/all.js:
 
                  pref("<some domain prefix>
       .SOAPCall.invoke","allAccess"); | 
               
             | Modify the security settings in the preferences 
   file to disallow even dross-domain calls made with verifySource header, 
which is generally permitted by default. 
 | Remove or comment out the setting in 
default/pref/all.js:
 
               pref("capability.policy.default.SOAPCall.invokeVerifySourceHeader","allAccess"); | 
           
                 | Register alternative transport mechanisms,
  making  available alternative transports  to all scripts and perhaps creating
   alternative  security models for protocols besides http(s).  See
              
the futures section
 for more info on possible transports. 
 | Install an appropriate registerable encoding
   in components/<new transport>
       .js.
 | 
                                           
                     
        
                     
        
                   
        
 4 Future Features
                     
        
 4.1 Access to SOAP as Proxies
           Although a SOAP call can generally be accomplished using this
low-level    API in a  few  dozen lines, WSDL   is a standard that contains
enough information  to enable this to occur with no manual  argument and
type setup required.   An  implementation is under development that
 instantiates web service  proxies  complete with appropriate xpconnect interfaces
 by simply loading  and using  information out of a WSDL file that describes 
the service.  The  proxy's  interface has dynamically-generated  methods 
named appropriately  to match the services described in the WSDL file  which 
accept arguments of the appropriate  data types and calls the appropriate 
 low-level SOAP functions with the appropriate   type information, making 
it even simpler not only to invoke services from   Javascript code, but to 
associate appropriate schema types loaded from the   WSDL file with the arguments. 
 This higher level is not available in the first release.  When 
it is available, invoking WSDL-described features gets even easier and more 
reliable.
                     
        
 
                     
        
 4.2 Arbitrary Graphs of Data
           The SOAP specification allows objects to be passed as arguments
 which    may  have originally referenced other objects that are not owned
 in a pure    hierarchy.   This is represented by using an href attribute.
  Due    to the problems  with leaking reference counts in COM objects
 with cyclic    references, this  has not been implemented yet.  Also,
 the output of   a cyclicly-referencing  set of objects has not been implemented.
  Outgoing    objects that do not  reference cyclicly currently create
 separate copies   for each reference to  an object, and with cycles output
 may never complete.     On input, hrefs are currently ignored.  In
 the future it may  be  possible to solve this and transmit and receive arbitrarily-referencing
  objects,  but the solution  is more complex than just using weak references.
                     
        
 4.3 SOAP With Attachments
           Many clients and servers now support automatically transmitting
 large    Mime  with a SOAP message by encapsulating it in MIME, DIME, or
other enveloping     formats.  This has been anticipated in the APIs,
but the SOAPAttachments     API is currently a placeholder for this future
feature which is not yet   implemented.
                   
        
 4.4 New Transports and Local Services
          Obvious new transports that would be useful include e-mail -- permitting 
   a SOAP exchange  to occur as an email exchange --, instant messenger for 
  peer to peer, and  a local manager with a controlled security model but 
without   the size limitations, enabling SOAP to save and restore arbitrary 
Javascript   application data on the client.  These services require 
a framework,   already being planned, for  permitting the browser to host 
services as well   as being a good client.   There are obviously security 
issues to be  solved to make these successful.
             
        
 4.5 Standards
       The interfaces to the objects of this API were designed to be as simple
   and universal as possible.  We believe that we should submit a note
  describing them and sponser a W3C proposal to standardize an API for invoking
  this type of service from web clients.  In such an effort, changes
would  be inevitable and welcomed as the price for interoperability within
web clients.   Part of this API are incomplete, specifically the SOAPAttachments
 object,  which will be defined to allow encoders and decoders to control
uniqueness  and referencing, both for resolving arbitrary graphs of data
(as described  above in "Arbitrary Graphs of Data") as well as for automatically
resolving  references to attached objects carried with the message in an
external encapsulation  (as described above in "SOAP With Attachments").
                     
        
 5 Samples and Testing
       Some samples or tests have been created, but these commonly only use 
 the   basic operations.  Some of the higher-level features are being 
 tested by the prosy code (as described above in "Access to SOAP as Proxies"). 
  While most of the methods of this API are well-exercized internally 
  during even basic invocation, we need samples that test and demonstrate 
external  access to the functions.  What exists today is mozilla/extensions/xmlextras/tests 
  /soap*.html.  We welcome the contribution of tests  by other parties.
   Most samples work but at least one (soapcall.html) is no longer correctly
  configured to talk to a server -- but it genrates interesting messages
anyway.
    
    To test the services, it is 
 interesting  to turn on MOZ_DEBUG=1, because even if you do not debug the
 program, this  causes the exchanged SOAP messages to be displayed on the
standard output  if you run from a command shell where this is visible.
       
       A SOAP service server has been set up at ray.dsl.xmission.com where
 additional  services may be deployed to help test and demo the features
for  scripting   SOAP in Mozilla.  No home page describes the Apache
Jakarta  server  on port 8080 which is the test facility, but this is currently
used  in two  tests in the previously-mentioned directory: soapisprimenumber.html
 and soapunscramble.html.   Adding services is as easy as writing functions
 in Javascript, Java,  or other supported languages and describing the deployment
 in XML.  Disclaimer:  as this is merely an end-subscriber DSL service,
 if the server becomes too  widely published, it may have to be shut down.
       
       Bugs should be reported as usual.
             
        
 6 Object Interfaces