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!
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 the /Database/External Data Sources/External Linked Objects tab with the Stored Procedures check box selected .
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.
Select the check-box Store Procedures, click the Apply button. and as result the list of available procedures will be presented.
Select the check-boxes for the procedures you want to link and click the Link button.
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.
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 result set 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.
![[Tip]](https://docs.openlinksw.com/virtuoso/qstexpwspls/images/tip.png){kind=small} |
See Also: |
|---|---|
| Linking Remote Procedures |
Defining Virtual Directories
Before any procedures native or linked can be exposed as SOAP Services a location in the HTTP space must be defined. From Conductor Web Application Server/Virtual Domains & Directories tab new URL Mappings can be made. Click on the New Directory link for the {Default Web Site} line to begin defining a new SOAP mapping.
Select for Type from the list the value SOAP access point and click the Next button.
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.
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.
|
See Also: |
|---|---|
| Virtual Directories |
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 the Web Application Server/Virtual Domains & Directories tab . 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.
Go to tab publish Objects to expose/hide your procedures, Pl Modules, User Defined Types and Saved Queries.
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.
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
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.
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.
![[Tip]](https://docs.openlinksw.com/virtuoso/qstxmlqtemplates_01/images/tip.png){kind=small} |
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.
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 (); };
![[Tip]](https://docs.openlinksw.com/virtuoso/qstpublishbifs_01/images/tip.png){kind=small} |
See Also: |
|---|---|
| The C Interface Chapter |
Testing Web Published Web Services
Virtuoso provides a mechanism for testing SOAP messages instantly. This mechanism is the Virtuoso Service Module for XML (VSMX) - an automatically generated test page for published web services. The VSMX file is generated at the same time the WSDL file is generated. A VSMX file is a SOAP operations test page generated based on the descriptions of a WSDL file. The VSMX file has the extension .vsmx, as opposed to the .wsdl extension of the WSDL file, and can be accessed similarly.
VSMX pages give instant access to published SOAP services for testing. Any newly created service will need testing which normally means writing more code to call the service, supply parameters, retrieve the result, display the results in some manor, etc. The VSMX feature of Virtuoso eliminates this otherwise repetitive process by automatically maintaining a test page for SOAP messages: the VSMX file. This greatly speeds up the development and testing cycle. The beauty of this is that this is automated, even Microsoft’s ASMX file requires that you code the services descriptions before seeing the results.
Web Service developers would use VSMX to forego the test bed creation step in light of automatic test page generation. Project managers can easily keep track of their developers progress by checking the test page periodically.
Since WSDL descriptions by themselves are not very pleasing to the human eye, the VSMX test page can be used to preview services available on a Virtuoso server, or from a remote source using SOAP/WSDL Proxying . Even experienced developers will find these easier to read than WSDL files.
Each SOAP enabled virtual directory will have a WSDL and VSMX file available. The VSMX file is a test page for the SOAP operations. This test page can be found as simply as the WSDL can be found. From the WSDL chapter we have seen that for every SOAP enabled virtual directory you automatically get the file:
http://[host:port]/[SOAP Virtual Directory]/services.wsdl
likewise you also get:
http://[host:port]/[SOAP Virtual Directory]/services.vsmx
You simply point your web browser to this file for the test page. The demo database contains samples that can be found as:
http://[host:port]/SOAP/services.vsmx
The page shows all the operations that are available. Click on the link that corresponds to the operation to be tested and the services details and test facilities will also appear, allowing you to supply input parameters making the SOAP call.
Once executed the result of SOAP call will be rendered using the Virtuoso XSLT processor and built-in style sheet, and appended to bottom of the services details.
In addition to the simple types: numbers and strings, more complex types such as arrays and structures can be specified as input parameters. For an array, each value must be specified on a separate row in the input text field. For structures the names of structure members will be displayed, following by the equals sign, the values of the structures members can then be input after the equals sign. Arrays of arrays or structures of arrays cannot be used on the test page.
The first comment line of a stored procedure in the format:
--## [comment]
will be included in the WSDL description of the SOAP message for that procedure when generating the WSDL file.
