3.7. 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:
-
Choose your stored procedure(s). 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.
-
Choose a virtual directory. 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.
-
Publish procedures to virtual directory. 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.
-
Test the VSMX output. Once procedures have been published as SOAP services they are automatically described by WSDL and testable using Virtuoso's VSMX feature.
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!
3.7.1. Publishing Stored Procedures as Web Services
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.
Figure 3.38. 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.
Figure 3.39. Linking Procedures from Remote Datasources
Select the check-boxes for the procedures you want to link and click the "Link" button.
Figure 3.40. 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.
Figure 3.41. 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: | |
---|---|
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.
Figure 3.42. Virtual Directories
Select for "Type" from the list the value "SOAP access point" and click the "Next" button.
Figure 3.43. 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".
Figure 3.44. 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.
Figure 3.45. Publish Objects
See Also: | |
---|---|
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".
Figure 3.46. Virtual Directories
Go to tab "publish Objects" to expose/hide your procedures, Pl Modules, User Defined Types and Saved Queries.
Figure 3.47. 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.
Figure 3.48. Choosing Procedure aPublish
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://example.com:8890/ , and defined your virtual directory with the logical path of /mysoap then you will be able to test the following URLs:
http://example.com:8890/mysoap/services.wsdl |
http://example.com:8890/mysoap/services.vsmx |
Figure 3.49. Services.wsdl
Figure 3.50. 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.