gecko-dev/extensions/webservices/docs/Soap_Scripts_in_Mozilla.html
timeless%mozdev.org 697618b07d Bug 106386 rid source of misspellings
patch by nb@ipnode.info r=biesi sr=dmose
2003-03-24 04:15:34 +00:00

1447 lines
73 KiB
HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<title>Soap Scripts in Mozilla</title>
</head>
<body>
<div align="Center">
<h1>SOAP Scripts in Mozilla</h1>
Last Modified <script type="text/javascript">document.write(document.lastModified)</script><br>
<h3><a href=mailto:rayw@netscape.com>Ray Whitmer</a></h3>
<h2>Abstract</h2>
<div align="Left"><font color="#000000">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 <a href="http://www.w3.org/TR"> W3C current drafts</a>
).&nbsp; <br>
<br>
The browser client is the most universal web agent in existence,
and Javascript is the standard, interoperable way of scripting browsers.&nbsp;
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.&nbsp;
Web data structures, exchanged in a platform-neutral way, should become
as fundamental to web agents as web content is today.&nbsp; 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.</font><br>
<br>
<h2><a name="0_Table_of_Contents"></a>
0 Table of Contents</h2>
<blockquote> <a href="#1_SOAP_Services">1 SOAP Services</a>
<br>
<br>
<a href="#2_SOAP_Blocks">2 SOAP Blocks</a>
<br>
<blockquote><a href="#2.1_Parameters">2.1 Parameters</a>
<br>
<a href="#2.2_Header_Blocks">2.2 Header Blocks</a>
<br>
<a href="#2.3_Encodings">2.3 Encodings</a>
<br>
</blockquote>
<a href="#3_Using_the_Mozilla_Low-Level_SOAP_API">3 Using the Mozilla
Low-Level SOAP API</a>
<br>
<blockquote><a href="#3.1_Conventions_Used_Below_in">3.1 Conventions
Used Below in</a>
<br>
<a href="#3.2_Basic_Operations_of_SOAP">3.2 Basic Operations of
SOAP</a>
<br>
<a href="#3.3_Beyond_Basic_Operations">3.3 Beyond Basic Operations</a>
<br>
<a href="#3.4_Header_Operations">3.4 Header Operations</a>
<br>
<a href="#3.5_Non-RPC_Operations">3.5 Non-RPC Operations</a>
<br>
<a href="#3.6_SOAPBlock_and_SOAPMessage_Supertypes">3.6 SOAPBlock
and SOAPMessage Supertypes</a>
<br>
<a href="#3.7_More_Operations">3.7 More Operations</a>
<br>
<a href="#3.8_Using_Schema_Types">3.8 Using Schema Types</a>
<br>
<a href="#3.9_Customization_of_Encodings">3.9 Customization of Encodings</a>
<br>
<a href="#3.10_Security_Operations">3.10 Security Operations</a>
<br>
</blockquote>
<a href="#4_Future_Features">4 Future Features</a>
<br>
<blockquote><a href="#4.1_Access_to_SOAP_as_Proxies">4.1 Access to
SOAP as Proxies</a>
<br>
<a href="#4.2_Arbitrary_Graphs_of_Data">4.2 Arbitrary Graphs of
Data</a>
<br>
<a href="#4.3_SOAP_With_Attachments">4.3 SOAP With Attachments</a>
<br>
<a href="#4.4_New_Transports_and_Local_Services">4.4 New Transports
and Local Services</a>
<br>
<a href="#4.5_Standards">4.5 Standards</a>
<br>
</blockquote>
<a href="#5_Samples_and_Testing">5 Samples and Testing</a>
<br>
<br>
<a href="#6_Object_Interfaces">6 Object Interfaces</a>
</blockquote>
<h2><a name="1_SOAP_Services"></a>
1 SOAP Services</h2>
There are a number of sources for services available on the
web being set up, such as the <a href="http://www.xmethods.com">XMethods
website</a>
which the Mozilla implementation has used for some tests and use
cases. &nbsp;Apache also provides modules for SOAP that have been used to
author services for purposes of testing the Mozilla implementation (and
entertainment).&nbsp; 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.&nbsp;
There are toolkits available from Microsoft and other webserver providers
for authoring such services as well.<br>
<h2><a name="2_SOAP_Blocks"></a>
2 SOAP Blocks</h2>
<h3><a name="2.1_Parameters"></a>
2.1 Parameters<br>
</h3>
SOAP-based services exchange message envelopes which contain
blocks of XML data roughly corresponding to the parameters of a service
call.&nbsp; 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.
&nbsp;In a non-RPC message, the blocks are placed directly inside the
body instead of under the method element.&nbsp; <br>
<h3><a name="2.2_Header_Blocks"></a>
2.2 Header Blocks<br>
</h3>
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.<br>
<h3><a name="2.3_Encodings"></a>
2.3 Encodings<br>
</h3>
Interpretation of each block depends upon the encoding that
was used, which is clearly specified in the message.&nbsp; If the standard
SOAP encoding is used, then XML Schema types control the interpretation
of the data within each block.<br>
<h2><a name="3_Using_the_Mozilla_Low-Level_SOAP_API"></a>
3 Using the Mozilla Low-Level SOAP API</h2>
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.&nbsp;
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.<br>
<br>
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.<br>
<h3><a name="3.1_Conventions_Used_Below_in"></a>
3.1 Conventions Used Below in Descriptions of Operations<br>
</h3>
Names or descriptions in angle brackets represent values or
objects matching the name or description. &nbsp;These may be literal,
constructed via "new", or variables. &nbsp;Occasionally the same syntax
may represent script performing an operation. &nbsp;Quoted angle brackets
indicate a character string of the described type.<br>
<br>
So the following sample operation:<br>
<ul>
<li><font color="#993300"><i>&lt;Foo&gt;</i></font> = new
Foo(<font color="#993300"><i> &lt;FooFact&gt;</i></font> );</li>
<li><font color="#993300"><i>&lt;Foo&gt;</i></font>.bar =
<font color="#993300"><i> &lt;any value or object&gt;</i></font>
;</li>
<li><font color="#993300"><i>&lt;Baz&gt;</i></font> = <font color="#993300"><i>
&lt;Foo&gt;</i></font>.find("<font color="#993300"><i>&lt;name&gt;</i></font>
");</li>
<li><font color="#993300"><i>&lt;find out what you have&gt;</i></font></li>
</ul>
might be replaced in a real Javascript program:<br>
<br>
<code>var myFoo = new Foo(new FooFact("always","Great","Baz"));<br>
myFoo.bar = 3.14159265;<br>
var myGreatBaz = myFoo.find("Great");<br>
if (checkBaz(myGreatBaz)) {<br>
&nbsp; alert(myGreatBaz.description);<br>
}<br>
</code><br>
where "myFoo" is a variable holding an object of type Foo and
myGreatBaz is a variable holding an object of type Baz.<br>
<h3><a name="3.2_Basic_Operations_of_SOAP"></a>
3.2 Basic Operations of SOAP<br>
</h3>
The following basic SOAP operations is nearly all that most
users of SOAP need to do.<br>
<br>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
<tbody>
<tr>
<td valign="Top" width="50%">Basic Operation<br>
</td>
<td valign="Top">How to Do It<br>
</td>
</tr>
<tr>
<td valign="Top">Create a parameter block, setting the
Javascript value and name for rpc-style call.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPParameter&gt;</i></font>
= new SOAPParameter(<font color="#993300"><i>&lt;any value or object&gt;</i></font>
, "<font color="#993300"><i>&lt;name&gt;</i></font>");</li>
<li> &nbsp;// or </li>
<li><font color="#993300"><i>&lt;SOAPParameter&gt;</i></font>
= new SOAPParameter();</li>
<li><font color="#993300"><i>&lt;SOAPParameter&gt;</i></font>
.value = <font color="#993300"><i>&lt;any value or object&gt;</i></font>
;</li>
<li> <font color="#993300"><i>&lt;SOAPParameter&gt;</i></font>
.name = "<font color="#993300"><i>&lt;name&gt;</i></font>";</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Set parameters in a Javascript array.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPParameter array&gt;</i></font>
= new Array(<font color="#993300"><i>&lt;SOAPParameter&gt;</i></font>
<font color="#990000"><i>&lt;,...&gt;</i></font>);</li>
<li> // or</li>
<li><font color="#993300"><i>&lt;SOAPParameter array&gt;</i></font>
= new Array();</li>
<li><font color="#993300"><i>&lt;SOAPParameter array&gt;</i></font>
[0] = <font color="#993300"><i>&lt;SOAPParameter&gt;</i></font>
;</li>
<li><font color="#990000"><i>&lt;...&gt;</i></font></li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Create and encode the parameters in
a basic SOAP 1.1 rpc-style message.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPCall&gt;</i></font>
= new SOAPCall();</li>
<li><font color="#993300"><i>&lt;SOAPCall&gt;</i></font>
.transportURI = "<font color="#993300"><i>&lt;http-based service URI&gt;</i></font>
"</li>
<li><font color="#993300"><i>&lt;SOAPCall&gt;</i></font>
.encode(0, "<font color="#993300"><i>&lt;method name&gt;</i></font>
", "<font color="#993300"><i> &lt;target object namespaceURI&gt;</i></font>
", 0, null, <font color="#993300"><i> &lt;SOAPParameter array&gt;</i></font>
.length, <font color="#993300"><i> &lt;SOAPParameter array&gt;</i></font>
);</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Invoke &nbsp;call (send call message
and receive response message).<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPResponse&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPCall&gt;</i></font>
.invoke();</li>
<li><font color="#993300"><i>&lt;process the response
-- see below&gt;</i></font></li>
<li> // or</li>
<li> <font color="#993300"><i>&lt;SOAPCall&gt;</i></font>
.asyncInvoke(<font color="#993300"><i> &lt;SOAPResponseListener&gt;</i></font>
);</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Handle completion of async SOAP call.<br>
</td>
<td valign="Top">
<ul>
<li>function <font color="#993300"><i>&lt;SOAPResponseListener
name&gt;</i></font>(<font color="#993300"><i>&lt;SOAPResponse&gt;</i></font>
, <font color="#993300"><i>&lt;SOAPCall&gt;</i></font>, <font color="#993300"><i>
&lt;error&gt;</i></font>)</li>
<li>{</li>
<li>&nbsp; if (error != 0) {</li>
<li>&nbsp; &nbsp; &nbsp;<font color="#993300"><i>&lt;action
to be taken on failure to transport message&gt;</i></font></li>
<li>&nbsp; }</li>
<li>&nbsp; <font color="#993300"><i>&lt;process the
response -- see below&gt;</i></font></li>
<li>}</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Get service's failure, if any.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPFault&gt;</i></font>
= <font color="#993300"><i> &lt;SOAPResponse&gt;</i></font>
.fault;</li>
<li>if (<font color="#993300"><i>&lt;SOAPFault&gt;</i></font>
!= null) {</li>
<li>&nbsp; <font color="#993300"><i>&lt;namespace URI
string&gt;</i></font> = <font color="#993300"><i>&lt;SOAPFault&gt;</i></font>
.faultNamespace;</li>
<li>&nbsp; <font color="#993300"><i>&lt;name string&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPFault&gt;</i></font> .faultCode;</li>
<li>&nbsp; <font color="#993300"><i>&lt;summary string&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPFault&gt;</i></font> .faultString;</li>
<li>&nbsp; <font color="#993300"><i>&lt;actor URI string&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPFault&gt;</i></font> .actorURI;</li>
<li>&nbsp; <font color="#993300"><i>&lt;action to be
taken in case of fault&gt;</i></font></li>
<li>}</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Get returned parameters from rpc-style
response .<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPParameter array&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPResponse&gt;</i></font> .getParameters(true,
{});</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Process Javascript values, etc. of returned
parameters.<br>
</td>
<td valign="Top">
<ul>
<li>for (i = 0; i != <font color="#993300"><i>&lt;SOAPParameter
array&gt;</i></font>.length; i++)</li>
<li>{</li>
<li>&nbsp; <font color="#993300"><i>&lt;SOAPParameter&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPParameter array&gt;</i></font>
[i];</li>
<li>&nbsp; <font color="#993300"><i>&lt;value or object&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPParameter&gt;</i></font> .value;</li>
<li>&nbsp; <font color="#993300"><i>&lt;name string&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPParameter&gt;</i></font> .name;</li>
<li>&nbsp; <font color="#993300"><i>&lt;checking and
processing of result&gt;</i></font></li>
<li>}</li>
</ul>
</td>
</tr>
</tbody>
</table>
<h3></h3>
<h3><a name="3.3_Beyond_Basic_Operations"></a>
3.3 Beyond Basic Operations<br>
</h3>
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 <a href="#5_Samples_and_Testing">
section 5</a>
). &nbsp;The bulk of the operations that follow will be used less frequently,
but they need to be there for certain cases. &nbsp;The casual reader may
wish to skip the remaining tables of operations in this section, or scan
for features of interest.<br>
<h3><a name="3.4_Header_Operations"></a>
3.4 Header Operations</h3>
The user can send or receive header blocks for information not carried
in the body of the message. &nbsp;Sending and receiving header blocks
is not very different from sending and receiving parameters as described
above.<br>
<br>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
<tbody>
<tr>
<td valign="Top" width="50%">Header Operation<br>
</td>
<td valign="Top">How to Do It<br>
</td>
</tr>
<tr>
<td valign="Top">Create a Header Block.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
= new SOAPHeaderBlock(<font color="#993300"><i>&lt;any value or
object&gt;</i></font> , "<font color="#993300"><i>&lt;name&gt;</i></font>
", "<font color="#993300"><i> &lt;namespaceURI&gt;</i></font> ");</li>
<li> &nbsp;// or </li>
<li> <font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
= new SOAPHeaderBlock();</li>
<li> <font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
.value = <font color="#993300"><i>&lt;any value or object&gt;</i></font>
;</li>
<li> <font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
.name = "<font color="#993300"><i>&lt;name&gt;</i></font> ";</li>
<li> <font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
.namespaceURI = "<font color="#993300"><i>&lt;namespaceURI&gt;</i></font>
";</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Establish non-default role of a header
block .<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
.actorURI = "<font color="#993300"><i>&lt;actorURI&gt;</i></font>
";</li>
<li><font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
.mustUnderstand = <font color="#993300"><i>&lt;true or false&gt;</i></font>
;</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Set header blocks in a Javascript array.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPHeaderBlock array&gt;</i></font>
= new Array(<font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
<font color="#990000"><i>&lt;,...&gt;</i></font>);</li>
<li> // or</li>
<li> <font color="#993300"><i>&lt;SOAPHeaderBlock array&gt;</i></font>
= new Array();</li>
<li> <font color="#993300"><i>&lt;SOAPHeaderBlock array&gt;</i></font>
[0] = <font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
;</li>
<li> <font color="#990000"><i>&lt;...&gt;</i></font></li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Encode the headers in a SOAP 1.1 rpc-style
message.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPCall&gt;</i></font>
.encode(0, "<font color="#993300"><i>&lt;method name&gt;</i></font>
", "<font color="#993300"><i> &lt;target object namespaceURI&gt;</i></font>
", <font color="#993300"><i>&lt;SOAPHeaderBlock array&gt;</i></font>
.length, <font color="#993300"><i>&lt;SOAPHeaderBlock array&gt;</i></font>
, <font color="#993300"><i>&lt;SOAPParameter array&gt;</i></font>
.length, <font color="#993300"><i>&lt;SOAPParameter array&gt;</i></font>
);</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Get returned headers.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPHeaderBlock array&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPResponse&gt;</i></font> .getHeaderBlocks(true,
{});</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Process Javascript values, etc. of returned
headers.<br>
</td>
<td valign="Top">
<ul>
<li>for (i = 0; i != <font color="#993300"><i>&lt;SOAPHeaderBlock
array&gt;</i></font>.length; i++)</li>
<li>{</li>
<li>&nbsp; <font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPHeaderBlock array&gt;</i></font>
[i];</li>
<li>&nbsp; <font color="#993300"><i>&lt;value or object&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
.value;</li>
<li>&nbsp; <font color="#993300"><i>&lt;name string&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
.name;</li>
<li>&nbsp; <font color="#993300"><i>&lt;namespace URI
string&gt;</i></font> = <font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
.namespaceURI;</li>
<li>&nbsp; <font color="#993300"><i>&lt;actor URI string&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
.actorURI;</li>
<li>&nbsp; <font color="#993300"><i>&lt;must understand
boolean&gt;</i></font> = <font color="#993300"><i>&lt;SOAPHeaderBlock&gt;</i></font>
.mustUnderstand;<br>
</li>
<li>&nbsp; <font color="#993300"><i>&lt;checking and
processing of result&gt;</i></font></li>
<li>}</li>
</ul>
</td>
</tr>
</tbody>
</table>
<h3><a name="3.5_Non-RPC_Operations"></a>
3.5 Non-RPC Operations</h3>
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. &nbsp;Otherwise, the basic operations are the same.<br>
<br>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
<tbody>
<tr>
<td valign="Top" width="50%">Non-RPC Operation<br>
</td>
<td valign="Top">How to Do It<br>
</td>
</tr>
<tr>
<td valign="Top">Setting the namespaceURI of a non-RPC
parameter .<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPParameter&gt;</i></font>
= new SOAPHeaderBlock(<font color="#993300"><i>&lt;any value or
object&gt;</i></font> , "<font color="#993300"><i>&lt;name&gt;</i></font>
", "<font color="#993300"><i> &lt;namespaceURI&gt;</i></font> ");</li>
<li> &nbsp;// or </li>
<li><font color="#993300"><i>&lt;SOAPParameter&gt;</i></font>
.namespaceURI = "<font color="#993300"><i>&lt;namespaceURI&gt;</i></font>
";</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Encode a SOAP 1.1 non-rpc-style message.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPCall&gt;</i></font>
.encode(0, "", "", <font color="#993300"><i>&lt;header block array&gt;</i></font>
.length, <font color="#993300"><i>&lt;header block array&gt;</i></font>
, <font color="#993300"><i> &lt;parameter array&gt;</i></font>.length,
<font color="#993300"><i> &lt;parameter array&gt;</i></font>
)</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Get returned parameters from non-rpc-style
response.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPParameter array&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPResponse&gt;</i></font> .getParameters(false,
{});</li>
</ul>
</td>
</tr>
</tbody>
</table>
<h3><a name="3.6_SOAPBlock_and_SOAPMessage_Supertypes"></a>
3.6 SOAPBlock and SOAPMessage Supertypes</h3>
In the following operations, SOAPHeaderBlock and SOAPParameter may
be referred to collectively as SOAPBlock objects.<br>
<br>
Also, SOAPCall and SOAPResponse may be referred to collectively as
SOAPMessage objects.<br>
<h3><a name="3.7_More_Operations"></a>
3.7 More Operations</h3>
The following table contains less-common operations.<br>
<br>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
<tbody>
<tr>
<td valign="Top" width="50%">Operation<br>
</td>
<td valign="Top">How to Do It<br>
</td>
</tr>
<tr>
<td valign="Top">Set or get an actionURI carried for the
message in the HTTP header.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPMessage&gt;</i></font>
.actionURI = "<font color="#993300"><i>&lt;action URI&gt;</i></font>
";</li>
<li>// or<br>
</li>
<li><font color="#993300"><i>&lt;action URI string&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPMessage&gt;</i></font> .actionURI;<br>
</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Directly set the DOM element to represent
the block's encoded content, bypassing encoding of the value on the
block .<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPBlock&gt;</i></font>
.element = <font color="#993300"><i>&lt;DOM Element&gt;</i></font>
;<br>
</li>
</ul>
<br>
</td>
</tr>
<tr>
<td valign="Top">Directly get the DOM element that represents
the block's encoded content, bypassing decoding of the value on the
block .<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;DOM Element&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPBlock&gt;</i></font>
.element;<br>
</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Directly get the DOM element containing
the SOAP envelope , header, or body of an encoded message.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;DOM Element&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPMessage&gt;</i></font>
.envelope;</li>
<li>// OR</li>
<li><font color="#993300"><i>&lt;DOM Element&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPMessage&gt;</i></font>
.header;</li>
<li>// or</li>
<li><font color="#993300"><i>&lt;DOM Element&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPMessage&gt;</i></font>
.body;<br>
</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Directly set the DOM document to represent
the message's entire encoded content, bypassing encoding.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPMessage&gt;</i></font>
.message = <font color="#993300"><i>&lt;DOM Document&gt;</i></font>
;<br>
</li>
</ul>
<br>
</td>
</tr>
<tr>
<td valign="Top">Directly get the DOM document of an encoded
message, bypassing encoding.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;DOM Document&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPMessage&gt;</i></font>
.message;<br>
</li>
</ul>
<br>
</td>
</tr>
<tr>
<td valign="Top">Get the method name and target object
URI, if any, of the message.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;method name string&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPMessage&gt;</i></font> .methodName;</li>
<li><font color="#993300"><i>&lt;object URI string&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPMessage&gt;</i></font> .targetObjectURI;</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Get the actual SOAP version of an encoded
message -- 0 for SOAP 1.1 and 1 for SOAP 1.2.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;version integer&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPMessage&gt;</i></font> .version;</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Encode a SOAP 1.2 message.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPCall&gt;</i></font>
.encode(1, "<font color="#993300"><i>&lt;method name&gt;</i></font>
", "<font color="#993300"><i> &lt;target object namespaceURI&gt;</i></font>
", <font color="#993300"><i>&lt;SOAPHeaderBlock array&gt;</i></font>
.length, <font color="#993300"><i>&lt;SOAPHeaderBlock array&gt;</i></font>
, <font color="#993300"><i>&lt;SOAPParameter array&gt;</i></font>
.length, <font color="#993300"><i>&lt;SOAPParameter array&gt;</i></font>
);</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">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.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPCallCompletion&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPCall&gt;</i></font> .asyncInvoke(<font color="#993300"><i>
&lt;SOAPResponseListener&gt;</i></font>);</li>
<li><font color="#990000"><i>&lt;...&gt;</i></font></li>
<li><font color="#993300"><i>&lt;SOAPCallCompletion&gt;</i></font>
.abort();<br>
</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Get the encoding (style) used to encode
or decode message. &nbsp;Not available on an unencoded call unless explicitly
set -- use following operation instead.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPMessage&gt;</i></font>
.encoding;</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Set the primary encoding style used
to encode a message. &nbsp;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().<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font>
= new SOAPEncoding();</li>
<li><font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font>
.getAssociatedEncoding("<font color="#993300"><i> &lt;style URI&gt;</i></font>
",<font color="#993300"><i>&lt;true to create&gt;</i></font> );</li>
<li><font color="#993300"><i>&lt;customize encodings&gt;</i></font><br>
</li>
<li><font color="#993300"><i>&lt;SOAPMessage&gt;</i></font>
.encoding = <font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font>
;</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Specify the encoding style used to encode
or decode specific blocks.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font>
.getAssociatedEncoding("<font color="#993300"><i> &lt;style URI&gt;</i></font>
",<font color="#993300"><i>&lt;true to create&gt;</i></font> );</li>
<li><font color="#993300"><i>&lt;SOAPBlock&gt;</i></font>
.encoding = <font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font>
;</li>
</ul>
</td>
</tr>
</tbody>
</table>
<h3></h3>
<h3><a name="3.8_Using_Schema_Types"></a>
3.8 Using Schema Types</h3>
The default SOAP encodings implement most XML built-in types,
as well as the basic SOAP types. &nbsp;In the absence of a specified
type, native values and objects will typically be correctly identified
and mapped to a corresponding schema type. &nbsp;There may be no perfect
correspondence between Javascript and XML Schema types, so they will be mapped
to a close corresponding type.<br>
<br>
Providing specific schema types can help the encoding produce the desired
results. &nbsp;For example, multidimensional arrays must be decoded
as nested arrays because Javascript only supports single-dimensional
arrays. &nbsp;If no schema type is given that identifies the array as
multidimensional, then a multidimensional array will be encoded as a
nested array. &nbsp;An accurate schema type can also help when encoding
or decoding of other complex objects such as SOAP structs.<br>
<br>
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. &nbsp;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).<br>
<br>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
<tbody>
<tr>
<td valign="Top" width="50%">Schema Operation<br>
</td>
<td valign="Top">How to Do It<br>
</td>
</tr>
<tr>
<td valign="Top">Get the schema collection of all associated
encodings.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SchemaCollection&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font> .schemaCollection;</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Load additional schema types from XML
Schema files into the schema collection.<br>
<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SchemaLoader&gt;</i></font>
= <font color="#993300"><i>&lt;SchemaCollection&gt;</i></font>
;</li>
<li>// and then<br>
</li>
<li><font color="#993300"><i>&lt;SchemaLoader&gt;</i></font>
.load("<font color="#993300"><i> &lt;schema file URI&gt;</i></font>
");</li>
<li>// &nbsp;or<br>
</li>
<li><font color="#993300"><i>&lt;SchemaLoader&gt;</i></font>
.loadAsync("<font color="#993300"><i> &lt;schemaURI&gt;</i></font>
", <font color="#993300"><i> &lt;load completion function&gt;</i></font>
);</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Specify the XML Schema type to be used
when encoding or decoding a block. &nbsp;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.</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SchemaType&gt;</i></font>
= <font color="#993300"><i> &lt;SchemaCollection&gt;</i></font>
.getType("<font color="#993300"><i> &lt;name&gt;</i></font> ",
"<font color="#993300"><i> &lt;namespaceURI&gt;</i></font> ");</li>
<li>if (<font color="#993300"><i>&lt;schemaType != null)
{<br>
</i></font></li>
<font color="#993300"><i> <li>&nbsp; <font color="#993300"><i>
&lt;SOAPBlock&gt;</i></font> .schemaType = <font color="#993300"><i>
&lt;SchemaType&gt;</i></font> ;</li>
<li>}</li>
</i></font>
</ul>
<font color="#993300"><i> </i></font></td>
</tr>
</tbody>
</table>
<h3></h3>
<h3></h3>
<h3><a name="3.9_Customization_of_Encodings"></a>
3.9 Customization of Encodings</h3>
A specific encoding must have encoders and decoders to function.
&nbsp;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. &nbsp;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, separated by "#" to look up additional decoders
for specific schema types. &nbsp;Additional encoders and decoders registered
within the default encodings will automatically be invoked as an object
identified as the corresponding type is processed. &nbsp;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. &nbsp;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. &nbsp;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.<br>
<br>
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. &nbsp;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. &nbsp;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. &nbsp;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. &nbsp;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. &nbsp;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.<br>
<br>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
<tbody>
<tr>
<td valign="Top" width="50%">Encoding Customization Operation<br>
</td>
<td valign="Top">How to Do It<br>
</td>
</tr>
<tr>
<td valign="Top">Create a custom encoder.</td>
<td valign="Top">
<ul>
<li>function <font color="#993300"><i>&lt;New DOM Element&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPEncoder name&gt;</i></font>
(<font color="#993300"><i> &lt;SOAPEncoding&gt;</i></font>, <font color="#993300"><i>
&lt;value&gt;</i></font> , <font color="#993300"><i>&lt;namespaceURI&gt;</i></font>
, <font color="#993300"><i> &lt;name&gt;</i></font>, <font color="#993300"><i>
&lt;SchemaType&gt;</i></font> , <font color="#993300"><i>&lt;SOAPAttachments&gt;</i></font>
, <font color="#993300"><i> &lt;Parent DOM Element&gt;</i></font>
)</li>
<li>{</li>
<li><font color="#990000"><i>&lt;...&gt;</i></font><br>
</li>
<li><font color="#993300"><i>&lt;DOM Element&gt;</i></font>
= <font color="#993300"><i>&lt;Parent DOM Element&gt;</i></font>
.ownerDocument.createElementNS(namespaceURI,name);<br>
</li>
<li><font color="#990000"><i>&lt;...&gt;</i></font><br>
</li>
<li>&nbsp; <font color="#993300"><i>&lt;Parent DOM Element&gt;</i></font>
.appendChild(<font color="#993300"><i>&lt;DOM Element&gt;</i></font>
);<br>
</li>
<li>&nbsp; return <font color="#993300"><i>&lt;DOM Element&gt;</i></font>
;<br>
</li>
<li>}</li>
<li>// and</li>
<li><font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font>
.defaultEncoder = <font color="#993300"><i>&lt;SOAPEncoder&gt;</i></font>
;</li>
<li>// or</li>
<li> <font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font>
.setEncoder("<font color="#993300"><i> &lt;namespaceURI&gt;</i></font>
#<font color="#993300"><i> &lt;name&gt;</i></font> ",<font color="#993300"><i>
&lt;SOAPEncoder&gt;</i></font> );</li>
</ul>
<br>
</td>
</tr>
<tr>
<td valign="Top">Create a custom decoder.<br>
</td>
<td valign="Top">
<ul>
<li>function <font color="#993300"><i>&lt;New DOM Element&gt;</i></font>
= <font color="#993300"><i>&lt;SOAPDecoder name&gt;</i></font>
(<font color="#993300"><i> &lt;SOAPEncoding&gt;</i></font>, <font color="#993300"><i>
&lt;DOM Element&gt;</i></font> , <font color="#993300"><i> &lt;SchemaType&gt;</i></font>
, <font color="#993300"><i> &lt;SOAPAttachments&gt;</i></font>)</li>
<li>{</li>
<li><font color="#990000"><i>&lt;...&gt;</i></font></li>
<li>&nbsp; return <font color="#993300"><i>&lt;value or
object&gt;</i></font> ;<br>
</li>
<li>}</li>
<li>// and</li>
<li><font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font>
.defaultDecoder = <font color="#993300"><i>&lt;SOAPDecoder&gt;</i></font>
;</li>
<li>// or</li>
<li> <font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font>
.setDecoder("<font color="#993300"><i> &lt;namespaceURI&gt;</i></font>
#<font color="#993300"><i> &lt;name&gt;</i></font> ",<font color="#993300"><i>
&lt;SOAPDecoder&gt;</i></font> );</li>
</ul>
<br>
</td>
</tr>
<tr>
<td valign="Top">Map or unmap schema&nbsp; URI aliases<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font>
.mapSchemaURI("<font color="#993300"><i> &lt;external URI&gt;</i></font>
", "<font color="#993300"><i>&lt;internal URI&gt;</i></font>",
<font color="#993300"><i> &lt;true to alias output&gt;</i></font>
);</li>
<li> // or</li>
<li> <font color="#993300"><i>&lt;SOAPEncoding&gt;</i></font>
.unmapSchemaURI("<font color="#993300"><i> &lt;external URI&gt;</i></font>
");</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Register modified or alternative encodings,
making them automatically available to all SOAP scripts in the system<br>
</td>
<td valign="Top">Install an appropriate registerable encoding
in <code> components/<font color="#993300"><i>&lt;new encoding&gt;</i></font>
.js</code><br>
</td>
</tr>
</tbody>
</table>
<h3><a name="3.10_Security_Operations"></a>
3.10 Security Operations</h3>
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. &nbsp;This same restriction applies by default
to SOAP requests executed within the browser. &nbsp;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. &nbsp;Even
if the page was loaded from the user's own hard disk, the script must ask
for permission to make SOAP calls. &nbsp;A browser enhancement is planned
to permit more-precise control of trust between scripts and specific available
services.<br>
<br>
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. &nbsp;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. &nbsp;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.<br>
<br>
<table cellpadding="2" cellspacing="2" border="1" width="100%">
<tbody>
<tr>
<td valign="Top" width="50%">Security Operation<br>
</td>
<td valign="Top">How to Do It<br>
</td>
</tr>
<tr>
<td valign="Top">Mark the call with a verifySourceHeader
so, if the service permits it, the browser can make the call with less
privilege and risk.<br>
</td>
<td valign="Top">
<ul>
<li><font color="#993300"><i>&lt;SOAPCall&gt;</i></font>
.verifySourceHeader = true;</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Request risky privileges within a local
or signed script to make an unverified SOAP calls to other domains.<br>
</td>
<td valign="Top">
<ul>
<li>netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead")</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">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.</td>
<td valign="Top">Add the setting in <code>default/pref/all.js</code>
:<br>
<ul>
<li>pref("<font color="#993300"><i>&lt;some domain prefix&gt;</i></font>
.SOAPCall.invoke","allAccess");</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Modify the security settings in the preferences
file to disallow even dross-domain calls made with verifySource header,
which is generally permitted by default.<br>
</td>
<td valign="Top">Remove or comment out the setting in <code>
default/pref/all.js</code> :<br>
<ul>
<li>pref("capability.policy.default.SOAPCall.invokeVerifySourceHeader","allAccess");</li>
</ul>
</td>
</tr>
<tr>
<td valign="Top">Register alternative transport mechanisms,
making available alternative transports to all scripts and perhaps creating
alternative security models for protocols besides http(s). &nbsp;See
<a href="#4.4_New_Transports_and_Local_Services"> the futures
section</a>
for more info on possible transports.<br>
</td>
<td valign="Top">Install an appropriate registerable
encoding in <code>components/<font color="#993300"><i>&lt;new transport&gt;</i></font>
.js</code>.<br>
</td>
</tr>
</tbody>
</table>
<h3></h3>
<h2><a name="4_Future_Features"></a>
4 Future Features</h2>
<h3><a name="4.1_Access_to_SOAP_as_Proxies"></a>
4.1 Access to SOAP as Proxies</h3>
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. &nbsp;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. &nbsp;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. &nbsp;This higher level is not available in the first release.
&nbsp;When it is available, invoking WSDL-described features gets even easier
and more reliable.<br>
<h3> </h3>
<h3><a name="4.2_Arbitrary_Graphs_of_Data"></a>
4.2 Arbitrary Graphs of Data</h3>
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. &nbsp;This is represented by using an href attribute.
&nbsp;Due to the problems with leaking reference counts in COM objects
with cyclic references, this has not been implemented yet. &nbsp;Also,
the output of a cyclic-referencing set of objects has not been implemented.
&nbsp;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. &nbsp;On input, hrefs are currently ignored.
&nbsp;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.<br>
<h3><a name="4.3_SOAP_With_Attachments"></a>
4.3 SOAP With Attachments</h3>
Many clients and servers now support automatically transmitting
large Mime with a SOAP message by encapsulating it in MIME, DIME, or
other enveloping formats. &nbsp;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.<br>
<h3><a name="4.4_New_Transports_and_Local_Services"></a>
4.4 New Transports and Local Services</h3>
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. &nbsp;These services
require a framework, already being planned, for permitting the browser
to host services as well as being a good client. &nbsp;There are obviously
security issues to be solved to make these successful.<br>
<h3><a name="4.5_Standards"></a>
4.5 Standards</h3>
The interfaces to the objects of this API were designed to be as
simple and universal as possible. &nbsp;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. &nbsp;In such an effort,
changes would be inevitable and welcomed as the price for interoperability
within web clients. &nbsp;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").<br>
<h2><a name="5_Samples_and_Testing"></a>
5&nbsp;Samples and Testing</h2>
Tests and samples exist today can be found in the mozilla tree at <a
href=http://lxr.mozilla.org/seamonkey/source/extensions/xmlextras/tests/>
mozilla/extensions/xmlextras/tests/soap*.html</a>. &nbsp;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.<br>
<br>
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.<br>
<br>
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. &nbsp;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. &nbsp;Adding services is as easy as writing functions
in Javascript, Java, or other supported languages and describing the deployment
in XML. &nbsp;Disclaimer: as this is merely an end-subscriber DSL service,
if the server becomes too widely published, it may have to be shut down.<br>
<br>
SOAP Bugs should be reported using bugzilla.mozilla.org, as a new bug on
Browser, specifying the XML component, and assigned to <a href="mailto:rayw@netscape.com">
rayw@netscape.com</a>
, which is the email address you can use to contact me directly if you have
an issue that cannot be solved in the newsgroup <a href="news:netscape.public.mozilla.xml">
netscape.public.mozilla.xml</a>
or by filing a bug.<br>
<h2><a name="6_Object_Interfaces"></a>
6&nbsp;Object Interfaces</h2>
<h3><a href=http://unstable.elemental.com/mozilla/build/latest/mozilla/extensions/dox/interfacensISOAPBlock.html>SOAPBlock</a></h3>
<h3><a href=http://unstable.elemental.com/mozilla/build/latest/mozilla/extensions/dox/interfacensISOAPCall.html>SOAPCall</a></h3>
<h3><a href=http://unstable.elemental.com/mozilla/build/latest/mozilla/extensions/dox/interfacensISOAPCallCompletion.html>SOAPCallCompletion</a></h3>
<h3><a href=http://unstable.elemental.com/mozilla/build/latest/mozilla/extensions/dox/interfacensISOAPDecoder.html>SOAPDecoder</a></h3>
<h3><a href=http://unstable.elemental.com/mozilla/build/latest/mozilla/extensions/dox/interfacensISOAPEncoder.html>SOAPEncoder</a></h3>
<h3><a href=http://unstable.elemental.com/mozilla/build/latest/mozilla/extensions/dox/interfacensISOAPEncoding.html>SOAPEncoding</a></h3>
<h3><a href=http://unstable.elemental.com/mozilla/build/latest/mozilla/extensions/dox/interfacensISOAPFault.html>SOAPFault</a></h3>
<h3><a href=http://unstable.elemental.com/mozilla/build/latest/mozilla/extensions/dox/interfacensISOAPHeaderBlock.html>SOAPHeaderBlock</a></h3>
<h3><a href=http://unstable.elemental.com/mozilla/build/latest/mozilla/extensions/dox/interfacensISOAPMessage.html>SOAPMessage</a></h3>
<h3><a href=http://unstable.elemental.com/mozilla/build/latest/mozilla/extensions/dox/interfacensISOAPParameter.html>SOAPParameter</a></h3>
<h3><a href=http://unstable.elemental.com/mozilla/build/latest/mozilla/extensions/dox/interfacensISOAPResponse.html>SOAPResponse</a></h3>
<h3><a href=http://unstable.elemental.com/mozilla/build/latest/mozilla/extensions/dox/interfacensISOAPResponseListener.html>SOAPResponseListener</a></h3>
</body>
</html>