mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-06 17:16:12 +00:00
1447 lines
73 KiB
HTML
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>
|
|
). <br>
|
|
<br>
|
|
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.</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. 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.<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. 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. <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. 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.
|
|
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. 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.<br>
|
|
<br>
|
|
So the following sample operation:<br>
|
|
|
|
<ul>
|
|
<li><font color="#993300"><i><Foo></i></font> = new
|
|
Foo(<font color="#993300"><i> <FooFact></i></font> );</li>
|
|
<li><font color="#993300"><i><Foo></i></font>.bar =
|
|
<font color="#993300"><i> <any value or object></i></font>
|
|
;</li>
|
|
<li><font color="#993300"><i><Baz></i></font> = <font color="#993300"><i>
|
|
<Foo></i></font>.find("<font color="#993300"><i><name></i></font>
|
|
");</li>
|
|
<li><font color="#993300"><i><find out what you have></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>
|
|
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><SOAPParameter></i></font>
|
|
= new SOAPParameter(<font color="#993300"><i><any value or object></i></font>
|
|
, "<font color="#993300"><i><name></i></font>");</li>
|
|
<li> // or </li>
|
|
<li><font color="#993300"><i><SOAPParameter></i></font>
|
|
= new SOAPParameter();</li>
|
|
<li><font color="#993300"><i><SOAPParameter></i></font>
|
|
.value = <font color="#993300"><i><any value or object></i></font>
|
|
;</li>
|
|
<li> <font color="#993300"><i><SOAPParameter></i></font>
|
|
.name = "<font color="#993300"><i><name></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><SOAPParameter array></i></font>
|
|
= new Array(<font color="#993300"><i><SOAPParameter></i></font>
|
|
<font color="#990000"><i><,...></i></font>);</li>
|
|
<li> // or</li>
|
|
<li><font color="#993300"><i><SOAPParameter array></i></font>
|
|
= new Array();</li>
|
|
<li><font color="#993300"><i><SOAPParameter array></i></font>
|
|
[0] = <font color="#993300"><i><SOAPParameter></i></font>
|
|
;</li>
|
|
<li><font color="#990000"><i><...></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><SOAPCall></i></font>
|
|
= new SOAPCall();</li>
|
|
<li><font color="#993300"><i><SOAPCall></i></font>
|
|
.transportURI = "<font color="#993300"><i><http-based service URI></i></font>
|
|
"</li>
|
|
<li><font color="#993300"><i><SOAPCall></i></font>
|
|
.encode(0, "<font color="#993300"><i><method name></i></font>
|
|
", "<font color="#993300"><i> <target object namespaceURI></i></font>
|
|
", 0, null, <font color="#993300"><i> <SOAPParameter array></i></font>
|
|
.length, <font color="#993300"><i> <SOAPParameter array></i></font>
|
|
);</li>
|
|
|
|
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="Top">Invoke call (send call message
|
|
and receive response message).<br>
|
|
</td>
|
|
<td valign="Top">
|
|
|
|
|
|
<ul>
|
|
<li><font color="#993300"><i><SOAPResponse></i></font>
|
|
= <font color="#993300"><i><SOAPCall></i></font>
|
|
.invoke();</li>
|
|
<li><font color="#993300"><i><process the response
|
|
-- see below></i></font></li>
|
|
<li> // or</li>
|
|
<li> <font color="#993300"><i><SOAPCall></i></font>
|
|
.asyncInvoke(<font color="#993300"><i> <SOAPResponseListener></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><SOAPResponseListener
|
|
name></i></font>(<font color="#993300"><i><SOAPResponse></i></font>
|
|
, <font color="#993300"><i><SOAPCall></i></font>, <font color="#993300"><i>
|
|
<error></i></font>)</li>
|
|
<li>{</li>
|
|
<li> if (error != 0) {</li>
|
|
<li> <font color="#993300"><i><action
|
|
to be taken on failure to transport message></i></font></li>
|
|
<li> }</li>
|
|
<li> <font color="#993300"><i><process the
|
|
response -- see below></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><SOAPFault></i></font>
|
|
= <font color="#993300"><i> <SOAPResponse></i></font>
|
|
.fault;</li>
|
|
<li>if (<font color="#993300"><i><SOAPFault></i></font>
|
|
!= null) {</li>
|
|
<li> <font color="#993300"><i><namespace URI
|
|
string></i></font> = <font color="#993300"><i><SOAPFault></i></font>
|
|
.faultNamespace;</li>
|
|
<li> <font color="#993300"><i><name string></i></font>
|
|
= <font color="#993300"><i><SOAPFault></i></font> .faultCode;</li>
|
|
<li> <font color="#993300"><i><summary string></i></font>
|
|
= <font color="#993300"><i><SOAPFault></i></font> .faultString;</li>
|
|
<li> <font color="#993300"><i><actor URI string></i></font>
|
|
= <font color="#993300"><i><SOAPFault></i></font> .actorURI;</li>
|
|
<li> <font color="#993300"><i><action to be
|
|
taken in case of fault></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><SOAPParameter array></i></font>
|
|
= <font color="#993300"><i><SOAPResponse></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><SOAPParameter
|
|
array></i></font>.length; i++)</li>
|
|
<li>{</li>
|
|
<li> <font color="#993300"><i><SOAPParameter></i></font>
|
|
= <font color="#993300"><i><SOAPParameter array></i></font>
|
|
[i];</li>
|
|
<li> <font color="#993300"><i><value or object></i></font>
|
|
= <font color="#993300"><i><SOAPParameter></i></font> .value;</li>
|
|
<li> <font color="#993300"><i><name string></i></font>
|
|
= <font color="#993300"><i><SOAPParameter></i></font> .name;</li>
|
|
<li> <font color="#993300"><i><checking and
|
|
processing of result></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>
|
|
). 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.<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. 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><SOAPHeaderBlock></i></font>
|
|
= new SOAPHeaderBlock(<font color="#993300"><i><any value or
|
|
object></i></font> , "<font color="#993300"><i><name></i></font>
|
|
", "<font color="#993300"><i> <namespaceURI></i></font> ");</li>
|
|
<li> // or </li>
|
|
<li> <font color="#993300"><i><SOAPHeaderBlock></i></font>
|
|
= new SOAPHeaderBlock();</li>
|
|
<li> <font color="#993300"><i><SOAPHeaderBlock></i></font>
|
|
.value = <font color="#993300"><i><any value or object></i></font>
|
|
;</li>
|
|
<li> <font color="#993300"><i><SOAPHeaderBlock></i></font>
|
|
.name = "<font color="#993300"><i><name></i></font> ";</li>
|
|
<li> <font color="#993300"><i><SOAPHeaderBlock></i></font>
|
|
.namespaceURI = "<font color="#993300"><i><namespaceURI></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><SOAPHeaderBlock></i></font>
|
|
.actorURI = "<font color="#993300"><i><actorURI></i></font>
|
|
";</li>
|
|
<li><font color="#993300"><i><SOAPHeaderBlock></i></font>
|
|
.mustUnderstand = <font color="#993300"><i><true or false></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><SOAPHeaderBlock array></i></font>
|
|
= new Array(<font color="#993300"><i><SOAPHeaderBlock></i></font>
|
|
<font color="#990000"><i><,...></i></font>);</li>
|
|
<li> // or</li>
|
|
<li> <font color="#993300"><i><SOAPHeaderBlock array></i></font>
|
|
= new Array();</li>
|
|
<li> <font color="#993300"><i><SOAPHeaderBlock array></i></font>
|
|
[0] = <font color="#993300"><i><SOAPHeaderBlock></i></font>
|
|
;</li>
|
|
<li> <font color="#990000"><i><...></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><SOAPCall></i></font>
|
|
.encode(0, "<font color="#993300"><i><method name></i></font>
|
|
", "<font color="#993300"><i> <target object namespaceURI></i></font>
|
|
", <font color="#993300"><i><SOAPHeaderBlock array></i></font>
|
|
.length, <font color="#993300"><i><SOAPHeaderBlock array></i></font>
|
|
, <font color="#993300"><i><SOAPParameter array></i></font>
|
|
.length, <font color="#993300"><i><SOAPParameter array></i></font>
|
|
);</li>
|
|
|
|
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="Top">Get returned headers.<br>
|
|
</td>
|
|
<td valign="Top">
|
|
|
|
|
|
<ul>
|
|
<li><font color="#993300"><i><SOAPHeaderBlock array></i></font>
|
|
= <font color="#993300"><i><SOAPResponse></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><SOAPHeaderBlock
|
|
array></i></font>.length; i++)</li>
|
|
<li>{</li>
|
|
<li> <font color="#993300"><i><SOAPHeaderBlock></i></font>
|
|
= <font color="#993300"><i><SOAPHeaderBlock array></i></font>
|
|
[i];</li>
|
|
<li> <font color="#993300"><i><value or object></i></font>
|
|
= <font color="#993300"><i><SOAPHeaderBlock></i></font>
|
|
.value;</li>
|
|
<li> <font color="#993300"><i><name string></i></font>
|
|
= <font color="#993300"><i><SOAPHeaderBlock></i></font>
|
|
.name;</li>
|
|
<li> <font color="#993300"><i><namespace URI
|
|
string></i></font> = <font color="#993300"><i><SOAPHeaderBlock></i></font>
|
|
.namespaceURI;</li>
|
|
<li> <font color="#993300"><i><actor URI string></i></font>
|
|
= <font color="#993300"><i><SOAPHeaderBlock></i></font>
|
|
.actorURI;</li>
|
|
<li> <font color="#993300"><i><must understand
|
|
boolean></i></font> = <font color="#993300"><i><SOAPHeaderBlock></i></font>
|
|
.mustUnderstand;<br>
|
|
</li>
|
|
<li> <font color="#993300"><i><checking and
|
|
processing of result></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. 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><SOAPParameter></i></font>
|
|
= new SOAPHeaderBlock(<font color="#993300"><i><any value or
|
|
object></i></font> , "<font color="#993300"><i><name></i></font>
|
|
", "<font color="#993300"><i> <namespaceURI></i></font> ");</li>
|
|
<li> // or </li>
|
|
<li><font color="#993300"><i><SOAPParameter></i></font>
|
|
.namespaceURI = "<font color="#993300"><i><namespaceURI></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><SOAPCall></i></font>
|
|
.encode(0, "", "", <font color="#993300"><i><header block array></i></font>
|
|
.length, <font color="#993300"><i><header block array></i></font>
|
|
, <font color="#993300"><i> <parameter array></i></font>.length,
|
|
<font color="#993300"><i> <parameter array></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><SOAPParameter array></i></font>
|
|
= <font color="#993300"><i><SOAPResponse></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><SOAPMessage></i></font>
|
|
.actionURI = "<font color="#993300"><i><action URI></i></font>
|
|
";</li>
|
|
<li>// or<br>
|
|
</li>
|
|
<li><font color="#993300"><i><action URI string></i></font>
|
|
= <font color="#993300"><i><SOAPMessage></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><SOAPBlock></i></font>
|
|
.element = <font color="#993300"><i><DOM Element></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><DOM Element></i></font>
|
|
= <font color="#993300"><i><SOAPBlock></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><DOM Element></i></font>
|
|
= <font color="#993300"><i><SOAPMessage></i></font>
|
|
.envelope;</li>
|
|
<li>// OR</li>
|
|
<li><font color="#993300"><i><DOM Element></i></font>
|
|
= <font color="#993300"><i><SOAPMessage></i></font>
|
|
.header;</li>
|
|
<li>// or</li>
|
|
<li><font color="#993300"><i><DOM Element></i></font>
|
|
= <font color="#993300"><i><SOAPMessage></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><SOAPMessage></i></font>
|
|
.message = <font color="#993300"><i><DOM Document></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><DOM Document></i></font>
|
|
= <font color="#993300"><i><SOAPMessage></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><method name string></i></font>
|
|
= <font color="#993300"><i><SOAPMessage></i></font> .methodName;</li>
|
|
<li><font color="#993300"><i><object URI string></i></font>
|
|
= <font color="#993300"><i><SOAPMessage></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><version integer></i></font>
|
|
= <font color="#993300"><i><SOAPMessage></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><SOAPCall></i></font>
|
|
.encode(1, "<font color="#993300"><i><method name></i></font>
|
|
", "<font color="#993300"><i> <target object namespaceURI></i></font>
|
|
", <font color="#993300"><i><SOAPHeaderBlock array></i></font>
|
|
.length, <font color="#993300"><i><SOAPHeaderBlock array></i></font>
|
|
, <font color="#993300"><i><SOAPParameter array></i></font>
|
|
.length, <font color="#993300"><i><SOAPParameter array></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><SOAPCallCompletion></i></font>
|
|
= <font color="#993300"><i><SOAPCall></i></font> .asyncInvoke(<font color="#993300"><i>
|
|
<SOAPResponseListener></i></font>);</li>
|
|
<li><font color="#990000"><i><...></i></font></li>
|
|
<li><font color="#993300"><i><SOAPCallCompletion></i></font>
|
|
.abort();<br>
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="Top">Get the encoding (style) used to encode
|
|
or decode message. Not available on an unencoded call unless explicitly
|
|
set -- use following operation instead.<br>
|
|
</td>
|
|
<td valign="Top">
|
|
|
|
|
|
<ul>
|
|
<li><font color="#993300"><i><SOAPEncoding></i></font>
|
|
= <font color="#993300"><i><SOAPMessage></i></font>
|
|
.encoding;</li>
|
|
|
|
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="Top">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().<br>
|
|
</td>
|
|
<td valign="Top">
|
|
|
|
|
|
<ul>
|
|
<li><font color="#993300"><i><SOAPEncoding></i></font>
|
|
= new SOAPEncoding();</li>
|
|
<li><font color="#993300"><i><SOAPEncoding></i></font>
|
|
= <font color="#993300"><i><SOAPEncoding></i></font>
|
|
.getAssociatedEncoding("<font color="#993300"><i> <style URI></i></font>
|
|
",<font color="#993300"><i><true to create></i></font> );</li>
|
|
<li><font color="#993300"><i><customize encodings></i></font><br>
|
|
</li>
|
|
<li><font color="#993300"><i><SOAPMessage></i></font>
|
|
.encoding = <font color="#993300"><i><SOAPEncoding></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><SOAPEncoding></i></font>
|
|
= <font color="#993300"><i><SOAPEncoding></i></font>
|
|
.getAssociatedEncoding("<font color="#993300"><i> <style URI></i></font>
|
|
",<font color="#993300"><i><true to create></i></font> );</li>
|
|
<li><font color="#993300"><i><SOAPBlock></i></font>
|
|
.encoding = <font color="#993300"><i><SOAPEncoding></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. 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.<br>
|
|
<br>
|
|
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.<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. 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><SchemaCollection></i></font>
|
|
= <font color="#993300"><i><SOAPEncoding></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><SchemaLoader></i></font>
|
|
= <font color="#993300"><i><SchemaCollection></i></font>
|
|
;</li>
|
|
<li>// and then<br>
|
|
</li>
|
|
<li><font color="#993300"><i><SchemaLoader></i></font>
|
|
.load("<font color="#993300"><i> <schema file URI></i></font>
|
|
");</li>
|
|
<li>// or<br>
|
|
</li>
|
|
<li><font color="#993300"><i><SchemaLoader></i></font>
|
|
.loadAsync("<font color="#993300"><i> <schemaURI></i></font>
|
|
", <font color="#993300"><i> <load completion function></i></font>
|
|
);</li>
|
|
|
|
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="Top">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.</td>
|
|
<td valign="Top">
|
|
|
|
|
|
<ul>
|
|
<li><font color="#993300"><i><SchemaType></i></font>
|
|
= <font color="#993300"><i> <SchemaCollection></i></font>
|
|
.getType("<font color="#993300"><i> <name></i></font> ",
|
|
"<font color="#993300"><i> <namespaceURI></i></font> ");</li>
|
|
<li>if (<font color="#993300"><i><schemaType != null)
|
|
{<br>
|
|
</i></font></li>
|
|
<font color="#993300"><i> <li> <font color="#993300"><i>
|
|
<SOAPBlock></i></font> .schemaType = <font color="#993300"><i>
|
|
<SchemaType></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.
|
|
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, separated 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.<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. 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.<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><New DOM Element></i></font>
|
|
= <font color="#993300"><i><SOAPEncoder name></i></font>
|
|
(<font color="#993300"><i> <SOAPEncoding></i></font>, <font color="#993300"><i>
|
|
<value></i></font> , <font color="#993300"><i><namespaceURI></i></font>
|
|
, <font color="#993300"><i> <name></i></font>, <font color="#993300"><i>
|
|
<SchemaType></i></font> , <font color="#993300"><i><SOAPAttachments></i></font>
|
|
, <font color="#993300"><i> <Parent DOM Element></i></font>
|
|
)</li>
|
|
<li>{</li>
|
|
<li><font color="#990000"><i><...></i></font><br>
|
|
</li>
|
|
<li><font color="#993300"><i><DOM Element></i></font>
|
|
= <font color="#993300"><i><Parent DOM Element></i></font>
|
|
.ownerDocument.createElementNS(namespaceURI,name);<br>
|
|
</li>
|
|
<li><font color="#990000"><i><...></i></font><br>
|
|
</li>
|
|
<li> <font color="#993300"><i><Parent DOM Element></i></font>
|
|
.appendChild(<font color="#993300"><i><DOM Element></i></font>
|
|
);<br>
|
|
</li>
|
|
<li> return <font color="#993300"><i><DOM Element></i></font>
|
|
;<br>
|
|
</li>
|
|
<li>}</li>
|
|
<li>// and</li>
|
|
<li><font color="#993300"><i><SOAPEncoding></i></font>
|
|
.defaultEncoder = <font color="#993300"><i><SOAPEncoder></i></font>
|
|
;</li>
|
|
<li>// or</li>
|
|
<li> <font color="#993300"><i><SOAPEncoding></i></font>
|
|
.setEncoder("<font color="#993300"><i> <namespaceURI></i></font>
|
|
#<font color="#993300"><i> <name></i></font> ",<font color="#993300"><i>
|
|
<SOAPEncoder></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><New DOM Element></i></font>
|
|
= <font color="#993300"><i><SOAPDecoder name></i></font>
|
|
(<font color="#993300"><i> <SOAPEncoding></i></font>, <font color="#993300"><i>
|
|
<DOM Element></i></font> , <font color="#993300"><i> <SchemaType></i></font>
|
|
, <font color="#993300"><i> <SOAPAttachments></i></font>)</li>
|
|
<li>{</li>
|
|
<li><font color="#990000"><i><...></i></font></li>
|
|
<li> return <font color="#993300"><i><value or
|
|
object></i></font> ;<br>
|
|
</li>
|
|
<li>}</li>
|
|
<li>// and</li>
|
|
<li><font color="#993300"><i><SOAPEncoding></i></font>
|
|
.defaultDecoder = <font color="#993300"><i><SOAPDecoder></i></font>
|
|
;</li>
|
|
<li>// or</li>
|
|
<li> <font color="#993300"><i><SOAPEncoding></i></font>
|
|
.setDecoder("<font color="#993300"><i> <namespaceURI></i></font>
|
|
#<font color="#993300"><i> <name></i></font> ",<font color="#993300"><i>
|
|
<SOAPDecoder></i></font> );</li>
|
|
|
|
|
|
</ul>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="Top">Map or unmap schema URI aliases<br>
|
|
</td>
|
|
<td valign="Top">
|
|
|
|
|
|
<ul>
|
|
<li><font color="#993300"><i><SOAPEncoding></i></font>
|
|
.mapSchemaURI("<font color="#993300"><i> <external URI></i></font>
|
|
", "<font color="#993300"><i><internal URI></i></font>",
|
|
<font color="#993300"><i> <true to alias output></i></font>
|
|
);</li>
|
|
<li> // or</li>
|
|
<li> <font color="#993300"><i><SOAPEncoding></i></font>
|
|
.unmapSchemaURI("<font color="#993300"><i> <external URI></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><new encoding></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. 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.<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. 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.<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><SOAPCall></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><some domain prefix></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). 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><new transport></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. 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.<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. 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.<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. 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. 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.<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. 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").<br>
|
|
|
|
<h2><a name="5_Samples_and_Testing"></a>
|
|
5 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>. 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. 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.<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 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>
|