<!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="3. Quick Start & Tours" />
<meta name="dc.subject" content="3. Quick Start & Tours" />
<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="quicktours.html" title="Chapter Contents" />
<link rel="prev" href="qswebservices.html" title="Web Services" />
<link rel="next" href="qsvsmx.html" title="VSMX - Virtuoso Service Module for XML" />
<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>3. Quick Start & Tours</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="qstexpwsmodules" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>3. Quick Start & Tours</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="quicktours.html">Chapter Contents</a> | <a class="link" href="qswebservices.html" title="Web Services">Prev</a> | <a class="link" href="qsvsmx.html" title="VSMX - Virtuoso Service Module for XML">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="quicktours.html">Quick Start & Tours</a>
</div>
<br />
<div>
<a href="newadminui.html">Where to Start</a>
</div>
<div>
<a href="qsclientcon.html">Client Connections</a>
</div>
<div>
<a href="qsvdbsrv.html">Virtual Database Server</a>
</div>
<div>
<a href="qswebserver.html">Web Server</a>
</div>
<div>
<a href="qswebdav.html">WebDAV</a>
</div>
<div>
<a href="qswebservices.html">Web Services</a>
</div>
<div class="selected">
<a href="qstexpwsmodules.html">Exposing Persistent Stored Modules as Web Services</a>
<div>
<a href="#qstexpwspls" title="Publishing Stored Procedures as Web Services">Publishing Stored Procedures as Web Services</a>
<a href="#qstxmlqtemplates" title="XML Query Templates">XML Query Templates</a>
<a href="#qstpublishbifs" title="Publishing VSE's as Web Services">Publishing VSE's as Web Services</a>
</div>
</div>
<div>
<a href="qsvsmx.html">VSMX - Virtuoso Service Module for XML</a>
</div>
<div>
<a href="qssqltoxml.html">SQL to XML</a>
</div>
<div>
<a href="qsnntp.html">NNTP</a>
</div>
<div>
<a href="vspquickstart.html">Dynamic Web Pages</a>
</div>
<div>
<a href="qsvspexamples.html">VSP Examples</a>
</div>
<div>
<a href="qshostingplugs.html">Third-Party Runtime Typing, Hosting & User Defined Types</a>
</div>
<div>
<a href="troutips.html">Troubleshooting Tips</a>
</div>
<br />
</div>
<div id="text">
<a name="qstexpwsmodules" />
<h2>3.7. Exposing Persistent Stored Modules as Web Services</h2>
<p>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:
</p>
<ul>
<li>
<div class="formalpara">
<strong>Choose your stored procedure(s)</strong>
<p>The procedures that you want to expose can either be native Virtuoso stored procedures,
or remote stored procedures that can be linked in using the Remote Procedures user interface.
</p>
</div>
</li>
<li>
<div class="formalpara">
<strong>Choose a virtual directory</strong>
<p>Because SOAP services need to be exposed and accessed via HTTP a Virtuoso virtual
directory must be used. Either use the existing SOAP virtual directory or create a new one.
</p>
</div>
</li>
<li>
<div class="formalpara">
<strong>Publish procedures to virtual directory</strong>
<p>The user specified as SOAP account on the virtual directory must have execute
privileges on the procedures. Use the Publish options on the virtual directory user interface.
</p>
</div>
</li>
<li>
<div class="formalpara">
<strong>Test the VSMX output</strong>
<p>Once procedures have been published as SOAP services they are automatically
described by WSDL and testable using Virtuoso's VSMX feature.
</p>
</div>
</li>
</ul>
<p>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.
</p>
<p>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!
</p>
<a name="qstexpwspls" />
<h3>3.7.1. Publishing Stored Procedures as Web Services</h3>
<a name="qstexpwssps" />
<h4>3.7.1.1. Choosing Stored Procedures to Expose</h4>
<p>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.
</p>
<p>Virtuoso lists available stored procedures for each catalog in Conductor under:
<strong>/Database/External Data Sources/External Linked Objects / with checked "Stored Procedures"</strong>.
</p>
<p>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.
</p>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Linking Procedures from Remote Data Sources" src="../images/ui/admrmtprocs001.png" />
</td>
</tr>
<tr>
<td>Figure: 3.7.1.1.1. Linking Procedures from Remote Data Sources</td>
</tr>
</table>
<p>Select the check-box "Store Procedures". Click the "Apply" button. As result will
be shown the list of available procedures.
</p>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Linking Procedures from Remote Datasources" src="../images/ui/admrmtprocs002.png" />
</td>
</tr>
<tr>
<td>Figure: 3.7.1.1.2. Linking Procedures from Remote Datasources</td>
</tr>
</table>
<p>Select the check-boxes for the procedures you want to link and click the "Link" button.
</p>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Linking Procedures from Remote Datasources" src="../images/ui/admrmtprocs003.png" />
</td>
</tr>
<tr>
<td>Figure: 3.7.1.1.3. Linking Procedures from Remote Datasources</td>
</tr>
</table>
<p>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.
</p>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Linking Procedures from Remote Datasources" src="../images/ui/admrmtprocs004.png" />
</td>
</tr>
<tr>
<td>Figure: 3.7.1.1.4. Linking Procedures from Remote Datasources</td>
</tr>
</table>
<p>For each remote procedure you may change how they will be referenced within Virtuoso
by making changes to the fields for <strong>Catalog</strong>, <strong>Owner</strong>,
<strong>Link as</strong>, and <strong>Description</strong> fields. These fields define how
you will find the linked procedure locally to Virtuoso only and do not affect the remote data source.
</p>
<p>For each procedure there is an option to <strong>PL Wrapper Requirement</strong>.
This option is required if your remote procedure is capable of returning a resultset that you
want to process via Virtuoso. Can be <strong>SOAP Execution</strong>, <strong>SQL Execution</strong>
or <strong>None</strong>. Also you can specify <strong>Return Type</strong>,
<strong>Data Type</strong>, <strong>SOAP Type</strong>.
</p>
<p>Once the details are correct press the "Link" button.
</p>
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>
<a href="htmlconductorbar.html#remoteprocedures">Linking Remote Procedures</a>
</p>
</div>
<br />
<a name="qstexpwsvirtdir" />
<h4>3.7.1.2. Defining Virtual Directories</h4>
<p>Before any procedures native or linked can be exposed as SOAP Services a location in
HTTP space must be defined. From Conductor <strong>Web Application Server/Virtual Domains & Directories</strong>
you make a new URL Mappings. Click on the <strong>New Directory</strong> link for the
{Default Web Site} line to begin defining a new SOAP mapping.
</p>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Virtual Directories" src="../images/ui/admvirtdir001.png" />
</td>
</tr>
<tr>
<td>Figure: 3.7.1.2.1. Virtual Directories</td>
</tr>
</table>
<p>Select for "Type" from the list the value "SOAP access point" and click the "Next" button.
</p>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Virtual Directories Mappings" src="../images/ui/admvirtdir003.png" />
</td>
</tr>
<tr>
<td>Figure: 3.7.1.2.2. Virtual Directories Mappings</td>
</tr>
</table>
<p>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".
</p>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Virtual Directories" src="../images/ui/admvirtdir004.png" />
</td>
</tr>
<tr>
<td>Figure: 3.7.1.2.3. Virtual Directories</td>
</tr>
</table>
<p>In <strong>Publish Objects</strong> 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.
</p>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Publish Objects" src="../images/ui/admvirtdir005.png" />
</td>
</tr>
<tr>
<td>Figure: 3.7.1.2.4. Publish Objects</td>
</tr>
</table>
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>
<a href="htmlconductorbar.html#httpvirtualdirs">Virtual Directories</a>
</p>
</div>
<br />
<a name="qstexpspublishbtn" />
<h4>3.7.1.3. Publishing Procedures to a Virtual Directory</h4>
<p>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
<strong>Web Application Server/Virtual Domains & Directories</strong>. 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 <strong>Edit</strong> link. Note, the virtual
directory should have type "SOAP".
</p>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Virtual Directories" src="../images/ui/admvirtdir006.png" />
</td>
</tr>
<tr>
<td>Figure: 3.7.1.3.1. Virtual Directories</td>
</tr>
</table>
<p>Go to tab "publish Objects" to expose/hide your procedures, Pl Modules, User Defined Types
and Saved Queries.
</p>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Publish Objects" src="../images/ui/admvirtdir008.png" />
</td>
</tr>
<tr>
<td>Figure: 3.7.1.3.2. Publish Objects</td>
</tr>
</table>
<p>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.
</p>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Choosing Procedure aPublish" src="../images/ui/admvirtdir007.png" />
</td>
</tr>
<tr>
<td>Figure: 3.7.1.3.3. Choosing Procedure aPublish</td>
</tr>
</table>
<br />
<a name="qstexpsvsmxtest" />
<h4>3.7.1.4. Testing SOAP Services Using VSMX</h4>
<p>Virtual directory definitions have a <strong>Logical Path</strong> field, which is
reference in URL to find the correct SOAP services. If you connect to Virtuoso on
<strong>http://localhost:8890/</strong>, and defined your virtual directory with
the logical path of <strong>/mysoap</strong> then you will be able to test the following URLs:
</p>
<ul>
<li>http://localhost:8890/mysoap/services.wsdl</li>
<li>http://localhost:8890/mysoap/services.vsmx</li>
</ul>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Services.wsdl" src="../images/ui/admvirtdir009.png" />
</td>
</tr>
<tr>
<td>Figure: 3.7.1.4.1. Services.wsdl</td>
</tr>
</table>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Services.vsmx" src="../images/ui/admvirtdir010.png" />
</td>
</tr>
<tr>
<td>Figure: 3.7.1.4.2. Services.vsmx</td>
</tr>
</table>
<p>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.
</p>
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>
<a href="vsmx.html">VSMX</a>;
<a href="soap.html">SOAP</a>;
<a href="wsdl.html">WSDL</a>.
</p>
</div>
<br />
<br />
<a name="qstxmlqtemplates" />
<h3>3.7.2. XML Query Templates</h3>
<p>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
<a href="updategrams.html">updategrams</a>. XML templates can be executed from within Virtuoso
procedure language using the <a href="fn_xml_template.html">xml_template()</a>
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.
</p>
<p>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.
</p>
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>The <a href="xmltemplates.html">XML Templates</a> Section</p>
</div>
<p>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.
</p>
<p>Stylesheets transformations with be inactive for published XML templates invoked from SOAP.
</p>
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>The <a href="">Publishing Stored Procedures</a> Section above
for a further description of publishing XML Templates.
</p>
</div>
<br />
<a name="qstpublishbifs" />
<h3>3.7.3. Publishing VSE's as Web Services</h3>
<p>The Virtuoso distribution includes the sample VSE, bif_sample.c. It is thus possible
to create a function such as:
</p>
<div>
<pre class="programlisting">
.....
static caddr_t
bif_hello_world (caddr_t * qst, caddr_t * err_ret, state_slot_t ** args)
{
return box_dv_short_string ("Hello world.");
}
....
</pre>
</div>
<p>Then declare it in the init_func() by adding the following code:</p>
<div>
<pre class="programlisting">
...
bif_define_typed ("hello_world", bif_hello_world, &bt_any);
...
</pre>
</div>
<p>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.
</p>
<div>
<pre class="programlisting">
create procedure BIF_HELLO_WORLD () { return hello_world (); };
</pre>
</div>
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>The <a href="cinterface.html">C Interface</a> Chapter
</p>
</div>
<br />
<table border="0" width="90%" id="navbarbottom">
<tr>
<td align="left" width="33%">
<a href="qswebservices.html" title="Web Services">Previous</a>
<br />Web Services</td>
<td align="center" width="34%">
<a href="quicktours.html">Chapter Contents</a>
</td>
<td align="right" width="33%">
<a href="qsvsmx.html" title="VSMX - Virtuoso Service Module for XML">Next</a>
<br />VSMX - Virtuoso Service Module for XML</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
>
833
