# 15. Web Services

Chapter Contents | Prev | Next
Keyword Search:
www.openlinksw.com
docs.openlinksw.com
Book Home
Contents
Preface
Web Services
SOAP
WSDL
Exposing Stored Procedures as WSDL Services Exposing SQL Stored Procedures containing complex datatype definitions Exposing Third Party SQL Stored Procedures as WSDL-Compliant Web Services WSDL Descriptions of SOAP Header Messages Importing A WSDL File & SOAP/WSDL Proxying SOAP/WSDL Interoperability
WS-Security (WSS) Support in Virtuoso SOAP Server
Web Services Routing Protocol (WS-Routing)
Web Services Reliable Messaging Protocol (WS-ReliableMessaging)
Web Services Trust Protocol (WS-Trust)
XML for Analysis Provider
XML-RPC support
SyncML
UDDI
Exposing Persistent Stored Modules as Web Services
Testing Web Published Web Services
BPEL Reference
XSQL

## 15.2. WSDL

The Web Services Description Language (WSDL) is a standard, structured way of describing SOAP messages and Web services. It is an XML format for describing the network services offered by a service provider. The provider will publish a WSDL file that contains details about the services provided, and the set of operations within each service that the provider supports. For each of the operations, the WSDL file also describes the format that the client must follow in requesting an operation.

Since the WSDL file sets up requirements for both the provider and service requester, this file is like a contract between the two. The provider agrees to provide certain services if the client sends a properly formatted SOAP request. Suppose that we have a WSDL file defining a service called StockQuoteService. This service describes operations such as getTradePrice, getLowestTradePrice, and getHighestTradePrice. You place this WSDL file on the service provider server. A client who wishes to send a SOAP request to this server must first obtain a copy of the WSDL file from the provider, and then use it to format a suitable SOAP request. The client sends this request to the provider. The provider executes the requested operation and sends the results back to the client requester as a SOAP response.

See Also:

The specification of WSDL and its file structures can be found on the W3C site.

### 15.2.1. Exposing Stored Procedures as WSDL Services

Virtuoso can be both a provider and a client of WSDL. In this section we will explain how to use Virtuoso to expose procedures as SOAP messages, and then publish them as WSDL consumables.

In the descriptions below, lines preceded by SQL> denote that the command is intended to be issued using the ISQL command line interface to Virtuoso.

Virtuoso procedures can easily be published as WSDL consumables. We follow the same steps as we would take to create SOAP objects and then for every SOAP object Virtuoso automatically generates a WSDL file entry. The default Virtuoso has the user SOAP and reserved HTTP path of /SOAP/. All procedures that are created in the default qualifier namespace of the SOAP user (WS.SOAP) and have had a 'grant execute to SOAP' permissions established in the database are available to SOAP and thus are automatically available to WSDL. In Virtuoso this is done by requesting the file services.wsdl from the server via HTTP from the /SOAP/ path: http://[host:port]/SOAP/services.wsdl. WSDL files such as this are often referred to as "endpoints" for services.

Virtual directories increase our flexibility by allowing us to map logical HTTP paths to the location /SOAP/. This means that we can separate WSDL/SOAP functionality, making groups of services available under different locations. We will now demonstrate this:

1. First, create a new user in the database for creating the stored procedures as SOAP messages:

       SQL>CREATE USER SOAPDEMO;

2. Now, set the default catalogue/qualifier for the new user to the WS catalogue where we will create procedures to be used as SOAP objects:

       SQL>USER_SET_QUALIFIER ('SOAPDEMO', 'WS');

3. Now create a new virtual host definition, using the vhost_define(), so that we can find our SOAP objects later at a desired location.

       SQL>VHOST_DEFINE (vhost=>'*ini*',lhost=>'*ini*',lpath=>'/services',ppath=>'/SOAP/',soap_user=>'SOAPDEMO');

   If the mapping already exists, producing an error in the call above, and is not being used, then you can remove it using the command:

       SQL>VHOST_REMOVE (vhost=>'*ini*',lhost=>'*ini*',lpath=>'/services')

   Note:

   *ini* is a special indicator telling Virtuoso to take the default values from its initialization file.

