<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->

<sect1 id="expwsmodules"><title>Exposing Persistent Stored Modules as Web Services</title>
  <para>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:
  </para>
  <itemizedlist>
    <listitem>
      <formalpara>
        <title>Choose your stored procedure(s)</title>
        <para>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.
        </para>
      </formalpara>
    </listitem>
    <listitem>
      <formalpara>
        <title>Choose a virtual directory</title>
        <para>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.
        </para>
      </formalpara>
    </listitem>
    <listitem>
      <formalpara>
        <title>Publish procedures to virtual directory</title>
        <para>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.
        </para>
      </formalpara>
    </listitem>
    <listitem>
      <formalpara>
        <title>Test the VSMX output</title>
        <para>Once procedures have been published as SOAP services they are automatically
described by WSDL and testable using Virtuoso's VSMX feature.
        </para>
      </formalpara>
    </listitem>
  </itemizedlist>

  <para>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.
  </para>
  <para>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!
  </para>

<sect2 id="qstexpwspls"><title>Publishing Stored Procedures as Web Services</title>
    <sect3 id="qstexpwssps"><title>Choosing Stored Procedures to Expose</title>
      <para>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.
      </para>
      <para>Virtuoso lists available stored procedures for each catalog in Conductor under:
<emphasis>/Database/External Data Sources/External Linked Objects / with checked "Stored Procedures"</emphasis>.
      </para>
      <para>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.
      </para>
      <figure float="1">
        <title>Linking Procedures from Remote Data Sources</title>
        <graphic fileref="ui/admrmtprocs001.png"/>
      </figure>
      <para>Select the check-box "Store Procedures". Click the "Apply" button. As result will
be shown the list of available procedures.
      </para>
      <figure float="1">
        <title>Linking Procedures from Remote Datasources</title>
        <graphic fileref="ui/admrmtprocs002.png"/>
      </figure>
      <para>Select the check-boxes for the procedures you want to link and click the "Link" button.
      </para>
      <figure float="1">
        <title>Linking Procedures from Remote Datasources</title>
        <graphic fileref="ui/admrmtprocs003.png"/>
      </figure>
      <para>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.
      </para>
      <figure float="1">
        <title>Linking Procedures from Remote Datasources</title>
        <graphic fileref="ui/admrmtprocs004.png"/>
      </figure>
      <para>For each remote procedure you may change how they will be referenced within Virtuoso
by making changes to the fields for <emphasis>Catalog</emphasis>, <emphasis>Owner</emphasis>,
<emphasis>Link as</emphasis>, and <emphasis>Description</emphasis> fields. These fields define how
you will find the linked procedure locally to Virtuoso only and do not affect the remote data source.
      </para>
      <para>For each procedure there is an option to <emphasis>PL Wrapper Requirement</emphasis>.
This option is required if your remote procedure is capable of returning a resultset that you
want to process via Virtuoso. Can be <emphasis>SOAP Execution</emphasis>, <emphasis>SQL Execution</emphasis>
or <emphasis>None</emphasis>. Also you can specify <emphasis>Return Type</emphasis>,
<emphasis>Data Type</emphasis>, <emphasis>SOAP Type</emphasis>.
      </para>
      <para>Once the details are correct press the "Link" button.
      </para>
  <tip><title>See Also:</title>
  <para><link linkend="remoteprocedures">Linking Remote Procedures</link></para></tip>
  </sect3>

    <sect3 id="qstexpwsvirtdir"><title>Defining Virtual Directories</title>
      <para>Before any procedures native or linked can be exposed as SOAP Services a location in
HTTP space must be defined. From Conductor <emphasis>Web Application Server/Virtual Domains &amp; Directories</emphasis>
you make a new URL Mappings. Click on the <emphasis>New Directory</emphasis> link for the
{Default Web Site} line to begin defining a new SOAP mapping.
      </para>

      <figure float="1"><title>Virtual Directories</title>
        <graphic fileref="ui/admvirtdir001.png"/></figure>

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

      <figure float="1"><title>Virtual Directories Mappings</title>
        <graphic fileref="ui/admvirtdir003.png"/></figure>

      <para>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".
      </para>

      <figure float="1"><title>Virtual Directories</title>
        <graphic fileref="ui/admvirtdir004.png"/></figure>

      <para>In <emphasis>Publish Objects</emphasis> 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.
      </para>

      <figure float="1"><title>Publish Objects</title>
        <graphic fileref="ui/admvirtdir005.png"/></figure>


  <tip><title>See Also:</title>
  <para><link linkend="httpvirtualdirs">Virtual Directories</link></para></tip>
  </sect3>

    <sect3 id="qstexpspublishbtn"><title>Publishing Procedures to a Virtual Directory</title>
      <para>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
