<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head profile="http://internetalchemy.org/2003/02/profile">
<link rel="foaf" type="application/rdf+xml" title="FOAF" href="http://www.openlinksw.com/dataspace/uda/about.rdf" />
<link rel="schema.dc" href="http://purl.org/dc/elements/1.1/" />
<meta name="dc.title" content="15. Web Services" />
<meta name="dc.subject" content="15. Web Services" />
<meta name="dc.creator" content="OpenLink Software Documentation Team ; " />
<meta name="dc.copyright" content="OpenLink Software, 1999 - 2009" />
<link rel="top" href="index.html" title="OpenLink Virtuoso Universal Server: Documentation" />
<link rel="search" href="/doc/adv_search.vspx" title="Search OpenLink Virtuoso Universal Server: Documentation" />
<link rel="parent" href="webservices.html" title="Chapter Contents" />
<link rel="prev" href=".html" title="" />
<link rel="next" href="wsdl.html" title="WSDL" />
<link rel="shortcut icon" href="../images/misc/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="doc.css" />
<link rel="stylesheet" type="text/css" href="/doc/translation.css" />
<title>15. Web Services</title>
<meta http-equiv="Content-Type" content="text/xhtml; charset=UTF-8" />
<meta name="author" content="OpenLink Software Documentation Team ; " />
<meta name="copyright" content="OpenLink Software, 1999 - 2009" />
<meta name="keywords" content="" />
<meta name="GENERATOR" content="OpenLink XSLT Team" />
</head>
<body>
<div id="header">
<a name="soap" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>15. Web Services</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="webservices.html">Chapter Contents</a> | <a class="link" href="webservices.html" title="Web Services">Prev</a> | <a class="link" href="wsdl.html" title="WSDL">Next</a>
</div>
</div>
<div id="currenttoc">
<form method="post" action="/doc/adv_search.vspx">
<div class="search">Keyword Search: <br />
<input type="text" name="q" /> <input type="submit" name="go" value="Go" />
</div>
</form>
<div>
<a href="http://www.openlinksw.com/">www.openlinksw.com</a>
</div>
<div>
<a href="http://docs.openlinksw.com/">docs.openlinksw.com</a>
</div>
<br />
<div>
<a href="index.html">Book Home</a>
</div>
<br />
<div>
<a href="contents.html">Contents</a>
</div>
<div>
<a href="preface.html">Preface</a>
</div>
<br />
<div class="selected">
<a href="webservices.html">Web Services</a>
</div>
<br />
<div class="selected">
<a href="soap.html">SOAP</a>
<div>
<a href="#soapovervw" title="Virtuoso SOAP Support Overview">Virtuoso SOAP Support Overview</a>
<a href="#soapcallhandling" title="Handling of SOAP HTTP Requests">Handling of SOAP HTTP Requests</a>
<a href="#dtschsoaps" title="Extending Datatypes for SOAP Objects">Extending Datatypes for SOAP Objects</a>
<a href="#dtsch_inherit" title="Inheritance of Datatypes for SOAP Objects">Inheritance of Datatypes for SOAP Objects</a>
<a href="#dtsoapcplx" title="Complex Types in PL Procedure and UDT Method Definition">Complex Types in PL Procedure and UDT Method Definition</a>
<a href="#dtsch_procdef" title="Complex Types in Procedure Definition using a pre-defined XML Schema datatypes">Complex Types in Procedure Definition using a pre-defined XML Schema datatypes</a>
<a href="#defaultsoapsqltypes" title="Default SOAP-SQL Datatype Mappings">Default SOAP-SQL Datatype Mappings</a>
<a href="#exposingprocsassoaps" title="Exposing Stored Procedures as SOAP Objects">Exposing Stored Procedures as SOAP Objects</a>
<a href="#soapudtproxy" title="Creation of SOAP proxy based on User Defined Types">Creation of SOAP proxy based on User Defined Types</a>
<a href="#exposingudtssoap" title="Exposing User Defined Type Methods as SOAP Objects">Exposing User Defined Type Methods as SOAP Objects</a>
<a href="#exposrmtprocsoap" title="Exposing Remote Third Party SQL Stored Procedures as SOAP Services">Exposing Remote Third Party SQL Stored Procedures as SOAP Services</a>
<a href="#soapclient" title="Virtuoso/PL SOAP Client">Virtuoso/PL SOAP Client</a>
<a href="#execpriv" title="Execution Privileges">Execution Privileges</a>
<a href="#customsoapsrv" title="Custom Soap Server Support">Custom Soap Server Support</a>
<a href="#soapextendedsyntax" title="PL Procedures and UDT Methods Syntax Affecting WSDL & SOAP Processing">PL Procedures and UDT Methods Syntax Affecting WSDL & SOAP Processing</a>
<a href="#soapheadermessages" title="Exposing & Processing SOAP Header Messages">Exposing & Processing SOAP Header Messages</a>
<a href="#soapfaultmessages" title="Exposing & Processing SOAP Fault Messages">Exposing & Processing SOAP Fault Messages</a>
<a href="#soapdoclitenc1" title="Document Literal Encoding">Document Literal Encoding</a>
<a href="#soapdimeenc" title="DIME encapsulation of SOAP messages">DIME encapsulation of SOAP messages</a>
<a href="#soapoptions" title="SOAP Endpoint Options">SOAP Endpoint Options</a>
</div>
</div>
<div>
<a href="wsdl.html">WSDL</a>
</div>
<div>
<a href="vfoafssl.html">WebID Protocol Support</a>
</div>
<div>
<a href="voauth.html">OAuth Support</a>
</div>
<div>
<a href="vwsssupport.html">WS-Security (WSS) Support in Virtuoso SOAP Server</a>
</div>
<div>
<a href="ws-routing.html">Web Services Routing Protocol (WS-Routing)</a>
</div>
<div>
<a href="warm.html">Web Services Reliable Messaging Protocol (WS-ReliableMessaging)</a>
</div>
<div>
<a href="vwstrust.html">Web Services Trust Protocol (WS-Trust)</a>
</div>
<div>
<a href="xmlxmla.html">XML for Analysis Provider</a>
</div>
<div>
<a href="xmlrpc.html">XML-RPC support</a>
</div>
<div>
<a href="syncml.html">SyncML</a>
</div>
<div>
<a href="uddi.html">UDDI</a>
</div>
<div>
<a href="expwsmodules.html">Exposing Persistent Stored Modules as Web Services</a>
</div>
<div>
<a href="vsmx.html">Testing Web Published Web Services</a>
</div>
<div>
<a href="bpel.html">BPEL Reference</a>
</div>
<div>
<a href="xsql.html">XSQL</a>
</div>
<br />
</div>
<div id="text">
<a name="soap" />
<h2>15.1. SOAP</h2>
<p>The Simple Object Access Protocol (SOAP) is a lightweight, extensible,
XML-based application layer protocol for information exchange in a decentralized,
distributed environment.
SOAP defines a framework for message structures and a message processing
model. SOAP also defines a set of encoding rules for serializing data and a
convention for making remote procedure calls. The SOAP extensibility
model provides a foundation for a wide range of composable modules and protocols.
Although the most common way to transport SOAP messages is HTTP, it may also be
run on top of other protocols.</p>
<p>SOAP includes:</p>
<ul>
<li>an envelope that defines a framework for describing what
is in a message and how to process it</li>
<li>a set of encoding rules for expressing instances of
application-defined datatypes</li>
<li>a convention for representing remote procedure calls and responses.</li>
</ul>
<a name="soapovervw" />
<h3>15.1.1. Virtuoso SOAP Support Overview</h3>
<p>
Virtuoso provides a framework for both consuming SOAP services (acting as a
client) and producing them (acting as a server). The Virtuoso web server
has a mechanism for handling SOAP messages and passing them to stored procedures
for processing. Both SOAP 1.0 and SOAP 1.1 messages and data types are supported.
You may use all base SQL data types, as well as heterogeneous arrays, as both arguments and return values of
Virtuoso SOAP services. A full-featured set of functions for handling SOAP objects is provided.
Services using a transport mechanism other than HTTP can also be constructed using the API. The SOAP
framework may be used independently of any of the other web-related services.
</p>
<p>
Virtuoso/PL can also issue requests to SOAP servers. SOAP can be used to access any application
servers, including those running within the Virtuoso server.
</p>
<p>
The Virtuoso SOAP server extends Virtuoso/PL parameter handling by adding complex data types
declared with XML schema as parameter values for stored procedures.
The Virtuoso SOAP server provides
automatic validation of the parameters in requests, based on schema declarations.
</p>
<br />
<a name="soapcallhandling" />
<h3>15.1.2. Handling of SOAP HTTP Requests</h3>
<p>
The Virtuoso web server recognizes SOAP HTTP requests and their
version in the POST method handler. When
<span class="computeroutput">SOAPMethodName</span> or
<span class="computeroutput">SOAPAction</span> HTTP header attributes are present
with <span class="computeroutput">Content-Type: text/xml</span>, the
server initiates SOAP call handling. The XML namespace of the SOAP
method name is stripped off and Virtuoso searches for a stored
procedure with the same name, ignoring case.
</p>
<p> The search is done within the default qualifier of the SQL user
account assigned for SOAP call execution defined for the virtual host.
For example, if the database user assigned in the virtual host's
definition for SOAP execution is called SOAPDBUSER and this user has a
default qualifier 'SOAPDB' and the request contains an
invocation of method called
<span class="computeroutput">OurSoapMethod</span>, Virtuoso would
attempt to find a stored procedure named
<span class="computeroutput">SOAPDB.SOAPDBUSER.OurSoapMethod</span>.
</p>
<p>
When a matching stored procedure is found, any of its parameters that have names matching parameter
entity names in the SOAP call are bound to the call parameter. The parameter name match is also
case-insensitive.
</p>
<p>
Virtuoso maps the procedure parameter datatypes internally
by <a href="sqlrefDATATYPES.html#dtcasting">casting</a>
from XML data (a string) to the declared parameter datatype of the
stored procedure. There is one exception: When an array is being
passed, the server creates an array with values of types inferred from
the XML Schema of its elements.
It is possible to declare that a user defined SQL type be used to represent a
specific XML element in a SOAP request. Thus SQL objects can be constructed
and serialized automatically. Note that this also means that the implementation
of the user defined type instance may be in a hosted language, thus Java or
CLR code may be transparently involved.
</p>
<p>
Two special parameters - <span class="computeroutput">ws_soap_headers</span>
and <span class="computeroutput">ws_http_headers</span> - are available to a
stored procedure handling a SOAP method invocation. If declared as
input parameters for the procedure,
<span class="computeroutput">ws_soap_headers</span> must contain an XML parse tree
of the <span class="computeroutput">SOAP:Header</span> in same format as returned
by <a href="fn_xml_tree.html">xml_tree()</a>.
<span class="computeroutput">ws_http_headers</span> should hold a one-dimensional
array of attribute/value pairs representing the HTTP header fields in
the request.
</p>
<br />
<a name="dtschsoaps" />
<h3>15.1.3. Extending Datatypes for SOAP Objects</h3>
<p>
Complex datatypes can be defined using XMLSchema and represented by WSDL.
Any of the declared types may be used as arguments and return types of
Virtuoso/PL procedures. Any procedures can thus be exposed as SOAP methods.
</p>
<p>
Complex data type definitions are used for values that cannot be contained by
simple scalar datatypes. Typical examples are arrays of scalars, structures
of scalars, arrays of structures or structures of arrays. A complex datatype
may contain scalar and complex datatypes. When a complex type is used in
the definition of another complex type, the definition of the contained complex
type must exist.
</p>
<p>
In addition to 'usual' complex types as structures and arrays Virtuoso implements support for
'choice', 'enumeration', anyType and anyElement and extensions to the simple types.
Inheritance of complex types is also possible and is discussed further in next chapter.
</p>
<p>
The 'nillable' and 'minOccurs' attributes in schema definitions have special meaning
for PL values returned by PL procedure via SOAP. If this attribute is 'true' then
output of NULL values will be serialized in their XML form with XMLSchema instance
attribute 'nil' as 'true'. Otherwise if elements have 'minOccurs' equal to 0 (zero),
the element will be omitted. If minOccurs is equal to 1 (one) an empty element will
be sent to the client. The same algorithm applies to the serialization of PL values
passed as parameters to soap_client() function. Therefore it's important to make
proper use of these attributes when defining complex structures.
</p>
<p>
The '__VOID__' string constant has a special meaning in XMLSchema Datatypes.
It is used to designate no output for return value. In other words returned
value from PL procedure will not be serialized nor exposed in the WSDL file.
</p>
<p>
You define complex datatypes using
<a href="fn_soap_dt_define.html">soap_dt_define()</a>.
The function accepts a schema definition excerpt, based on the element
<span class="computeroutput">complexType</span>. The definition must be a valid XML document.
</p>
<a name="ex_soap_complex_dt_def" />
<div class="example">
<div class="exampletitle">Declaring and using complex datatypes in SOAP</div>
<p>
In this example we define two complex datatypes. The first one, <span class="computeroutput">SOAPStruct</span>,
consists of scalars; the second one, <span class="computeroutput">ArrayOfSOAPStruct</span>, is an array
of these structures. These schema excerpts
are stored in the filesystem as <span class="computeroutput">struct.xsd</span> and <span class="computeroutput">array.xsd</span>.
</p>
<p>
<strong>struct.xsd:</strong>
</p>
<div>
<pre class="programlisting">
<!-- a SOAPStruct type declaration
file name: struct.xsd -->
<complexType name="SOAPStruct"
targetNamespace="http://tempuri.tmp/"
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:tns="services.wsdl">
<sequence>
<element name="varString" type="string" nillable="true"/>
<element name="varInt" type="int" nillable="true"/>
<element name="varFloat" type="float" nillable="true"/>
</sequence>
</complexType>
</pre>
</div>
<p>
<strong>array.xsd:</strong>
</p>
<div>
<pre class="programlisting">
<!-- array of SOAPStruct
file name: array.xsd -->
<complexType name="ArrayOfSOAPStruct"
targetNamespace="http://tempuri.tmp/"
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:tns="services.wsdl">
<complexContent>
<restriction base="enc:Array">
<sequence>
<element name="item" type="tns:SOAPStruct" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<attribute ref="enc:arrayType" wsdl:arrayType="tns:SOAPStruct[]"/>
<attributeGroup ref="enc:commonAttributes"/>
<attribute ref="enc:offset"/>
</restriction>
</complexContent>
</complexType>
</pre>
</div>
<p>
Next, we issue commands to define a new complex datatype. Correct
order is important. (SQL> is the prompt of the Interactive
SQL utility included with Virtuoso and should not be typed)
</p>
<div>
<pre class="programlisting">
SQL> DB..soap_dt_define ('SOAPStruct', file_to_string ('struct.xsd'));
SQL> DB..soap_dt_define ('ArrayOfSOAPStruct', file_to_string ('array.xsd'));
</pre>
</div>
</div>
<div class="note">
<div class="notetitle">Note:</div>
<p>The WSDL specification requires that array names be prefixed with <span class="computeroutput">ArrayOf</span>.</p>
</div>
<br />
<a name="dtsch_inherit" />
<h3>15.1.4. Inheritance of Datatypes for SOAP Objects</h3>
<p>
The Virtuoso SOAP server implements handling of inherited XSD types.
The simple example of such relation between types can be explained as</p>
<div>
<pre class="programlisting">
Type A, also know as the 'base' type,
and type B an extension of A.
+---+ +---+
| a |-->| c |
| b | | d |
+---+ +---+
which can be defined by two separate types without relation
A type B type
+---+ +---+
| a | | a |
| b | | b |
+---+ +- -+
| c |
| d |
+---+
</pre>
</div>
<p>
But when type A has changed, type B will not be changed in second representation.
This is because B is not a relative to A per se. </p>
<p>
To work in such situations Virtuoso SOAP server handles extensions to
XSD types as follows:
</p>
<ol>
<li>each type and base type have defined a User Defined SQL type (UDT).</li>
<li>the XSD types defined for SOAP processing are defined with UDT relation (see soap_dt_define)</li>
<li>the inheritance is declared with 'extension' element in XSD type declaration</li>
</ol>
<p>
When we have these preliminaries the WSDL will declare in 'schema' part of WSDL all
depending types. Furthermore the SOAP processor will handle inherited members of derived types.
</p>
<a name="inhertype" />
<div class="example">
<div class="exampletitle">Declaration and usage of depending types</div>
<p>Consider the following XSD and User Defined Type declaration for a base type
'BaseStruct':
</p>
<div>
<pre class="programlisting">
<!-- XSD type declaration, file base.xsd -->
<complexType name="BaseStruct">
<sequence>
<element name="floatMessage" type="xsd:float"/>
<element name="shortMessage" type="xsd:short"/>
</sequence>
</complexType>
-- corresponding user defined sql type
create type DB.DBA.BaseStruct as (floatMessage real, shortMessage int __soap_type 'short');
</pre>
</div>
<p>Furthermore we are extending the BaseStruct with adding three more elements (members)
with declaration of ExtendedStruct:
</p>
<div>
<pre class="programlisting">
<!-- XSD type declaration, file ext.xsd -->
<complexType name="ExtendedStruct">
<complexContent>
<extension base="tns:BaseStruct">
<sequence>
<element name="stringMessage" type="xsd:string"/>
<element name="intMessage" type="xsd:int"/>
<element name="anotherIntMessage" type="xsd:int"/>
</sequence>
</extension>
</complexContent>
</complexType>
-- corresponding user defined SQL type
create type DB.DBA.ExtendedStruct under DB.DBA.BaseStruct as (
stringMessage nvarchar __soap_type 'string',
intMessage int __soap_type 'int',
anotherIntMessage int __soap_type 'int');
</pre>
</div>
<p>
Once we are done with declarations as XSD files and user defined SQL types,
we must register them as SOAP types for processing:
</p>
<div>
<pre class="programlisting">
SQL> soap_dt_define ('', file_to_string ('base.xsd'), 'DB.DBA.BaseStruct');
SQL> soap_dt_define ('', file_to_string ('ext.xsd'), 'DB.DBA.ExtendedStruct');
</pre>
</div>
<p>
Now we are able to create a PL procedure to use as a SOAP method,
which simply will accept an ExtendedStruct and echo it back to the client.
</p>
<div>
<pre class="programlisting">
create procedure
echoExtendedStruct (in param DB.DBA.ExtendedStruct __soap_type 'http://soapinterop.org/types:ExtendedStruct')
returns DB.DBA.ExtendedStruct __soap_type 'http://soapinterop.org/types:ExtendedStruct'
{
-- All members of DB.DBA.ExtendedStruct and DB.DBA.BaseStruct are available in param.
return param;
}
;
grant execute on echoExtendedStruct to SOAP;
</pre>
</div>
<p>
The SOAP request to that method will be as follows:
</p>
<div>
<pre class="programlisting">
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:m0="http://soapinterop.org/types">
<SOAP-ENV:Body>
<m:echoExtendedStruct xmlns:m="http://soapinterop.org/wsdl">
<param xsi:type="m0:ExtendedStruct">
<floatMessage xsi:type="xsd:float">3.14159</floatMessage>
<shortMessage xsi:type="xsd:short">4096</shortMessage>
<stringMessage xsi:type="xsd:string">String</stringMessage>
<intMessage xsi:type="xsd:int">0</intMessage>
<anotherIntMessage xsi:type="xsd:int">0</anotherIntMessage>
</param>
</m:echoExtendedStruct>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
</pre>
</div>
<p>
The SOAP response to the above request will be as follows:
</p>
<div>
<pre class="programlisting">
<SOAP:Envelope
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:dt="urn:schemas-microsoft-com:datatypes"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
xmlns:ref="http://schemas.xmlsoap.org/ws/2002/04/reference/"
xmlns:ns0="http://soapinterop.org/types" xmlns:wsdl="services.wsdl">
<SOAP:Body>
<cli:echoExtendedStructResponse xmlns:cli="http://soapinterop.org/wsdl">
<CallReturn xsi:type="ns0:ExtendedStruct">
<stringMessage xsi:type="xsd:string">String</stringMessage>
<intMessage xsi:type="xsd:int">0</intMessage>
<anotherIntMessage xsi:type="xsd:int">0</anotherIntMessage>
<floatMessage xsi:type="xsd:float">3.14159</floatMessage>
<shortMessage xsi:type="xsd:short">4096</shortMessage>
</CallReturn>
</cli:echoExtendedStructResponse>
</SOAP:Body>
</SOAP:Envelope>
</pre>
</div>
<div class="note">
<div class="notetitle">Note:</div>
<p>Although the namespace declarations of XSD types are skipped for better
readability, these must be present when declaring (see the Extending Datatypes
for SOAP Objects section, discussed earlier)</p>
</div>
</div>
<br />
<a name="dtsoapcplx" />
<h3>15.1.5. Complex Types in PL Procedure and UDT Method Definition</h3>
<p>
Virtuoso/PL allows parameters to be declared as complex
objects (structures and arrays) without special XMLSchema datatype defined.
To declare a structure as a type of a parameter an UDT must be created
and parameter to have it as datatype reference. Also all permitted
datatypes (including UDTs) could be declared as elements of an ARRAY of unlimited or limited length.
</p>
<p>
Important: when a UDT is used in a SOAP context, it MUST be granted to the
SQL user for SOAP invocation. In other words the user on whose behalf the SOAP
call is processed.
</p>
<a name="ex_dtsoapcplx_1" />
<div class="example">
<div class="exampletitle">Procedure definition with a input and output as a structure</div>
<p>
The following example defines a UDT 'SOAP_Struct'
(containing varchar, integer and float members) and declares
the input parameter and return value of a PL procedure to be of the SOAP_Struct type.
The input will be verified, UDT will be instantiated with given values for members
and it will be echoed back to the client.
</p>
<div>
<pre class="programlisting">
create type SOAP_Struct as (varString varchar, varInt integer, varFloat real);
create procedure echoStruct (in s DB.DBA.SOAP_Struct) returns DB.DBA.SOAP_Struct
{
return s;
};
</pre>
</div>
</div>
<a name="ex_dtsoapcplx_2" />
<div class="example">
<div class="exampletitle">Procedure definition with a input and output as an integer array</div>
<p>
This example declares that input must be an array of integer values
with maximum length of 5. If input or output contains more than five
integers then a SOAP Fault will be sent back to the client containing
an appropriate error message ; otherwise the input array will be echoed back.
</p>
<div>
<pre class="programlisting">
create procedure echoIntArray (in ia integer array[5]) returns integer array[5]
{
return ia;
};
</pre>
</div>
</div>
<a name="ex_dtsoapcplx_3" />
<div class="example">
<div class="exampletitle">Procedure definition with a input and output as a two-dimensional varchar array</div>
<p>
This example declares that the input must be an array of integer array values
with unlimited length. If the input SOAP message contains a valid array following
the current XML encoding rules then an array of integer arrays
(vector containing vectors of integers) will be created and passed to the procedure.
On success the input array will be echoed back to the client.
</p>
<div>
<pre class="programlisting">
create procedure echoIntMulArray (in iaa integer array array) returns integer array array
{
return iaa;
};
</pre>
</div>
</div>
<a name="ex_dtsoapcplx_4" />
<div class="example">
<div class="exampletitle">Procedure definition with a input and output as an struct array</div>
<p>
This example shows how to use an array of structures (UDTs) and also shows
usage of the array type as an member of the structure. The UDT 'SOAP_StructA'
is similar to the those in first example except 4the member which is
an array of integers. This is to demonstrate that arrays are not limited
to the Stored Procedure's parameters declaration, they also can be used
as a type of UDT member.
Upon success the procedure will echo of the input back to the client.
</p>
<div>
<pre class="programlisting">
create type SOAP_StructA as (varString varchar, varInt integer, varFloat real, varArray integer array);
create procedure echoStructArray (in sa DB.DBA.SOAP_StructA array) returns DB.DBA.SOAP_StructA array
{
return sa;
};
</pre>
</div>
<p>
The SOAP request to an endpoint which exposes the echoStructArray as a
document/literal encoded SOAP method would be as follows:
</p>
<div>
<pre class="programlisting">
<?xml version="1.0" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<ns0:echoStructArray xmlns:ns0="http://temp.uri">
<sa>
<item>
<varString>abcd</varString>
<varInt>1234</varInt>
<varFloat>3.14</varFloat>
<varArray>
<item>3</item>
<item>4</item>
</varArray>
</item>
</sa>
</ns0:echoStructArray>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
</pre>
</div>
<p>
The SOAP server will receive and array of one element containing a
structure with string, integer, float and integer array of two elements.
Then the response from the SOAP server to the requestor will be:
</p>
<div>
<pre class="programlisting">
<?xml version="1.0" ?>
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP:Body>
<cli:echoStructArrayResponse xmlns:cli="http://temp.uri">
<CallReturn>
<item>
<varString>abcd</varString>
<varInt>1234</varInt>
<varFloat>3.14</varFloat>
<varArray>
<item>3</item>
<item>4</item>
</varArray>
</item>
</CallReturn>
</cli:echoStructArrayResponse>
</SOAP:Body>
</SOAP:Envelope>
</pre>
</div>
</div>
<p>
See also the WSDL file generation section for details how such PL procedures with parameters of
complex datatypes are exposed via SOAP enabled virtual HTTP directories.
</p>
<br />
<a name="dtsch_procdef" />
<h3>15.1.6. Complex Types in Procedure Definition using a pre-defined XML Schema datatypes</h3>
<p>
Declaration of a complex datatype as a parameter is done by adding a special
keyword <span class="computeroutput">__soap_type</span> followed by the name of the defined complex
type after normal parameter declaration in the parameter list. The type name is given
as a string literal. The same syntax extension also applies to declaration of the return type.
This is shown in the following example.
</p>
<a name="ex_soap_complex_parm_proc_def" />
<div class="example">
<div class="exampletitle">Procedure Definition with Complex Datatype Parameters</div>
<p>
We create a procedure that will accept an array of structures (as defined in the previous example) and
return it to the client. It instructs the WSDL generator to assign <span class="computeroutput">ArrayOfSOAPStruct</span> as
the input parameter and return value types when
<span class="computeroutput">WS.SOAP.echoSOAPArray()</span> is exposed as a
SOAP method. The type information is available to SOAP clients that read the WSDL description.
Upon receiving an incoming SOAP request, Virtuoso converts the XML
representation of the data, after validation, to the
form <span class="computeroutput">vector(vector([varchar],[integer],[real]), ...)</span> and passed to the
<span class="computeroutput">WS.SOAP.echoSOAPArray</span>. Failed parameter validation is reported to the client.
</p>
<div>
<pre class="programlisting">
SQL> CREATE PROCEDURE WS.SOAP.echoSOAPArray (in inArray any __soap_type 'ArrayOfSOAPStruct')
RETURNS any __soap_type 'ArrayOfSOAPStruct'
{
return inArray;
};
</pre>
</div>
</div>
<br />
<a name="defaultsoapsqltypes" />
<h3>15.1.7. Default SOAP-SQL Datatype Mappings</h3>
<p>
When no alternative datatype is assigned, the WSDL generator and SOAP server
will use the default mapping described below:
</p>
<table class="data">
<caption>Table: 15.1.7.1. Default datatype mappings in SOAP</caption>
<tr>
<th class="data">Datatype</th>
<th class="data">Maps to</th>
</tr>
<tr>
<td class="data">integer</td>
<td class="data">xsd:int</td>
</tr>
<tr>
<td class="data">real</td>
<td class="data">xsd:float</td>
</tr>
<tr>
<td class="data">double precision</td>
<td class="data">xsd:double</td>
</tr>
<tr>
<td class="data">numeric</td>
<td class="data">xsd:decimal</td>
</tr>
<tr>
<td class="data">datetime</td>
<td class="data">xsd:timeInstant</td>
</tr>
<tr>
<td class="data">any other type</td>
<td class="data">xsd:string</td>
</tr>
</table>
<br />
<p>The REAL SQL type is mapped to the xsd:float SOAP datatype by default
and so loss of precision can occur. To improve the precision, the SOAP
server will map the xsd:float to the PL double precision datatype instead,
but only if the SOAP type is specified. The explicit declaration of
__soap_type 'xsd:float' is required to instruct Virtuoso to use the mapping
to double precision.</p>
<p>All strings from a SOAP request declared with the SOAP datatype
xsd:string will be treated as NVARCHARs on input. All string data such a
CHAR, VARCHAR, or NVARCHAR will be encoded as UTF-8 in a SOAP response.
This makes processing of wide character sets in SOAP operations possible.</p>
<p>If a User Defined Type (UDT) is used as a type of parameter and no
explicit XML Schema datatype given (see special syntax for PL procedures)
then in WSDL will be included as a struct definition. Further upon
SOAP processing the input struct will be encoded as a UDT instance and passed
to the given PL procedure.
</p>
<p>
The parameters which are declared as an array (see PL procedure syntax)
and having no explicit XML Schema datatype given will be exposed as
array by means of SOAP encoding rules (see also 'Use' SOAP option to the
virtual directory).
</p>
<p>Some SOAP applications need a void return as opposed to an empty return,
from SOAP operations. To distinguish the empty return from the void return
a special SOAP datatype '__VOID__' has been introduced. This will cause
the SOAP server to omit the procedure return value when responding to a
SOAP request. Also, the return message will be discarded from the
WSDL description file.</p>
<br />
<a name="exposingprocsassoaps" />
<h3>15.1.8. Exposing Stored Procedures as SOAP Objects</h3>
<p>
The special physical path <span class="computeroutput">/SOAP/</span> in the Virtuoso
Web server is reserved for SOAP objects. Virtuoso makes available any
stored procedure created in the default qualifier of the SOAP user,
with execution privileges granted to the SOAP user.
You can also use Virtuoso's <a href="webserver.html#virtdir">virtual
host</a> mechanism to create new logical paths for accessing SOAP
objects. A logical path property <span class="computeroutput">soap_user</span>
determines the db user for SOAP. If a logical path points to the
<span class="computeroutput">/SOAP/</span> special physical path, it will expose any
procedures created in the default qualifier of, and with execution
privileges to, <span class="computeroutput">soap_user</span> to the world as SOAP
objects.
</p>
<p>If the physical path of <span class="computeroutput">/SOAP</span>
exists under the VSP root directory
then any non-SOAP specific HTTP requests will be directed there for content.
This can be useful for helping to establish the presence and location of a SOAP
endpoint - some applications attempt a standard HTTP connection first.
You might configure a virtual directory, intended for SOAP, with a
default page referencing a description of the SOAP endpoint, a page
in the <VSPROOT>/SOAP directory, preventing an
<span class="computeroutput">HTTP 404</span> style error misleading an
application into believing the SOAP endpoint is down regardless of whether
it tried to talk SOAP to it or not.</p>
<div class="note">
<div class="notetitle">Note:</div>
<p>
Procedures exposed as SOAP procedures run as any other stored procedure in Virtuoso
and can call and get return values from other procedures and functions not exposed through SOAP.
The ability to execute procedures attached from remote data sources facilitates
SOAP-enabling existing database applications in a heterogeneous environment.
</p>
</div>
<a name="ex_soap_new_vhost" />
<div class="example">
<div class="exampletitle">Creating a new virtual host for SOAP execution</div>
<p>
Create new user in the database for SOAP:
</p>
<div>
<pre class="screen">
SQL>CREATE USER SOAPDEMO;
</pre>
</div>
<p>
Set the default catalogue/qualifier for the new user to WS. This is where
procedures to be used as SOAP objects will be created:
</p>
<div>
<pre class="screen">
SQL>USER_SET_QUALIFIER ('SOAPDEMO', 'WS');
</pre>
</div>
<p>
Create a new virtual host definition, using
<a href="fn_vhost_define.html">vhost_define()</a>.
</p>
<div>
<pre class="screen">
SQL>VHOST_DEFINE (vhost=>'*ini*',lhost=>'*ini*',lpath=>'/mysoapdomain',ppath=>'/SOAP/',soap_user=>'SOAPDEMO');
</pre>
</div>
<p>
An existing mapping could be removed using the command:
</p>
<div>
<pre class="screen">
SQL>VHOST_REMOVE (vhost=>'*ini*',lhost=>'*ini*',lpath=>'/mysoapdomain')
</pre>
</div>
<div class="note">
<div class="notetitle">Note:</div>
<p>
'<span class="computeroutput">*ini*</span>' is a special value that instructs Virtuoso to use the default
values from the Virtuoso initialization file.
</p>
</div>
<p>
All procedures that are created with the WS.SOAPDEMO qualifier and then
granted execution to SOAPDEMO will be visible to SOAP.
Make a simple SOAPTEST procedure and grant the appropriate
privileges to the SOAPDEMO user:
</p>
<div>
<pre class="screen">
SQL> create procedure
WS.SOAPDEMO.SOAPTEST (in par varchar)
{
return (upper(par));
};
SQL> grant execute on WS.SOAPDEMO.SOAPTEST to SOAPDEMO;
</pre>
</div>
<p>
The SOAP object may now be tested by
using the <a href="fn_soap_client.html">soap_client()</a>
function, which returns a vector representation of
the SOAP object returned by the call. The example below simply extracts
the returned string with <a href="fn_aref.html">aref()</a>, as
the exact format of the object returned is known:
</p>
<div>
<pre class="screen">
SQL>select aref(aref(
soap_client (url=>sprintf ('http://localhost:%s/mysoapdomain', server_http_port ()),
operation=>'SOAPTEST',
parameters=>vector('par', 'demotext')),
1), 1);
callret
VARCHAR
_______
DEMOTEXT
</pre>
</div>
<p>
Printing the output on the console or server log with
<a href="fn_dbg_obj_print.html">dbg_obj_print()</a> would
output something like:
</p>
<div>
<pre class="screen">
(("SOAPTESTResponse" ) (("CallReturn" ) "DEMOTEXT" ) )
</pre>
</div>
<p>
The automatic service description generation can be verified by retrieving
<span class="computeroutput">http://<server:port>/mysoapdomain/services.wsdl</span>,
and preferably tested by pointing a web browser at
<span class="computeroutput">http://<server:port>/mysoapdomain/services.vsmx</span>
</p>
<div>
<pre class="screen">
SQL> select http_get (sprintf ('http://localhost:%s/mysoapdomain/services.wsdl', server_http_port()));
callret
VARCHAR
_______________________________________________________________________________
<?xml version="1.0"?>
<definitions
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:s="services.wsdl"
xmlns:tns="services.wsdl"
targetNamespace="services.wsdl"
name="VirtuosoSOAP" xmlns="http://schemas.xmlsoap.org/wsdl/">
<types>
<schema targetNamespace="services.wsdl"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
<complexType name="echoStringArrayResponse">
<sequence>
<element name="return" type="ArrayOfstring_literal"/>
</sequence>
</complexType>
<complexType name="echoVoid"/>
<complexType name="ArrayOffloat">
<complexContent>
<restriction base="soapenc:Array">
<sequence>
<element name="item" type="float" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<attributeGroup ref="soapenc:commonAttributes"/>
<attribute ref="soapenc:offset" />
<attribute ref="soapenc:arrayType" wsdl:arrayType="float[]"/>
</restriction>
</complexContent>
</complexType>
<complexType name="SOAPStruct">
<sequence>
<element name="varString" type="string"/>
<element name="varInt" type="int"/>
<element name="varFloat" type="float"/>
</sequence>
</complexType>
<complexType name="echoStructResponse">
<sequence>
<element name="return" type="SOAPStruct"/>
</sequence>
</complexType>
<complexType name="echoVoidResponse"/>
<complexType name="ArrayOfString2D">
...
</pre>
</div>
</div>
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>
<a href="vsmx.html">Testing Web Services using VSMX</a>
</p>
</div>
<br />
<a name="soapudtproxy" />
<h3>15.1.9. Creation of SOAP proxy based on User Defined Types</h3>
<p>It is possible to automatically generate PL procedures or UDT classes for invoking a remote SOAP service.
</p>
<div class="tip">
<div class="tiptitle">See Also</div>
<p>The <a href="fn_wsdl_import_udt.html">WSDL_IMPORT_UDT()</a> function for details and examples.</p>
</div>
<p>The proxy-creation function <span class="computeroutput">WSDL_IMPORT_UDT()</span> performs the following purposes:</p>
<ul>
<li>retrieve and expand the WSDL file published by the end point to be called</li>
<li>compile the result and make SQL script with UDT definition</li>
<li>generate and register XML Schema definition for special types used in the source service</li>
<li>optionally execute the SQL script generated</li>
</ul>
<p>Once such UDT SOAP proxy is defined it can be used within application code
or be re-exposed as a SOAP service on local server instance (see next chapter how to
expose UDT as service).
</p>
<div class="tip">
<div class="tiptitle">See Also</div>
<p>The Virtuoso Administration Interface provides a web based
interface for importing WSDL definitions and creating UDTs and procedures.
This can be found in the <a href="htmlconductorbar.html#admiui.wsdl">Virtuoso Server Administration
Interface</a> Chapter.</p>
</div>
<br />
<a name="exposingudtssoap" />
<h3>15.1.10. Exposing User Defined Type Methods as SOAP Objects</h3>
<p>
SQL User Defined Types may define methods. In context of
Virtuoso SOAP server they can be exposed as SOAP methods.
To do that the UDT must be published at an endpoint. So publishing could be done in
two ways: using SQL INSERT statement or using Admin UI: Publishing UI via
Virtual directories section.
</p>
<p>
The published UDTs will then expose all methods to the given virtual directory
assigned for SOAP execution. In this case the default constructor will be called
for method invocation if the UDT method is non-static.
</p>
<p>
Note: The method definitions may also contains special SOAP syntax for XML Schema datatypes, using the same options as
for PL procedures. (see "PL Procedures and UDT Methods Syntax Affecting WSDL & SOAP Processing" section for details)
</p>
<p>
The following table specifies which UDTs are published at which end points.</p>>
<div>
<pre class="programlisting">
create table SYS_SOAP_UDT_PUB
(SUP_CLASS varchar, -- name of the published UDT, referencing SYS_USER_TYPES.UT_NAME
SUP_LHOST varchar, -- listen host, referencing HTTP_PATH.HP_LISTEN_HOST
SUP_HOST varchar, -- virtual host, referencing HTTP_PATH.HP_HOST
SUP_END_POINT varchar, -- logical path, referencing HTTP_PATH.HP_LPATH
primary key (SUP_LHOST, SUP_HOST, SUP_END_POINT, SUP_CLASS))
;
</pre>
</div>
<a name="ex_soap_expose_udt" />
<div class="example">
<div class="exampletitle">Exposing a UDT Method using SQL statement</div>
<p>
The below code creates a UDT containing two methods: static and non-static
and exposes them on a virtual directory '/soap-udt'
</p>
<div>
<pre class="programlisting">
create user SOAP_U2;
VHOST_DEFINE (lpath=>'/soap-udt', ppath=>'/SOAP/', soap_user=>'SOAP_U2',
soap_opts=>
vector ('ServiceName', 'UDT',
'Namespace', 'http://temp.uri',
'SchemaNS', 'http://temp.uri',
'MethodInSoapAction', 'yes',
'elementFormDefault', 'unqualified',
'Use', 'encoded')
);
create type MyWebSvc
static method echoStatInt (in a int) returns int,
method echoInt (in a int) returns int;
create static method echoStatInt (in a int)
returns int for MyWebSvc
{
return a;
}
;
create method echoInt (in a int)
returns int for MyWebSvc
{
return a;
}
;
-- Important: without grant publishing is not final as
-- user for SOAP invocation will not have permissions to instantiate the UDT nor
-- to call its methods
grant execute on MyWebSvc to SOAP_U2;
-- exposing the UDT methods to the /soap-udt endpoint
insert soft SYS_SOAP_UDT_PUB values ('MyWebSvc', '*ini*', '*ini*', '/soap-udt');
</pre>
</div>
</div>
<p>
Exposing the methods of a UDT could be done using Admin UI/Virtual Directories:
Create a new or edit an existing SOAP enabled virtual directory and navigate to the
SOAP options section, click on the 'Publish' button and from presented list of
Database qualifiers select the qualifier containing target UDT, then select
it from the User Defined Types list and follow the wizard.
</p>
<br />
<a name="exposrmtprocsoap" />
<h3>15.1.11. Exposing Remote Third Party SQL Stored Procedures as SOAP Services</h3>
<p>Virtuoso can expose any of its available PL resources to the SOAP
world. This includes data from remote attached tables and procedures. To do this, one needs to
write a wrapper procedure in Virtuoso/PL.</p>
<a name="ex_exposrmtprocsoap" />
<div class="example">
<div class="exampletitle">Exposing a MS SQL Server procedure to SOAP using Virtuoso</div>
<p>Here we have a sample MS SQL Server procedure and an accompanying Virtuoso wrapper
function. The MS SQL Server function returns a result set based on a simple join
query with a filter input. The Virtuoso procedure calls the remote procedure,
iterates through the result set returned and produces XML output. First the MS SQL Server procedure:
</p>
<div>
<pre class="programlisting">
create procedure ms_remote
@mask varchar(15)
as
select c.CustomerID, c.CompanyName, o.OrderDate,
o.ShippedDate,ol.ProductID, ol.Quantity, ol.Discount
from Northwind..Customers c
inner join Northwind..Orders o on c.CustomerID = o.CustomerID
inner join Northwind.."Order Details" ol on o.OrderID = ol.OrderID
where c.CustomerID like @mask
;
</pre>
</div>
<p>Then the Virtuoso wrapper function:</p>
<div>
<pre class="programlisting">
create procedure WS.SOAP.ms_remote_call (
in dsn varchar, in uid varchar, in pwd varchar, in mask varchar)
{
declare m, r, ses any;
vd_remote_data_source (dsn, '', uid, pwd);
rexecute (dsn, 'ms_remote ?', null, null, vector (mask), 1000, m, r);
ses := string_output ();
http ('<?xml version="1.0" ?>\n<remote>\n', ses);
if (isarray(m) and isarray (r))
{
declare i, l, j, k integer;
declare md, rs any;
md := m[0];
i := 0; l := length (md); k := length (r); j := 0;
while (j < k)
{
http ('<record ', ses);
i:=0;
while (i < l)
{
dbg_obj_print (md[i][0],r[j][i]);
http (sprintf (' %s="%s"', trim(md[i][0]), trim(cast (r[j][i] as varchar))), ses);
i := i + 1;
}
http (' />\n', ses);
j := j + 1;
}
}
http ('</remote>', ses);
return string_output_string (ses);
};
</pre>
</div>
<p>
Now, as before, we grant execute rights to the SOAP user:
</p>
<div>
<pre class="screen">
grant execute on WS.SOAP.ms_remote_call to SOAP;
</pre>
</div>
<p>
The remote procedure <span class="computeroutput">ms_remote()</span> can now be accessed via SOAP.
</p>
</div>
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>The <a href="">Virtual Database</a> chapter for information regarding use of
remote datasources and their tables.</p>
</div>
<br />
<a name="soapclient" />
<h3>15.1.12. Virtuoso/PL SOAP Client</h3>
<p>
Virtuoso has generic SOAP client functionality. This was demonstrated in an example
above, where we showed that we had correctly exposed a stored procedure
as a SOAP object. The entry point to the SOAP client is
<a href="fn_soap_client.html">soap_client ()</a>.
</p>
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>
<a href="">Importing A WSDL File</a>
</p>
</div>
<br />
<a name="execpriv" />
<h3>15.1.13. Execution Privileges</h3>
<p>
<a href="webserver.html#virtandmultihosting">Virtual directory</a> mappings allow you to define a
specific database user on behalf of which to execute code invoked via SOAP. By
default Virtuoso disables SOAP calls unless the database account
'SOAP' exists or a virtual directory mapping is
defined for SOAP call execution. If we map a logical HTTP path to <span class="computeroutput">/SOAP</span> and
specify the user 'demo' as the SOAP user then stored procedures or UDT methods will be executed
with demo's privileges.
</p>
<br />
<a name="customsoapsrv" />
<h3>15.1.14. Custom Soap Server Support</h3>
<p>
Virtuoso allows any VSP page to act as a SOAP endpoint.
This permits preprocessing of the SOAP requests to extract
additional information - such as one placed for ebXML - and
conversion of the SOAP replies to put any additional information in them.
SOAP messages with attachments can also be processed this way.
</p>
<p>
SOAP extensions, such as the ones required for ebXML, can be programmed
as VSP services that can handle the additional information contained in the
SOAP requests. The <a href="fn_xpath_eval.html">xpath_eval()</a> function
is useful here. The SOAP server could be called
after removing extension information; this removal could be done with an XSL transformation.
After the SOAP request is processed, additional information can be
placed in the result by another XSL transformation.
</p>
<p>
Having a SOAP server outside the <span class="computeroutput">/SOAP</span> physical
path allows a greater degree of
control over what procedures are executed by providing a list of mappings.
Having this suite of functions allows SOAP requests to be processed outside an
HTTP context (for example after doing <span class="computeroutput">mime_tree()</span> over an e-mail) and sending
the SOAP replies as SMTP messages.
</p>
<p>
The following built-in functions are relevant in this context:
</p>
<p>
<a href="fn_soap_server.html">soap_server()</a>
</p>
<p>
<a href="fn_soap_make_error.html">soap_make_error()</a>
</p>
<p>
<a href="fn_soap_box_xml_entity.html">soap_box_xml_entity()</a>
</p>
<p>
<a href="fn_soap_print_box.html">soap_print_box()</a>
</p>
<p>
<a href="fn_http_body_read.html">http_body_read()</a>
</p>
<a name="soap1.1server" />
<div class="example">
<div class="exampletitle">Sample SOAP 1.1 server</div>
<div>
<pre class="screen">
<?vsp
dbg_obj_print ('vspsoap called');
declare content_type, soap_method, soap_xml varchar;
declare payloads any;
-- get the encoding to find out where the SOAP request should be searched for
content_type := http_request_header (lines, 'Content-Type');
if (isstring (content_type))
content_type := lower (content_type);
-- get the SOAP method name to execute
soap_method := http_request_header (lines, 'SOAPAction');
soap_xml := NULL;
payloads := NULL;
-- get the SOAP request
if (content_type = 'multipart/related')
{
-- as in SOAP messages with attachments
declare attrs any;
declare inx integer;
declare start_req varchar;
-- the SOAP body is in the root part
-- so get the root part's name
start_req := http_request_header (lines, 'Content-Type', 'start');
-- loop over the parts and get the root one.
-- Others are placed in the payload array
inx := 1;
soap_xml := null;
attrs := vector (1);
while (isarray (attrs))
{
declare content_id varchar;
-- get the part's MIME header
attrs := get_keyword (sprintf ('attr-mime_part%d', inx), params);
if (isarray (attrs))
{
-- extract the Content-ID from it
content_id := get_keyword ('Content-ID', attrs);
dbg_obj_print ('cont-id', content_id);
if (isstring (content_id))
{
-- if it is the root part (SOAP request) parse it.
if (content_id = start_req)
soap_xml := xml_tree_doc (xml_tree (
get_keyword (sprintf ('mime_part%d', inx), params)));
else
{
-- otherwise consider it a payload and store a info about the payload
-- for later retrieval by get_keyword () VSE based on Content-ID
if (payloads is null)
payloads := vector (vector (content_id, inx));
else
payloads := vector_concat (payloads, vector (content_id, inx));
}
}
}
inx := inx + 1;
}
}
else if (content_type = 'text/xml')
{
-- it's a SOAP request without attachments
-- so get the POST body and parse it.
soap_xml := xml_tree_doc (xml_tree (http_body_read ()));
}
else
signal ('42000', 'unsupported encoding');
-- the things retrieved so far
dbg_obj_print ('vspsoap message', soap_xml);
dbg_obj_print ('vspsoap payloads', payloads);
-- execute the message
-- catch any subsequent SQL error and generate and return SOAP reply XML for it.
declare exit handler for SQLSTATE '*' {
dbg_obj_print ('vspsoap in error handler for ', __SQL_MESSAGE);
declare err_msg varchar;
err_msg := soap_make_error ('300', __SQL_STATE, __SQL_MESSAGE);
dbg_obj_print ('vspsoap error', err_msg);
http (err_msg);
-- note the SOAP SQL state - this is required since based on this value the
-- HTTP server will not generate any additional reply if the SQL state starts with SOAP
-- and this way the client will get a properly formatted reply
resignal 'SOAP';
};
-- now check what is required and act accordingly
if (soap_method = 'ebXML')
{
signal ('42000', 'ebXML not implemented yet');
}
else if (soap_method in ('fake#test'))
{
declare res any;
-- note the mapping here : the SOAP call to fake:test will result in a
-- call to DB.DBA.SOAPTEST PL procedure and it's results returned.
res := soap_server (soap_xml, soap_method, lines, 11,
vector ('fake:test', 'DB.DBA.SOAPTEST'));
dbg_obj_print ('vspsoap result', res);
http (res);
}
else
{
-- simple signal will do as this will be cached by the handler
-- and formatted as an SOAP error XML
signal ('42000', concat ('Procedure ', soap_method, ' not defined'));
}
?>
</pre>
</div>
</div>
<br />
<a name="soapextendedsyntax" />
<h3>15.1.15. PL Procedures and UDT Methods Syntax Affecting WSDL & SOAP Processing</h3>
<p>Special PL syntax can be applied to any of the parameters (including the
return value) in a declaration. All of these begins with __SOAP_ prefix and
have special meaning. To manipulate more than the XMLSchema type
representation and SOAP encoding style, extended syntax is available. With
this syntax we can further override the default request/response namespace,
name of the output elements, "soapAction" corresponding to the PL procedure
and such.</p>
<p>The syntax is as follows:</p>
<div>
<pre class="programlisting">
...
CREATE (PROCEDURE|METHOD) ([param_decl [rout_alt_type]] ...) { [BODY] } [RETURNS ....] [rout_alt_type]
...
rout_alt_type
: /* no SOAP options */
| soap_kwd STRING opt_soap_enc_mode /* the basic syntax */
| __SOAP_OPTIONS '(' soap_kwd EQUALS STRING opt_soap_enc_mode ',' soap_proc_opt_list ')'/* extended syntax */
;
soap_proc_opt_list
: soap_proc_opt
| soap_proc_opt_list ',' soap_proc_opt
;
soap_proc_opt /* extension options as PartName:='part2' */
: NAME EQUALS signed_literal
;
soap_kwd
: __SOAP_TYPE /* denotes XML datatype, RPC encoding style if applied to the procedure */
| __SOAP_HEADER /* the parameter is a message in the SOAP Header */
| __SOAP_FAULT /* the parameter is a message in SOAP Fault */
| __SOAP_DOC /* applies to the procedure, free-form of encoding (literal) */
| __SOAP_XML_TYPE /*applies to the parameters, the input will be XML tree */
| __SOAP_DOCW /* applies to the procedure, literal encoding in style like RPC */
| __SOAP_HTTP /* HTTP GET/POST binding will be used */
;
opt_soap_enc_mode /* which part of traffic will be encapsulated and in what way : DIME or MIME */
: /* no encapsulation */
| __SOAP_DIME_ENC IN
| __SOAP_DIME_ENC OUT
| __SOAP_DIME_ENC INOUT
| __SOAP_MIME_ENC IN
| __SOAP_MIME_ENC OUT
| __SOAP_MIME_ENC INOUT
;
param_decl
: (IN|OUT|INOUT) param_name data_type_ref [(DEFAULT|:=) literal]
;
data_type_ref
: (data_type_name|udt_name) [ARRAY [intnum] ...]
;
</pre>
</div>
<p>The above syntax can be applied to the parameter and to the whole
procedure, so both places designate different purposes and limitations.
When it is applied to the parameter the following keywords can be used:
__SOAP_TYPE, __SOAP_HEADER, __SOAP_FAULT and __SOAP_XML_TYPE.
The __SOAP_TYPE means that only XSD type will be used to interpret the data,
in contrast __SOAP_XML_TYPE designates no deserialization from XML, only
parses the parameter XML representation to XML tree and passes it to the
procedure. The __SOAP_HEADER and __SOAP_FAULT designate that parameter
will be exposed in the SOAP Header or in the SOAP Fault elements. In the
second case, that parameter needs to be an 'OUT' parameter (not IN or INOUT).
The string after these keywords always denotes the XSD type for SOAP serialization.
When it is applied to the PL procedure (after procedure's body), the
__SOAP_TYPE, __SOAP_DOC, __SOAP_DOCW, __SOAP_HTTP, __SOAP_DIME_ENC and
__SOAP_MIME_ENC can be used. The string after these keywords always denotes
the XSD type for SOAP serialization, except __SOAP_DIME_ENC and __SOAP_MIME_ENC
which are used for other purposes and can be combined with other keywords.
The __SOAP_TYPE denotes RPC style encoding, __SOAP_DOC for document literal
(bare parameters) encoding, __SOAP_DOCW for the free-form literal (wrapped)
encoding. __SOAP_HTTP is used to denote HTTP style binding instead of SOAP
one, in that way procedure can be called via HTTP GET/POST methods without
SOAP XML encoding. </p>
<p>The following keywords are supported as extended options:</p>
<ul>
<li>
<strong>PartName</strong> - changes the name of a OUT parameter
to the string as specified, affects WSDL generation and SOAP serialization.</li>
<li>
<strong>RequestNamespace</strong> - designate namespace for
the message in the request, affects header, fault and body WSDL declaration,
and serialization of SOAP in RPC encoding style.</li>
<li>
<strong>ResponseNamespace</strong> - the same as RequestNamespace,
but for SOAP response and output in WSDL declaration.</li>
<li>
<strong>soapAction</strong> - sets the 'soapAction' attribute
in WSDL generation, can be applied to the procedure only.</li>
</ul>
<p>The RequestNamespace and ResponseNamespace can be used only for
the procedure and together with the __SOAP_FAULT and __SOAP_HEADER keywords.</p>
<p>The 'ARRAY' modifier to the SQL datatype is allowed when no XML Schema datatype is
assigned to the given parameter of the PL procedure or UDT method. In this case
the input and output value will be verified to confirm to the rules applicable for
an array. Furthermore in this case an XSD definition will be added in the WSDL
file at run time.
</p>
<a name="ex_soapextsynt" />
<div class="example">
<div class="exampletitle">SOAP Extension</div>
<p>This example shows both approaches to define parameters and
SOAP encoding style. In practice this definition is part of the Interop tests
round 4 (group H). The meaning of this is: the SOAP operation is uses RPC
encoding style, 'whichFault' is integer, 'param1' and 'param2' are strings.
The out parameters 'part2_1' and 'part2_2' will be printed in SOAP:Fault element
(see Exposing & Processing SOAP Fault Messages for more
details). The interesting fact is that the last two parameters will be serialized
as "part2" in different namespaces. And finally no return of the SOAP
operation is defined (it's empty). </p>
<div>
<pre class="programlisting">
create procedure
"echoMultipleFaults3" (
in whichFault int __soap_type 'http://www.w3.org/2001/XMLSchema:int',
in param1 varchar __soap_type 'http://www.w3.org/2001/XMLSchema:string',
in param2 varchar __soap_type 'http://www.w3.org/2001/XMLSchema:string',
out part2_1 varchar __soap_options (
__soap_fault:='http://www.w3.org/2001/XMLSchema:string',
PartName:='part2',
ResponseNamespace:='http://soapinterop.org/wsdl/fault1'),
out part2_2 varchar __soap_options (
__soap_fault:='http://www.w3.org/2001/XMLSchema:string',
PartName:='part2',
ResponseNamespace:='http://soapinterop.org/wsdl/fault2')
)
__soap_type '__VOID__'
{
if (whichFault > 2)
whichFault := mod (whichFault, 3) + 1;
declare exit handler for sqlstate 'SF000'
{
http_request_status ('HTTP/1.1 500 Internal Server Error');
if (whichFault = 1)
{
part2_1 := param1;
}
else if (whichFault = 2)
{
part2_2 := param2;
}
connection_set ('SOAPFault', vector ('400', 'echoMultipleFaults3'));
return;
};
signal ('SF000', 'echoEmptyFault');
}
;
</pre>
</div>
</div>
<br />
<a name="soapheadermessages" />
<h3>15.1.16. Exposing & Processing SOAP Header Messages</h3>
<p>The Virtuoso SOAP server can be used to process the SOAP Header
messages as described in the W3C recommendation
(<a href="http://www.w3c.org/TR/SOAP/">http://www.w3c.org/TR/SOAP</a>,
SOAP Header section). They can also be exposed in the WSDL file
(services.wsdl) as per W3C WSDL recommendation, using the RPC style encoding.</p>
<p>To bind a message to a SOAP header the special keyword __soap_header
is reserved for input and output parameters. The __soap_header followed by the
SOAP datatype can be specified for any input or output parameter after
normal datatype declarations. This will expose parameters as input or
output messages separately. Header binding will also be added to an
appropriate section of the WSDL description file for the SOAP message.</p>
<a name="procsoapheader" />
<div class="example">
<div class="exampletitle">Processing of the SOAP Header element</div>
<p>Consider the following simple SOAP request message with Header element:</p>
<div>
<pre class="programlisting">
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Header>
<h:echoMeStringRequest
xmlns:h="http://soapinterop.org/echoheader/"
SOAP-ENV:actor="http://schemas.xmlsoap.org/soap/actor/next"
mustUnderstand="1">hello world</h:echoMeStringRequest>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<m:echoVoid xmlns:m="http://soapinterop.org/"></m:echoVoid>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope></pre>
</div>
<p>This request will be processed by the Virtuoso SOAP server in the
following way:</p>
<ol>
<li>Check whether the echoVoid operation is defined for the given
web directory mapping (see: exposing a PL procedure as a SOAP operation)</li>
<li>Test whether there is an in-parameter echoMeStringRequest defined
for header processing (see below exposing a header parameters)</li>
<li>Test the mustUnderstand attribute:
<ul>
<li>If mustUnderstand is 0 or is undefined the request will continue
without an error.</li>
<li>If mustUnderstand is 1 and the actor attribute is not empty
or defined with the http://schemas.xmlsoap.org/soap/actor/next special URI,
the request will continue without an error.</li>
<li>If the two conditions about fail then the request will be
rejected with a SOAP MustUnderstand error.</li>
</ul>
</li>
<li>The value of the echoMeStringRequest will be passed as a parameter
to the echoVoid procedure.</li>
<li>If the call to the echoVoid succeeds, and the corresponding out
parameter is supplied for the SOAP response header then it will be
sent to the SOAP client.</li>
</ol>
<p>The following procedure, which represents a part from echoHeaderBindings
iterop test (round C), for the demonstration purposes is designed to process
the above SOAP message.</p>
<div>
<pre class="programlisting">
create procedure
Interop.INTEROP.echoVoid
(in echoMeStringRequest nvarchar := NULL __soap_header 'http://www.w3.org/2001/XMLSchema:string',
out echoMeStringResponse nvarchar := NULL __soap_header 'http://www.w3.org/2001/XMLSchema:string')
__soap_type '__VOID__'
{
if (echoMeStringRequest is not null)
echoMeStringResponse := echoMeStringRequest;
};</pre>
</div>
<div class="note">
<div class="notetitle">Note:</div>
<p>The __soap_header keyword that instructs the SOAP server to process this
parameter via a SOAP Header with datatype string. Also, the condition in
the procedure is needed to return the value in SOAP header only if it is
supplied. In some other cases it can be returned always, but in this
particular example it will be echoed only if the appropriate header is sent.</p>
</div>
</div>
<br />
<a name="soapfaultmessages" />
<h3>15.1.17. Exposing & Processing SOAP Fault Messages</h3>
<p>
The SOAP:Fault message is used to indicate which part of SOAP request fails,
so in its general form it may not have a detailed error. But in some cases it is
useful to report in detail which element's input(s) are not correct.</p>
<p>
Custom soap:fault messages can be generated by application logic as illustrated below:
</p>
<p>Have a procedure to generate custom SOAP:Fault messages with at least one OUT parameter
denoted by __SOAP_FAULT instead of __SOAP_TYPE keyword following by type to be returned as literal.</p>
<p>Once we have such parameter(s) declared we can set these to some value (of atomic, simple or complex type) as may be appropriate.
</p>
<p>
And finally we need to set a special connection variable 'SOAPFault', in order to signal custom SOAP:Fault
on output. The value of the connection variable needs to be an array of two elements :
An integer of 100, 200, 300, 400 which represents the SOAP:VersionMismatch, SOAP:MustUnderstand,
SOAP:Client and SOAP:Server errors.
And a string which will be printed in textual explanation, human readable format.
In real life we will not need to generate 100 or 200 fault messages, but anyway it is possible to do that.
</p>
<a name="procsoapfault" />
<div class="example">
<div class="exampletitle">Signalling a custom SOAP Fault element</div>
<p>Consider we need to indicate to the client that some string is not a valid input, we can use
the custom fault message mechanism as.</p>
<div>
<pre class="programlisting">
create procedure
echoStringFault (in param nvarchar,
out part2 nvarchar __soap_fault 'string')
returns nvarchar
{
declare exit handler for sqlstate 'SF000'
{
http_request_status ('HTTP/1.1 500 Internal Server Error');
-- we are setting the fault message
part2 := param;
-- and instructing the SOAP server to make error 400 with text explanation StringFault
connection_set ('SOAPFault', vector ('400', 'StringFault'));
----------------^^^^^^^^^^
return;
};
-- in real life signalling of the error is under some condition
-- for example if string is longer that 10 chars
signal ('SF000', 'echoEmptyFault');
}
;
</pre>
</div>
<p>And an wire dump of SOAP request</p>
<div>
<pre class="programlisting">
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" ...>
<SOAP-ENV:Body>
<m:echoStringFault xmlns:m="http://soapinterop.org/wsdl">
<param xsi:type="xsd:string">String</param>
</m:echoStringFault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
</pre>
</div>
<p>And SOAP Fault response</p>
<div>
<pre class="programlisting">
<?xml version="1.0"?>
<SOAP:Envelope SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" ...>
<SOAP:Body>
<SOAP:Fault>
<faultcode>SOAP:Server</faultcode>
<faultstring>[Virtuoso SOAP server] StringFault</faultstring>
<detail>
<h:part2 xmlns:h="http://soapinterop.org/wsdl" xsi:type="xsd:string">String</h:part2>
</detail>
</SOAP:Fault>
</SOAP:Body>
</SOAP:Envelope>
</pre>
</div>
<p>Please note that in wire dumps there is no namespace declarations for brevity (places are denoted with '...').
</p>
</div>
<br />
<a name="soapdoclitenc1" />
<h3>15.1.18. Document Literal Encoding</h3>
<p>The Virtuoso SOAP server and client support Document Literal encoding
for processing as an alternative to SOAP/RPC. The document/literal
encoding allows the transmission of any arbitrary valid XML document instead
of a SOAP call following rules from section 5 from
SOAP/1.1 specification. This allows us to send and receive SOAP packets that
are more free-form ("document" style). If you create a service that can accept
more free-form type packets, you can employ constraints within the methods so
that they can be independent (bare) or serialized as embedded elements within
the method's SOAP structure (wrapped parameters style).</p>
<a name="ex_soapi3doclit" />
<div class="example">
<div class="exampletitle">Comparing SOAP Types</div>
<p>Here are examples of SOAP requests that represent the RPC, Doc/Literal
and Doc/Literal with parameters types of SOAP message</p>
<p>-- RPC encoded --</p>
<div>
<pre class="programlisting">
<?xml version="1.0"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<m:echoString
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:m="http://soapinterop.org/">
<param0 xsi:type="xsd:string">Enter a message here</param0>
</m:echoString>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
</pre>
</div>
<p>-- Document Literal --</p>
<div>
<pre class="programlisting">
<?xml version="1.0"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<ns1:echoStringParam xmlns:ns1="http://soapinterop.org/xsd">Enter a message here</ns1:echoStringParam>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
</pre>
</div>
<p>-- Document Literal with parameters --</p>
<div>
<pre class="programlisting">
<?xml version="1.0"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<ns1:echoString xmlns:ns1="http://soapinterop.org/xsd">
<param0>Enter a message here</param0>
</ns1:echoString>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
</pre>
</div>
</div>
<p>SOAP operations can be designated as document/literal or RPC by using the
appropriate values in the WSDL description file associated to that SOAP endpoint.
As Virtuoso SOAP operations are PL procedures special keywords are used within
the procedure to indicate that the document/literal encoding should be used.
These special keywords are:</p>
<ul>
<li>__soap_doc</li>
<li>__soap_docw</li>
</ul>
<p>These should be placed after the 'returns' keyword in a Virtuoso procedure
definition. If 'returns ... __soap_type' is omitted the procedure return type
will be equivalent to 'returns varchar __soap_type 'http://www.w3.org/2001/XMLSchema:string'.</p>
<p>Another way to expose a PL procedure or UDT method as a document/literal SOAP
methods is to use non-explicit XMLSchema datatypes and to force encoding rules
via virtual directory option 'Use' (see also SOAP options section in this chapter and in WSDL chapter section: "Exposing SQL Stored Procedures containing complex datatype definitions" for details and examples).
</p>
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>
<a href="http://www.w3.org/TR/wsdl">WSDL 1.1 Specification</a>
</p>
</div>
<a name="ex_soapreturnrpc" />
<div class="example">
<div class="exampletitle">SOAP Returns RPC</div>
<p>The following example shows a procedure that will be exposed as an RPC
encoded SOAP operation:</p>
<div>
<pre class="programlisting">
create procedure
Import1.echoString (in x nvarchar __soap_type 'http://www.w3.org/2001/XMLSchema:string')
returns nvarchar __soap_type 'http://www.w3.org/2001/XMLSchema:string'
{
return x;
};
</pre>
</div>
</div>
<a name="ex_soapreturndoclit" />
<div class="example">
<div class="exampletitle">SOAP Returns Document Literal</div>
<p>The following example shows a procedure that will be exposed as a document
literal encoded operation. Note the __soap_doc keyword after 'returns', also
in this case __soap_type for each parameter must be specified since the incoming
request must be validated by the given schema element declaration (see below
for XMLSchema elements declaration).</p>
<div>
<pre class="programlisting">
create procedure
DocLit.echoString (in echoStringParam varchar __soap_type 'http://soapinterop.org/xsd:echoStringParam')
returns any __soap_doc 'http://soapinterop.org/xsd:echoStringReturn'
{
return echoStringParam;
};
</pre>
</div>
</div>
<a name="ex_soapreturndoclitwrapped" />
<div class="example">
<div class="exampletitle">SOAP Returns Document Literal with Parameters</div>
<p>The following example shows a procedure that will be exposed as document
literal encoding operation with parameters style (wrapped). note the __soap_docw
keyword after 'returns'.</p>
<div>
<pre class="programlisting">
create procedure
DocPars.echoString (in echoString varchar __soap_type 'http://soapinterop.org/xsd:echoString')
returns any __soap_docw 'http://soapinterop.org/xsd:echoStringResponse'
{
return echoString;
};
</pre>
</div>
</div>
<p>In both cases of Document Literal encoding we need to specify the schema
element for validation of the incoming SOAP request. Furthermore, this applies
to the output elements and return value, as they need to be encoded/validated
properly.</p>
<a name="wsdlschemadtandelts" />
<h4>15.1.18.1. Defining WSDL Schema Data Type and Elements</h4>
<p>When defining a schema data type (for use within SOAP) the
'targetNamespace' attribute on top level element must be specified in order
to describe in which namespace this type is valid. In other words, this type
will be used to validate request only within this namespace. Therefore it
will be exposed only at this WSDL point where it is used to describe a
parameter of an operation associated to it.</p>
<p>
<span class="important">
<strong>Important:</strong> All datatypes and elements defined for use in SOAP must have
namespace (QName), which means that 'targetNamespace' must be specified in the
definition. All non-qualified types will be rejected in SOAP validation and
will not be described in the WSDL file.</span>
</p>
<a name="ex_soapi3stringarray" />
<div class="example">
<div class="exampletitle">Making an array of string data type</div>
<p>Here is an example demonstrating making an array-of-string datatype:</p>
<div>
<pre class="programlisting">
select soap_dt_define('','<complexType name="ArrayOfstring"
targetNamespace="http://soapinterop.org/xsd"
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://soapinterop.org/xsd">
<complexContent>
<restriction base="enc:Array">
<sequence>
<element name="item" type="string" minOccurs="0" maxOccurs="unbounded" nillable="true"/>
</sequence>
<attributeGroup ref="enc:commonAttributes"/>
<attribute ref="enc:arrayType" wsdl:arrayType="string[]"/>
</restriction>
</complexContent>
</complexType>');
</pre>
</div>
</div>
<p>As document literal encodings work with elements, the elements must be
declared as a part of the WSDL file (in the types/schema section). The declared
elements can be used to define a doc/literal encoded SOAP operation. This
allows for the definition of an element of request and response to enable
the server to understand the requests (validate and process) and respond to
them (validate the PL data and serialize properly).</p>
<a name="ex_si3params" />
<div class="example">
<div class="exampletitle">Example of defining elements</div>
<p>Here is an example for the DocLit.echoString SOAP operation using
parameters (input parameter and return type):</p>
<div>
<pre class="programlisting">
select soap_dt_define('','<element xmlns="http://www.w3.org/2001/XMLSchema"
name="echoStringParam"
targetNamespace="http://soapinterop.org/xsd" type="string" />');
select soap_dt_define('','<element xmlns="http://www.w3.org/2001/XMLSchema"
name="echoStringReturn"
targetNamespace="http://soapinterop.org/xsd" type="string" />');
</pre>
</div>
</div>
<br />
<a name="soapexttosimptypes" />
<h4>15.1.18.2. Extensions to Simple Types</h4>
<p>The attribute extensions to the simple types (string, float, etc...) can
be defined and used in SOAP messages. In that case a PL value is
represented as a special structure of 3 elements as follows:</p>
<div>
<pre class="programlisting">
vector (<composite>, vector (<attr-name>, <attr-value>, ...), <simple type value>)
</pre>
</div>
<a name="ex_defsimptypedocument" />
<div class="example">
<div class="exampletitle">An example to define a simple type 'Document'</div>
<div>
<pre class="programlisting">
select soap_dt_define('','<complexType name="Document"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://soapinterop.org/xsd">
<simpleContent>
<extension base="string">
<xsd:attribute name ="ID" type="string"/>
</extension>
</simpleContent>
</complexType>');
</pre>
</div>
<p>Note that soap_dt_define() does not need the name to be specified when
adding a new type, the name/namespace will be extracted from XSD fragment.</p>
</div>
<br />
<a name="wsdlgeneration" />
<h4>15.1.18.3. WSDL Generation</h4>
<p>As the WSDL file generation is based on granted PL procedures exposed to
a given SOAP endpoint, only SOAP datatypes and schema elements used for them will
be printed in <types> section. If an undeclared datatype is used for an
exposed procedure, the error will be printed in an XML comment where the type
definition was expected and not found. If an element or datatype refers to
other (dependent) types they will also be automatically included. For example,
if we have exposed for a SOAP endpoint only the following procedure:</p>
<div>
<pre class="programlisting">
create procedure
INTEROP.echoStructArray (
in inputStructArray any __soap_type 'http://soapinterop.org/xsd:ArrayOfSOAPStruct')
__soap_type 'http://soapinterop.org/xsd:ArrayOfSOAPStruct'
{
return inputStructArray;
};
</pre>
</div>
<p>The schema fragment will consist of both SOAPStructure and ArrayOfSOAPStruct
data types declaration:</p>
<div>
<pre class="programlisting">
<schema targetNamespace="http://soapinterop.org/xsd"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" >
<complexType name="ArrayOfSOAPStruct" >
<complexContent>
<restriction base="soapenc:Array">
<sequence>
<element name="item" type="ns0:SOAPStruct" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<attribute ref="soapenc:arrayType" wsdl:arrayType="ns0:SOAPStruct[]"/>
<attributeGroup ref="soapenc:commonAttributes"/>
<attribute ref="soapenc:offset"/>
</restriction>
</complexContent>
</complexType>
<!-- Note this fragment, it's included because ArrayOfSOAPStruct depends from it -->
<complexType name="SOAPStruct" >
<all>
<element name="varString" type="string" nillable="true"/>
<element name="varInt" type="int" nillable="true"/>
<element name="varFloat" type="float" nillable="true"/>
</all>
</complexType>
</schema>
</pre>
</div>
<br />
<a name="multnswsdlsoap" />
<h4>15.1.18.4. Multiple Namespaces in WSDL and SOAP</h4>
<p>When you define a SOAP operation that has parameters from different
namespaces or a type referring to a type in another namespace, both will be defined
and printed as a separate schema definition in the WSDL file. Hence,
we can define a data type in different namespace so they will live together in
a single WSDL file. This allows us to make more complex and flexible
document-centric style SOAP operations.</p>
<a name="ex_mnsi3test" />
<div class="example">
<div class="exampletitle">Example from the SOAP Interop 3 Tests</div>
<p>This example is of the echoEmployee operation from interop 3 tests:</p>
<div>
<pre class="programlisting">
create procedure
Compound2.echoEmployee (in x any __soap_type 'http://soapinterop.org/employee:x_Employee')
returns any __soap_doc 'http://soapinterop.org/employee:result_Employee'
{
return x;
};
</pre>
</div>
<p>This will generate the following schema in the WSDL file (only affected
parts are shown):</p>
<div>
<pre class="programlisting">
<definitions
...
xmlns:ns1="http://soapinterop.org/person"
xmlns:ns0="http://soapinterop.org/employee"
... >
<types>
<schema targetNamespace="http://soapinterop.org/person"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" elementFormDefault="qualified" >
<complexType name="Person" >
<sequence>
<element minOccurs="1" maxOccurs="1" name="Name" type="string"/>
<element minOccurs="1" maxOccurs="1" name="Male" type="boolean"/>
</sequence>
</complexType>
</schema>
<schema targetNamespace="http://soapinterop.org/employee"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" elementFormDefault="qualified" >
<import namespace='http://soapinterop.org/person' />
<complexType name="Employee" >
<sequence>
<element minOccurs="1" maxOccurs="1" name="person" type="ns1:Person"/>
<element minOccurs="1" maxOccurs="1" name="salary" type="double"/>
<element minOccurs="1" maxOccurs="1" name="ID" type="int"/>
</sequence>
</complexType>
<element name="result_Employee" type="ns0:Employee" />
<element name="x_Employee" type="ns0:Employee" />
</schema>
</types>
...
</pre>
</div>
<p>The PL procedure is defined to use element declaration x_Employee and result_Employee,
so this will automatically include the Employee and Person type, upon which they
depend. Also, as these types are defined in different namespace, two schema
parts will be specified in the WSDL file.</p>
</div>
<p>In practice the SOAP developer needs to define elements and
types (using soap_dt_define() function), after this, specifying a parameter of
PL procedure (or return type) will cause automatic generation of the
associated WSDL description in the manner described. Hence, no user intervention
is required besides the initial element/type definition.</p>
<br />
<a name="soapi3endpoints" />
<h4>15.1.18.5. SOAP Interop round III Endpoints</h4>
<p>The following endpoints are pre-defined in the Demo database for
SOAP interop III testing (the WSDL files are in the usual services.wsdl for
each group of tests):</p>
<ul>
<li>
<p>
<strong>D tests</strong>
</p>
<ul>
<li>/r3/EmptySA/ - echoString operation with empty ("") soapAction (PRC encoded)</li>
<li>/r3/Import1/ - echoString operation, rpc encoded</li>
<li>/r3/Import2/ - echoStruct operation, rpc encoded</li>
<li>/r3/Import3/ - echoStruct and adds method echoStructArray, rpc encoded (echoStruct is in different namespace)</li>
<li>/r3/Compound1/ - Use of attributes in SOAP payload, including attribute on element of simpleType , doc/literal</li>
<li>/r3/Compound2/ - Two schema sections, types in 1st schema references types in the 2nd schema, doc/literal</li>
<li>/r3/DocPars/ - Reduced version of SOAPBuilders Interop test wsdl with "parameters" way of describing rpc requests in Document/Literal (Document/Literal - Wrapped). Version has operations echoString, echoArrayOfString and echoStruct</li>
<li>/r3/DocLit/ - Reduced version of SOAPBuilders InteropTest test, document/literal mode. Version has operations echoString, echoArrayOfString and echoStruct</li>
<li>/r3/RpcEnc/ - Reduced version of SOAPBuilders InteropTest test, rpc/encoded mode. Version has operations echoString, echoArrayOfString and echoStruct</li>
</ul>
</li>
<li>
<p>
<strong>E tests</strong>
</p>
<ul>
<li>
<p>/r3/List/ - echo of list structure (as shown) , RPC encoded</p>
<div>
<pre class="programlisting">
struct list {
int varInt;
string varString;
list child; //nullable
}
</pre>
</div>
</li>
</ul>
</li>
<li>
<p>
<strong>F tests</strong>
</p>
<ul>
<li>/r3/Hdr/ - Modified version of SOAPBuilders InteropTest test, document/literal mode Version has one operation echoString with 2 headers defined.</li>
</ul>
</li>
</ul>
<br />
<br />
<a name="soapdimeenc" />
<h3>15.1.19. DIME encapsulation of SOAP messages</h3>
<p>
The Direct Message Encapsulation (DiME) format is a message format
that can be used to encapsulate one or more payloads of arbitrary type and size.
This format can be used in place of MIME, but benefits of DIME are ease of parsing and
low memory consumption, as DIME does not require loading the whole message body in order to parse it.
This is due to the fact that MIME does not have mechanism for specifying the length of payloads etc. DIME prefixes all data with length and type information.
</p>
<p>
The structure of a DIME message as per draft-nielsen-dime-02 is:
</p>
<div>
<pre class="programlisting">
/*
Legend:
VERSION = 0x01
RESRVD = 0x00
MB - begin mark
ME - end mark
CF - chunked flag
TYPE_T - type of content type field
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |M|M|C| | | |
| VERSION |B|E|F| TYPE_T| RESRVD| OPTIONS_LENGTH |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ID_LENGTH | TYPE_LENGTH |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| DATA_LENGTH |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| /
/ OPTIONS + PADDING /
/ |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| /
/ ID + PADDING /
/ |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| /
/ TYPE + PADDING /
/ |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| /
/ DATA + PADDING /
/ |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
*/
</pre>
</div>
<p>
The MB,ME,CF flags are used to indicate which part of the DIME message is the
current block of data. Also, we notice that there are four length fields
of fixed length before any data, id or type payload. This is to make the payload
easier to read.
</p>
<p>
The Virtuoso server implements a DIME parser and composer as functions and filter for DIME in SOAP server.
Furthermore the Virtuoso WSDL generator can be instructed to specify a DIME extension to the
PL procedure exposed as SOAP method. The implementation is based on draft-nielsen-dime-02 RFC proposal.
Please note that in the rest of document we will use 'DIME attachment' term , which is about
SOAP message with attachment encapsulated with DIME as per draft-nielsen-dime-soap-01. The special case in these messages is type of first payload, so it's supposed to be a SOAP:Envelope message.
</p>
<p>
Note: Option fields are not supported.
</p>
<p>
To setup a SOAP endpoint to recognize DIME encapsulation the "DIME-ENC" option to SOAP in virtual directory
must be set to 'yes'. Furthermore the WSDL description of endpoint defined as DIME enabled will contain
WSDL extensions to DIME.
</p>
<p>
As not in all cases input and output of the SOAP server needs to be DIME encoded,
the particular PL procedure exposed as SOAP method needs to be defined in special way to indicate which
traffic is encoded as DIME.
This is done by using special keywords on procedure declaration:
</p>
<div>
<pre class="programlisting">
CREATE PROCEDURE ([PARAMETERS DECLARATION])
[RETURNS TYPE] [(__SOAP_TYPE|__SOAP_DOC|_SOAP_DOCW) 'LITERAL'] [__SOAP_DIME_ENC (IN/OUT/INOUT)]
</pre>
</div>
<p>
The '__SOAP_DIME_ENC IN' indicate that the procedure expects a DIME attachments on input.
This can also be used with OUT and INOUT.
This will also be indicated in WSDL file (services.wsdl) as DIME extension in
appropriate place of 'soap:operation' element.
</p>
<p>
The format of SOAP attachments passed to PL procedure defined in this way
is an array which consists of three string elements: ID, content-type, and attachment data itself.
The same format must be used when parameter is an output which needs to be sent as DIME attachment.
There is also a special parameter of PL procedure exposed as SOAP method named 'ws_soap_attachments',
so when we have such, all attachments received will be passed thru it. In practice we will not need to use 'ws_soap_attachments' , but anyway it's practical use is to handle unreferenced parameters or to debug the request.
</p>
<p>
Finally we must say that type of parameter needs to have datatype declared as per 'WSDL Extension for SOAP in DIME' proposal, this is needed for indicating in the WSDL what to expect and how to send the attachment. See also the example below.
</p>
<a name="procdimesoap" />
<div class="example">
<div class="exampletitle">Using DIME encapsulation</div>
<p>Suppose we need to accept a binary attachment and echo it back as string
encoded in the popular 'base64'.</p>
<p>We first need to enable DIME encapsulation to an endpoint, with virtual directory definition:</p>
<div>
<pre class="programlisting">
SQL> VHOST_DEFINE (lpath=>'/r4/groupG/dime/rpc', ppath=>'/SOAP/', soap_user=>'interop4',
soap_opts => vector ('DIME-ENC', 'yes')) ;
</pre>
</div>
<p>The sample PL procedure that takes a binary attachment and transforms it to
a base64 encoded string must be declared as:
</p>
<div>
<pre class="programlisting">
create procedure
EchoAttachmentAsBase64 (in "In" nvarchar __soap_type 'http://soapinterop.org/attachments/xsd:ReferencedBinary')
returns nvarchar __soap_type 'base64Binary'
__soap_dime_enc in
{
-- we are getting the attachment as the 3rd element of input,
-- do the base64 encoding for it and return it to the requestor
return encode_base64 (cast ("In"[2] as varchar));
}
;
</pre>
</div>
<p>
As we have noticed an 'ReferencedBinary' is used to declare 'In' parameter.
This has a special purpose for WSDL definition, not for SOAP processing itself.
In that case clients are instructed to look at annotation/appinfo of a simple type declared as:
</p>
<div>
<pre class="programlisting">
<complexType name="ReferencedBinary">
<simpleContent>
<restriction base="soap-enc:base64Binary">
<annotation>
<appinfo>
<content:mediaType value="application/octetstream"/>
</appinfo>
</annotation>
<attributeGroup ref="soap-enc:commonAttributes"/>
</restriction>
</simpleContent>
</complexType>
</pre>
</div>
<p>
This is a little-bit tricky, but this is how to indicate the type of the content and how to resolve the
references to the attachments as per the WSDL Extension for SOAP in DIME' proposal.
</p>
</div>
<br />
<a name="soapoptions" />
<h3>15.1.20. SOAP Endpoint Options</h3>
<p>The virtual directory mechanism provides a special SOAP options for
SOAP processing. The SOAP options are name-value pairs contained in a vector:
i.e. vector ('name1', 'value1', ....). The SOAP server accepts the following
optional parameters settable in the SOAP Options field of the
<a href="htmlconductorbar.html#httpvirtualdirs">HTTP Virtual Directories Setup</a>
interface, or using the
<a href="fn_vhost_define.html">vhost_define()</a>
function:</p>
<ul>
<li>
<strong>ServiceName</strong>: name of the SOAP service, will be
prefixed with 'Virtuoso'. That name is shown in WSDL description.</li>
<li>
<strong>Namespace</strong>: namespace URI of the SOAP:Body
request and response.</li>
<li>
<strong>HeaderNS</strong>: namespace URI for SOAP:Header messages.</li>
<li>
<strong>FaultNS</strong>: namespace URI for SOAP:Fault messages. </li>
<li>
<strong>MethodInSoapAction</strong>: enable or disable appending
of the method name in the soapAction attribute (WSDL) after namespace URI.</li>
<li>
<strong>CR-escape</strong>: enable or disable escaping of the
CRs on wire as &#0xd</li>
<li>
<strong>elementFormDefault=(unqualified|qualified);</strong>
<p>Sets the elementFormDefault for schema specification. if
qualified is used the elementFormDefault attribute will be set to qualified,
in which case elements required to be unqualified can be declared with
value of "form" attribute "unqualified".</p>
</li>
<li>
<strong>Use=(encoded|literal)</strong>
<p>
Sets the default SOAP message encoding rules for those PL procedures which have no
explicit encoding rule assigned (see SOAP special syntax for PL procedures).
The default is 'encoded' which means to follow SOAP RPC encoding as described
in SOAP v1.1 specification section 5.1.
The 'literal' mode forces the SOAP server to expose PL procedures
with the document/literal parameter encoding style.
</p>
</li>
<li>
<strong>MethodInSoapAction=(no|yes|empty|only);</strong>
<p>Controls soapAction attribute manipulation. <strong>no</strong> -
only URL for soap requests will be printed. <strong>yes</strong>
(default) - the URL and soap method will be printed in form:
<url>#<method name>. <strong>empty</strong> - no value will
be specified for soapAction. <strong>only</strong> - only the method
will be specified in form #<method name>.</p>
</li>
<li>
<strong>DIME-ENC</strong>: Controls DIME encapsulation on particular
SOAP endpoint, valid values are <strong>no</strong> - (default) not enabled. <strong>yes</strong> -
DIME encapsulation is enabled on endpoint
</li>
<li>
<strong>WS-SEC</strong>: WS-Security processing is enabled on the endpoint, if it's <strong>yes</strong>, otherwise disabled (default)
</li>
<li>
<strong>WSS-KEY</strong>: name of PL procedure, which is supposed to return a key instance, used together with "WS-SEC" option.
</li>
<li>
<strong>WSS-Template</strong>: path to the file for making the XML Signature in response message.
The "[key reference for signing]" denotes using a default template for signing, see WS Security signing SOAP messages.
</li>
<li>
<strong>WSS-Validate-Signature</strong>: This option controls the
input behavior, i.e. how to verify the incoming message. Possible values are
"0", "1" or "2", where 0 does not verify signatures, 1 expects a signature to
exist, 2 will verify signature if one exists.</li>
<li>
<strong>WS-RP</strong>: to enable WS-Routing protocol on particular endpoint, if it's <strong>yes</strong>, otherwise disabled (default).
</li>
<li>
<strong>wsrp-from</strong>: Constant for identification of endpoint, an example is 'some@user.network'. This will be included in 'form' element in WS Routing header.
</li>
</ul>
<br />
<table border="0" width="90%" id="navbarbottom">
<tr>
<td align="left" width="33%">
<a href="webservices.html" title="Web Services">Previous</a>
<br />Contents of Web Services</td>
<td align="center" width="34%">
<a href="webservices.html">Chapter Contents</a>
</td>
<td align="right" width="33%">
<a href="wsdl.html" title="WSDL">Next</a>
<br />WSDL</td>
</tr>
</table>
</div>
<div id="footer">
<div>Copyright© 1999 - 2009 OpenLink Software All rights reserved.</div>
<div id="validation">
<a href="http://validator.w3.org/check/referer">
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" />
</a>
<a href="http://jigsaw.w3.org/css-validator/">
<img src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" height="31" width="88" />
</a>
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
71d40963b505df4524269198e237b3e3
>
files
>
876