4. Now create a simple SOAPTEST procedure and grant the appropriate privileges to the SOAPDEMO user:

       SQL> create procedure
         WS.SOAPDEMO.SOAPTEST (in par varchar)
       {
         return (upper(par));
       };

       SQL> grant execute on WS.SOAPDEMO.SOAPTEST to SOAPDEMO;

5. Now test this new SOAP object's availability by using soap_client(). This function would normally return a vector representation of the SOAP object but since we know the dimensions of the object ahead of time we can pin-point the entry using the aref() function as follows:

       SQL> select aref(aref(
       	soap_client (url=>sprintf ('http://localhost:%s/services', server_http_port ()),
       	operation=>'SOAPTEST', parameters=>vector('par', 'demotext')), 1), 1);
       callret
       VARCHAR
       _______

       DEMOTEXT

   The actual SOAP object looks more like:

       (("SOAPTESTResponse" ) (("CallReturn" ) "DEMOTEXT" ) )

   which was generated in a Virtuoso server log for debugging purposes using the dbg_obj_print() function.

6. Procedures that exist under the WS.SOAPDEMO namespace and have been granted execution to the new SOAPDEMO user are now available as SOAP services and described by WSDL in this example, Virtuoso would publish them from the URL:

       http://localhost/services/services.wsdl

   which will yield the following WSDL description:

       <?xml version='1.0'?>
       <definitions
        targetNamespace='services.wsdl'
        xmlns:xsd='http://www.w3.org/1999/XMLSchema'
        xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'
        xmlns:tns ='services.wsdl'
        xmlns ='http://schemas.xmlsoap.org/wsdl/'
        name='VirtuosoSOAP'>
       	<message name='SOAPTEST'>
       		<part name='par' type='xsd:string'/>
       	</message>
       	<message name='SOAPTESTResponse'>
       		<part name='CallReturn' type='xsd:string'/>
       	</message>
       	<portType name='SOAPPortType'>
       		<operation name='SOAPTEST'>
       			<input message='tns:SOAPTEST' name='SOAPTEST'/>
       			<output message='tns:SOAPTESTResponse' name='SOAPTESTResponse'/>
       		</operation>
       	</portType>
       	<binding name='SOAPBinding' type='tns:SOAPPortType'>
       		<soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http'/>
       		<operation name='SOAPTEST'>
       			<soap:operation soapAction='urn:openlinksw.com:virtuoso_soap_schema#SOAPTEST'/>
       			<input>
       				<soap:body use='encoded' namespace='urn:openlinksw.com:virtuoso_soap_schema' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
       			</input>
       			<output>
       				<soap:body use='encoded' namespace='urn:openlinksw.com:virtuoso_soap_schema' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
       			</output>
       		</operation>
       	</binding>
       	<service name='SOAPService'>
       		<port name='SOAPPort' binding='tns:SOAPBinding'>
       			<soap:address location='http://localhost/services'/>
       		</port>
       	</service>
       </definitions>

   See Also:

   The Testing Web Services (VSMX) section describes Virtuoso's ability to also automatically generate a test page for your SOAP services, simply by replacing services.wsdl with services.vsmx in the URL.

### 15.2.2. Exposing SQL Stored Procedures containing complex datatype definitions

When parameters of a PL procedure or UDT (User Defined Type) methods contain parameters declared as UDT or/and as ARRAY then WSDL generation will include XML Schema for them. The schema types in this case will be generated every time WSDL URL is accessed. Also the XMLSchema datatypes will be generated following the default encoding rules forced via 'Use' SOAP option to the given virtual directory.

Exposing a PL Stored procedures containing complex datatypes

The following example will create a virtual directory '/soap-lit' on default HTTP listener and will expose a single method accepting a array of structures which contains an array of integers, integer, varchar and float members. The SOAP message will use the document/literal encoding rules (option Use=literal).

    create user SOAP_U1;

    VHOST_DEFINE (	lpath=>'/soap-lit',
    		ppath=>'/SOAP/', soap_user=>'SOAP_U1',
        		soap_opts=>
    	    	vector ('ServiceName', 'Literal',
    		    'Namespace', 'http://temp.uri',
    		    'SchemaNS', 'http://temp.uri',
    		    'MethodInSoapAction', 'yes',
    		    'elementFormDefault', 'unqualified',
    		    'Use', 'literal'));

    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;
    };

    grant execute on SOAP_StructA to SOAP_U1;
    grant execute on echoStructArray to SOAP_U1;

