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