www.openlinksw.com
docs.openlinksw.com

Book Home

Contents
Preface

Web Services

SOAP
WSDL
FOAF+SSL Support
OAuth Support
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
Publishing Stored Procedures as Web Services XML Query Templates Publishing VSE's as Web Services
Testing Web Published Web Services
BPEL Reference
XSQL

15.13. Exposing Persistent Stored Modules as Web Services

Virtuoso SQL stored procedures and functions can be exposed as SOAP services very simply from Virtuoso, whether they are native Virtuoso or on remote data sources. This powerful ability means that any database servers already existing within an organization can easily become a component in an eBusiness solution using Virtuoso. All you need is a few simple steps that typically take mere minutes to complete:

XML Query Templates provide a direct way to store SQL in an XML file on the Virtuoso server that when executed, i.e. fetched from a web browser, actually returns the results of the query.

The C Interface chapter describes how users can define custom built-in functions, from C or other programming languages, that can be used from within Virtuoso PL. This also means that VSE's can also be published as a Web Service!

15.13.1. Publishing Stored Procedures as Web Services

15.13.1.1. Choosing Stored Procedures to Expose

You can either expose native Virtuoso stored procedures (previously defined or newly created) using the CREATE PROCEDURE statement, or stored procedures from other database types can be linked into Virtuoso using an ODBC datasource.

Virtuoso lists available stored procedures for each catalog in Conductor under: /Database/External Data Sources/External Linked Objects / with checked "Stored Procedures".

To link a stored procedure from another database system we must first create a valid data source that leads to a connection to that database. Once verified proceed to the Remote Procedures page. Select the "Link objects" link for a data source.

Linking Procedures from Remote Data Sources
Figure: 15.13.1.1.1. Linking Procedures from Remote Data Sources

Select the check-box "Store Procedures". Click the "Apply" button. As result will be shown the list of available procedures.

Linking Procedures from Remote Datasources
Figure: 15.13.1.1.2. Linking Procedures from Remote Datasources

Select the check-boxes for the procedures you want to link and click the "Link" button.

Linking Procedures from Remote Datasources
Figure: 15.13.1.1.3. Linking Procedures from Remote Datasources

You will be presented with a new page listing the chosen procedures and their data type information. This gives you an opportunity to alter the data type mappings that Virtuoso will use both internally and for any future interactions with the SOAP server. If you do not want to specify any special type information the details can be left as default.

Linking Procedures from Remote Datasources
Figure: 15.13.1.1.4. Linking Procedures from Remote Datasources

For each remote procedure you may change how they will be referenced within Virtuoso by making changes to the fields for Catalog, Owner, Link as, and Description fields. These fields define how you will find the linked procedure locally to Virtuoso only and do not affect the remote data source.

For each procedure there is an option to PL Wrapper Requirement. This option is required if your remote procedure is capable of returning a resultset that you want to process via Virtuoso. Can be SOAP Execution, SQL Execution or None. Also you can specify Return Type, Data Type, SOAP Type.

Once the details are correct press the "Link" button.

See Also:

Linking Remote Procedures


15.13.1.2. Defining Virtual Directories

Before any procedures native or linked can be exposed as SOAP Services a location in HTTP space must be defined. From Conductor Web Application Server/Virtual Domains & Directories you make a new URL Mappings. Click on the New Directory link for the {Default Web Site} line to begin defining a new SOAP mapping.

Virtual Directories
Figure: 15.13.1.2.1. Virtual Directories

Select for "Type" from the list the value "SOAP access point" and click the "Next" button.

Virtual Directories Mappings
Figure: 15.13.1.2.2. Virtual Directories Mappings

You will then be presented with the following tabs: "Virtual Directory Information", "Authentication", "Web Service Option", "WS Security" and "Publish Objects". Particular options to note are "Virtual Directory Information" and "Publish Objects".

Virtual Directories
Figure: 15.13.1.2.3. Virtual Directories