This would produce the following WSDL file when accessing the http://[host:port]/soap-lit/services.wsdl URL.

    <?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:dime="http://schemas.xmlsoap.org/ws/2002/04/dime/wsdl/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:content="http://schemas.xmlsoap.org/ws/2002/04/content-type/" xmlns:ref="http://schemas.xmlsoap.org/ws/2002/04/reference/" xmlns:ns0="http://temp.uri" xmlns:dl="http://temp.uri" xmlns:tns="services.wsdl" xmlns="http://schemas.xmlsoap.org/wsdl/" targetNamespace="services.wsdl" name="VirtuosoLiteral">
      <types>
        <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" targetNamespace="http://temp.uri">
          <complexType name="echoStructArray_Response_t">
            <sequence>
              <element name="item" type="ns0:SOAP_StructA" minOccurs="0" maxOccurs="unbounded" nillable="true"/>
            </sequence>
          </complexType>
          <complexType name="echoStructArray_sa_t">
            <sequence>
              <element name="item" type="ns0:SOAP_StructA" minOccurs="0" maxOccurs="unbounded" nillable="true"/>
            </sequence>
          </complexType>
          <complexType name="SOAP_StructA">
            <all>
              <element name="varString" type="string" nillable="true"/>
              <element name="varInt" type="int" nillable="true"/>
              <element name="varFloat" type="float" nillable="true"/>
              <element name="varArray" type="ns0:SOAP_StructA_varArray_t" nillable="true"/>
            </all>
          </complexType>
          <complexType name="SOAP_StructA_varArray_t">
            <sequence>
              <element name="item" type="int" minOccurs="0" maxOccurs="unbounded" nillable="true"/>
            </sequence>
          </complexType>
          <element name="echoStructArray">
            <complexType>
              <sequence>
                <element minOccurs="1" maxOccurs="1" name="sa" type="ns0:echoStructArray_sa_t"/>
              </sequence>
            </complexType>
          </element>
          <element name="echoStructArrayResponse">
            <complexType>
              <all>
                <element minOccurs="1" maxOccurs="1" name="CallReturn" type="ns0:echoStructArray_Response_t"/>
              </all>
            </complexType>
          </element>
        </schema>
      </types>
      <message name="echoStructArrayRequest">
        <part element="dl:echoStructArray" name="parameters"/>
      </message>
      <message name="echoStructArrayResponse">
        <part element="dl:echoStructArrayResponse" name="parameters"/>
      </message>
      <portType name="LiteralDocLiteralPortType">
        <operation name="echoStructArray">
          <input message="tns:echoStructArrayRequest" name="echoStructArrayRequest"/>
          <output message="tns:echoStructArrayResponse" name="echoStructArrayResponse"/>
        </operation>
      </portType>
      <binding name="LiteralDocLiteralBinding" type="tns:LiteralDocLiteralPortType">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="echoStructArray">
          <soap:operation soapAction="http://temp.uri#echoStructArray" style="document"/>
          <input name="echoStructArrayRequest">
            <soap:body use="literal"/>
          </input>
          <output name="echoStructArrayResponse">
            <soap:body use="literal"/>
          </output>
        </operation>
      </binding>
      <service name="VirtuosoLiteral">
        <documentation>Virtuoso SOAP services</documentation>
        <port name="LiteralDocLiteralPort" binding="tns:LiteralDocLiteralBinding">
          <soap:address location="http://localhost:8890/soap-lit"/>
        </port>
      </service>
    </definitions>

### 15.2.3. Exposing Third Party SQL Stored Procedures as WSDL-Compliant Web Services

Virtuoso can expose any of its available PL resource to the SOAP world, and subsequently to the WDSL file. This includes data from remote attached tables and procedures. All you have to do is make sure that the entry point exists as a stored procedure in the correct namespace with the appropriate grants, as before.

See Also

The Virtual Database chapter for information regarding use of remote data sources and their tables.