<emphasis>Web Application Server/Virtual Domains &amp; Directories</emphasis>. 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 <emphasis>Edit</emphasis> link. Note, the virtual
directory should have type "SOAP".
      </para>

      <figure float="1"><title>Virtual Directories</title>
        <graphic fileref="ui/admvirtdir006.png"/></figure>

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

      <figure float="1"><title>Publish Objects</title>
        <graphic fileref="ui/admvirtdir008.png"/></figure>

      <para>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.
      </para>

      <figure float="1"><title>Choosing Procedure aPublish</title>
        <graphic fileref="ui/admvirtdir007.png"/></figure>

  </sect3>

    <sect3 id="qstexpsvsmxtest"><title>Testing SOAP Services Using VSMX</title>
      <para>Virtual directory definitions have a <emphasis>Logical Path</emphasis> field, which is
reference in URL to find the correct SOAP services. If you connect to Virtuoso on
<emphasis>http://example.com/</emphasis>, and defined your virtual directory with
the logical path of <emphasis>/mysoap</emphasis> then you will be able to test the following URLs:
      </para>
    <simplelist>
        <member>http://example.com/mysoap/services.wsdl</member>
        <member>http://example.com/mysoap/services.vsmx</member>
    </simplelist>

    <figure float="1"><title>Services.wsdl</title>
        <graphic fileref="ui/admvirtdir009.png"/></figure>

    <figure float="1"><title>Services.vsmx</title>
        <graphic fileref="ui/admvirtdir010.png"/></figure>

      <para>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.
      </para>

  <tip><title>See Also:</title>
        <para>
          <link linkend="vsmx">VSMX</link>;
    <link linkend="soap">SOAP</link>;
          <link linkend="wsdl">WSDL</link>.
        </para>
      </tip>
  </sect3>
  </sect2>

  <sect2 id="qstxmlqtemplates"><title>XML Query Templates</title>
    <para>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
<link linkend="updategrams">updategrams</link>. XML templates can be executed from within Virtuoso
procedure language using the <link linkend="fn_xml_template"><function>xml_template()</function></link>
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.
    </para>

    <para>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.
    </para>

  <tip><title>See Also:</title>
  <para>The <link linkend="xmltemplates">XML Templates</link> Section</para></tip>

    <para>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.
    </para>
    <para>Stylesheets transformations with be inactive for published XML templates invoked from SOAP.
    </para>

  <tip><title>See Also:</title>
      <para>The <link linkend="expspublishbtn">Publishing Stored Procedures</link> Section above
for a further description of publishing XML Templates.
      </para>
    </tip>
  </sect2>

  <sect2 id="qstpublishbifs"><title>Publishing VSE's as Web Services</title>
    <para>The Virtuoso distribution includes the sample VSE, bif_sample.c. It is thus possible
to create a function such as:
    </para>
<programlisting><![CDATA[
.....
static caddr_t
bif_hello_world (caddr_t * qst, caddr_t * err_ret, state_slot_t ** args)
{
  return box_dv_short_string ("Hello world.");
}
....
]]></programlisting>
    <para>Then declare it in the init_func() by adding the following code:</para>
<programlisting><![CDATA[
...
  bif_define_typed ("hello_world", bif_hello_world, &bt_any);
...
]]></programlisting>
    <para>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.
    </para>
<programlisting>
create procedure BIF_HELLO_WORLD () { return hello_world (); };
</programlisting>

  <tip><title>See Also:</title>
      <para>The <link linkend="cinterface">C Interface</link> Chapter
      </para>
    </tip>
  </sect2>
</sect1>