In Publish Objects you can select Virtuoso stored procedures, or remotely linked procedures to be published as SOAP web services. Also you can publish Pl Modules, User Defined Types, or Saved Queries.

Publish Objects
Figure: 15.13.1.2.4. Publish Objects
See Also:

Virtual Directories


15.13.1.3. Publishing Procedures to a Virtual Directory

If you already have a virtual directory defined and know what procedures you want to expose as web services you will have to repeat some of the steps in the section above. From Conductor go to Web Application Server/Virtual Domains & Directories. Click on the "folder" icon for your {Default Web Site}. You will find the list of previously existing mappings, from which you can select the mapping that you want to edit by pressing on its Edit link. Note, the virtual directory should have type "SOAP".

Virtual Directories
Figure: 15.13.1.3.1. Virtual Directories

Go to tab "publish Objects" to expose/hide your procedures, Pl Modules, User Defined Types and Saved Queries.

Publish Objects
Figure: 15.13.1.3.2. Publish Objects

The "Procedures" tab presents the list of available procedures. You can select a catalogue in order to list the procedures you want to publish. When the procedures to be published are selected, you can either click the "Publish Selected" button, or before this to click the "Edit Description" button.

Choosing Procedure aPublish
Figure: 15.13.1.3.3. Choosing Procedure aPublish

15.13.1.4. Testing SOAP Services Using VSMX

Virtual directory definitions have a Logical Path field, which is reference in URL to find the correct SOAP services. If you connect to Virtuoso on http://localhost:8890/, and defined your virtual directory with the logical path of /mysoap then you will be able to test the following URLs:

Services.wsdl
Figure: 15.13.1.4.1. Services.wsdl
Services.vsmx
Figure: 15.13.1.4.2. Services.vsmx

The WSDL description is a standards-based description of the Web Services available from /mysoap. The VSMX page is a Virtuoso generated test page allowing you to test SOAP services. This feature should improve your development time.

See Also:

VSMX; SOAP; WSDL.



15.13.2. XML Query Templates

Virtuoso XML templates allow execution of SQL/XML queries over HTTP to obtain an XML document in response and/or perform some operation in the database using updategrams. XML templates can be executed from within Virtuoso procedure language using the xml_template() function. XML templates support two types of action: SQL based or updategram based. SQL query based templates must contain the FOR XML clause used in a SELECT statement and hence cannot update the database. Updates to the database can only occur from an updategram. The XML document returned from calling an XML template can be served either raw, or transformed using XSLT.

XML templates provide quick easy access to results from a SQL query as usual, but now this can be saved to a file. The results are not saved, just the query definition. You can use this feature to rapidly produce dynamic reports that can potentially be rendered in different ways by providing an alternate stylesheet. The report can be refined on the fly by providing parameters for the query. The output is reachable via HTTP directly by providing the URL to the template.

See Also:

The XML Templates Section

XML Templates can also be published just like normal store procedures. This is achieved by using a PL wrapper around the XML template. Then the store procedure is published in the normal way.

Stylesheets transformations with be inactive for published XML templates invoked from SOAP.

See Also:

The Publishing Stored Procedures Section above for a further description of publishing XML Templates.


15.13.3. Publishing VSE's as Web Services

The Virtuoso distribution includes the sample VSE, bif_sample.c. It is thus possible to create a function such as:

.....
static caddr_t
bif_hello_world (caddr_t * qst, caddr_t * err_ret, state_slot_t ** args)
{
  return box_dv_short_string ("Hello world.");
}
....

Then declare it in the init_func() by adding the following code:

...
  bif_define_typed ("hello_world", bif_hello_world, &bt_any);
...

The next step is creating a stored procedure that calls this function and you are back to publishing a Virtuoso stored procedure again, as in the above section.

create procedure BIF_HELLO_WORLD () { return hello_world (); };
See Also:

The C Interface Chapter