Because remote procedures may not be directly compatible you are required to write a Virtuoso wrapper function first to handle the remote procedure. Below is a sample MS SQLServer procedure and an accompanying Virtuoso wrapper function. The MS SQLServer 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.

MS SQLServer procedure:

    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
    ;

Virtuoso wrapper function:

    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);
    };

Now, as before, we grant execute rights to the SOAP user:

    grant execute on WS.SOAP.ms_remote_call to SOAP;

The third-party procedures can now be accessed via SOAP and are listed in the WSDL file.

### 15.2.4. WSDL Descriptions of SOAP Header Messages

The Virtuoso web server automatically generates WSDL descriptions for procedures exposed as SOAP messages, and those exposed to have parameters bound to SOAP Header messages.

Consider the sample of the Interop.INTEROP.echoVoid procedure defined as an example in the SOAP section as:

    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;
    };

The WSDL description will now contain the header messages also. No extra user intervention is required. The WSDL file that will result will look like:

     ......... WSDL excerpt (consider http://[host:port]/Interop/services.wsdl of an demo DB) ............
    	<message name="echoVoidRequest"></message>
    	<message name="echoVoidResponse"></message>
    	<message name="echoVoidechoMeStringRequest">
    		<part name="echoMeStringRequest" type="xsd:string" />
    	</message>
    	<message name="echoVoidechoMeStringResponse">
    		<part name="echoMeStringResponse" type="xsd:string" />
    	</message>
     ........ in bindings section note the soap:header sections.............
    	<operation name="echoVoid">
    	<soap:operation soapAction="http://soapinterop.org/" />
    	<input>
    	<soap:body use="encoded" namespace="http://soapinterop.org/" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
    	<soap:header use="encoded" message="tns:echoVoidechoMeStringRequest" part="echoMeStringRequest" namespace="http://soapinterop.org/echoheader/" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
    	</input>
    	<output>
    	<soap:body use="encoded" namespace="http://soapinterop.org/" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
    	<soap:header use="encoded" message="tns:echoVoidechoMeStringResponse" part="echoMeStringResponse" namespace="http://soapinterop.org/echoheader/" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" />
    	</output>
    	</operation>
     ........more..........

### 15.2.5. Importing A WSDL File & SOAP/WSDL Proxying

Virtuoso can import WSDL files from other locations using the function:

soap_wsdl_import()

This function reads the descriptions of SOAP messages available in the WSDL file and automatically creates Virtuoso stored procedure wrappers for executing the SOAP messages directly from Virtuoso in procedures. These generated procedures can then be exposed as SOAP messages in the normal way from the Virtuoso SOAP server, and of course fully described by an automatically generated WSDL file for them, thus creating a proxy service for original messages.

### 15.2.6. SOAP/WSDL Interoperability

A key feature of the Web services promise is that Web services published with one server can be called from any other client. The ability of each implementation to make use of each others' output is called interoperability. Thus, Web services created with Virtuoso should interoperate smoothly with services created with Microsoft's .NET, Sun's Java, and so on. Interoperable Web services mean that developers and users do not have to think about which programming language or operating system the services are hosted on.

The evolving nature of the SOAP specification, as well as its complexity, leads to differences in SOAP implementations. Unfortunately, these implementation differences decrease interoperability. To counteract this problem, a volunteer group of SOAP application builders has developed a series of interoperability tests.

OpenLink, as a participant in this group, ensures that its SOAP implementation interoperates fully. This means that Virtuoso's SOAP server properly exposes your Web services so they can be used by any client. It also means that Virtuoso can call services published by any compliant provider.

You can view the Round 1 "Interoperability Lab" at www.xmethods.net and the Round 2 at www.whitemesa.com. Please note that OpenLink has no connection with these companies; they are simply places that volunteered to host the testing reference documents on their servers.

The Round 2 tests include base functionality (which duplicates Round 1) as well as more advanced tests labeled "Group B" and "Group C". The WSDL published by OpenLink containing the descriptions of these tests can be found at http://demo.openlinksw.com:8890/Interop/. This URL will be updated as new interoperability tests are devised.

As of the general release of Virtuoso 2.7, the SOAP implementation passes all known interoperability tests.

Previous SOAP | Chapter Contents | Next WS-Security (WSS) Support in Virtuoso SOAP Server