OpenLink Virtuoso Features Demonstrations and Tutorials OpenLink Virtuoso Features Demonstrations and Tutorials Data Management - SQL Tutorial Data Management - XML Tutorial Data Management - Data Replication Tutorial Data Management - RDF Tutorial Web Services - SOAP Services Tutorial Web Services - Wireless Access Protocols Tutorial Business Process Integration - BPEL Tutorial Development - Web 1.0 Tutorial Development - Web 2.0 Tutorial Development - XML Tutorial Development - RDF Tutorial Development - NNTP Tutorial Demo applications - Framework Hosting Tutorial Demo applications - XML Data Access Tutorial Demo applications - Linked Data Tutorial Integrating Common Language Runtime Objects with Virtuoso Fri, 27 Dec 2019 14:12:52 GMT Using C# Objects to extend Virtuoso via User Defined Types. Overview The following tutorial demonstrates how Virtuoso can be extended through the use of a .NET bound language such as C# to create User Defined Types (UDTs), Stored Procedures, and Functions. This is an enhancement of its Object-Relational Database functionality. The demonstrations in this section highlight transparent integration (hosting) between Virtuoso and the Microsoft .NET and Mono implementations of the ECMA Common Language Infrastructure (CLI). Prerequisites The following prerequisites ensure the usability of these tutorial demos on Windows or Linux (and in other future Mono implementations): Linux Mono Runtime and Frameworks (ideally the version bundled with Virtuoso) Mono SDK (if you seek to write your own Objects for integration with Virtuoso) Virtuoso Universal Server for Linux with Mono Hosting Windows .NET Runtime and Frameworks .Net Runtime and Framework SDK (if you seek to write your own Objects for integration with Virtuoso) Virtuoso Universal Server for Windows with .NET CLR Hosting Tutorial Example The following tutorial shows how C# classes are used to create User Defined Types (UDTs) in Virtuoso. Please follow the steps below to maximize the value of this tutorial: Click on the "Set Initial State" link which registers the two C# classes with Virtuoso. Click on the "ho_s_2.sql" link to see the code behind this step Click on the "Run" links to actually experience the demo Demo Breakdown "ho_s_2.sql" performs the following steps Registers the "MyFinances" and "Point" classes with Virtuoso. Click on the "MyFinances.cs" and "Point.cs" links to see the C# source code of these classes Creates the conventional SQL table "Employee" Creates the Object-Relational table "Supplier" that includes a column named "Location" that is of Type "Point" (a UDT) Populates each of the newly created tables with data Creates the "distance" stored procedure which uses a C# function member (method) to calculate the distance between points. "vsp1.vsp" uses the static method "tax" of the "MyFinances" class to compute the payroll tax values for each employee via the "salary" column (like a SQL function would). Take note of the Virtuoso class invocation syntax for static C# methods (the relevant member function type in this demo; true to C# these are called by name rather than instance). "vsp2.vsp" uses the "distance" method of the UDT based column "location" to test for distance values less than "3". The distance values are return values from the "Point" class. Note that the "Point" class computes the distance between two arbitrary points. "vsp3.vsp" is a variation of the previous demo, with the column "location" being used to access and conditionally test the values of data member "x" (shown in "Point.cs" as 0). "vsp4.vsp" is another variation of a query on the "Supplier" table, in this particular case the query uses a Stored Procedure (see definition in "ho_s_2.sql") to filter its result set. It achieves this by using data member values "x" and "y" from column "location", and the arbitrary values 1 & 2 as input parameters for the Stored Procedure "distance". It then tests the return values for those less than 3. Sending an SMS message through an ASP .NET SOAP Client to update a table Fri, 27 Dec 2019 14:12:52 GMT Demonstrating the use of C# to create Virtuoso hosted Stored Procedures and Triggers. In this demo the database events trigger SMS messages that are relayed via C# based SOAP Client. Overview The following tutorial demonstrates how a C# based Managed SOAP Client is used to create SMS based database notification services inside Virtuoso. This demo executes a database trigger every time a new Supplier record is added, updated or deleted. In this example a C# class acts as a SOAP client to a 3rd party XML Web Service that provides the SMS (Short Message Services) delivery to mobile phones. Note, this demo will work with any phone that is capable of receiving SMS (TEXT) messages. Prerequisites This demo currently works only on a Virtuoso server running under Microsoft Windows with following components installed: Windows .NET Runtime and Frameworks .Net Runtime and Framework SDK (if you seek to write your own Objects for integration with Virtuoso) Virtuoso Universal Server for Windows with .NET CLR Hosting. Tutorial Example Please follow the steps below to maximize the value of this tutorial: Click on the "Set Initial State" link which registers the "redcoalsmssvc" service with Virtuoso. Click on the "ho_s_3.sql" link to see the code behind this step Click on the "Run" links to actually experience the demo Demo Breakdown "ho_s_3.sql" performs the following steps Registers the "redcoalsmssvc" class with Virtuoso. Click on the "redcoalsms.cs" and "redcoalsmsref.cs" links to see the C# source code. Note that the class "redcoalsmssvc" is part of an assembly that has the namespace "redcoalsms" Creates the "Suppliers" table Creates a stored procedure "redcoal_send_sms" which demonstrates the syntax for creating an instance variable which includes the assembly namespace in the type reference. Specifically, note the use of an underscore instead of a dot when making this assignment Creates a Trigger named "send_sms_to_mgr_new_supp" that sends an SMS message each time a new "Supplier" table record is inserted Creates a Trigger named "send_sms_to_mgr_mod_supp" that sends an SMS message each time a "Supplier" record is updated Creates a Trigger named "send_sms_to_mgr_mod_supp" that sends an SMS message each time a supplier record is deleted "setup_sms.vsp" sets up all of the base data and verifies that SMS service connectivity required by this demo is available. "handler.vsp" is the actual interface through which you add or delete supplier records which result in SMS notifications being sent to your mobile phone. Hosting CLR types using VSPX session management Fri, 27 Dec 2019 14:12:52 GMT Demonstrating the use of C# to create Virtuoso hosted Stored Procedures and Triggers. In this demo a database events trigger SMS messages that are relayed via a C# based SOAP Client. It also demonstrates Virtuoso Server Pages session management. Overview This is a variation of HO-S-3 with the SOAP client implemented ASP.NET and also demonstrates Virtuoso Server Pages for XML (VSPX) session management. Prerequisites This demo currently works only on a Virtuoso server running under Microsoft Windows with following components installed: Windows .NET Runtime and Frameworks .Net Runtime and Framework SDK (if you seek to write your own Objects for integration with Virtuoso) Virtuoso Universal Server for Windows with .NET CLR Hosting. Tutorial Example The setup_sms.vspx sets up the SMS sending unit. The handler.vspx does inserts/deletes/updates to demonstrate the SMS sending from triggers. The redcoalsms*.cs is an MS Visual Studio.NET generated SOAP client. The redcoalsms.dll should be installed as a private assembly (not as CodeBase) because of permissions. For details of the Redcoal SOAP service see it's description in http://www.xmethods.com Hosting CLR types using VSPX session management Fri, 27 Dec 2019 14:12:52 GMT Demonstrating the use of C# to create Virtuoso hosted Stored Procedures and Triggers. In this demo a database event trigger SMS messages that are relayed via a .NET DOM frameworks based C# SOAP Client. It also demonstrates Virtuoso Server Pages session management. Overview HO-S-5 is a variation of HO-S-3 that makes use of VSPX session management Prerequisites The following prerequisites ensure the usability of these tutorial demos on Windows or Linux (and in other future Mono implementations): Linux Mono Runtime and Frameworks (ideally the version bundled with Virtuoso) Mono SDK (if you seek to write your own Objects for integration with Virtuoso) Virtuoso Universal Server for Linux with Mono Hosting Windows .NET Runtime and Frameworks .Net Runtime and Framework SDK (if you seek to write your own Objects for integration with Virtuoso) Virtuoso Universal Server for Windows with .NET CLR Hosting Tutorial Example The setup_sms.vspx sets up the SMS sending unit. The handler.vspx does inserts/deletes/updates to demonstrate the SMS sending from triggers. The redcoalsms_dom.cs is an HttpWebRequest SOAP client using DOM to process SOAP result. The redcoalsms_dom.dll should be installed as a private assembly (not as CodeBase) because of permissions. For details of the Redcoal SOAP service see it's description in http://www.xmethods.com This service is compatible with Mono (http://go-mono.com) Integrating Common Language Runtime Objects with Virtuoso Fri, 27 Dec 2019 14:12:52 GMT Using C# Objects to extend Virtuoso via User Defined Types using CREATE LIBRARY/ASSEMBLY syntax. Overview The HO-S-10 sample is very similar to HO-S-2. The difference is using syntax CREATE LIBRARY. The statement imports assembly to internal Virtuoso table and imports types from it. After this the assembly can be removed from physical path and next time will be read from the table. The "DROP LIBRARY" removes assembly from table and drops imported types. Prerequisites The following prerequisites ensure the usability of these tutorial demos on Windows Windows .NET Runtime and Frameworks .Net Runtime and Framework SDK (if you seek to write your own Objects for integration with Virtuoso) Virtuoso Universal Server for Windows with .NET CLR Hosting Tutorial Example The following tutorial shows how C# classes are used to create User Defined Types (UDTs) in Virtuoso. Please follow the steps below to maximize the value of this tutorial: Click on the "Set Initial State" link which registers the two C# classes with Virtuoso. It also copies the Point_ho_s_10.dll file to "tmp" directory in the server root. Note that the directory must exists, must be writeable for the user running virtuoso and must be in the DirsAllowed parameter in Virtuoso ini file. Click on the "ho_s_10.sql" link to see the code behind this step Click on the "Run" links to actually experience the demo Demo Breakdown "ho_s_10.sql" performs the following steps Registers the "Point" classes with Virtuoso. Click on the "Point_ho_s_10.cs" links to see the C# source code of these classes Creates the Object-Relational table "Supplier_ho_s_10" that includes a column named "Location" that is of Type "Point" (a UDT) Populates table with data Using syntax: CREATE LIBRARY/ASSEMBLY "myPoint" as "assembly" WITH PERMISSION_SET = SAFE WITH AUTOREGISTER is simular to: CREATE LIBRARY/ASSEMBLY "myPoint" as "assembly"; and import_clr ('myPoint', NULL); "vsp1.vsp" is a variation of HO-S-2 (vsp3.vsp), with the column "location" being used to access and conditionally test the values of data member "x" (shown in "Point.cs" as 0). Integrating Common Language Runtime Objects with Virtuoso Fri, 27 Dec 2019 14:12:52 GMT Using Restrictions for C# Imported types. Overview This tutorial demonstrates the options PERMISSION_SET = SAFE and PERMISSION_SET = UNRESTRICTED on CREATE LIBRARY / ASSEMBLY. Prerequisites The following prerequisites ensure the usability of these demos on Windows Windows .NET Runtime and Frameworks .Net Runtime and Framework SDK (if you seek to write your own Objects for integration with Virtuoso) Virtuoso Universal Server for Windows with .NET CLR Hosting Tutorial Example The tutorial shows how C# classes are used to create User Defined Types (UDTs) in Virtuoso. Please follow the steps below to maximize the value of this tutorial: Click on the "Set Initial State" link which registers the two C# classes within Virtuoso. It also copies the restricted.dll and unrestricted.dll files to "tmp" directory in the server root. Note that the directory must exists, must be writeable for the user running virtuoso and must be in the DirsAllowed parameter in Virtuoso ini file. Click on the "ho_s_11.sql" link to examine the code behind this step. Click on the "Run" links to execute the demo. Demo Breakdown "ho_s_11.sql" performs the following steps Registers the "Rest" and "UnRest" classes with Virtuoso. Click on the "restricted.cs" and "unrestricted.cs" links to see the C# source code of these classes. The "unrestricted.vsp" is shows classes that try to access File system and system variables. The "restricted.vsp", uses the same clases, but cannot complete the execution sucessfully because the assembly is imported with PERMISSION_SET = SAFE. The sample shows the error returned upon executing the classes. Making Table valued functions in C# Fri, 27 Dec 2019 14:12:52 GMT Using C# Objects to make table valued functions. Overview The following tutorial demonstrates how Virtuoso can be extended through the use of a .NET bound language such as C# to create resultsets. The demonstrations in this section highlight transparent integration (hosting) between Virtuoso and the Microsoft .NET and Mono implementations of the ECMA Common Language Infrastructure (CLI) as well as how to use the Virtuoso in-process ODBC client to call back the server from hosted managed code. Prerequisites The following prerequisites ensure the usability of these tutorial demos on Windows or Linux (and in other future Mono implementations): Linux Mono Runtime and Frameworks (ideally the version bundled with Virtuoso) Mono SDK (if you seek to write your own Objects for integration with Virtuoso) Virtuoso Universal Server for Linux with Mono Hosting Virtuoso .NET provider Windows .NET Runtime and Frameworks .Net Runtime and Framework SDK (if you seek to write your own Objects for integration with Virtuoso) Virtuoso Universal Server for Windows with .NET CLR Hosting Virtuoso .NET provider Tutorial Example The following tutorial shows how C# classes can interact with the Virtuoso server. Please follow the steps below to maximize the value of this tutorial: Copy the file ho_s_14.dll next to the OpenLink.Data.VirtuosoClient.dll (if not allready there). Click on the "Set Initial State" link which registers the C# class with Virtuoso. Click on the "ho_s_14.sql" link to see the code behind this step Click on the "Run" links to actually experience the demo Demo Breakdown "ho_s_14.sql" registers the "openlink.virtuoso.tutorial.ho_s_14.add_data" C# static method with Virtuoso. Click on the "ho_s_14.cs" link to see the C# source code of this class "vsp1.vsp" uses the static method "add_data" of the "openlink.virtuoso.tutorial.ho._s_14" class to make a resultset (like a SQL function would) through an in-process connection to the server. Take note of the usage of "OpenLink.Virtuoso.InProcessPort" key from AppDomain.GetData() to get the port on which the hosting Virtuoso server is listening at. Accessing COM Objects via C# Fri, 27 Dec 2019 14:12:52 GMT Using the .NET to access native COM objects from Virtuoso/PL Overview The following tutorial demonstrates how Virtuoso can access MS Windows COM objects via .NET. The demonstrations in this section highlight transparent integration (hosting) between Virtuoso, the Microsoft .NET implementations of the ECMA Common Language Infrastructure (CLI) and the Win32 COM Layer. Prerequisites The following prerequisites ensure the usability of these tutorial demos on Windows: .NET Runtime and Frameworks .Net Runtime and Framework SDK (if you seek to write your own Objects for integration with Virtuoso) Virtuoso Universal Server for Windows with .NET CLR Hosting Tutorial Example The following tutorial shows how the Virtuoso server can call native Win32 COM objects using the .NET runtime as intermediary. Please follow the steps below to maximize the value of this tutorial: Register the COM library COM/VirtCOMServer/Debug/VirtCOMServer.dll with COM (via regsvr32.exe COM/VirtCOMServer/Debug/VirtCOMServer.dll). Copy the interop assembly COM/VirtCOMServer/VirtCOMServer.dll next to the virtuoso server binary (if not allready there). Click on the "Set Initial State" link which registers the C# interop class for the Interface IVirtCOMObject with Virtuoso. Click on the "ho_s_15.sql" link to see the code behind this step Click on the "Run" links to actually experience the demo Demo Breakdown "ho_s_15.sql" registers the "VirtCOMServer.CVirtCOMObjectClass" C# interop class with Virtuoso. Click on the "VirtCOMObject.c" and "VirtCOMObject.h" link to see the C++ source code of this interface and it's class "vsp1.vsp" uses the methods "AddAmount", "Clear" and "get_balance" of the "VirtCOMServer.IVirtCOMObject" Interface to sum a number of amounts and get the resulting total. Integrating Java Objects with Virtuoso Fri, 27 Dec 2019 14:12:52 GMT Using Java Objects to extend Virtuoso via User Defined Types. Overview The following tutorial demonstrates how Virtuoso can be extended through the use of Java to create User Defined Types (UDTs), Stored Procedures, and Functions. This is an enhancement of its Object-Relational Database functionality. The demonstrations in this section highlight transparent integration (hosting) between Virtuoso and the Java Runtime Environment. Prerequisites The following prerequisites ensure the usability of these tutorial demos on any platform with a Java Runtime environment: Java Runtime (J2EE 1.2 and Higher) Java SDK (if you seek to write your own Objects for integration with Virtuoso) Virtuoso Universal Server with Java Runtime Hosting Tutorial Example The following tutorial shows how Java Classes are used to create User Defined Types (UDTs), Stored Procedures, and Functions in Virtuoso. Please follow the steps below to maximize the value of this tutorial: Click on the "Set Initial State" link which registers the Java classes used in this demo with Virtuoso. Click on the "ho_s_1.sql" link to see the code behind this step Click on the "Run" links to actually experience the demo Demo Breakdown "ho_s_1.sql" performs the following steps Registers the "MyFinances" and "Point" Classes with Virtuoso as UDTs. Click on the "MyFinances.java" and "Point.java" links to see the JAVA source code Creates the conventional SQL table "Employee" Creates the Object-Relational table "Supplier" that includes a column named "Location" that is of Type "Point" (which is a UDT) Populates each of the newly created tables with data Creates the "distance" stored procedure which uses UDT methods to calculate the distance between points. "vsp1.vsp" uses the static method "tax" of the "MyFinances" class to compute the payroll tax values for each employee via the "salary" column (like a SQL function would). "vsp2.vsp" uses the "distance" method of the UDT based column "location" to test for distance values less than "3". The distance values are return values from the "Point" UDT. Note that "Point" class is computing the distance between two arbitrary points "vsp3.vsp" is a variation of the previous demo, with the UDT based column "location" being used to access and conditionally test the values of data member "x" (shown in "Point.java" as 0) "vsp4.vsp" is another variation of a query on the "Supplier" table, in this particular case the query uses a Stored Procedure (see definition in "ho_s_2.sql") to filter its result set. It achieves this by using data member values "x" and "y" from column "location", and the arbitrary values 1 & 2 as input parameters for the Stored Procedure "distance". It then tests the return values for those less than 3. Integrating Java Objects with Virtuoso Fri, 27 Dec 2019 14:12:52 GMT Using Restrictions for Java hosted types. Overview The following tutorial demonstrates how Virtuoso can Restrict Java hosted types. Prerequisites The following prerequisites ensure the usability of these tutorial demos on any platform with a Java Runtime environment: Java Runtime (J2EE 1.2 and Higher) Java SDK (if you seek to write your own Objects for integration with Virtuoso) Virtuoso Universal Server with Java Runtime Hosting Tutorial Example Please follow the steps below to maximize the value of this tutorial: Click on the "Set Initial State" link which registers the Java classes used in this demo with Virtuoso. Click on the "ho_s_13.sql" link to see the code behind this step Click on the "Run" links to actually experience the demo Demo Breakdown "ho_s_13.sql" performs the following steps Registers the "Restricted" and "Unrestricted" Classes with Virtuoso as UDTs. Click on the "Restricted.java" and "Unrestricted.java" links to see the JAVA source code The Restricted types can't write to FS, can't read System envariment. For full list from restrictions, please see documentation. Filter WebDAV content content by XQuery Fri, 27 Dec 2019 14:12:54 GMT fn:collection usage example Preliminary XQuery collection function can be used to get all parsed documents in collection. Virtuoso engine supports several types of collections: http://local.virt/DAV/PATHTO - local DAV collection. Contains all documents in DAV collection with path "PATHTO". http://host:port/path - any other URL that can be used to access remote WebDAV collections In this example collection function is used to filter local blog entries and all cached blog entries from subscriptions. search.vsp uses this collection to filter blogs by XPath exression. For instance, search.vsp with '//a' expression returns all link from all blogs. text.vsp uses collection function to search blogs which contain some word. Note, it uses "contains" predicate to search blogs, this means it is case sensitive. Prerequisites This example needs the following VAD packages to be installed: Conductor Framework Briefcase Feed Manager Weblog If you do not have permissions to install the above please ask the administrator. The VAD installation can be done via Conductor (if it's installed) or via ISQL tool using vad_install() API function. For more details on vad installation please read the user manual. Important: before to run any of the actions bellow you need to setup a ODS account (or use tutorial_demo with password secret). In both cases you will need to login in ODS and create instances of the Briefcase, Feed Manager and Weblog applications. Using the Feed Manager you should subscribe to some news feeds in RSS, Atom or RDF format. Using the Briefcase you can upload some sample data in the account's home directory. Using the Weblog, make few sample blog posts. Example overview This example demonstrates: XQuery collection function XPath extension functions WebDAV Resource Filtering and WebDAV Extension Types (DETs) Example Operation Login into ODS using the link bellow, after successfull authentication the ODS login will redirect browser back to this page Using the link 'Run' start the search.vsp Initially you will have the ODS account's home directory set as a base, so you can change it using the browse button If you don't have initial data loaded or data which not satisfies the conditions, the query execution will be produce empty result. Example Setup The demo support functions are prepared by loading the supplied SQL file How to run the examples In order to enter the initial data via ODS you need to login and create instances via ODS. After entering the initial data, you will need to go back to this page. If you already done this just skip this step In order to run the examples, you need to login in the Web Applications. To login you can use the already defined user "tutorial_demo" with password "secret" case sensitive. When you click the "Run" link of the search.vsp file the browser will be redirected to ODS login page. After succefull login the browser will be redirected back to this page. Filter blogs content by XQuery Fri, 27 Dec 2019 14:12:54 GMT collection usage example Example collection description XQuery collection function can be used to get all parsed documents in collection. Virtuoso engine supports several types of collections: http://local.virt/DAV/PATHTO - local DAV collection. Contains all documents in DAV collection with path "PATHTO". http://..... - any other URI relates to remote DAV collections In this example collection function is used to concatenate the entries from several RSS feed files and show their titles and link to the articles. example.vsp uses this collection to filter blogs by XPath exression. For instance, example.vsp with '//link' expression returns all link from all feeds. Click on the "Set initial state" link to load the XML files in /DAV/feeds/xq_s_2a/ DAV Collection. Click on the "Run" link to experience the demo. Please note that some of the options query files loaded in demo XQ-S-2. Slashdot RSS feed retrieval Fri, 27 Dec 2019 14:12:54 GMT document usage example Example document description XQuery document function can be used to get a parsed document via URL. In this example the document is used to retreive the Slashdot RSS feed and convert the contents into a feed index. Click on the "Set initial state" link to load the slash.xml file in /DAV/xmlsql/ DAV Collection with execute permisions. Click on the "Run" link and the browser will be redirected to /DAV/xmlsql/slash.xml?contenttype=text/html. OPML file generation from XHTML source Fri, 27 Dec 2019 14:12:54 GMT document usage example Example The demo retrieve a HTML pages containing attendees or bloggers listings and convert them to OPML. The conversion is done with XQuery and user-defined XPath functions to resolve the feeds URLs. The demo also retrieve few OPML files and re-construct them having the feeds URLs if they are missing. When setting the initial state, the demo starts to retrieve pages from the different sites. It could take a long time depending on the Internet connection of the machine that Virtuoso is running on. It is safe to leave the pop-up open without waiting it to finish and press on the "Run" links, however if this is the first time you run the initial state, the demo will show only partial results. Once the feeds are resolved they will be cached locally in a database table and the generated OPML files will be stored as a WebDAV resources. The following are source references used in the demo: http://wiki.techcrunch.com/third_meetup http://news.com.com/html/ne/blogs/CNETNewsBlog100.opml http://conferences.oreillynet.com/pub/w/23/speakers.html http://conferences.oreillynet.com/pub/w/38/speakers.html http://www.alwayson-network.com/comments.php?id=10852_0_11_0_C http://www.gnomedex.com/holdings/br_2005%20Gnomedexers.opml http://www.web2con.com/pub/w/40/speakers.html http://www.thenewpr.com/wiki/pmwiki.php?pagename=Resources.CEOBlogsList http://nwr.cowblock.net/index.php?action=list http://okrasoup.typepad.com/black_looks/2005/05/naija_blogs.html http://allafrica.com/afdb/blogs/blogafrica.opml Overview Fri, 27 Dec 2019 14:12:54 GMT XMLELEMENT() function. XMLELEMENT() function. Overview XMLELEMENT takes an element name for identifier, an optional collection of attributes for the element, and arguments that make up the element's content. It returns an XML element. The second parameter may be omitted and at that time the rest parameters may be present. If one of the arguments is a call of the xpath_eval returning an attribute value, then this value would be added to element's content (not to element's attributes). XMLATTRIBUTES() function. Overview This function creates a vector that may be used only as argument of XMLELEMENT function. The vector has an even number of elements, each odd element is a name of an attribute, an even element is its value. If the attribute value is NULL, then no attribute and no value is created. If none of the attribute is created, then the function returns null. If a parameter of the function is a column name, then you can omit the 'AS clause', and Virtuoso uses the partially escaped form of the column name as the attribute name. sx_e_? Demos Countinue with the next sx_e_? demos to see examples of functoins usage Making an XML element without content Fri, 27 Dec 2019 14:12:54 GMT XML element without content Example 1 This example shows a simple use of the XMLELEMENT() for creating the xml element 'Employee' (for each employee) without content: select XMLELEMENT ("Employee") from "Demo"."demo"."Employees" Making an XML element with a text content Fri, 27 Dec 2019 14:12:54 GMT XML element with a text content Example 2 This example shows a use of the XMLELEMENT() for creating the xml element 'EmployeeName' (for each employee) with the text content that is value of the 'LastName' column from the "Demo"."demo"."Employees" table. select XMLELEMENT ("EmployeeName", "LastName") from "Demo"."demo"."Employees"; Making an XML element with attributes Fri, 27 Dec 2019 14:12:54 GMT XML element with attributes Example 3 This example shows a use of the XMLELEMENT() for creating the xml element 'Emp' with three attributes - 'EmployeeID', 'firstname' and 'lastname' getting their values from the 'EmployeeID', 'FirstName' and 'LastName' columns, respectively. The pairs of attribute and its value are produced by XMLATTRIBUTES() function. If a parameter of the XMLATTRIBUTES() has no 'as clause', Virtuoso uses the partially escaped form of the column name as the attribute name. select XMLELEMENT ("Emp", XMLATTRIBUTES ("EmployeeID", "FirstName" as "firstname", "LastName" as "lastname")) from "Demo"."demo"."Employees"; Making an XML element with attribute, a text content and a sublement Fri, 27 Dec 2019 14:12:54 GMT XML element with attribute, a text content and a sublement Example 4 This example shows a use of the XMLELEMENT() for creating the xml element 'Employee' with the 'EmployeeID' attribute, text content that is concatenations of the value of the 'FirstName' column, of the blank character and of the value of the 'LastName', and the 'Title' subelement having 'title' attribute. select XMLELEMENT ('Employee', XMLATTRIBUTES ("EmployeeID"), "FirstName"||' '||"LastName", XMLELEMENT("Title", XMLATTRIBUTES ( "Title" as "title"))) from "Demo"."demo"."Employees"; Making an XML element with two nested subelements Fri, 27 Dec 2019 14:12:54 GMT XML element with two nested subelements Example 5 This example shows a use of the XMLELEMENT() for creating the xml element 'FullName' with two subelements 'firstname' and 'lastname'. Both subelements have the simple text content. select XMLELEMENT ('FullName', XMLELEMENT ('firstname', "FirstName"), XMLELEMENT ('lastname', "LastName")) from "Demo"."demo"."Employees"; Making an XML element with nested XMLFOREST() function Fri, 27 Dec 2019 14:12:54 GMT XML element with XMLFOREST() function call as parameter Example 6 The example shows a use of the XMLELEMENT() with the nested call of XMLFOREST() function. The result is identical to the previous example. select XMLELEMENT ('FullName', XMLFOREST ("FirstName"as "firstname", "LastName" as "lastname")) from "Demo"."demo"."Employees"; Making an XML element with nested XMLCONCAT() function Fri, 27 Dec 2019 14:12:54 GMT XML element with XMLCONCAT() function call as parameter Example 7 The example shows a use of the XMLELEMENT() with the nested call of XMLCONCAT() function. The result is identical to the previous two examples. select XMLELEMENT ('FullName', XMLCONCAT ( XMLELEMENT ('firstname', "FirstName"), XMLELEMENT ('lastname', "LastName"))) from "Demo"."demo"."Employees"; Making an XML element with nested XMLAGG() function Fri, 27 Dec 2019 14:12:54 GMT XML element with XMLAGG() function call as parameter Example 8 This example produces an 'Emp' element with attribute 'Title' and a list of all employees having the title 'Sales Representative' as element content. select XMLELEMENT ('Emp', XMLATTRIBUTES ("Title"), XMLAGG (XMLELEMENT ('Name', "FirstName", ' ', "LastName"))) from "Demo"."demo"."Employees" where "Title"= 'Sales Representative'; Making an XML element with the entity objects as parameters Fri, 27 Dec 2019 14:12:54 GMT XML element with the entity objects as parameters Example 9 This example creates an 'FullAddress' element with four attributes, three of them ('PostalCode', 'Address', 'City') are produced by XMLATTRIBUTES, and the fourth attribute - 'country' is calculated by xquery_eval 'Region' subelement, that is produced by xtree_doc text content, that is produced by xpath_eval 'emp' subelement with text content from the column "LastName", that is created by nested XMLELEMENT select XMLELEMENT ('FullAddress', XMLATTRIBUTES ( "PostalCode", "Address", "City"), xtree_doc ('<Region>WA</Region>'), xquery_eval('//@country', xtree_doc('<a country="USA"/>')), xpath_eval('//@Phone', xtree_doc('<a Phone="(206) 555-9857"/>')), XMLELEMENT('emp', "LastName")) from "Demo"."demo"."Employees" Making a Forest of XML elements Fri, 27 Dec 2019 14:12:54 GMT XMLFOREST() function XMLFOREST() function. Overview XMLFOREST produces a forest of XML elements from the given list of arguments. The arguments may be string expressions with optional aliases. If string expression is a column name, then you can omit the 'AS clause', and Virtuoso uses the partially escaped form of the column name as the name of the enclosing tag. If the expression evaluates to NULL, then no element is created for that expression. If none of the element is created, then the function returns null. Example 1 This example produces a forest of five (or four) elements ('FName', 'LName', 'Title', 'Region' - if there is a value, 'str') with the text content from 'FirstName', 'LastName', 'Title', and 'Region' columns of the "Employees" table and 'simple_string' string, and concatenates the elements produced. Five elements are created for the employee with "EmployeeId" = 1 and four elements are created for the employee with "EmployeeId" = 5: select XMLFOREST ("FirstName" as "FName", "LastName" as "LName", "Title", "Region", 'simple_string' as "str") from "Demo"."demo"."Employees" where "EmployeeId" = 1 or "EmployeeId" = 5 Making a Forest of XML elements by XMLCONCAT() function Fri, 27 Dec 2019 14:12:54 GMT XMLCONCAT() function XMLCONCAT() function Overview XMLCONCAT() accepts a list of XML value expressions as its arguments, and produces a forest of elements by concatenating the XML values that are returned from the same row to make one value. XMLCONCAT works like XMLFOREST, except that XMLCONCAT parameters is a list of XML elements. Null expressions are dropped from the result. If all the value expressions are null, then the function returns null. Example 1 This example produces a forest from the 'FName', 'LName' and 'Region' (if a column value is not NULL) elements for each employee: select XMLCONCAT ( XMLELEMENT ('FName', "FirstName"), XMLELEMENT ('LName', "LastName"), XMLELEMENT ('Region', "Region") ) from "Demo"."demo"."Employees"; Making a Forest of XML elements by XMLAGG() function Fri, 27 Dec 2019 14:12:54 GMT XMLAGG() function XMLAGG() function. Overview XMLAGG is aggregate function that produces a forest of XML elements from the given list of xml elements. It concatenates the values returned from one column of multiple rows, unlike XMLCONCAT, which concatenates the values returned from multiple columns in the same row. Example 1 This example produces a forest of all 'Name' of the employees having the title 'Sales Representative' and places it into one top-level element: select XMLELEMENT ('SalesRepresentatives', XMLAGG (XMLELEMENT ('Name', "FirstName", ' ', "LastName")) ) from "Demo"."demo"."Employees" where "Title"='Sales Representative'; Making a freetext index Fri, 27 Dec 2019 14:12:54 GMT Freetext index over XML data Preliminaries Virtuoso provides a compact and efficient free text indexing capability for text and XML data. A free text index can be created on any character column, including wide and long data. If the column being indexed is XML data, this can be declared and enforced by the text index. XML data will be indexed specially to support efficient XPATH predicate evaluation with the xcontains predicate. create_freetext_index : CREATE TEXT [XML] INDEX ON q_table_name '(' column ')' [WITH KEY column] [NOT INSERT] [CLUSTERED WITH '(' column_commalist ')' ] [USING FUNCTION] [LANGUAGE STRING] ; The XML keyword specifies that the data is to be indexed as XML, hence element names and attributes will be processed separately for use with the XCONTAINS predicate. Example The script inserts the files into the table. The data is stored as text, not as persistent XML. A VSP page shows the list of rows in the table. Each row has the following links: XML source - send the XML text as escaped text enclosed in an HTML <pre> tag. Raw XML - send the XML to the user agent, which must be able to render XML. Making a freetext index Fri, 27 Dec 2019 14:12:54 GMT Freetext index over persistent XML data Example Take the table def from nwxml3.sql note the create text xml index .... The script inserts the files into the table. The data is stored as persistent XML. A VSP page shows the list of rows in the table. Each row has the following links: XML source - send the XML text as escaped text enclosed in an HTML <pre> tag. Raw XML - send the XML to the user agent. Must be able to render XML. Search on freetext indexed data Fri, 27 Dec 2019 14:12:54 GMT Search on freetext indexed data Example The example shows entity references using data from XS-S-1. The VSP page has a button for retrieving title elements from a selected document, where the title element contains a substring. The example uses the 'xpath-contains' predicate. The VSP page has a second button with the same function using text-contains. This illustrates that xcontains + text-contains does not go through links, but that xpath_contains + contains does. The example has a viewer for the source of each page so that the entity references can be seen. The page has some of the rows of the text table as persistent XML and others as text. The columns are declared as ANY in SQL. This illustrates the late binding dependent on representation. Storing of XSLT results Fri, 27 Dec 2019 14:12:54 GMT Search on freetext indexed data using xcontains predicate Example The example shows entity references using data from XS-S-1. The VSP page has a button for retrieving title elements from a selected document, where the title element contains a substring. The example uses the 'xpath contains' predicate. The VSP page has a second button with the same function using text-contains. This illustrates that xcontains + text-contains does not go through links, but that xpath_contains + contains does. The example has a viewer for the source of each page so that the entity references can be seen. The page has some of the rows of the text table as persistent XML and others as text. The columns are declared as ANY in SQL. This illustrates the late binding dependent on representation. Storing of XSLT results Fri, 27 Dec 2019 14:12:55 GMT Storing of XSLT results Example The sample shows storing of XSLT results into a table. The sample will take abstracts and other suitable subsections from the XS-S-1 data and insert them into another table. The VSP will show the source and result of the transformation side by side for any given document. The example uses data from XS-S-1, so it is important to set it first before trying this demo. XPATH interpreter Fri, 27 Dec 2019 14:12:55 GMT Applying the XPATH expression Example This example allows a selection from a document formed by XS-S-1, and applies a user-written XPATH expression to it. The page has selectable sample expressions including: Count of all titles Sum of the length of sect2 titles All first paragraphs of sect2's. The example uses xpath_eval, and iterates on the results if an array is produced. A single element of the XS-S-1 data is picked as the context node. A special button applies the operation on all rows with xpath_contains, showing the result set with doc name and result. This shows how one row can make multiple results with xpath_contains, but will return an array with xpath_eval. XSL-T transformation Fri, 27 Dec 2019 14:12:55 GMT Passing an XML entity as parameter to the XSL-T style-sheet Example This example uses the result from the XML parser in HTML mode to pass a parameter to the XSL-T style-sheet. The XSL-T style-sheet renders the target XML document. The section to be transformed is passed as the entity. Freetext indexing hooks Fri, 27 Dec 2019 14:12:55 GMT Building a freetext index using a custom PL indexing hooks Freetext Index The freetext index has a default mechanism for indexing and unindexing. By default indexing/unindexing is performed over data column. A custom PL hook can be made for indexing/unindexing, and be associated to the freetext index definition. The data from additional columns can be indexed in the custom PL hooks. Working together with off-band data columns to make index sensitive to changes in the additional columns data they should be declared as off-band data. Example The example SQL script does the following steps: Definition of the hooks Making of text index Using the xpath_eval() Fri, 27 Dec 2019 14:12:55 GMT Making the resultsets with xpath_eval() function Preliminaries The xpath_eval() function returns the result of applying the xpath expression to the context node. By default only the first result is returned, but supplying a third argument allows an index for the value to be specified. The default assumes a value of 1 here. A value of 0 returns an array of 0 or more elements, one for each value selected by the xpath expression. Examples The examples create an internal representation of the XML image using xml_tree_doc(). An xpath_eval() statement is then executed against the internal representation of the XML document specified as /ROOT/Customers which identifies the <Customers> nodes to be processed. The loop iterates over result for each attribute value (as CustomerID and ContactName in the first example) and retrieves the necessary values. Then the PL procedures calls result_names() and result() to send the result set to the client. The first example will produce (when applying via ISQL utility) CustomerID ContactName VARCHAR VARCHAR ________________________ VINET Paul Henriot LILAS Carlos Gonzalez Here is the result from execution of the second script: OrderID CustomerID OrderDate ProductID Quantity VARCHAR VARCHAR VARCHAR VARCHAR VARCHAR ______________________________________________________________________ 10248 VINET 1996-07-04T00:00:00 11 12 10248 VINET 1996-07-04T00:00:00 42 10 10283 LILAS 1996-08-16T00:00:00 72 3 The VSP code displays the same data, but formats it into a table. The third example shows XML entities that have returned from first execution of the xpath_eval(); Overview Fri, 27 Dec 2019 14:12:54 GMT Mapping Schemas Mapping Schemas as XML views. XML views of relational data is similar to creating views by using CREATE VIEW statements. XML views can be created by using the XML Schema Definition (XSD) language, and then can be queried by using XML Path language (XPATH) queries or XML Query (XQUERY) queries with using xmlview function. An XSD schema with the special set of annotations is referred to as a mapping schema. These annotations are used within the XSD schema to specify XML data to relational store mapping. This includes mapping between elements and attributes in the XSD schema to tables (views) and columns in the databases. If you do not specify the annotations, default mapping takes place. By default, an XSD element with complex type maps to a table (view) name in the specified database and an element or attribute with a simple type maps to the column with the same name as the element/attribute. These annotations can also be used to specify the hierarchical relationships in XML (thus, representing the relationships in the database because XSD schemas are simply an XML view of relational data). A file containg a mapping schema may be loaded by calling the xml_load_mapping_schema_decl function. A name (without extension .xsd) of the file containg a mapping schema is considered to be the name of the xml view, defined by a given mapping schema. Fri, 27 Dec 2019 14:12:54 GMT Using sql:relation and sql:field Preliminaries The sql:relation annotation maps an XML node in the XSD schema to a database table. The name of a table (view) is specified as the value of the sql:relation annotation. When sql:relation is specified on an element, the scope of this annotation applies to all attributes and subelements that are described in the complex type definition of that element, therefore, providing a shortcut in writing annotations. The sql:relation annotation also may be used if identifiers that are valid in SQL are not valid in XML. For example, 'Order Details' is a valid table name in SQL, but not in XML. In such cases, the sql:relation annotation can be used to specify the mapping, for example: <xsd:element name="OrderDetails" sql:relation="Order Details"> ... The sql:field annotation maps an XML node in the schema to a database column. It's not allowed to specify sql:field on an empty content element. Example In this example, the XSD schema consists of an 'Emp' element of complex type with 'FirstName', 'LastName' and 'title' child elements and the 'EmpID' attribute. The sql:relation annotation maps the 'Emp' element to the Demo.demo.Employees table. The sql:field annotation maps the 'title' element to the 'Title' column and the 'EmpID' attribute to the "EmployeeID" column. No annotations are specified for the 'FirstName' and 'LastName' elements. This results in a default mapping of the elements to the columns with the same names. <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:sql="urn:schemas-microsoft-com:mapping-schema"> <xsd:element name="Emp" sql:relation="Demo.demo.Employees" > <xsd:complexType> <xsd:sequence> <xsd:element name="FirstName" type="xsd:string" /> <xsd:element name="LastName" type="xsd:string" /> <xsd:element name="title" sql:field="Title" type="xsd:string" /> </xsd:sequence> <xsd:attribute name="EmpID" sql:field="EmployeeID" type="xsd:integer" /> </xsd:complexType> </xsd:element> </xsd:schema> Let the schema is written to the file 'EmpSchema.xsd', then after loading this file by xml_load_mapping_schema_decl function, the first example will produce a result for the XPath query: XPATH [__view 'EmpSchema'] /* the second example will produce a result for the XQuery query: select xquery_eval('<doc>{for $r in xmlview("EmpSchema")/* return $r}</doc>', xtree_doc('<q/>')); <doc> is necessary for serialization (any name instead 'doc' is possible) Fri, 27 Dec 2019 14:12:54 GMT Using sql:relationship to Specify Relationships Preliminaries In the annotated XSD schema, the sql:relationship annotation is used to nest the schema elements hierarchically, on the basis of primary key and foreign key relationships among the underlying tables to which the elements map. In specifying the sql:relationship annotation, you must identify: The parent table (Customers) and the child table (Orders). The necessary join condition. (CustomerID in Orders is a child key that refers to the CustomerID parent key in the Customers table.) This information is used in generating the proper hierarchy. (For each parent element, the related child elements appear as subelements.) To provide the table names and the necessary join information, the following attributes are specified on the sql:relationship annotation: 'name' specifies the unique name of the relationship; 'parent' specifies the parent relation (table). This is an optional attribute; if the attribute is not specified, the parent table name is obtained from information in the child hierarchy in the document. If the schema specifies two parent-child hierarchies that use the same <sql:relationship> but different parent elements, you do not specify the parent attribute in <sql:relationship>. This information is obtained from the hierarchy in the schema. 'parent-key' specifies the parent key of the parent. If the parent key is composed of multiple columns, values are specified with a space between them. There is a positional mapping between the values that are specified for the multicolumn key and for the corresponding child key. 'child' specifies the child relation (table). 'child-key' specifies the child key in the child referring to parent-key in parent. If the child key is composed of multiple attributes (columns), the child-key values are specified with a space between them. There is a positional mapping between the values that are specified for the multicolumn key and for the corresponding parent key. These attributes are valid only with the <sql:relationship> element. Example. Specifying the sql:relationship annotation on an element. The following annotated XSD schema includes 'Customer' and 'Order' elements. The 'Order' element is a subelement of the 'Customer' element. In the schema, the sql:relationship annotation is specified on the 'Order' subelement. The relationship itself is defined in the 'appinfo' element. The 'relationship' element identifies CustomerID in the Orders table as a foreign key that refers to the CustomerID primary key in the Customers table. Therefore, orders that belong to a customer appear as a subelement of that 'Customer' element. <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:sql="urn:schemas-microsoft-com:mapping-schema"> <xsd:annotation> <xsd:appinfo> <sql:relationship name="CustOrders" parent="Demo.demo.Customers" parent-key="CustomerID" child="Demo.demo.Orders" child-key="CustomerID" /> </xsd:appinfo> </xsd:annotation> <xsd:element name="Customer" sql:relation="Demo.demo.Customers" type="CustomerType" /> <xsd:complexType name="CustomerType" > <xsd:sequence> <xsd:element name="Order" sql:relation="Demo.demo.Orders" sql:relationship="CustOrders" > <xsd:complexType> <xsd:attribute name="OrderID" type="xsd:integer" /> <xsd:attribute name="CustomerID" type="xsd:string" /> </xsd:complexType> </xsd:element> </xsd:sequence> <xsd:attribute name="CustomerID" type="xsd:string" /> <xsd:attribute name="ContactName" type="xsd:string" /> </xsd:complexType> </xsd:schema> Let the schema is written to the file 'CustOr_constant.xsd', then after loading this file by xml_load_mapping_schema_decl function, the first example will produce a result for the XPath query: XPATH [__view 'Customer_Order'] /Customer[@CustomerID="QUEEN"]; the second example will produce a result for the XQuery query: select xquery_eval('<doc>{for $r in xmlview("Customer_Order")/*[@CustomerID="QUEEN"] return $r}</doc>', xtree_doc('<q/>')) Fri, 27 Dec 2019 14:12:54 GMT Using sql:relationship to Specify Relationship on an attribute Example. The schema in this example includes a 'Customer' element with 'CustomerID' and 'ContactName' child elements and an OrderIDList attribute of IDREFS type. The 'Customer' element maps to the Customers table. By default, the scope of this mapping applies to all the child elements or attributes unless sql:relation is specified on the child element or attribute, in which case, the appropriate primary-key/foreign-key relationship must be defined using the 'relationship' element. And the child element or attribute, which specifies the different table using the relation annotation, must also specify the relationship annotation. <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:sql="urn:schemas-microsoft-com:mapping-schema"> <xsd:annotation> <xsd:appinfo> <sql:relationship name="CustOrders" parent="Demo.demo.Customers" parent-key="CustomerID" child="Demo.demo.Orders" child-key="CustomerID" /> </xsd:appinfo> </xsd:annotation> <xsd:element name="Customer" sql:relation="Demo.demo.Customers" type="CustomerType" /> <xsd:complexType name="CustomerType" > <xsd:sequence> <xsd:element name="ContactName" type="xsd:string" /> <xsd:element name="CompanyName" type="xsd:string" /> <xsd:element name="City" type="xsd:string" /> </xsd:sequence> <xsd:attribute name="OrderIDList" type="xsd:IDREFS" sql:relation="Demo.demo.Orders" sql:field="OrderID" sql:relationship="CustOrders" > </xsd:attribute> <xsd:attribute name="CustomerID" type="xsd:string" /> </xsd:complexType> </xsd:schema> Let the schema is written to the file 'Cust_Order_attr.xsd', then after loading this file by xml_load_mapping_schema_decl function, the first example will produce a result for the XPath query: XPATH [__view 'Cust_Order_attr'] /Customer[@CustomerID="QUEEN"] the second example will produce a result for the XQuery query: select xquery_eval('<doc>{for $r in xmlview("Cust_Order_attr")/*[@CustomerID="QUEEN"] return $r}</doc>', xtree_doc('<q/>')); Fri, 27 Dec 2019 14:12:54 GMT Using sql:relationship to Specify Relationship on multiple elements. Example. Specifying sql:relationship on multiple elements. In this example, the annotated XSD schema contains the 'Customer', 'Order', and 'OD' elements. The 'Order' element is a subelement of the 'Customer' element. <sql:relationship> is specified on the 'Order' subelement; therefore, orders that belong to a customer appear as subelements of 'Customer'. The 'Order' element includes the 'OD' subelement. 'sql:relationship' is specified on 'OD' subelement, so the order details that pertain to an order appear as subelements of that 'Order' element. <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:sql="urn:schemas-microsoft-com:mapping-schema"> <xsd:annotation> <xsd:appinfo> <sql:relationship name="CustOrders" parent="Demo.demo.Customers" parent-key="CustomerID" child="Demo.demo.Orders" child-key="CustomerID" /> <sql:relationship name="OrderOrderDetail" parent="Demo.demo.Orders" parent-key="OrderID" child="Demo.demo.Order_Details" child-key="OrderID" /> </xsd:appinfo> </xsd:annotation> <xsd:element name="Customer" sql:relation="Demo.demo.Customers" > <xsd:complexType> <xsd:sequence> <xsd:element name="Order" sql:relation="Demo.demo.Orders" sql:relationship="CustOrders" maxOccurs="unbounded" > <xsd:complexType> <xsd:sequence> <xsd:element name="OrderDetail" sql:relation="Demo.demo.Order_Details" sql:relationship="OrderOrderDetail" maxOccurs="unbounded" > <xsd:complexType> <xsd:attribute name="OrderID" type="xsd:integer" /> <xsd:attribute name="ProductID" type="xsd:string" /> <xsd:attribute name="Quantity" type="xsd:integer" /> </xsd:complexType> </xsd:element> </xsd:sequence> <xsd:attribute name="OrderID" type="xsd:integer" /> <xsd:attribute name="CustomerID" type="xsd:string" /> </xsd:complexType> </xsd:element> </xsd:sequence> <xsd:attribute name="CustomerID" type="xsd:string" /> </xsd:complexType> </xsd:element> </xsd:schema> Let the schema is written to the file 'Cust_Order_OD.xsd', then after loading this file by xml_load_mapping_schema_decl function, the first example will produce a result for the XPath query: XPATH [__view 'Cust_Order_OD'] /Customer[@CustomerID="QUEEN"]; the second example will produce a result for the XQuery query: select xquery_eval('<doc>{for $r in xmlview("Cust_Order_OD")/*[@CustomerID="QUEEN"] return $r}</doc>', xtree_doc('<q/>')) Fri, 27 Dec 2019 14:12:54 GMT Using sql:is-constant for creating constant elements Preliminaries The sql:is-constant annotation can be used to specify a constant element, an element in the XSD schema that does not map to any database table or column. sql:is-constant takes a Boolean value (false, true), 0 and 1 (0 = false, 1 = true). The is-constant annotation can be specified on an element that does not have any attributes. If this annotation is specified on an element with the value true (or 1), that element is not mapped to the database but still appears in the XML document. The sql:is-constant annotation can be added to a <complexType> element. Example. Specifying sql:is-constant to add a container element In this annotated XSD schema, 'CustomerOrders' is defined as a constant element by specifying the sql:is-constant attribute with the value of 1. Therefore, 'CustomerOrders' element is not mapped to any database table or column. This constant element consists of the 'Order' subelements. Although 'CustomerOrders' element does not map to any database table or column, it still appears in the resulting XML as a container element containing the 'Order' subelements. <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:sql="urn:schemas-microsoft-com:mapping-schema"> <xsd:annotation> <xsd:appinfo> <sql:relationship name="CustOrders" parent="Demo.demo.Customers" parent-key="CustomerID" child="Demo.demo.Orders" child-key="CustomerID" /> </xsd:appinfo> </xsd:annotation> <xsd:element name="Customer" sql:relation="Demo.demo.Customers" > <xsd:complexType> <xsd:sequence> <xsd:element name="CustomerOrders" sql:is-constant="1" > <xsd:complexType> <xsd:sequence> <xsd:element name="Order" sql:relation="Demo.demo.Orders" sql:relationship="CustOrders" maxOccurs="unbounded" > <xsd:complexType> <xsd:attribute name="OrderID" type="xsd:integer" /> <xsd:attribute name="CustomerID" type="xsd:string" /> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:sequence> <xsd:attribute name="CustomerID" type="xsd:string" /> </xsd:complexType> </xsd:element> </xsd:schema> Let the schema is written to the file 'CustOr_constant.xsd', then after loading this file by xml_load_mapping_schema_decl function, the first example will produce a result for the XPath query: XPATH [__view 'CustOr_constant'] /*[@CustomerID="QUEEN"] the second example will produce a result for the XQuery query: select xquery_eval('<doc>{for $r in xmlview("CustOr_constant")/*[@CustomerID="QUEEN"] return $r}</doc>', xtree_doc('<q/>')) Fri, 27 Dec 2019 14:12:54 GMT Filtering Values by Using sql:limit-field and sql:limit-value Preliminaries Rows returned from a database query can be limited on the basis of some limiting value. The sql:limit-field is used to identify the database column that contains limiting values and sql:limit-value annotations is used to specify a specific limiting value to be used to filter the data returned. The sql:limit-value annotation is optional. If sql:limit-value is not specified, a NULL value is assumed. Example. This is the mapping schema in which the 'product_Chai' schema attribute maps to the 'ProductID' column in the 'Demo.demo.Products' relation. The values that are returned for this attribute are limited to only 'ProductName' having the 'Chai' value by specifying the sql:limit-field and sql:limit-value annotations. Similarly, the 'product_Chang' schema attribute returns only the 'ProductID' limited to 'ProductName' having the 'Chang' value. <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:sql="urn:schemas-microsoft-com:mapping-schema"> <xsd:annotation> <xsd:appinfo> <sql:relationship name="CategoryProduct" parent="Demo.demo.Categories" parent-key="CategoryID" child="Demo.demo.Products" child-key="CategoryID" /> </xsd:appinfo> </xsd:annotation> <xsd:element name="category" sql:relation="Demo.demo.Categories" type="CategoryType" /> <xsd:complexType name="CategoryType" > <xsd:sequence> <xsd:element name="product_Chai" type="xsd:string" sql:relation="Demo.demo.Products" sql:field="ProductID" sql:limit-field="ProductName" sql:limit-value="Chai" sql:relationship="CategoryProduct" > </xsd:element> <xsd:element name="product_Chang" type="xsd:string" sql:relation="Demo.demo.Products" sql:field="ProductID" sql:limit-field="ProductName" sql:limit-value="Chang" sql:relationship="CategoryProduct" > </xsd:element> </xsd:sequence> <xsd:attribute name="CategoryID" type="xsd:integer" /> <xsd:attribute name="description" sql:field="Description" type="xsd:string" /> </xsd:complexType> </xsd:schema> Let the schema is written to the file 'Cat_Product.xsd', then after loading this file by xml_load_mapping_schema_decl function, the first example will produce a result for the XPath query: XPATH [__view 'Cat_Product'] /*[@CategoryID=1] the second example will produce a result for the XQuery query: select xquery_eval('<doc>{for $r in xmlview("Cat_Product")/*[@CategoryID=1] return $r}</doc>', xtree_doc('<q/>')) Genaral Fri, 27 Dec 2019 14:12:54 GMT Using XPath queries to XML views. Overview. XPATH Implementation and SQL Virtuoso offers XPATH as a query language for XML views. The statement is there converted into SQL in the context of the mapping defined by the __view XPATH option, which is mandatory. An XPATH query string is a valid top level SQL statement. This is interpreted as a single select or union of selects with the result columns being specified by various XPATH options. The basic query string XPATH [__view "xmlview_name"] /xpath_query The same functionality can be got by the following query: select * from (XPATH '[__view "xmlview_name"]/xpath_query')n Xml view can be created by two methods: using CREATE XML VIEW statement using Annotated XSD Schemas The second method is described in 'Using Annotated XSD Schemas for Creating XML View' chapter of this tutorial. CREATE XML VIEW statement The XML view declaration establishes a 'virtual document' a context within which XML hierarchy relationships can be translated into arbitrary joins. The virtual document can be then materialized into an actual set of persistent XML elements or used to generate SQL from XPATH. The XML view declaration corresponds to the grammar rules described in XML Support chapter, Virtuoso XML Services section. Each table in the declaration generates an element into the result document. SQL views can be used as tables to accommodate for hidden joins, sub-queries, ordering and aggregates. If a view is used, which by nature has no primary key, the primary key clause should be used to define a uniquely identifying set of view columns. Each level of the hierarchy is declared as a list of child elements. Each such element maps one table or view into an entity according to a join condition. The join conditions can reference columns from the associated table and columns from tables in parent elements. The join condition can also have scalar filtering conditions. A top element's join condition may only specify scalar conditions. Each set of sibling child nodes is delimited by braces {}. The top level of the view typically consists of one element in the outermost braces. This element has itself a child list delimited by braces. Each such list can have more than one different element. Each element specifies: SQL table Correlation name for use in subsequent joins for this table XML element name to use for delimiting a row of this table List of columns, with optional XML element or attribute names join condition - will relate rows of this table to rows of the table in the enclosing element. If this element is at the top level, this can only consist of scalar conditions Optional PRIMARY KEY clause, needed if the table in this element is a view, does not have a primary key or if a non-primary key unique identity is desired Optional ELEMENT flag Optional list of child elements, delimited by braces The column list can mention a single column or a single column renamed into an XML attribute of a different name. If a column of a table is referenced in a subsequent join condition it must appear in the output columns list. Expressions are not directly allowed but a view with expression columns can be used. The opt_public clause, when present, offers a shorthand for calling xml_view_publish at the same time as making the definition. This makes a DAV resource reflecting the contents of the view. The contents may either be generated on demand or persisted as a DAV accessible XML document. In the latter case the document may be regenerated at a fixed interval. The interval is expressed in minutes. The path is expressed as an absolute path from the root collection of the DAV server. Examples create xml view "cat" as { "Demo"."demo"."Categories" "C" as "category" ("CategoryID", "Description" as "description") { "Demo"."demo"."Products" "P" as "product" ("ProductName") on ("P"."CategoryID" = "C"."CategoryID") } } This declares a two level hierarchy with a category node for each category and a product child node for each product in the category. create xml view "cats_e" as select "category"."CategoryID", "CategoryName", "ProductName", "ProductID" from "Demo".."Categories" "category", "Demo".."Products" as "product" where "product"."CategoryID" = "category"."CategoryID" element; Here is a similar example, this time using the element option. create xml view "product" as { "Demo"."demo"."Products" p as "product" ("ProductID", "ProductName" as "product_name","UnitPrice" as "price", "SupplierID","CategoryID") { "Demo"."demo"."Suppliers" s as "supplier" ("CompanyName") on (s."SupplierID" = p."SupplierID") , "Demo"."demo"."Categories_aux" c as "category" ("Description") on (c."CategoryID" = p."CategoryID") } } This declares a two level hierarchy with a product node for each product and a supplier and category children node for each supplier and category in the product. Examples Fri, 27 Dec 2019 14:12:54 GMT Using XPath queries with options. XML serialization text You can get xml serialization text of the selected entity by the query XPATH [__view "xmlview_name"] /xpath_query e.g. for given 'cat' xml view the full serialization text can be received by the query XPATH [__view "cat"] /* or XPATH [__view "cat"] /category see xp_v_2_sample Select all columns instead of a serialization text You can select all columns of the selected entity instead of its serialization text by using __* option: XPATH [__* __view "cat"] //product ProductID ProductName SupplierID CategoryID QuantityPerUnit UnitPrice UnitsInStock UnitsOnOrder ReorderLevel Discontinued INTEGER VARCHAR INTEGER INTEGER VARCHAR DOUBLE PRECISION SMALLINT SMALLINT SMALLINT SMALLINT ______________________________________________________________________________________________________________________ 1 Chai 1 1 10 boxes x 20bags 8 39 0 10 0 2 Chang 1 1 24 - 12 oz bottles 19 17 40 25 0 3 Aniseed Syrup 1 2 12 - 550 ml bottles 10 13 70 25 0 . . . . . . This is only valid when __view is specified and the result set is homogeneous. Select the key instead of the serialization text You can select the key of the selected entities instead of the serialization text by using __key option: XPATH [__key __view "cat"] /*; CategoryID INTEGER NOT NULL _______________________________________________________________________________ 1 2 3 4 5 6 7 8 Examples Fri, 27 Dec 2019 14:12:54 GMT Using XPATH in SQL Queries and Procedures. Example An XPATH expression can appear as a SQL query expression, that is, as a derived table or subquery predicate or scalar subquery. This means that the XPATH expression is expanded compile time to the corresponding SQL. The query select * from (XPATH '[__* __view "DB"."DBA"."cat"]//product/@ProductName') P order by P."ProductName" will evaluate the //product query in the context of the 'cat' XML view and produce a result set consisting of the ordered 'ProductName' attributes of the product entity as defined in the view: ProductName VARCHAR _______________________________________________________________________________ Alice Mutton Aniseed Syrup Boston Crab Meat Camembert Pierrot Carnarvon Tigers Chai Chang Chartreuse verte . . . . . . Zaanse koeken General Fri, 27 Dec 2019 14:12:55 GMT Updategrams Updategram Overview Updategrams allow database updates to be defined as XML. This is ultimately achieved by mapping the XML nodes against corresponding database columns. Updategrams can be used to replace existing data access components in a middle tier. A typical application will include a middle tier consisting of Business Logic and Data Access code. The Data Access code will interface with the database using disconnected Recordsets and Command objects calling stored procedures etc. Most of the Data Access section of the middle tier can be replaced with Updategrams. Most Data Access tiers (both middle tier code and stored procedures) will individually deal with specific database tables or groups of related tables. This can inhibit performance and quite often several round trips to the database are required to complete a transaction. Updategrams can solve this problem by including all of the data in an XML document, which is then mapped to database tables and columns. The entire database update can then be accomplished in one fell swoop. This update can include inserting, updating and deleting data. The 'xmlsql_update' function supports XML-based insert, update, and delete operations performed on an existing table in database. Updategram Basics The general format of an updategram is: <sql:sync xmlns:sql="xml-sql"> <sql:before> <TABLENAME [sql:id="value"] col="value" col="value"?../> </sql:before> <sql:after> <TABLENAME [sql:id="value"] [sql:at-identity="value"] col="value" col="value"?../> </sql:after> </sql:sync> or <sql:sync xmlns:sql="xml-sql"> <sql:before> <TABLENAME [sql:id="value"]> <col>"value"</col> <col>"value"</col> ... </TABLENAME> ... </sql:before> <sql:after> <TABLENAME [sql:id="value"] [sql:at-identity="value"]> <col>"value"</col> <col>"value"</col> ... </TABLENAME> ... </sql:after> </sql:sync> Elements Description The <sync> tag of the updategram signifies the beginning of an operation(s). The rows specified in the <before> refer to existing records in the database. The rows specified in the <after> block refer to what the user wants in the database. TABLENAME identifies target table. The sql:at-identity attribute stores the last identity value added by the system (if possible). The captured identity value can then be used in subsequent operations. The sql:id attribute is used to mark rows. This forces an association between the record specified in the <before> and <after> block in the updategram. When there are multiple instances specified, it is recommended that sql:id attribute be used for all of the instances. Each TABLENAME refers to a single table. Multiple <TABLENAME..../> entries are allowed in the same <before> , or <after> tags, or in both <before> and <after> tags; however, nesting is not allowed. The <before> and <after> tags are optional. A missing tag is the same as having a tag with no content. Determining Actions In an updategram if only the <after> block is specified, the rows specified in the <after> block are inserted in the table(s). If both the <before> and <after> blocks are specified, then the rows specified in the <after> block for which there is no corresponding rows in the <before> block are inserted in the table(s). In an update operation, the instances (rows) specified in the <before> block refer to the existing rows in the database. The corresponding instances (rows) in the <after> block reflect what the user wants in the database. A row update operation is performed if there is an instance (row) in both <before> and <after> sections with the same set of values for the attributes that uniquely identify a row in a table. The set of rows specified in the <before> block must be valid in the database for the updategram to successfully update the rows. In a delete operation, if only the <before> block is specified in the updategram, the instances (rows) specified in the <before> block are deleted from the table(s). If both the <before> and <after> blocks are specified, the instances (rows) for which there is no corresponding instances (rows) in the <after> block are deleted from the table(s). Example This example creates a SQL function that takes the orders and order lines from the demo database and applies a stylesheet to the FOR XML rendition of these to make updategrams. Use the updategrams to fill out a similar table structure containing order summary with only fulfilled orders included. The interface will show the sources of the report and the transformed report which is the updategram. Exercises Fri, 27 Dec 2019 14:12:55 GMT Parameter usage in updategrams Preliminaries This sample program demonstrates the use of parameters in an updategram: Create a form that allows new records to be inserted into a table. Use the form text fields as input parameters for the updategram. After insert display a list of records to show that new record has been inserted into the table. Using a XML temapltes Fri, 27 Dec 2019 14:12:55 GMT Row Insertion and Report Generation using XML Templates Preliminaries This sample program demonstrates the use of XML templates: Use the XS_U_3 SQL script to create a Web virtual directory that allows execution of the XML template. Create a form that allows new records to be inserted into a table. Use the form text fields as input parameters for the XML template. The XML template (shippers.xml) will insert a new record using the form parameters. It makes an XML document using SQL/XML query, and renders it with an XML-T style sheet. General Fri, 27 Dec 2019 14:12:55 GMT FOR XML SQL Clause For XML SQL Clause Overview This feature enables the execution SQL queries against the Virtuoso Server to return results as XML documents rather than as standard rowsets. To retrieve results directly, use the FOR XML clause of the SELECT statement and in the FOR XML clause, specify one of these XML modes: RAW - transforms each row in the query result set into an XML element with the generic identifier row. AUTO - returns query results as nested XML elements. EXPLICIT - authors of query can control the structure of the XML document returned by the query. Examples This example shows a simple use of the For XML SQL 'Auto' statement for executing a query and returning the results in XML format. General Fri, 27 Dec 2019 14:12:55 GMT FOR XML EXPLICIT SQL statements Example This sample demonstrates the use of the FOR XML EXPLICIT mode. Creating a publication Fri, 27 Dec 2019 14:12:53 GMT Creating a replication publication account Preliminaries Virtuoso supports bidirectional transactional replication via mechanism of updateable subscriptions. Every table has only one publisher. Subscribers can update replicated tables on their side and then submit data back to publisher. Publisher performs conflict resolution and either accepts or rejects that data. It is assumed that all the tables in publication with updateable subscriptions option have primary keys and that primary key columns are never modified. Example publication account setup Login to the Conductor UI using the dba account. Go to the "Replication" tab, then go to the "Transactional" tab and then go the "Publications" sub-tab. Press the "Create" button. Enter publication name, check the "Updateable" checkbox and press the "Create" button. Equivalent SQL commands to above Connect to the Virtuoso server via ISQL utility as DBA user. Create publication "repldemo" with log file "repldemo.log" SQL> repl_publish('repldemo', 'repldemo.log', 1); Creating a publication Fri, 27 Dec 2019 14:12:53 GMT Adding tables to publication To add a table to publication execute the following steps: Login to the Conductor UI using the dba account. Go to the "Replication" tab, then go to the "Transactional" tab and then go the "Publications" sub-tab. From the publications list select the link with the name of your publication ("repldemo"). Press the "Add Tables" button. Select a database, then a table or multiple tables (select "Demo.demo.Orders"), and then press "Add to Publication" button. Equivalent SQL commands to above Connect to the Virtuoso server via ISQL utility as DBA user. Add table "Demo.demo.Orders" to publication "repldemo" SQL> repl_pub_add('repldemo', 'Demo.demo.Orders', 2, 1, 0); Creating a publication Fri, 27 Dec 2019 14:12:53 GMT Defining conflict resolvers Preliminaries Because every table can have only one publisher, conflicts can occur only on publisher (when modifications from subscriber are applied). Every table on publisher can have a number of conflict resolvers which are used for conflict resolution. Each conflict resolver has a type ('I', 'U', or 'D') and an order. Conflict resolvers are applied in ascending order. Conflict resolver is a Virtuoso/PL procedure which receives conflicting row (row from subscriber) and some other arguments. Conflict resolver signatures are described in Virtuoso documentation. Conflict resolver can modify the row which is passed in as 'inout' arguments. Conflict resolver should return an integer value which will be used for conflict resolution. Possible return values and their meaning are described in Virtuoso documentation. Conflict resolution occurs differently for each kind of DML operation. Details can be found in Virtuoso documentation. There is a possibility to automatically generate some types of conflict resolvers. Automatically generated conflict resolver classes are: max - row with maximum value of specified column wins min - row with minumum value of specified column wins ave - new value of specified column is calculated as: current_val = (current_val + new_val) / 2 add - new value of specified column is calculated as: current_val = current_val + (new_val - old_val) pub_wins - publisher always wins sub_wins - subscriber always wins Example defining a conflict resolver Login to the Conductor UI using the dba account. Go to the "Replication" tab, then go to the "Transactional" tab and then go the "Publications" sub-tab. Select the link with the name of your publication ("repldemo"). Select the link with the name of the table ("Demo.demo.Orders"). Press the "New Resolver" button. Enter conflict resolver name suffix for example "min_OrderDate", select conflict resolver type (select "U"), select conflict resolver class (select "min"), select a column (select "OrderDate"). You can optionally specify conflict resolver order (default is 100). Press "Add" button. A conflict resolver will be added. You can view and edit conflict resolver code by selecting the link with its name from the list of conflict resolvers. Equivalent SQL commands to above Connect to the Virtuoso server via ISQL utility as DBA user. Create 'U' conflict resolver for table "Demo.demo.Orders" that will choose a row with minimal OrderDate column. SQL> repl_add_cr('Demo.demo.Orders', 'min_OrderDate', 'U', 100, 'min', 'OrderDate'); Creating a subscription Fri, 27 Dec 2019 14:12:53 GMT Creating a subscription Preliminaries In order to run this example you need two Virtuoso servers running (publisher and subscriber). In the example scripts it is assumed that the first Virtuoso server (publisher) is running at localhost:1111 and the second Virtuoso server (subscriber) is running at localhost:1112. If you are running ODBC versions of the servers there should be 2 ODBC DSN's records named "localhost:1111" and "localhost:1112". Example creating a subscription These steps should be executed on subscriber. Login to the Conductor UI using the dba account. Go to the "Replication" tab, then go to the "Transactional" tab and then go the "Subscriptions" sub-tab. Press "New Subscription" button. Select connected DSN from the list and then press "Publications list" button. If the desired DSN is not connected yet you can connect to it using "Specify new data source" dialog below. Select a publication and press "List items" button. Press "Subscribe" button. You can optionally load initial data by checking "Load data" checkbox. Equivalent SQL commands to the above Connect to the subscriber via ISQL utility as DBA user. Define a replication server "demoserver" at "localhost:1111" and subscribe to publication "repldemo" from it. SQL> repl_server('demoserver', 'localhost:1111', 'localhost:1111'); SQL> repl_subscribe('demoserver', 'repldemo', 'dba', 'dba', 'dba', 'dba'); Publishing a table Fri, 27 Dec 2019 14:12:53 GMT Publishing a table for replication Preliminaries Bidirectional snapshot replication allows you to set up snapshot replication between multiple servers where updates can be performed on all servers. Publisher-subscriber model where each table has only one publisher and when an update is performed on subscriber it goes to publisher first, and then to all other subscribers. Conflict resolution may need to take place on the publisher when data coming from a subscriber is processed. It is assumed that all published tables have primary keys and that primary key columns are never modified. Example publishing a table Login to the Conductor UI using the dba account. Go to the "Replication" tab and then go to the "Bidirectional Snapshot" tab. Press the "Add table" button. Enter table name or select the table using "Browse..." button and press "Add" button. Equivalent SQL commands to above Connect to the Virtuoso server via ISQL utility as DBA user. Publish "Demo.demo.Orders" table. SQL> repl_create_snapshot_pub ('Demo.demo.Orders', 2); Publishing a table Fri, 27 Dec 2019 14:12:53 GMT Defining conflict resolvers Preliminaries Because every table can have only one publisher conflicts can occur only on publisher (when modifications from subscriber are applied). Every table on publisher can have a number of conflict resolvers which are used for conflict resolution. Each conflict resolver has a type ('I', 'U', or 'D') and an order. Conflict resolvers are applied in ascending order. Conflict resolver is a Virtuoso/PL procedure which receives conflicting row (row from subscriber) and some other arguments. Conflict resolver signatures are described in Virtuoso documentation. Conflict resolver can modify the row which is passed in as 'inout' arguments. Conflict resolver should return an integer value which will be used for conflict resolution. Possible return values and their meaning are described in Virtuoso documentation. Conflict resolution occurs differently for each kind of DML operation. Details can be found in Virtuoso documentation. There is a possibility to automatically generate some types of conflict resolvers. Automatically generated conflict resolver classes are: max - row with maximum value of specified column wins min - row with minumum value of specified column wins ave - new value of specified column is calculated as: current_val = (current_val + new_val) / 2 pub_wins - publisher always wins sub_wins - subscriber always wins Example defining a conflict resolver Login to the Conductor UI using the dba account. Go to the "Replication" tab and then go to the "Bidirectional Snapshot" tab. Click "Conflict Resolvers" for the desired published table ("Demo.demo.Orders"). Press "New Resolver" button. Enter conflict resolver name suffix (enter "max_OrderDate"), select conflict resolver type (select "U"), select conflict resolver class (select "max"), select a column (select "OrderDate"). You can optionally specify conflict resolver order (default is 100). Press "Add" button. A conflict resolver will be added. You can view and edit conflict resolver code by selecting a link with its name from the list of conflict resolvers. Equivalent SQL commands to above Connect to the Virtuoso server via ISQL utility as DBA user. Create 'U' conflict resolver for table "Demo.demo.Orders" that will choose a row with latest OrderDate. SQL> REPL_ADD_SNAPSHOT_CR ('Demo.demo.Orders', 'max_OrderDate', 'U', 100, 'max', 'OrderDate'); Defining subscribers for published table Fri, 27 Dec 2019 14:12:53 GMT Defining subscribers Preliminaries In order to run this example you need two Virtuoso servers running (publisher and subscriber). In the example scripts it is assumed that the first Virtuoso server (publisher) is running at localhost:1111 and the second Virtuoso server (subscriber) is running at localhost:1112. If you are running ODBC versions of the servers there should be 2 ODBC DSN's records named "localhost:1111" and "localhost:1112". Subscriber should have "ServerName" configuration parameter set to "demoserver2". Example creating a subscription These steps should be executed on publisher. Login to the Conductor UI using the dba account. Go to the "Replication" tab and then go to the "Bidirectional Snapshot" tab. Click "Subscriptions" for desired published table ("Demo.demo.Orders"). Press "New Subscriber" button. Select connected DSN from the list and then press "Create Subscription" button. If the desired DSN is not connected yet you can connect to it using "Specify new data source" dialog below. Equivalent SQL commands to above Connect to the publisher via ISQL utility as DBA user. Define a replication server "demoserver2" at "localhost:1112" and subscribe it to published "Demo.demo.Orders" table. SQL> repl_snp_server('localhost:1112'); SQL> repl_create_snapshot_sub('demoserver2', 'Demo.demo.Orders', 2, 'dba', 'dba'); Bidirectional Snapshot Replication Demo Fri, 27 Dec 2019 14:12:53 GMT Bidirectional snapshot replication demo Preliminaries This tutorial demonstrates basic snapshot replication features. In order to run this tutorial execute the following steps: Setup ODBC data source named "demoserver2". Make sure that user "demo" with password "demo" can connect to data source "demoserver2". Make sure that there is no table named "Shippers" in target data source. The data source can be Virtuoso data source as well as any other data source type which is supported by Virtuoso bidirectional snapshot replication (E.g. Oracle or MS SQL data source). This tutorial will demonstrate Virtuoso heterogeneous snapshot replication capabilities. Publishing a DAV collection Fri, 27 Dec 2019 14:12:53 GMT Publishing a DAV collection for replication Preliminaries Bidirectional snapshot replication allows you to set up snapshot replication between multiple servers where updates can be performed on all servers. Publisher-subscriber model where each DAV collection has only one publisher and when an update is performed on subscriber it goes to publisher first, and then to all other subscribers. Conflict resolution may need to take place on the publisher when DAV resources coming from a subscriber are processed. Example publishing a DAV collection Login to the Conductor UI using the dba account. Go to the "Replication" tab and then go to the "Bidirectional Snapshot" tab. Press "Add DAV Collection" button. Enter DAV collection name or select DAV collection using "Browse..." button and press "Add" button. Equivalent SQL commands to above Connect to the Virtuoso server via ISQL utility as DBA user. Publish "/DAV/doc" DAV collection. SQL> repl_create_snapshot_pub ('/DAV/doc', 1); Publishing a DAV collection Fri, 27 Dec 2019 14:12:53 GMT Defining conflict resolvers Preliminaries Every DAV collection on publisher can have a number of conflict resolvers which are used for conflict resolution. Each conflict resolver has an integer number (order) associated with it. Conflict resolvers are applied in ascending order. Conflict resolver is a Virtuoso/PL procedure which receives conflicting DAV resource. DAV conflict resolver signatures are described in Virtuoso documentation. Conflict resolver can modify the resource which is passed in as 'inout' arguments. Conflict resolver should return an integer value which will be used for conflict resolution. Possible return values and their meaning are described in Virtuoso documentation. There is a possibility to automatically generate some types of conflict resolvers. Automatically generated conflict resolver classes are: max_mtime - resource with maximum modification time wins min_mtime - resource with minumum modification time wins max_ctime - resource with maximum creation time wins min_ctime - resource with minumum creation time wins backup - backup of resource that lost conflict resolution will be performed, conflict resolution will continue notify - owner of resource will be notified if his resource lost conflict resolution pub_wins - publisher always wins sub_wins - subscriber always wins Example defining a conflict resolver Login to the Conductor UI using the dba account. Go to the "Replication" tab and then go to the "Bidirectional Snapshot" tab. Click "Conflict Resolvers" for desired published DAV collection ("/DAV/doc"). Press "New Resolver" button. Enter conflict resolver name suffix (enter "max_mtime"), select conflict resolver class (select "max_mtime"). You can optionally specify conflict resolver order (default is 100). Press "Add" button. A conflict resolver will be added. You can view and edit conflict resolver code by selecting the link with its name from the list of conflict resolvers. Equivalent SQL commands to above Connect to the Virtuoso server via ISQL utility as DBA user. Create a conflict resolver for collection "/DAV/doc" that will choose a resource with maximum modification time (more recent resource). SQL> REPL_ADD_DAV_CR ('/DAV/doc', 'max_mtime', 100, 'max_mtime'); Defining subscribers for a pulished DAV collection Fri, 27 Dec 2019 14:12:53 GMT Defining subscribers Preliminaries In order to run this example you need two Virtuoso servers running (publisher and subscriber). In the example scripts it is assumed that the first Virtuoso server (publisher) is running at localhost:1111 and the second Virtuoso server (subscriber) is running at localhost:1112. If you are running ODBC versions of the servers there should be 2 ODBC DSN's records named "localhost:1111" and "localhost:1112". Subscriber should have "ServerName" configuration parameter set to "demoserver2". Example creating a subscription These steps should be executed on publisher. Login to the Conductor UI using the dba account. Go to the "Replication" tab and then go to the "Bidirectional Snapshot" tab. Click "Subscriptions" for desired published DAV collection ("/DAV/doc"). Press "New Subscriber" button. Select connected DSN from the list and then press "Create Subscription" button. If desired DSN is not connected yet you can connect to it using "Specify new data source" dialog below. Equivalent SQL commands to above Connect to the publisher via ISQL utility as DBA user. Define a replication server "demoserver2" at "localhost:1112" and subscribe it to published "/DAV/doc" DAV collection. SQL> repl_snp_server('localhost:1112'); SQL> repl_create_snapshot_sub('demoserver2', '/DAV/doc', 1, 'dba', 'dba'); SyncML Server Fri, 27 Dec 2019 14:12:53 GMT Setting up SyncML server Preliminaries SyncML is a protocol for syncronizing data between two devices called server and client. Usually as client we may consider PDA, mobile phone or a workstation that have the ability to syncoronize their contacts, calendar etc. databases using SyncML protocol. On the other hand the server have ability to recoginize such requests and to store the data into the repository. Basically this is a protocol for data replication, oriented to the portable devices. The usual message flow is: Initial request from client Server response asking for credentials, if not supplied Client sends credentials included in the request Server accepts or rejects the sync request. When request for sync is accepted, then server checks what sync to perform: slow two-way (full data) or two-way sync. Client send the items that are changed or all items depending of sync type Server sends items that are changed or all items depending of sync type requested. The Virtuoso WebDAV repository can be used to keep such data. The server will recognize SyncML request by MIME content type 'application/vnd.syncml+xml' or 'application/vnd.syncml+wbxml' upon POST request and will act then as SyncML server over HTTP. Shortly: on server side are needed: 1.WebDAV collection with permisions for given accounts 2.Virtual directory assigned to it. Optionally virtual host can be defined in order to work with clients that do not have the ability to specify URL, such clients can work only with virtual root collection. Note that WebDAV collection(s) creation is a vital step; apropriate rights MUST be set before using it with SyncML client; clients can only store items(resources), they can't make sub-folders. Instructions for setting SyncML server and client Create a new folder named '/DAV/sync/' under WebDAV root. This can be done via Conductor UI going to the "Web Application Server" tab and then going to the "Content Management" tab. Create subfolders calendar and contacts under /DAV/sync/ Create a new virtual host with virtual root assigned to /DAV/sync/ WebDAV collection. Please reffer to the documentation for more information. Nokia 92x0 Communicator In Extras menu open "Remote sync" In "Profile settings" choose "New Profile" Select apropriate internet access Enter the Virtuso HTTP server address and port values as you created them earlier. Enter username and password for account which have permissions to the '/DAV/sync/' and descendants. Select tab "Data" Choose Calendar and enter for "Remote calendar" './calendar/'. Choose Contacts and enter for "Remote contacts" './contacts/'. Close the Sync Profile menus, confirm saving Select "Sync" option. Verify that items are uploaded into WebDAV collections: /DAV/sync/calendar/ and /DAV/sync/contacts/. For this you can use Conductor's WebDAV content management UI Edit some of Contacts/Events on device and perform Sync again. Check the repository as in previous step. Note: Editing the items on the server needs knowlage of VCARD/VCALENDAR formats as they can be edited as text files. Siemens SX1 Select "menu" button Choose "Organizer" Choose "Sync" Select from menu "Options", "New sync profile" Give a meaningful name for this profile in "Sync profile name" Bearer type: Internet Access point: choose some predefined Host address: URL to the SyncML server without HTTP port number Port: SyncML HTTP port number User name: username for account which have permissions to the '/DAV/sync/' and descendants. Password: password for the account Calendar: Yes Remote calendar: ./calendar Contacts: Yes Remote contacts: ./contacts HTTP authentication: No HTTP user name: blank HTTP password: blank Select "Back" from menu New profile should exists. Click on it to perform syncronization. Sony Ericsson P900 From main menu choose "Remote Sync" Via menu "Edit" - "Preferences" Server address: [type URL to the SyncML server] User Name: Password: Press button "Done" Click on "Contacts" Enable task: on Server database: ./contacts Press button "Done" To perform Sync on defined items, press button "Sync" Important: Internet connection must be alredy defined and must work with device's browser. Replication Demo between two Datsources (DSNs) Fri, 27 Dec 2019 14:12:53 GMT Replication Demo between two Datsources (DSNs) Preliminaries This sample shows how to replicate two heterogeneous DSNs (MySQL DSN and Microsoft SQL Server DSN for example) with all logic in Virtuoso. The replicated table has two columns. First is varchar Primary key, second integer representing user data. Sample includes: Select DSN for demo. There must be two connected DSNs to start the sample. Create tables on the two DSNs. Attach tables from these DSNs. Show simple page with table content. How it works: The Primary key plus timestamp column from source is replicated locally. On initial state all date from the first DSN s copyed to the Second. The user table on the first DSN has one timestamp column more that the table on the second. This column is used to get new / changed rows on replication state. Instructions for setting: Click on the "Set Initial State" to create virtuoso table. Click on the "Run" links to actually experience the demo. Important: This sample is not thread save. RDF Views Fri, 27 Dec 2019 14:12:53 GMT Develop custom RDF views for NorthWind database. Concept RDF Views map relational data into RDF and allow customizing RDF representation of locally stored RDF data. To let SPARQL clients access relational data as well as physical RDF graphs in a single query, we introduce a declarative Meta Schema Language for mapping SQL Data to RDF Ontologies. As a result, all types of clients can efficiently access all data stored on the server. The mapping functionality dynamically generates RDF Data Sets for popular ontologies such as SIOC, SKOS, FOAF, and ATOM/OWL without disruption to the existing database infrastructure of Web 1.0 or Web 2.0 solutions. RDF views are also suitable for declaring custom representation for RDF triples, e.g. property tables, where one row holds many single-valued properties. The Virtuoso RDF Views meta schema is a built-in feature of Virtuoso's SPARQL to SQL translator. It recognizes triple patterns that refer to graphs for which an alternate representation is declared and translates these into SQL accordingly. The main purpose of this is evaluating SPARQL queries against existing relational databases. There exists previous work from many parties for rendering relational data as RDF and opening it to SPARQL access. We can mention D2RQ, SPASQL, Squirrel RDF, DBLP and others. The Virtuoso effort differs from these mainly in the following: Integration with a triple store. Virtuoso can process a query for which some triple patterns will go to local or remote relational data and some to local physical RDF triples. SPARQL query can be used in any place where SQL can. Database connectivity protocols are neutral to the syntax of queries they transmit, thus any SQL client, e.g. JDBC, ODBC or XMLA application, can send SPARQL queries and fetch result sets. Moreover, a SQL query may contain SPARQL subqueries and SPARQL expressions may use SQL built-in functions and stored procedures. Integration with SQL. Since SPARQL and SQL share the same run time and query optimizer, the query compilation decisions are always made with the best knowledge of the data and its location. This is especially important when mixing triples and relational data or when dealing with relational data distributed across many outside databases. No limits on SPARQL. It remains possible to make queries with unspecified graph or predicate against mapped relational data, even though these may sometimes be inefficient. Coverage of the whole relational model. Multi-part keys etc. are supported in all places. Quad Map Patterns, Value and IRI Classes In the simplest sense, any relational schema can be rendered into RDF by converting all primary keys and foreign keys into IRI's, assigning a predicate IRI to each column, and an rdf:type predicate for each row linking it to a RDF class IRI corresponding to the table. Then a triple with the primary key IRI as subject, the column IRI as predicate and the column's value as object is considered to exist for each column that is neither part of a primary or foreign key. Strictly equating a subject value to a row and each column to a predicate is often good but is too restrictive for the general case. Multiple triples with the same subject and predicate can exist. A single subject can get single-valued properties from multiple tables or in some cases stored procedures. An IRI value of a subject or other field of a triple can be composed from more than one SQL value, these values may reside in different columns, maybe in different joined tables. Some table rows should be excluded from mapping. Thus in the most common case the RDF meta schema should consist of independent transformations; the domain of each transformation is a result-set of some SQL SELECT statement and range is a set of triples. The SELECT that produce the domain is quite simple: it does not use aggregate functions, joins and sorting, only inner joins and WHERE conditions. There is no need to support outer joins in the RDF meta schema because NULLs are usually bad inputs for functions that produce IRIs. In the rare cases when NULLs are OK for functions, outer joins can be encapsulated in SQL views. The range of mapping can be described by a SPARQL triple pattern: a pattern field is a variable if it depends on table columns, otherwise it is a constant. Values of variables in the pattern may have additional restrictions on datatypes, when datatypes of columns are known. This common case of an RDF meta schema is implemented in Virtuoso, with one adjustment. Virtuoso stores quads, not triples, using the graph field (G) to indicate that a triple belongs to some particular application or resource. A SPARQL query may use quads from different graphs without large difference between G and the other three fields of a quad. E.g., variable ?g in expression GRAPH ?g {...} can be unbound. SPARQL has special syntax for "graph group patterns" that is convenient for sets of triple patterns with a common graph, but it also has shorthands for common subject and predicate, so the difference is no more than in syntax. There is only one feature that is specific for graphs but not for other fields: the SPARQL compiler can create restrictions on graphs according to FROM and FROM NAMED clauses. Virtuoso RDF Views should offer the same flexibility with the graphs as SPARQL addressing physical triples. A transformation cannot always be identified by the graph used for ranges because graph may be composed from SQL data. The key element of the meta schema is a "quad map pattern". A simple quad map pattern fully defines one particular transformation from one set of relational columns into triples that match one SPARQL graph pattern. The main part of quad map pattern is four declarations of "quad map values", each declaration specifies how to calculate the value of the corresponding triple field from the SQL data. The pattern also lists boolean SQL expressions that should be used to filter out unwanted rows of source data (and to join multiple tables if source columns belong to different tables). There are also quad map patterns that group together similar quad patterns but do not specify any real transformation or even prevent unwanted transformations from being used, they are described in "Grouping Map Patterns" below. Quad map values refer to schema elements of two further types: "IRI classes" and "literal classes". Implementation In the example script we implement RDF Views for Northwind tables (Customers, Orders, Order Details, Products, Product Categories, Employee, Region, Country, Province). To test the mapper we just use /sparql to execute: sparql select ?o where { graph ?g {?s ?p ?o . filter(?p like '%Country%') }} limit 10; Or use iSparql application. Making an Executable SOAP Directory Fri, 27 Dec 2019 14:12:53 GMT Exposing SOAP Endpoints Example The SQL script makes a directory in the web server space SOAP capable. The interface page has a test button which sends a SOAP request to the server. The Service for testing will just return its own argument. At least 2 web threads are needed, so this should be noted before starting. An Error message is shown if only one is available. The page shows the command and explains the manual operation for doing this from the admin interface. Simple usage of the SOAP service Fri, 27 Dec 2019 14:12:53 GMT Order Entry Service Example The service function accepts data for entering an order into the demo database. The arguments contain the customer id, item to order and quantity. The response is an element with price and expected delivery date, 10 days forward. The function creates a SOAP exception if the customer is not found in the database. The web page will take the data and call the service on the local server. It will display the in and out going messages, including envelopes. WSDL description Fri, 27 Dec 2019 14:12:53 GMT Generating WSDL descriptions for SOAP Services Example The page shows the automaticaly generated WSDL description of the resources granted to SOAPDEMO user. These descriptions are shown as source, and and also rendered by xslt. The original content of WSDL description can be seen at http://[host:port]/services/services.wsdl Data types and SOAP Fri, 27 Dec 2019 14:12:53 GMT Using SQL Data Types in SOAP Services Example Example has a sample call which passes all supported data types. Composite types e.g. arrays are just repeats of a constant element. The page shows the data going in and out. SOAP & remote data sources Fri, 27 Dec 2019 14:12:53 GMT Exposing Third-Party SQL Stored Procedures as SOAP Services Preliminaries This example demonstrates the processing of a result set obtained from a PL procedure defined on a remote database. The example shows a remote execution of a PL procedure against Microsoft SqlServer and Oracle DBMS. The remote procedure is called via rexecute(). The result set is converted to an XML document by a local PL procedure that can then be called via SOAP. The demo VSP pages offers a form to accept DSN, login info and a search string. A soap_call() is executed with these parameters, and the result is parsed with an XSL-T engine for HTML output. SQLServer Preparation Configure this example for SQLServer by loading the ms.sql script using the ISQL tool on behalf of the demo user. Make sure the demo Northwind DB is installed. Create a DSN to the SQLServer DB. Grant rexecute on DSN to the SOAP_SO_S_14 user: GRANT REXECUTE on [SQLServer DSN] to SOAP_SO_S_14; Oracle Preparation Configure this example for Oracle by loading the ora.sql script using the SQLPLUS tool on behalf of the demo user. Make sure the Oracle demo DB is installed. Create a DSN to the Oracle DB. The driver must be 'Microsoft ODBC Driver for Oracle'. Grant rexecute on DSN to the SOAP_SO_S_14 user: GRANT REXECUTE on [Oracle DSN] to SOAP_SO_S_14; SOAP & WSDL service Fri, 27 Dec 2019 14:12:53 GMT Email Address Validation Service Example overview This example demonstrates: The use of raw TCP session operations: ses_connect(), ses_disconnect(), ses_read_line(), ses_write(). A SOAP call. Using the SMTP protocol for email verification. Processing the results with an XSL-T engine. Example Setup The service is prepared by loading the SQL file. This performs the following: Define a stored procedure for the SOAP service that opens a TCP session, and makes a SMTP exchange without sending a mail body to the server. Read responses from the server and makes an XML document. The SOAP service is achieved by defining the /email_service URL to have same functionality as using soap_server() function call. SOAP Interoperability Test Round III Fri, 27 Dec 2019 14:12:53 GMT SOAP Interoperability Test Page Example This example uses the Virtuoso SOAP client for testing a SOAP interop III endpoints. At least 2 web threads are needed, so this should be noted before starting. An Error message is shown if only one is available. The index page shows operations defined for SOAP Interop Round III tests. The second level pages are SOAP clients defined to perform apropriate SOAP call. The VSP based clients make a specific form for entering the input data and selecting a endpoint to test. Once call is made (invoked with Call button), the results will be extracted from SOAP response and will be shown. Also the request and response wire dumps will be shown for debugging purposes. SOAP services Fri, 27 Dec 2019 14:12:53 GMT Google API demo Preliminaries This example demonstrates the ability to access the SOAP API provided by Google. The Google API has three services: Search for text on the web. Check details of a page cached by Google. Find correct spelling for a partial word. The service requests may be configured in various ways by the parameters supplied to the API. Google Registration Google API home page http://www.google.com/apis/ has details about the services offered by Google. You must register with Google to be authorized to use the API. You can sign up for a new account from the Google API home page. Verify your email address by accessing a page, as indicated in the email sent by Google. Collect the license key in a subsequent email from Google. Search Demo Enter the registration key for your personal Google account. The key is stored in a browser cookie, and is loaded when the tutorial is run again. Check the box if you wish to view the result as raw XML format. Enter some text to be searched, and press the search button. The raw XML result shows the overview of the search results. If XML view is not checked, then only the number of pages found is shown. Enter a url of a page that is likely to be cached by Google. Then press the button to get the details of this page. The raw XML result will contain the page typically encoded in Base64. If XML view is not checked, then only the size of the page is shown. Enter one or more words to have the spelling verified. A partial word is possible. Then press the button to verify the spelling. The raw XML result shows the suggested spelling. If XML view is not checked, then only the suggested spelling is shown. Publishing C function as SOAP service Fri, 27 Dec 2019 14:12:53 GMT Publishing C/C++ functions as Web Services Example The Virtuoso distribution includes the sample bif, bif_sample.c. It is thus possible to create following function and make server including it. The next step is creating a stored procedure that calls this function and you are back to publishing a Virtuoso stored procedure. The Service for testing will just return string "Hello world". At least 2 web threads are needed, so this should be noted before starting. An Error message is shown if only one is available. static caddr_t bif_hello_world (caddr_t * qst, caddr_t * err_ret, state_slot_t ** args) { return box_dv_short_string ("Hello world."); } IMPORTANT: You need to start the sample server containing bif_hello_world , in order run this example. Publishing Java class as SOAP service Fri, 27 Dec 2019 14:12:53 GMT Publishing Java classes as Web Services Example This example demonstrates how to call Java VM methods from Virtuoso/PL and expose them as SOAP services. It's based on the java class demo_server.java. Also provided is a demonstration of how the JAVA Reflect API can be used to automatically generate PL wrappers. Click on the Run link or point your browser to: http://[host]:[port]/services/services.vsmx Source code detail javavm_xml.pl - This file contains a Virtuoso/PL procedure which produces a XML description of the java classes. jvm_ref_describe_class (in class_name varchar, in inherited integer := 0) First argument is the absolute JAVA class name (example: java_server or java.util.Calendar). Second argument controls whether to create entries for the inherited constructors/ methods/ attributes of the class, or only for the ones defined in it (java.lang.Class.getDeclaredMethods() vs. java.lang.Class.getMethods()). javavm_pl.xsl - Is an XSLT stylesheet that produces the Virtuoso/PL wrappers based on the XML file from jvm_ref_describe_class. The stylesheet has a parameter "module" = "1" | "0" (default "1") which controls whether it to generate code for a Virtuoso/PL module, or a set of procedures. For each field it generates Get../Set.. methods (or only Get.. if the field is read-only). It also generates wrappers for each class method. For the non-static fields/methods it instantiates a java object every time the method is invoked. java_pl_wrapper.sql - This file is generated using the above files and then the java_properties procedure is added. Important: This demo needs Virtuoso server with Java hosting option. Otherwise demo will not run properly. SOAP services Fri, 27 Dec 2019 14:12:53 GMT Amazon API demo Preliminaries The online retailer Amazon.com has provided developers with an interface, that will allow them to do product searches based on a keyword, and a base category. The API is used either by a SOAP call or by a fetch of a XML document. Amazon.com suggests you to download the developer kit. However this is optional, as it is not necessary to run the following OpenLink tutorial. A developer key is required to access the service. One may be applied for at the Amazon.Com Web API page. The service requests may be configured in various ways by the parameters supplied to the API. Example Product search using SOAP API In the SQL setup file, the SOAP call is prepared by the function call to soap_wsdl_import() which reads in the web service ".wsdl" file from Amazon.com. Enter the Developer Key, result type, root node for the search, and the keyword to be searched for. Hit the search button to get the products matching the keyword. This example uses the "heavy" mode of results, that contains the full customer reviews. A local stylesheet is applied to the result for either an XML or HTML view. SOAP Interoperability Test Round IV Fri, 27 Dec 2019 14:12:53 GMT SOAP Interoperability Test Page Example This example uses the Virtuoso SOAP client for testing a SOAP interop IV endpoints. At least 2 web threads are needed, so this should be noted before starting. An Error message is shown if only one is available. This page shows operations defined for SOAP Interop Round IV tests, grouped by encoding and test group name. The demo pages are SOAP clients defined to perform appropriate SOAP call. The VSP based clients make a specific form for entering the input data and selecting an endpoint to test. Once call is made (invoked with Call button), the results will be extracted from SOAP response and shown. Also the request and response wire dumps will be shown for debugging purposes. SOAP services Fri, 27 Dec 2019 14:12:53 GMT Sending a SMS Example The setup_sms.vspx sets up the SMS sending unit. The handler.vspx does inserts/deletes/updates to demonstrate the SMS sending from triggers. For details of the Redcoal SOAP service see it's description in http://www.xmethods.com SOAP services Fri, 27 Dec 2019 14:12:53 GMT Yahoo GeoCode API demo Overview This example demonstrates how to use Yahoo GeoCode API as a local SOAP service. For more information on Yahoo GoeCode API visit: http://developer.yahoo.net/maps/rest/V1/geocode.html Breakdown In the initial state we create a simple procedure that: takes input parameters as described by Yahoo GoeCode API page. Generates URL and calls it. returns the XML result formated throught raw.xsl. Create SOAP_SO_S_27 user and grant the procedure to it. The SOAP service is achieved by defining the /SOAP_SO_S_27 URL to have same functionality as using soap_server() function call. The client uses AJAX to call the service and show the result. SOAP services Fri, 27 Dec 2019 14:12:53 GMT Google Maps API demo Overview This example demonstrates how to implement Google Maps API using XML and Asynchronous RPC ("AJAX"). For more information on Google Maps API visit: http://www.google.com/apis/maps/documentation/ Breakdown In the Initial state we will extend the Demo.demo.Customers table with some new fields (Longitude and Latitude). Then we will use Yahoo GeoCode API to find Longitude, Latitude values for the customers addresses and store the values in the database. The data_xml.vsp page generates XML from that table similar to the one described in Google Maps API Documentation. We have extend it a little bit to have information for the Customer Name and Address. Click on the 'googlemaps.vsp' Run link to see the generated Google Map. You can click on the markers to view additional information. SOAP services Fri, 27 Dec 2019 14:12:53 GMT Yahoo Maps API demo Overview This example demonstrates how to implement Yahoo Maps API Generated Rss feed. For more information on Yahoo Maps API visit: http://developer.yahoo.net/maps/simple/index.html Breakdown Yahoo Maps API can get map information using data formatted in Web-standard RSS format. We show in 'yahoomaps.vsp' how you can easily generated the feed to be posted to yahoo using just one SQL statement with xml_auto function. For more information on xml_auto refer to the documentation. Research Service for the Microsoft Office 2003 Fri, 27 Dec 2019 14:12:53 GMT Creating Research Service for the Microsoft Office 2003 Research Library Overview Microsoft Office 2003 provides a new tool called "The Research Library", which is available from the task pane in all of the Microsoft Office Suite including Microsoft Office Excel 2003, Microsoft Office PowerPoint 2003, Microsoft Office Word 2003, and Microsoft Office Outlook 2003. By default, the Research Library allows to search for terms using several built-in resources. The Research Library is also extensible: users can add their own research service by creating a Web service that follows schemas defined for Microsoft research services. Prerequisites The following prerequisites are needed to ensure that you can experience this demonstration. Virtuoso 3.5 or above Microsoft Office 2003 or higher Tutorial Example The following demonstration creates a service which exposes two methods: "Registration" and "Query". The first method allows Microsoft Office to discover the Query service; also it could be extended to log the registration info for specific application purposes. The "Query" service is used to make a Free-text search within WebDAV repository by a given set of keywords entered by user in task panel. The demo script also creates a virtual directory which forces "Document/Literal" encoding of SOAP messages, which is another way to expose Virtuoso PL stored procedures without having special SOAP user-defined data-types. Please follow the steps below to maximize the value of this tutorial: Step 1: Run the following sql script to set up so_s_34.sql. Step 2: After executing the initial setup above, add the service using a "Research" task pane by selecting "Research Options" and then "Add Services". Note: To access this Research Task pane, select Research from the Tools menu, or by pressing Ctrl+F1 and choosing Research from the Other Task Panes drop-down list. Step 3: In the presented text entry for the Address , type the URL to the demo service http://host:port/VRes/ and press "Add", then "Continue" and finally "Install" (in that step "Virtuoso FTi Search (PL)" should be displayed). Once you have installed the demo service, you can query it with typing search keywords in "Search for" text entry and selecting the "Virtuoso FTi Search (PL)" from drop-down box. On success a list of top 10 public readable items from WebDAV matching the "AND" of keywords will be displayed. Additional Information: For More details regarding the Microsoft Research Library for Microsoft Office 2003 see http://www.microsoft.com/office/editions/prodinfo/technologies/research.mspx For More details regarding WebDAV see http://docs.openlinksw.com/virtuoso/qswebdav.html#qswebdav For More details regarding Free-Text Search see http://docs.openlinksw.com/virtuoso/freetext.html#freetext Route Planner Demo Fri, 27 Dec 2019 14:12:53 GMT Using a MS MapPoint service for route planning Example There are several mapping services available today, but they only provide point to point services. Once such service is from Microsoft, which has a SOAP-based MapPoint service that allows location searching and distance calculations. The following demonstration uses the Microsoft MapPoint services to resolve addresses and to calculate the distance between two points. The demonstration will also calculate an optimized round-trip from a given start point to the destinations specified. In order to run the demonstration a MapPoint username and password are needed. Evaluation accounts from Microsoft are available here. eBay API demo Fri, 27 Dec 2019 14:12:53 GMT Using a eBay SOAP API Example This example uses eBay SOAP API to perform browsing of categories on eBay sandbox site. The demo uses WSDL_IMPORT_UDT() function to define SOAP proxy class for invocation of the eBay API. This will be done upon initial setup of the demo. The source code for imported UDT for SOAP proxy could be read via eBay.sql source file below. Also it defines a procedure for "getCategories" method invocation and it's used further in functions for vspx tree control to instantiate the nodes. To run the demo you will need to obtain a three developer keys : ApiId, DevId & CertificateId. Further a demo user on ebay sandbox site needs to be created and it's credentials must be used for to make API calls. To obtain developer keys please visit the eBay developer zone and follow the instructions. Once you have registered for eBay developer program and have the Api, Dev & Certificate IDs, go to "getting setup on sandbox" and follow the instructions to make a test user. Northwind query via SOAP Fri, 27 Dec 2019 14:12:53 GMT Building a document style oriented Web services Preliminaries The SOAP messages are XML documents which may follow encoding rules or an XML Schema. The ones that follow encoding rules are known as RPC encoded, so the XML Schema following messages are known as Document/literal encoded. Most of SOAP toolkits can work with both kind of messages, but for some purposes RPC encoded messages are not suitable. The MS Office Infopath supports only document/literal encoded SOAP messages. So to inter operate with it, Web services have to be set to define document/literal SOAP messages and generate appropriate WSDL file. The Virtuoso can expose a services that using document/literal encoding by two ways: explicit declarations in stored procedure's definition default SOAP encoding as an option of the SOAP enabled virtual directory The first approach imply that procedure can be used only in the designated encoding style. So the second is more flexabile as it can switch very easy between encodings without procedure's re-definition. To allow a stored procedure to be exposed in a virtual directory that default SOAP encoding as a document/literal it should not use explicit declarations. This is because explicit declarations are not compatible in all cases. Instead of explicit declarations a user defined types must be used to describe the structures and array modifier have to be used to describe array parameters. Example The example script defines a service that do a query on Northwind Demo Database and return an array of structures containing sales volume per product category. To run example, set the initial state and then click on the Run link or point your browser to http://[host]:[port]/NorthwindSvc/services.vsmx to go to vsmx test pages. Note: the dateinput must follow ISO8601 format (for example: YYYY-MM-DD'T'HH:MM:SS) Serializing Java classes as SOAP structures Fri, 27 Dec 2019 14:12:53 GMT Serializing Java classes as SOAP structures Example To test the service click on the Run link or point your browser to: http://[host]:[port]/services/services.vsmx This example demonstrates how to use Java user defined types for SOAP datatype mappings. It's based on the java class so_s_30.java. It demontsrates the two approaches in using the user defined types for SOAP structure mappings : Attach a user defined type to a predefined schema instance (user defined type SO_S_30). Generate the WSDL based on the user defined type's definition (user defined type SO_S_30_2). In order that to be runnable the so_s_30.java should be compiled to so_s_30.class with the java compiler and so_s_30.class be present in the server's CLASSPATH. Serializing SQL native classes as SOAP structures Fri, 27 Dec 2019 14:12:53 GMT Serializing SQL native classes as SOAP structures Example To test the service click on the Run link or point your browser to: http://[host]:[port]/services/services.vsmx This example demonstrates how to use SQL user defined types for SOAP datatype mappings. It demontsrates the two approaches in using the user defined types for SOAP structure mappings : Attach a user defined type to a predefined schema instance (user defined type SO_S_30). Generate the WSDL based on the user defined type's definition (user defined type SO_S_30_2). The example uses the implicit constructor for SQL native types (based on the default values). Serializing CLR classes as SOAP structures Fri, 27 Dec 2019 14:12:53 GMT Serializing CLR classes as SOAP structures Example To test the service click on the Run link or point your browser to: http://[host]:[port]/services/services.vsmx This example demonstrates how to use CLR user defined types for SOAP datatype mappings. It's based on the CLR class so_s_32.cs. It demontsrates the two approaches in using the user defined types for SOAP structure mappings : Attach a user defined type to a predefined schema instance (user defined type SO_S_30). Generate the WSDL based on the user defined type's definition (user defined type SO_S_30_2). SOAP services Fri, 27 Dec 2019 14:12:53 GMT Sending a SMS using a SOAP and User Defined Type Example The redcoal.sql is a script which implements SOAP proxy wrapper for sending SMS messages. The SOAP proxy wrapper is encapsulated in a User Defined Type The sms.vsp is web interface to the SMS sending unit. For details of the Redcoal SOAP service see it's description in http://www.xmethods.com Collaboration with other clients Fri, 27 Dec 2019 14:12:53 GMT Consuming a Virtuoso Web Service from Microsoft VB.NET VB.NET Virtuoso is able to interact with the Microsoft .NET by providing a WSDL description of all the stored procedures exposed as a SOAP operation within a given virtual directory. The WSDL description is an XML document available at http://<server_http_host_and_port>/SOAP/services.wsdl on any Virtuoso HTTP server. This allows for easy creation of .NET clients. fishselect example The following .NET VBA routine calls the fishselect stored procedure, and prints the results on the console. Open a new VB.NET project for Console Application. Add a web reference to the Virtuoso WSDL end point (http://host:port/SOAP/services.wsdl). Drag and drop the VirtuosoSOAP() from Class wizard in routine code. Module Module1 Sub Main() Dim s As New [drop here the VirtuosoSOAP() method from Class wizard] Dim r As String r = s.fishselect("G%") System.Console.WriteLine(r) End Sub End Module WSDL service Fri, 27 Dec 2019 14:12:53 GMT Generating HTML based Service interactions from a WSDL file Web services architecture Service providers deploy and publish services by registering them with the Service broker. Service requesters find services by searching the Service broker's registry of published services. Service requesters bind to the Service provider and consume the available services. Technology Uses In the world of Web services, each of these three operations involves three complimentary yet distinct technologies: Publishing services uses the Universal Description, Discovery and Integration (UDDI) API Locating services uses a combination of UDDI and the Web Services Description Language (WSDL) Binding to services leverages WSDL and the Simple Object Access Protocol (SOAP). At the most basic level, the Binding operation is the most important of the three. Example The example will create a SOAP based interface and WSDL description for searching an existing Customer Order New orders can be added into the demo database. The first page renders the WSDL as an HTML form for selecting the SOAP method. The second page renders the WSDL again to make a form for input parameters. Note that on this entry form needs to be entered valid _CustomerID (for example ALFKI) and _ProductID (for example is 1). Otherwise the servce will generate SOAP Fault message. Also _ShipVia needs to have a correct value to be entered (for example 1,2 or 3). Final page displays the result from the SOAP call. SOAP & WSDL service Fri, 27 Dec 2019 14:12:53 GMT Stock Quotes service SOAP Server setup An executable virtual directory is needed to create a SOAP based service. The service in practice is a PL procedure or group of PL procedures. In this example the PL module contains a single procedure. The procedure makes a request to the quotes.nasdaq.com. The retrieved XML document is returned as a string. VSP page for WSDL generation: For this example it is so_s_7_wsdl.vsp. A WSDL response is made and sent to the client. VSP for SOAP server: The SOAP server can be invoked using a soap_server() call. The so_s_7_server.vsp page shows setup of the SOAP server using the soap_server(). Example Virtuoso client invoked from VSP Virtuoso client is invoked from the VSP page so_s_7_client.vsp. This page accepts an issuer code and processes it with the Virtuoso SOAP client function - soap_call(). The soap method in this request is the name of the procedure defined in Step 2 above. The result from the SOAP request will be transformed with an XSL-T style-sheet, and sent to the browser as an HTML document. Example AJAX SOAP client invoked from JavaScript The "nasdaq_ajax.html" (listed below) contains a JavaScript code used to invoke SOAP client. This client will invoke the Virtuoso SOAP service as defined above. The JavaScript code uses XMLHttpRequest object. Invoking the operation via VB.NET application The following example demonstrates the usage of the Microsoft .NET against Virtuoso's SOAP service as defined in 'Server Setup': 1. Open a new VB.NET project for Console Application. 2. Add a web reference to the Virtuoso WSDL end point (http://[host:port]/xml-soap/services.wsdl). 3. Drag and drop the VirtuosoSOAP() from Class wizard in routine code. Sub Main() Dim soap As New WebReference1.VirtuosoDB_DBA_NasdaqQuotes() Dim result As String Dim sty As New Xml.Xsl.XslTransform() result = soap.get_NasdaqQuotes("YHOO") sty.Load("http://[host:port]/tutorial/services/so_s_7/sr.xsl") Dim strReader As New IO.StringReader(result) Dim xpDoc As New Xml.XPath.XPathDocument(strReader) Dim arg As New Xml.Xsl.XsltArgumentList() Dim strWriter As New IO.StringWriter() sty.Transform(xpDoc.CreateNavigator(), arg, strWriter) System.Console.WriteLine(strWriter.ToString) End Sub SOAP & WSDL service Fri, 27 Dec 2019 14:12:53 GMT Global provinces and administrative divisions lookup service Example overview This example demonstrates: Fetching HTML from a foreign host to populate a native table. A SOAP call. SQL to XML conversion with FOR XML EXPLICIT. XSL transformation. Example Setup The service is prepared by loading the SQL file. This performs the following: Fetch HTML country and province data from a foreign host. Insert the data into COUNTRY and PROVINCE tables. Fill tables COUNTRY_XML and PROVINCE_XML using http://[host:port]/DAV/factbook/factbook.xml. (http://www.xfront.org/factbook.xml) Define a stored procedure for the SOAP service that queries, using SQL, the data from the tables. The data is returned as XML, by including the FOR XML EXPLICIT clause, using the xml_auto() function to produce this as a string. Sample can use data from: Live feed from CIA factbook Cached XML Data The SOAP service is achieved by defining the /SOAP_SO_S_11 URL to have same functionality as using soap_server() function call. Example Operation Makes a SOAP client request. The XML result is held in a stream. Convert the stream using XSLT to HTML. Send the HTML to the browser for display. Invoking the operation via VB.NET application The following example demonstrates the usage of the Microsoft .NET against Virtuoso's SOAP service as defined in 'Server Setup': 1. Open a new VB.NET project for Console Application. 2. Add a web reference to the Virtuoso WSDL end point (http://[host:port]/SOAP_SO_S_11/services.wsdl). 3. Drag and drop the VirtuosoSOAP() from Class wizard in routine code. Sub Main() Dim soap As New WebReference1.VirtuosoSOAP() Dim result As String Dim sty As New Xml.Xsl.XslTransform() result = soap.administrative_divisions("United States", "") sty.Load("http://[host:port]/tutorial/services/so_s_11/sr.xsl") Dim strReader As New IO.StringReader(result) Dim xpDoc As New Xml.XPath.XPathDocument(strReader) Dim arg As New Xml.Xsl.XsltArgumentList() Dim strWriter As New IO.StringWriter() sty.Transform(xpDoc.CreateNavigator(), arg, strWriter) System.Console.WriteLine(strWriter.ToString) End Sub SOAP & WSDL service Fri, 27 Dec 2019 14:12:53 GMT Consuming Third-Party Services via WSDL URLs Example overview This example demonstrates usage of the WSDL_IMPORT_UDT() function. The result from calling of the WSDL_IMPORT_UDT() is the creation of a User Defined Type (UDT) which represents the SOAP service. Each method in the UDT represents an operation available from this SOAP service (proxy UDT). After successful retrieval of the WSDL, and UDT creation, the function returns UDT definition as string. The example also defines one test endpoint where it exposes the imported UDTs are own methods. Therefore it's easy to test using VSMX file for the demo endpoint. To cleanup the endpoint, use 'Clear cache' button. This would unpublish the SOAP proxy UDTs from the demo test endpoint. To setup and run, the initial script must be loaded. SOAP & WSDL service Fri, 27 Dec 2019 14:12:53 GMT Stock Quotes service hosted within Virtuoso's WebDAV repository Example This example repeats the example SO-S-7, but all VSPs are hosted in WebDAV repository. Important: make sure that EnabledDavVSP is set to 1 in the INI file, to allow VSP execution in WebDAV. The example script loads all pages into the WebDAV, and sets their execution flags. This example needs at least 2 HTTP server threads configured. SOAP & WSDL service Fri, 27 Dec 2019 14:12:53 GMT Stock Quotes client execution from within Virtuoso's WebDAV Repository Example This example repeats the example SO-S-7, but all VSPs for the SOAP client are hosted in the WebDAV repository. The SOAP & WSDL service are achieved by defining the /SOAP_SO_S_9 URL to have same functionality as using soap_server() and soap_wsdl() calls. '/SOAP_SO_S_9' represents the so_s_8_server.vsp and /SOAP_SO_S_9/services.wsdl represents the so_s_8_wsdl.vsp Important: make sure that EnabledDavVSP is set to 1 in the INI file, to allow VSP execution in WebDAV. The example script loads all pages into the WebDAV, and sets their execution flags. WS-ReliableMessaging demo Fri, 27 Dec 2019 14:12:53 GMT WS-Reliable Messaging: Setting up a SOAP endpoint Example The example below demonstrates configuring an endpoint for WS-Reliable Messaging operations. It also contains a simple client for issuing a 'ping' request to an endpoint which supports the WS-ReliableMessaging protocol. Note: To use the anonymous client, 'pingback URI' field in the send form should be empty. Making an SOAP router endpoint Fri, 27 Dec 2019 14:12:53 GMT Setting up a SOAP router endpoint Example This chapter describes general guide lines for using routing capabilities of the Virtuoso SOAP server. In order to have the rest of examples of this section working, the following steps must be performed. If you are going to try .NET examples the MS WSDK toolkit must be installed on a W2K machine. The .NET examples are tested with 1.0.0.0 version of Microsoft.WSDK.dll, so make sure that version of that assembly is the same. Make sure that WS Routing examples of MS WSDK working before trying any of interoperability examples. From this page run the setup script (set the initial state), this will define the routing and ultimate endpoints. The SOAP directory option we are using to setup a WS Routing (SOAP router) is: WS-RP - yes/no , this is to enable WS Routing filter The VSP page is example how Virtuoso SOAP client can be used to invoke the sample services as AddInt or echoString.Form this page we can invoke these operations via different routers. Note that "Operation to invoke" option must be set properly depending of type of endpoint (see remarks on select page). The .NET client example must be complied before trying it. To do this follow the steps: Change in the RoutingClient.cs and referalCache.config files <virtuoso:port> to host and port where your virtuoso HTTP server is listening. compile the example issuing nmake command in the tutorial/services/rp_s_1 directory. On that step you may need to have .NET Visual Studio installed and .NET Framework SDK if you going to compile the client on an other box, make sure that referralCache.config file is in the same directory where is .exe file. Manipulating of message path on a WS-Routing enabled endpoints Fri, 27 Dec 2019 14:12:53 GMT Routing path manipulation Example In order to try the following example you need first to setup the RP-S-1 as it uses the endpoints defined there. Also this example needs at least 3 HTTP threads configured in order to work properly. The VSP page demonstrates how routing path can be manipulated on a SOAP routers using the WS-Referral statements. The example show inserting an intermediary router in routing path Querying a router for already registered intermediary Execution of a single call to an endpoint Traveling of the message between client and endpoint via first and second router (added on step 1) Removal of a registered intermediary If step 1 is invoked twice sequentially an duplicates error will be shown If step 3 is invoked before step 1 or after step 5, an error for missing intermediary from routing path is shown Note: To determinate message routing path, see at content of 'rev' element in response message header when invoking the echoString operation. SOAP & WSDL service Fri, 27 Dec 2019 14:12:53 GMT Stock Quotes Service incorporating AJAX Example This example repeats the example SO-S-7, however client is using AJAX. The AJAX based client retrieves the XML data from Virtuoso SOAP service, and makes a client side XSL-T transformation. SOAP & WSDL service Fri, 27 Dec 2019 14:12:53 GMT Global provinces and administrative divisions lookup service incorporating AJAX Example This example repeats the SO-S-11, however client is using AJAX. Note: The tables and procedures are used from SO-S-11 example, so run SO-S-11 first. The SOAP & WSDL service are achieved by defining the /SOAP_SO_S_11 URL to have same functionality as using soap_server() and soap_wsdl() calls. SOAP & WSDL Fri, 27 Dec 2019 14:12:53 GMT Exchange Rate Conversion service Exchange Rate Conversion Example This example is an exchange calculator in two versions: based on VSP and soap_call() and another AJAX version based on WebService Behaviour. A virtual directory is configured to respond to SOAP service requests, which are handled in the context of the assigned SQL user. The example defines the following service descriptions and links: A SOAP directory of 'exchange' for describing exch's procedures. The WSDL file will be located at http://hostname:[port]/exchange/services.wsdl The server-based webservices file is exchange_rates.vsp, while the AJAX one is exchange_rates_ajax.html. Click on the 'Run' links to experience the demo. Note: loading the exchange.sql file will take some time, as it accesses a foreign host. SOAP & WSDL service Fri, 27 Dec 2019 14:12:53 GMT Web Registration form exploiting global provinces and administrative divisions lookup service Example overview This example demonstrates: Fetching a two-dimensional array from a SOAP service to populate a provinces list box. The clients in this case is using AJAX. Example This example uses the SO-S-11 for initial setup, and demonstrates making a simple registration form. Note: The tables and procedures are used from SO-S-11 example, so run SO-S-11 first. The SOAP & WSDL service are achieved by defining the /SOAP_SO_S_11 URL to have same functionality as using soap_server() and soap_wsdl() calls. SOAP services Fri, 27 Dec 2019 14:12:53 GMT Contact Details Extraction Service Example overview This example demonstrates: Fetching HTML from a foreign host as specified by the user. Rendering the page with regexp_match() to extract the contacts information. For example, it take information from sequences like: "quoted text" said John Smith, Manager at A Company. Making a Web search with the company name to find the domain. Making an email address from contact name, and domain name. A SOAP call. Processing the 4 dimensional array in the AJAX based client. XSL transformation. Example Setup The service is prepared by loading the SQL file. This performs the following: Define a SOAP type for 4 dimensional array. Define a stored procedure for the SOAP service that queries, web target and makes the contact info. The SOAP service is achieved by defining the /SOAP_SO_S_19 URL to have same functionality as using soap_server() function call. Example Operation Get a page from the URL. Substitute characters " as 0x94 etc. Remove <i>, <b>, <strong> elements. Take out CR/LF. Make breaks before <P and <H elements. Parse the page to have consistent escapes such as &quote; . If the above fails then achieve the same with substitutions. Have a function to return a regular expression(s) by given level of recursion. Have a recursive function which gets a regular expression based on depth and apply it against the text. If match found skip rest of pattern matching. If not, apply the next pattern. When contact matches name, title and company, the item will be added to a result array. Company of the result will be searched via Google to find 'home page' or 'welcome'. The top most result link from Google will be parsed to extract the name of the site ie. domain name part. The email will be composed as FirtsName.LastName@domain . A multidimensional array will be produced containing the name, company, title and email. Loop over the resulting array, and make an XML document. Render the XML to the HTML using XSL-T sheet. Invoking the operation via VB.NET application The following example demonstrates the usage of the Microsoft .NET against Virtuoso's SOAP service as defined in 'Server Setup': 1. Open a new VB.NET project for Console Application. 2. Add a web reference to the Virtuoso WSDL end point (http://[host:port]/SOAP_SO_S_19/services.wsdl). 3. Drag and drop the VirtuosoSOAP() from Class wizard in routine code. Sub Main() Dim soap As New WebReference1.VirtuosoSOAP() Dim result As String() Dim len, i As Integer result = soap.ExContacts("http://www.openlinksw.com/press/oplappl4.htm") len = result.Length - 1 For i = 0 To len Step 5 System.Console.WriteLine("Name: " + result(i)) System.Console.WriteLine("Title: " + result(i + 1)) System.Console.WriteLine("Company: " + result(i + 2)) System.Console.WriteLine("Email: " + result(i + 3)) System.Console.WriteLine("Home page: " + result(i + 4)) System.Console.WriteLine("") Next i End Sub Secure SOAP service Fri, 27 Dec 2019 14:12:53 GMT Secure SOAP Service invocation over SSL Example This example repeats the example SO-S-7, but SOAP call is executed over SSL. The SOAP & WSDL service are achieved by defining the /SOAP URL to have same functionality as using soap_server() and soap_wsdl() calls. '/SOAP' represents the so_s_7_server.vsp and /SOAP/services.wsdl represents the so_s_7_wsdl.vsp Make sure that files containing server and client certificate/key data are exists in the server working directory. The following files are required for the example: srv.cert.pem - server certificate srv.key.pem - server private key ca.pem - CA list cli.p12 - client certificate and private key in PKCS#12 format The example script defines and starts a HTTPS server on port 4433. Making an Secure SOAP Directory Fri, 27 Dec 2019 14:12:53 GMT Exposing Secure SOAP Endpoints Example In order to have the rest of examples of this section working, the following steps must be performed. The MS WSDK toolkit must be installed on a W2K mashine. The .NET examples are tested with 1.0.0.0 version of Microsoft.WSDK.dll, so make sure that version of that assembly is the same. Make sure that WS Secure examples of MS WSDK are working before trying any of interoperabilty examples. From this page run setup script (set the initial state), this will define symmetric keys, there is also included a x.509 import, but it's only for demonstration. To make your WSDK applications to work with Virtuoso you need to export from W2K box the certificate and import with registration page on this example. The setup script also defines a SOAP secure directory (/SecureWebServices) which is used in the rest of the examples. The SOAP directory options we are using to secure the messages are: WSS-SEC - yes/no , this is to enable WS secure processing WSS-KEY - name of procedure , which will return a key instance to encrypt the outbound messages WSS-Template - string or null, content of signature template, in that examples we will not make signatures on outbound messages. How to make signatures is explained in the x.509 siging example. WSS-Type - 1/0 to make signature or to encrypt only WSS-Validate-Signature - 0/1/2 - do not validate, validate signature, validate if exists in our examples we will accept both of variants, so 2 is used. Symmetric Encryption Fri, 27 Dec 2019 14:12:53 GMT Secure SOAP Client using Symmetric Encryption (3DES) Example This section describes how to make secure web services call, using a symmetric key encryption. The algorithm used for these examples is tripple-des. Both server and client have a shared secret, which is used to encryt and decrypt the SOAP message. In practice the key is transfered by some secure way between client and server, as if it's captured the all traffic between server and client can be compromised. Virtuoso keeps keys internally and can be instantiated with xenc_key_instance_create (). In this example we are using a key 'WSDK Sample Symmetric Key', imported from WSDK.NET SymmetricEncryption example. This is to have the same key in all places: .NET server and client, Virtuoso server and client. Another posibillity is to generate the key on Virtuoso side with xenc_key_3DES_rand_create() and export to the .NET client and server configuration. To export the 3DES key can be used xenc_key_serialize () function. The Virtuoso VSP based clients demonstrate accessing Virtuoso Web Service with Virtuoso client accessing .NET Web service with Virtuoso client To run .NET client against Virtuoso service you need: This example works with MS WSDK; MS WSE 2.0 obsolete the data encryption directly a key data. to change <virtuoso:port> to host and port where your virtuoso HTTP server is listening. compile the example issuing nmake command in the tutorial/services/ws_s_2 directory. if you going to compile the client on an other box, make sure that .config file is in the same directory where is .exe file. Asymmetric Encryption Fri, 27 Dec 2019 14:12:53 GMT Secure SOAP Client using RSA Encryption Example This section demonstrates how to make encrypted SOAP message using asymmetric algorithm (RSA). These examples are using a X.509 certificate to define the RSA key for encruption. To encrypt the message client uses public key of server's certificate, so only server know private key and can decrypt the message. In practice message itself is encrypted with 3DES algorthm using a random session key. The session key itself is encrypted with public part of RSA key. So the server first decode the session key, and then decrypt the message. The Virtuoso VSP based clients demonstrate accessing Virtuoso Web Service with Virtuoso client using asymmetric algorithm accessing .NET Web service with Virtuoso client using asymmetric algorithm To run .NET client against Virtuoso service you need: Microsoft WSE 2.0 installed Edit the Makefile and specify in CSLIBFLAGS where Microsoft.Web.Services.DLL reside. compile the example issuing nmake command in the tutorial/services/ws_s_3 directory. if you going to compile the client on an other box, make sure that .config file is in the same directory where is .exe file. X.509 Signing Fri, 27 Dec 2019 14:12:53 GMT Secure SOAP Client using X.509 certificate for signing Example This chapter demonstrates how to make signed SOAP message. The signed message contains certificate (only) in the Security header. In that example no encrypted data is sent, but in practice the both approaches can be combined. The server checks signature against this certificate and ensures it's validity. To run .NET client using X.509 certificate signed message, against Virtuoso service you need: Microsoft WSE 2.0 installed Edit the Makefile and specify in CSLIBFLAGS where Microsoft.Web.Services.DLL reside. compile the example issuing nmake command in the tutorial/services/ws_s_4 directory. Username Signing Fri, 27 Dec 2019 14:12:53 GMT Secure SOAP Client using Username and Password for signing Example This example demonstrates how to make signed SOAP message. The signed message contains Username and password in the Security header. In that example no encrypted data is sent. The server checks credentials against database users and ensures it's validity. To run .NET client using Username signed message, against Virtuoso service you need: Microsoft WSE 2.0 installed Edit the Makefile and specify in CSLIBFLAGS where Microsoft.Web.Services.DLL resides. compile the example issuing nmake command in the tutorial/services/ws_s_4a directory. Using a Secure SOAP Services Fri, 27 Dec 2019 14:12:53 GMT Exposing WS Trust SOAP Endpoints Preliminaries The WS Trust protocol is a SOAP based secure service and client that can be used to retrieve a security token (X.509 certificate or similar) in order to be used for making secure operation with an ultimate service in the client's operation. In common scenario the client asks Token Issuer for a security token. Then client uses token from WS Trust response to perform second remote call signed and/or encrypted to another service which is a ultimate target service. Usually Token Issuer, Client and Ultimate service are located on different physical locations. Example Before running this demo make sure that WS-S-1 tutorial is set-up and a valid X.509 certificate and corresponding private key are imported (for server and client usage) via WS-S-1 example certificate upload utility. This example uses WS Trust client to obtain X.509 security token from a Token Issuer service and then it uses to make signed request to dummy Weblog service. In real situation the Weblog service instead of echoing a random URL would create an entry in the user's blog. Note that in that demo all operations are performed in context of a same server (i.e. Token Issuer, Weblog service and client are running on one Virtuoso server instance). The following are demo's main points. Client uses a Username and password to digitally sign the request from Token Issuer. Token Issuer will check the signature and user credentials and then will issue security token to the client The Token Issuer service uses a PL hook to return appropriate X.509 token Client uses the returned token (from Token Issuer service) to match it against local key storage and to digitally sign the second request (to the Weblog service) The Weblog service will just verify the signature and will return an echo of the client's request plus an random URL string and post id. (In the real world such service should add data into a Database keeping the blog posts) The Weblog service will digitally sign the response before sending it to client. To see request/response messages from/to Token Issuer or Web service use the radio group buttons. Note: In this example Token Issuer, Weblog service and client uses same X.509 certificate. Add entity to UDDI Fri, 27 Dec 2019 14:12:53 GMT Business Contact Registration in Virtuoso hosted UDDI registry Example The example shows automatic convert demo..Suppliers to save_business UDDI query. Use UD-S-2 to see the result. Display entry from UDDI server Fri, 27 Dec 2019 14:12:53 GMT Querying Virtuoso hosted UDDI registry Example Setup a URL to a UDDI server Define a Name pattern (begin with) View the UDDI request Get the data from the server Web services registration Fri, 27 Dec 2019 14:12:53 GMT Step by step registration of SOAP services in Virtuoso hosted registry Preliminaries The UDDI provides a flexible way to register any kind of service. The services in particular can be SOAP or WSDL web services. SOAP and WSDL registration example This example makes a business record, and will define a service for it. The services can be provided by an organization (business). Without a defined provider service, it cannot be registered separately. Because there is no tModel for the service, one is provided for SOAP classification (tm.xml). Next step is to create a business description.(be.xml) Then create a service description (bs.xml). Then there is a binding (bnd.xml) of the service and business. This binding has two templates: SOAP template for information via Web page WSDL template for WSDL description of that service The example shows step by step for each template. Making and checking a Domain via Provider APIs Fri, 27 Dec 2019 14:12:53 GMT Exposing new domains Example The SQL script makes a Virtuoso API functions to create and check domains. The interface page has a test buttons which sends a REST request to the server. The Service for testing will just return its own argument. At least 2 web threads are needed, so this should be noted before starting. An Error message is shown if only one is available. The page shows the command and explains the manual operation for doing this from the admin interface. Checking if WebID and specific Public Key are in a relation Fri, 27 Dec 2019 14:12:53 GMT Checking WebID Example The service is an alternative to using SPARQL queries via the SPARQL protocol against Virtuoso endpoints re. WebID verification i.e., lookup a profile graph to see if WebID and specific Public Key are in a relation. The webid_demo.vsp is a vsp page which implements WebID checking. The webid_demo.php is a PHP page which implements WebID checking. The webid_demo.html is a HTML (JS) page which implements WebID checking. HTML-to-Wireless Fri, 27 Dec 2019 14:12:54 GMT HTML-to-Wireless Tranformation Preliminaries Traditional HTML-based web pages are not intended for wireless viewing. However, with a little Virtuoso server-side scripting, you can turn any WAP-based wireless phone into a full HTML web browser! Running the Demo on a WAP device To access this application via WAP/WML, enter the following URL into a WAP-enabled wireless device: http://<hostname>/tutorial/apps/wa_b_1/html2wml.vsp Running the Demo on a WAP emulator To simulate viewing the output on a wireless device. Run the RunHtml2wml.html file. Then choose a web-based emulator from one below: Wap.com - This is the most accurate Java and web based emulator, almost to the point of the definitive WAP SDK emulators from Openwave. However, its performance is not always optimal. Wapsilon.com - This is a reasonably accurate emulator, but the user interface handling is not quite the same as a real WAP phone. Wapmore.com - This is a PDA style emulator. Although its interface is a bit quirky, the performance is reasonable. Gelon.net - This is probably the fastest web-based WAP emulator; however, it sometimes exhibits problems displaying WML forms. Download WAP SDK - Our recommended option, this standard WAP SDK for emulators from Openwave.com (formerly Phone.com). WAP Phone Emulator Fri, 27 Dec 2019 14:12:54 GMT WAP Phone Emulator Preliminaries This application demonstrates the power of Virtuoso XSL-T by transforming an XML file in real time into a wireless phone emulator, using a simple XSL stylesheet. Although fuller-featured WAP emulators exist, this demo serves to illustrate what can be achieved with a few lines of VSP code and accompanying stylesheet. However, a more comprehensive and fuller-featured WAP emulator built around the same concepts may be available soon. Running the Demo on a WAP device To access this application, click on 'Run' link below. WAP based Email Fri, 27 Dec 2019 14:12:54 GMT WAP Phone E-mail Retrieval Preliminaries Thought the only way to check your email on a wireless phone was via Yahoo.com? This demo will illustrate how a few VSP scripts on a Virtuoso server can provide a fully-functional wireless E-mail solution. Read messages from your POP-based email account from any WAP-enabled wireless device, or from the wireless phone emulators. Running the Demo on a WAP device To access this application via WAP/WML, enter the following URL into a WAP-enabled wireless device: http://<hostname>/tutorial/apps/wa_b_3/index.vsp Email WAP Application files index.vap - Main page that calls the other files. signup.vsp - Code to register details about a new user. login.vsp - Code to sign-in a registered user. checkmail.vsp - Code to communicate with the POP3 account. logout.vsp - Code to sign-out. Running the Demo on a WAP emulator To simulate viewing the output on a wireless device. Run the RunWapEmail.html file. Then choose a web-based emulator from one below: Wap.com - This is the most accurate Java and web based emulator, almost to the point of the definitive WAP SDK emulators from Openwave. However, its performance is not always optimal. Wapsilon.com - This is a reasonably accurate emulator, but the user interface handling is not quite the same as a real WAP phone. Wapmore.com - This is a PDA style emulator. Although its interface is a bit quirky, the performance is reasonable. Gelon.net - This is probably the fastest web-based WAP emulator; however, it sometimes exhibits problems displaying WML forms. Download WAP SDK - Our recommended option, this standard WAP SDK for emulators from Openwave.com (formerly Phone.com). Echo Fri, 27 Dec 2019 14:12:55 GMT Simple BPEL4WS process Example The example contains code for simple echo service. It accepts a string as an input and echoes back to the client. So it shows the core BPEL concepts for building services. To build and run the example follow the steps bellow: Login into the BPEL UI via http://host:port/BPELGUI. From the 'Home' tab page go to section 'Tasks' and click 'Upload Process' link. Another way is to choose 'Processes' tab and go to the 'Process Upload' sub-tab. For the given entry form in the "Load Deployment Descriptor URI" field type 'http://host:port/BPELDemo/echo/bpel.xml'. Choose the 'Import Process' button. Choose the 'Compile process' button. If compilation succeeds, will go to the 'Processes' page where the process will be in the given processes list. To test the process click "Test" in the listing. This goes to a page allowing you to enter a start message for creating a new instance of this process. Fibonacci function Fri, 27 Dec 2019 14:12:55 GMT Fibonacci function BPEL4WS process Example The Fibonacci function calculates number based on following algorithm: int fi (int i) { if (i < 2) return i; return fi (i-1) + fi (i-2) } The example contains code for a simple Fibonacci function service. It accepts an integer number as an input and calculates the Fibonacci number. The process like the Fibonacci function does a recursive syncronous invocation of itself. The example is allowed with values less than 6. If is entered value greater then 6, will be printed the message "Entry values greater then 6 are not allowed!" and the input entry value will be initialized to 6. To build and run the example follow the steps bellow: Login into the BPEL UI via http://host:port/BPELGUI. From the 'Home' tab page go to section 'Tasks' and click 'Upload Process' link. Another way is to choose 'Processes' tab and go to the 'Process Upload' sub-tab. For the given entry form in the "Process name" field type 'Fi' in order the process to be invoked successfully. In the "Load Deployment Descriptor URI" field type 'http://host:port/BPELDemo/fi/bpel.xml'. Choose the 'Import Process' button. Choose the 'Compile process' button. If compilation succeeds, will go to the 'Processes' page where the process will be in the given processes list. To test the process click "Test" in the listing. This goes to a page allowing you to enter a start message for creating a new instance of this process. Loan Flow Fri, 27 Dec 2019 14:12:55 GMT LoanFlow process Example This example needs BPEL4WS VAD package to be installed on the server, before trying it. To learn more about VAD please visit http://docs.openlinksw.com/virtuoso/VAD.html. The example script creates services for Credit Rating, United Loan and Star Loan. The WSDL descriptions for these services are available via CreditRating.vsp, UnitedLoan.vsp and StarLoan.vsp. On the initial load the BPEL LoanFlow process will be deployed. The test client can be used to test the BPEL LoanFlow process. You can test the example using BPEL UI also by going to 'Processes' tab and click "Test" in the listing. This goes to a page allowing you to enter a start message for creating a new instance of this process. SecLoan Fri, 27 Dec 2019 14:12:55 GMT LoanFlow process using WS-Security Example The example contains code for LoanFlow Using WS-Security. The following are requirments to the caller and the process: The caller must supply a signed and encrypted SOAP message. Process must reply from a separate HTTP connection to the endpoint designated by the caller's ReplyTo WSA header. The process' reply must contain a signed and encrypted SOAP message. The X.509 certificates must be used to sign the message. The Session keys can be tripple-des or AES (128, 192 or 256 bit quality). A Session key must be encrypted with the partner's RSA public key. The test certificates from MS WSE 2.0 toolkit can be used. To build the example follow the steps bellow: This example needs BPEL4WS VAD package to be installed on the server, before trying it. To learn more about VAD please visit http://docs.openlinksw.com/virtuoso/VAD.html. The example script creates services for Credit Rating, United Loan and Star Loan. The WSDL descriptions for these services are available via CreditRating.vsp, UnitedLoan.vsp and StarLoan.vsp. On the initial load the BPEL LoanFlow Using WS-Security process will be deployed. To run the example follow the steps bellow: Login into the BPEL UI via http://host:port/BPELGUI. To enable debugging for the process with name 'SecLoanFlow' check the Debug checkbox in the listing. This will cause all instances of the process to run in single-step mode, pausing at each send or receive of a message. The debug console allows interacting with instances in this mode. To test the process click "Test" in the listing. This goes to a page allowing you to enter a start message for creating a new instance of this process. RMLoan Fri, 27 Dec 2019 14:12:55 GMT Reliable Loan Flow process Example The example contains code for Reliable Loan Flow. Invokation of loan services must be done using WS-RM protocol and rules: The caller must supply a valid WSA header 'ReplyTo' containing a valid response URL. The Process must send a reply from a separate HTTP connection to the endpoint designated by the caller's ReplyTo WSA header using WS-RM. To build the example follow the steps bellow: This example needs BPEL4WS VAD package to be installed on the server, before trying it. To learn more about VAD please visit http://docs.openlinksw.com/virtuoso/VAD.html. This example depends from the SecLoan example. Make sure there is initial load for this example. The example script creates services for Credit Rating, United Loan and Star Loan. The WSDL descriptions for these services are available via CreditRating.vsp, UnitedLoan.vsp and StarLoan.vsp. On the initial load the BPEL Reliable LoanFlow process will be deployed. To run the example follow the steps bellow: Login into the BPEL UI via http://host:port/BPELGUI. To enable debugging for the process with name 'SecLoanFlow' check the Debug checkbox in the listing. This will cause all instances of the process to run in single-step mode, pausing at each send or receive of a message. The debug console allows interacting with instances in this mode. To test the process click "Test" in the listing. This goes to a page allowing you to enter a start message for creating a new instance of this process. SecRMLoan Fri, 27 Dec 2019 14:12:55 GMT Secure and Reliable Loan Flow process Example This example is a combination of Secure and Reliable Loan Flow examples. The calls to the asynchronous services must be done via WS-RM protocol. The calls to partners must be encrypted and signed using the rules: The caller must supply a signed and encrypted SOAP message. The process must reply from a separate HTTP connection to the endpoint designated by the caller's ReplyTo WSA header. The process' reply must contain a signed and encrypted SOAP message. X.509 certificates must be used to sign the message. The session keys can be tripple-des or AES (128, 192 or 256 bit quality). A Session key must be encrypted with the partner's RSA public key. The test certificates from MS WSE 2.0 toolkit can be used. To build the example follow the steps bellow: This example needs BPEL4WS VAD package to be installed on the server, before trying it. To learn more about VAD please visit http://docs.openlinksw.com/virtuoso/VAD.html. This example depends from the SecLoan and the RMLoan example. Make sure there are initial loads for these examples. The example script creates services for Credit Rating, United Loan and Star Loan. The WSDL descriptions for these services are available via CreditRating.vsp, UnitedLoan.vsp and StarLoan.vsp. On the initial load the BPEL Secure and Reliable Loan Flow process will be deployed. To run the example follow the steps bellow: Login into the BPEL UI via http://host:port/BPELGUI. To enable debugging for the process with name 'SecRMLoanFlow' check the Debug checkbox in the listing. This will cause all instances of the process to run in single-step mode, pausing at each send or receive of a message. The debug console allows interacting with instances in this mode. To test the process click "Test" in the listing. This goes to a page allowing you to enter a start message for creating a new instance of this process. Inventory Service Fri, 27 Dec 2019 14:12:55 GMT Using SQL binding and SQLX to generate requests process Example The demo is a service which is invoked on time basis in order to update an inventory. This demo using the Northwind demo Database as an inventory. The client generates a list of items that are under 10 units using SQLX. This XML document is sent to the inventory process and will make new process instance. create procedure DB..update_inventory () { declare req any; whenever not found goto nf; -- the following statement generates an XML document using SQLX -- -- the result would like : -- <Items xmlns="http://temp.org"><Product><ProductID>5</ProductID><Quantity>10</Quantity></Product>...</Items> -- select xmlelement(Items, xmlattributes ('http://temp.org' as xmlns), xmlagg ( xmlelement (item, xmlelement (ProductID, ProductID), xmlelement (Quantity, UnitsInStock + 10) ))) into req from Demo..Products where UnitsInStock < 10 and Discontinued = 0; -- call the process with generated XML document as a input parameter soap_client ( url=>'http://host:port/InventorySvc', operation=>'initiate', parameters=>vector ('par0', req), soap_action=>'initiate', style=>1 ); nf: return; } The process will loop over all items in input and for each will ask for quote. Also the quote service will return a list of wholesalers and their prices. Then the process will choose the best price and will make an order using specific partner URL (this is simulated by appending a URL parameter to the service URL). When an order confirmation is received, the process will update the inventory. At the end of process it will sent an e-mail to the pre-configured operator address. The following code is a pseudo-code which describes the process flow: { declare i, l int; declare j, k, oid int; declare in, out, ord any; in = receive (); l = length (in); for (i = 0; i < l; i++) { declare q, best any; q = getQuote (in[i]); k = length (q); for (j := 0; j < k; j++) { if (q.price < best.price) best = q; } oid = newOrder (best.url, in[i].item, in[i].quantity, best.price); update Demo.demo.Products set UnitsOnStock = UnitsOnStock + in[i].quantity where ProductID = in[i].ProductID; } sendMail ('Inventory have been updated'); } To run the example follow the steps bellow: Load the initial setup file: 'store.sql' Login into the BPEL UI via http://host:port/BPELGUI. From the 'Home' tab page go to section 'Tasks' and click 'Upload Process' link. Another way is to choose 'Processes' tab and go to the 'Process Upload' sub-tab. In the "Load Deployment Descriptor URI" field type 'http://host:port/BPELDemo/sqlexec/bpel.xml'. Choose the 'Import Process' button. Choose the 'Compile process' button. If compilation succeeds, will go to the 'Processes' page where the process will be in the given processes list. Run via ISQL the DB..update_inventory () procedure. Also the update_inventory procedure can be used as a scheduled task (see 'Virtuoso scheduler' section in the documentation for details). UseCases Fri, 27 Dec 2019 14:12:55 GMT BPEL Data Manipulation Options processes Purpose This is a Technical Use Case as per OASIS MS01 document, illustrating various options for data manipulation inside a BPEL process. The following situations are shown: MS01-1: Variable initialization. MS01-2: Assignment of string, numeric, boolean and date values. MS01-3: Assignment of variables by copying other variable's values. MS01-4: Sample XPath calculations. MS01-5&6: Working with array structures. To run the example follow the steps bellow: Load the initial setup file: 'MS01.sql' Login into the BPEL UI via http://host:port/BPELGUI to test the processes. Java Execution Fri, 27 Dec 2019 14:12:55 GMT Java Execution BPEL4WS process Example This example demonstrates how the Java code can be embedded in a BPEL process. The example contains java code which gets data from BPEL variable, prints string to the console and returns string. To build and run the example follow the steps bellow: Make sure system calls are enabled in virtuoso.ini (AllowOSCalls parameter). Make sure CLASSPATH environment variable contains "classlib" entry. Make sure you are running java enabled server (virtuoso-odbc-javavm-t or virtuoso-odbc-javavm-clr-t). Login into the BPEL UI via http://host:port/BPELGUI. From the 'Home' tab page go to section 'Tasks' and click 'Upload Process' link. Another way is to choose 'Processes' tab and go to the 'Process Upload' sub-tab. For the given entry form in the "Load Deployment Descriptor URI" field type 'http://host:port/BPELDemo/java_exec/bpel.xml'. Choose the 'Import Process' button. Choose the 'Compile process' button. If compilation succeeds, will go to the 'Processes' page where the process will be in the given processes list. To test the process click "Test" in the listing. This goes to a page allowing you to enter a start message for creating a new instance of this process. .NET Execution Fri, 27 Dec 2019 14:12:55 GMT .NET Execution BPEL4WS process Example This example demonstrates how the C# code can be embedded in a BPEL process. The example contains .NET code which gets data from BPEL variable, prints string to the console and returns string. To build and run the example follow the steps bellow: Initialize "CLRAssembliesDir" configuration field at BPEL UI 'Configuration' tab with the directory name where the dlls from the distribution are located ( t.e. OpenLink.Data.VirtuosoClient.dll, virt_bpel4ws.dll etc). If you have problems initializing this CLRAssembliesDir, ask your system administrator to initialize this directory for you (and copy all needed DLLs there) or to tell you where this directory is located. Make sure you are running CLR or Mono enabled server (virtuoso-odbc-clr-t, virtuoso-odbc-mono-t, etc). Login into the BPEL UI via http://host:port/BPELGUI. From the 'Home' tab page go to section 'Tasks' and click 'Upload Process' link. Another way is to choose 'Processes' tab and go to the 'Process Upload' sub-tab. For the given entry form in the "Load Deployment Descriptor URI" field type 'http://host:port/BPELDemo/clr_exec/bpel.xml'. Choose the 'Import Process' button. Choose the 'Compile process' button. If compilation succeeds, will go to the 'Processes' page where the process will be in the given processes list. To test the process click "Test" in the listing. This goes to a page allowing you to enter a start message for creating a new instance of this process. processXSLT Fri, 27 Dec 2019 14:12:55 GMT XSLT processing example Example This example demonstrates how the XSLT styles can be used in BPEL script. The example contains invoking the processXSLT XPath function which transforms data from a BPEL variable. To build and run the example follow the steps bellow: Load the initial setup file: ' processXSLT.sql' Login into the BPEL UI via http://host:port/BPELGUI. From the 'Home' tab page go to section 'Tasks' and click 'Upload Process' link. Another way is to choose 'Processes' tab and go to the 'Process Upload' sub-tab. For the given entry form in the "Load Deployment Descriptor URI" field type 'http://host:port/BPELDemo/processXSLT/bpel.xml'. Choose the 'Import Process' button. Choose the 'Compile process' button. If compilation succeeds, will go to the 'Processes' page where the process will be in the given processes list. To test the process click "Test" in the listing. This goes to a page allowing you to enter a start message for creating a new instance of this process. processXQuery Fri, 27 Dec 2019 14:12:55 GMT XQuery processing example Example This example demonstrates how the XQuery program can be used in a BPEL process. The example contains invoking the processXQuery XPath function which returns a result of XQuery program. To build and run the example follow the steps bellow: Login into the BPEL UI via http://host:port/BPELGUI. From the 'Home' tab page go to section 'Tasks' and click 'Upload Process' link. Another way is to choose 'Processes' tab and go to the 'Process Upload' sub-tab. For the given entry form in the "Load Deployment Descriptor URI" field type 'http://host:port/BPELDemo/processXQuery/bpel.xml'. Choose the 'Import Process' button. Choose the 'Compile process' button. If compilation succeeds, will go to the 'Processes' page where the process will be in the given processes list. To test the process click "Test" in the listing. This goes to a page allowing you to enter a start message for creating a new instance of this process. Enter "2" as id and "Kathreen Smith" as "seller" for the test form fields. processXSQL Fri, 27 Dec 2019 14:12:55 GMT XSQL processing example Example This example demonstrates how the XSQL scripts can be used in a BPEL example. The example contains the XSQL file selectCustomers.xsql which selects a customer by given SSN. To build and run the example follow the steps bellow: Login into the BPEL UI via http://host:port/BPELGUI. From the 'Home' tab page go to section 'Tasks' and click 'Upload Process' link. Another way is to choose 'Processes' tab and go to the 'Process Upload' sub-tab. For the given entry form in the "Load Deployment Descriptor URI" field type 'http://host:port/BPELDemo/processXSQL/bpel.xml'. Choose the 'Import Process' button. Choose the 'Compile process' button. If compilation succeeds, will go to the 'Processes' page where the process will be in the given processes list. To test the process click "Test" in the listing. This goes to a page allowing you to enter a start message for creating a new instance of this process. Making an Executable Directory Fri, 27 Dec 2019 14:12:54 GMT Making an executable directory in Virtuoso's Web server space. Preliminaries It is necessary to complete the configuration of the executable directory before any of the subsequent tutorials will function. It is therefore important to follow these steps carefully before trying to run the vs_b_1.vsp file. The example demonstrated here creates an executable directory depending on either tutorial_dav.vad package was installled (i.e. the tutorials are in the DAV repository) or the tutorial_filesystem.dav package ( the tutorials have FS location.) These tutorials are designed for use on an OpenLink Virtuoso V3.0 VDBMS. Earlier versions will not work. Login to the Conductor UI using the dba account. Create the database user account vspdemo Go to "System Admin" tab and then go to the "User Accounts" tab. Click the "Create New Account" link. Enter for Account Name "vspdemo" and a desired password with confirmation. Check the check-box for "Allow SQL/ODBC Logins". Leave the rest of the fields at their default. Press the "Save" button. You will see the vspdemo now listed under current user accounts. Check tutorials type and path of installation (DAV or FS) Go to "Database" tab and then go to the "Interactive SQL" tab. Enter in the text area the following: select TUTORIAL_VDIR_DIR(); Click the "Execute" button. The found result will be the tutorials Path location. Click the button "Return". Enter in the text area the following: select TUTORIAL_IS_DAV(); Click the "Execute" button. The returned result will be the tutorials Type location: 1 - tutorials are installed in DAV, or 0 - tutorials are installed in the local FS. Allow VSP files to be run by vspdemo user with directory browsing allowed Go to "Web Application Server" tab and then go to the "Virtual Domains & Directories" tab. From the given list of HTTP Hosts click the icon in front of the Interface value. Click the "Add new directory" link. If tutorials Type location is FS, then choose the "File System" type and press the button "Next>>"; If tutorials Type location is DAV, then choose the "WebDAV domain" type and press the button "Next>>". Enter "/vs_b_1" for Path, Enter the tutorials Path location with "/tutorial/web/" at the end for physical path (for ex. /vad/vsp/tutorial/web/ or /DAV/VAD/tutorial/web/), select "vspdemo" for the VSP user, select "Allow Directory Browsing" checkbox and then press the "Save Changes" button. To test the new directory: enter the "http://host:port/vs_b_1" in browser. For example http://localhost:8889 as the URL. If all is ok, the content of the web tutorial directory is shown. Equivalent SQL commands to achieve executable directory Connect to the Virtuoso server via ISQL utility as DBA user. Create the user "vspdemo" SQL> create user vspdemo; SQL> user_set_qualifier ('vspdemo', 'vspdemo'); Create the virtual directory with user for execution "vspdemo" SQL> VHOST_REMOVE (vhost=>'*ini*',lhost=>'*ini*',lpath=>'/vs_b_1'); SQL> vhost_define (vhost=>'*ini*',lhost=>'*ini*',lpath=>'/vs_b_1', ppath=>TUTORIAL_VDIR_DIR() || '/tutorial/web/',vsp_user=>'vspdemo', is_brws=>1, is_dav=>TUTORIAL_IS_DAV()); Syntax of a Page Fri, 27 Dec 2019 14:12:54 GMT Overview of Virtuoso Server Pages (VSP) syntax Preliminaries The pages with active content are named Virtuoso Server Pages, or VSP in short. These pages consist of Virtuoso PL and HTML code. The Virtuoso Web server executes only files (resources) with the ".vsp" extension. The VSP file can contain VSP blocks and HTML blocks The VSP block contains the PL code The <?vsp marks the beginning of a VSP block. The ?> marks the end of a VSP block. The HTML block is everything outside of a VSP block. The VSP shortcut in an HTML block is used to include value. The <?= marks the beginning of VSP shortcut. The ?> marks the end of a VSP shortcut. Example The demonstration page uses the <?= <?vsp markup and SQL expressions to generate html content from within a VSP loop. Accessing Data in the Request Fri, 27 Dec 2019 14:12:54 GMT How to access form data. Preliminaries Data supplied to a VSP is normally posted from a form. Pressing a form submit button causes the browser to pass the data to the server. The form data may be encoded in two forms: www-url-encoded or multipart/form-data. Processing of the form data in VSPs. When the request arrives, the web server parses the request and creates three input arguments for VSP processing: path - array with path elements of the requested URL path. Ie. if the request is "http://foo.bar/a/b/c" then "path" argument will be a vector ('a','b','c'). params - array with name and value pairs of the passed form parameters lines - the vector of HTTP request header lines The form data is held in the "params" argument. The value of a named parameter can be extracted from the "params" array in two ways: Using the get_keyword function: declare x varchar; x := get_keyword('fieldname', params, 'default value'); Using the {?'variable_name'} VSP shortcut. x := {?'fieldname'}; Form example - A Simple Calculator. The user can enter two numbers, and choose a desired operation. Pressing the "=" button causes the form to be sent to the server. The VSP execution will show the result of the calculation. This example uses the get_keyword function to retrieve the parameters. Form example - Insert table data The second example demonstrates inserting the user entered form data into a table. This example uses the {?''} shortcuts for accessing the form data. The data in the table will be shown below the form, ordered by date. You must run the sample SQL first to create the table. Note Note that both examples do not handle the SQL errors. The handling of SQL errors in VSPs will be described in section "VS-B-6". Emitting Output to the User Agent Fri, 27 Dec 2019 14:12:54 GMT How to send data to the user-agents Preliminaries The Virtuoso Web server writes the content that is to be sent into the internal string session. The internal string session will be sent to the user-agent after VSP execution (if there is no unhandled SQL errors). There is full control over an internal session. It can be cleared, filled and flushed. Note when flushing an internal session the task will be executed in background, and no output will be sent after this action. The character data can be encoded in various ways. A default encoding (CharSet) can be defined in the database INI file HTTP session control functions http() - writes a string into the internal string session without conversion. http_value() - writes a string with escapes into the internal string session. http_rewrite() - clears the internal string session http_flush() - flushes the internal string to the user-agent and continues processing in background. <?=var ?> - a shortcut to write a variable (or function) from an HTML section. HTTP formatting and charset functions sprintf() - the special codes %V and %U used for HTML and URL escaping respectively. http_url() - converts argument to a URL escaping special characters. Result written to internal session. http_value() - converts argument to HTML escaping special characters. Result written to internal session. current_charset() - returns name of the current charset. Examples Use of http(). Use of http_value(). Use of http_rewrite(). Use of http_url(). Use of <?= ?> tags. Use of sprintf(). Controlling the Response Header Fri, 27 Dec 2019 14:12:54 GMT How to control the HTTP response from VSP Preliminaries The behavior of the user-agents (Eg. browser) depends on the server's HTTP response. The HTTP responses are: positive (2xx), informative (1xx), redirection(3xx), client error(4xx), server error(5xx). The Virtuoso Web server automatically generates positive, client error and server error codes. The http_request_status() function overwrites the default response. Example: http_request_status ('HTTP/1.1 404 Not found'); Note that the response line MUST begin with "HTTP/1.1 ", and numeric code MUST be one described in RFC2616. Some responses require additional information in the HTTP response header. The functions for setting the additional lines in a response header are: http_header() - accept a response header line(s) as string. If more than one line is supplied, they must be separated with <CR><LF> characters. Note that the string must always finish with <CR><LF> chars. Subsequent calls of this function replace the old response. http_header_get() - returns the HTTP response header currently defined. It is useful when you need to append more lines. Redirection example The first example demonstrates a redirection to another page. It uses http_request_status() and http_header() functions to set redirection code 'HTTP/1.1 302 Found' and 'Location:' header line in the response. If a document has moved to another url, it's possible to redirect using a meta tag within the <head> of a page. However using the method in this example, the redirection can be dynamic and conditional. Load random Images The second example demonstrates loading random images onto a page. Three images are loaded into the page by calling the vsp to generate each image. Each image URL is made unique by including a pic parameter. This does not imply the images will be different, however it stops the browser from reusing one image three times. The image content is made by setting the 'Content-Type' header field of the response to the 'image/gif', then returning a randomly chosen block of Gif data. A real world use for a random image, is to show an advertising banner graphic. Rather than change the url for the banner, the actual image content is controlled. This technique might also be useful for changing an appearance of a web page based on some criteria such as if the user has membership access or the time of day is either day or night to show a sun or moon image. Error Recovery Fri, 27 Dec 2019 14:12:54 GMT Error handling in VSPs Preliminaries When processing some form data in VSPs, there may be errors in the PL code (for example due to deadlock condition). The most popular way of catching the SQL errors is to declare an exception handler. declare error varchar; error := null; declare exit handler for sqlstate '*', not found result { error := __SQL_MESSAGE; }; { -- some operation(s) that may cause a SQL error } if (error is not null) -- print the error message To simplify VSP production, the error handler can be written in a common file and included in each page. The external file can be included using the following markup: <?include path_to_the_external_file.extension ?> Deadlock Example The first example demonstrates the creation of a universal deadlock handler. If this file is included in any VSP the deadlock condition will cause a retry up to 3 times on an operation that follows the handler. The VSP simulates the deadlock situation by signalling the error. The error handler is therefore called. Calculator with error handler The second example is the vs_b_3 Calculator example. In this example there is an added handler to trap errors such as division by zero, and entering characters instead of numbers. User Records Fri, 27 Dec 2019 14:12:54 GMT VSP exercise to create user records User record Example The object of the exercise is to handle form data, and data held in a table. This is achieved with 4 separate stages. Each stage has a separate file. Create a user table with a login name, password, real name and address. The login name is the primary key. This table can be made with a SQL file. Write an application which gets data from a form and inserts it into a table. Write a form to prompt for login details and pass to the query page. Write a form for querying the table based on the login name. The login name in the query form will be a SQL LIKE string. This example would be used in web sites that have some form of membership to gain access to information. Media Archive Fri, 27 Dec 2019 14:12:54 GMT Creating a simple file storage system using an SQL table Overview The media archive shall demonstrate a way to upload files and also to download them. The web page shows the upload feature, and download list at the same time. Upload Media The file upload form allows an arbitrary file to be browsed and uploaded. The input control is of type FILE for the upload field. The ENCTYPE of the form must be a "multipart/form-data", so that the uploaded file data and type (attr-file) is accessible to the VSP. Download media Display a list of stored files on a single page and have a download link to each. The default name in the download box must be the original file name. The INLINEFILE pseudo directory shall be used to set the original name of a file. The "Content-Type" header must be set to original media type. Note that INLINEFILE pseudo URL needs a parameter "VSP", this parameter MUST contain the target VSP link encoded as URL. Header Parsing Functions Fri, 27 Dec 2019 14:12:54 GMT Header Parsing Functions (Cookie Example) Preliminaries The HTTP request header contains lines of request information. Every user-agent (browser) sends at least one request line to the Web server. The "lines" argument in VSPs is an array of the user-agent request lines. Methods for accessing the request parameters A specific attribute can be accessed with the http_request_header() function. The header lines can be accessed with aref() function. Parsing the header line can be done with the split_and_decode() function. Cookie Demo This example shows how to set a cookie in the user-agent, and displaying a cookie string when retrieved. Setting the cookie is done with the http_header() function. (see also:VS-B-5) Retrieving the cookie string is done with http_request_header() function. Simple VSPX controls Fri, 27 Dec 2019 14:12:54 GMT Building a VSPX page Preliminaries The framework named Virtuoso Server Pages Extensions (VSPX) is a set of widgets (controls) which are executed on server side. The VSPX page itself is an active page which contains XHTML, VSP and widget code. The VSPX page like VSP is a server side executable, so in both cases the virtual directory where pages are placed needs to be executable. For the details of virtual directory setup please read VS-B-1. It might appear that VSPX pages and VSP pages are similar, but in practice there are differences: The content of a VSPX page must be well-formed XML (like XHTML), in contrast to a VSP page where this is not mandatory. VSPX pages have a container element named "page", VSP pages do not (they are processing instruction based). The controls and containers in the VSPX page are in a special name space: "http://www.openlinksw.com/vspx/", we will alias it with the prefix "vspx:" for the controls in the rest of the tutorials. Any active content must be in vspx:page container, and no more than one vspx:page can be in a separate VSPX source file. The VSPX pages are compiled to a more complex structure than VSPs. The processing model of VSPX pages have five phases on execution: initialization, data-binding, post processing, pre-rendering and rendering. VSP only has pre-processing, and execution. For more details please read the VSPX section in the Virtuoso server documentation. The VSPX page may contain one or more controls, VSPs do not have components. Also each control in the VSPX page (and page container itself) represents a user defined type (class). As VSPX pages may contain macros and may have a pre-processing XSL-T transformation, an intermediate file will be generated in the same place where the source page is. Also the compilation will generate a SQL script as a file before compilation of PL code in memory. These files will be explained later in the VX-S-8 example. Finally there are several notes about VSPX controls (widgets). They need to have unique names in the page space, including the macro expanded ones. It is not mandatory for the page name to be unique in the Web server space. All of the controls are represented by trees of class instances, where each member vc_children contains instances to the children controls. Example The example shows a simple page containing a vspx:page container and basic controls: vspx:label, vspx:url and vspx:include. The vspx:page container (as already discussed) can contain any executable content, but it may not be the topmost element in the page as we may see in the source of simple.vspx page. It also shows how VSP processing instructions can be nested in the VSPX page. On that point we need to say that a good VSPX programming style is to use very minimal VSP code to get the benefit of widgets. The rest of the controls used in this example can be placed in any other control or container allowing content. The special case is vspx:include which we will discuss later. The vspx:label is the simplest text label which can be data bound. The "data bound" term designates the ability of the control to obtain a value (it may be constant or Virtuoso/PL expression) on data bind phase when the page gets executed. The format attribute is used to render the data, so it depends on the data type of the control's value. In practice it's a format string as in sprintf() function. In that example the first label has string value and the format is '%s', but second one is integer and the format used is '%d'. The vspx:url represents a HTML anchor, but value and url are data bind-able. We can talk about it as an extended functionality of the vspx:label control. The last one is a vspx:include control. This is not a control per se, it's rather a place where the expanded content of another document will be placed before VSPX page compilation. In that way we can easily re-use common code between different pages. In that particular case the included file is very simple, but it can also be another VSPX page. With this approach VSPX pages have more complex ways to do macro expansions which will be explained in detail in VX-S-8. Generic VSPX form controls Fri, 27 Dec 2019 14:12:54 GMT Scriptable form and form controls Simple form and field validation example The vspx:form control represents scriptable container of a HTML form. It may contains several other controls which are represented below. In the form.vspx example the form contains two vspx:label, two vspx:text and vspx:button controls. In that way vspx:form behaves as control and container, as it may contain other controls and have rendition. The vspx:label controls are shown in that example again to see that these can be used as a child of any vspx: container. Also the values of vspx:label are data bound to the name of control and name of page class. The vspx:text is a text input control which can accept data from user. It may have modifiers which only change appearance from text to password or hidden field. In that example the vspx:text controls are in their default form. The vspx:button control is a generic scriptable button, which originates post events. In practice it renders as a submit button, but with modifiers it can appear as image or link, so in that cases client-side Java scripts are generated to allow posting. The last in that example we should notice is vspx:validator components assigned to the vspx:text fields. These are used to perform server-side validation of data entered by user. So in short the page will display two fields to enter a data, which must be integer numbers. Where the second one must be in the range from 10 to 20. If you enter a different value an error will appear. Check-box example This example presents a scriptable check-box (vspx:check-box) and submit button which is modified to look-like as link. Changing a state of check-box and posting a form will change the value of the label at the bottom. Radio and radio group controls The radio-button and radio-group represented in this example shows usage of radio controls. The main difference in approach is using a container to designate group of radio boxes or to use attribute "group-name" to do that. These are used as a scriptable variant of radio button in HTML. Select list example This example shows the usage of select-list control, which is a VSPX analogue of the select control. Its members must be pre-defined with vspx:item controls which are similar to "option" in HTML variant. Text area example Sometimes a free-form text needs to be entered in a forms, in that case (in HTML practice) textarea is used. In the VSPX world the scriptable variant of it is vspx:textarea. This example shows simple form allowing 50 chars at max to be entered. Inter-field form validation As we noticed in the last and first example we have a vspx:validators to control the user input. But they was per text field. What if we need to check two or more inputs against each other in some order? In that case we can use the form validation. The date.vspx example shows two fields to be filled as date strings. Each filed is tested to be valid date string, and finally if first date is below second the validation will be passed. This is done with validator assigned to the vspx:form control. The default values are initialized to be in incorrect order to see validation on first hit. Data-bound VSPX controls Fri, 27 Dec 2019 14:12:54 GMT Linking a DB data into a VSPX controls Select list initialized from SQL select statement The power of VSPX controls is easy way to bind to a Database objects as tables. In the selectdb.vspx file is shown an easy way to initialize a simple select list from database data. This example shows Products from Nortwind database rendered as select list. The focus on this control is vspx:data-list control. It's initialized with select statement, so the key and value attributes are used to designate what to be used for the drop-down box. Updating a Database table row via VSPX update form Beside showing a data in a form, the database data need to be changed via forms. The most easy way to do that is to use vspx:form with modifier attribute "type" with value of 'update'. The vspx:form[type='update'] used as container of few more elements: vspx:key - binder to a specific row, can be one or more. Usually it's a primary key. Note that this is a not a control, it's a marker in the update form. vspx:template[type='if-exists'] - this is a wrapper class for content to be shown under specific condition. In that case as if-not-exists template is not specified, content of this will be shown in both situations. In other words this example will show content of that template always. The difference will be in value of the fields inside it. vspx:text - it's used to show the data on the row, and accept the data to be updated. These fields have attribute "column" which designate column to be used for data rendition and update. Actually they are inside a template, but logically they are linked to the update form. vspx:button - this is a submit button used to submit the form. The example will: insert a record in Demo.demo.Customers table if CustomerID doesn'y exists will update the CompanyName column if CustomerID is set. Updating a enumerated values in a Database table To run this example we will first need to setup the initial state (using the link beside SQL script, see bellow). This action will cerate a simple table for the next experiment with update form. In some cases we need to enumerate values to the given column in Database table. In this example we will use a vspx:radio-button bound to the column to represent the data value and to allow it's modification to the some degree. (The degree is possible values allowed by group of radio-buttons). In practice we are repeating the previous example but instead using of vspx:text to enter the data , we will use a vspx:radio-button for the second column. The pane at the bottom of demo page shows the result of update, clicking a link of a 'e-id' will load appropriate record to the update form. The button is used to update the data row as in previous example. Simple scroll-able edit-able data grid (vspx:data-set) The most complex control used to view and modify the data in a Database tables is vspx:data-set. This control represents a result set from a SQL select statement as a table (or some other form depending of templates used) and allows scrolling, editing, inserting or deleting a row. In practice it's a combination of scroll-able grid plus one or two update forms. In the example data_set.vspx is shown navigation over Northwind's Customers table. So the following should be noticed in the demo source: The vspx:data-set contains a two simple templates for the header and footer. The middle template is special denoted by "repeat" value of "type" attribute, it's used to render the row in a grid, form to insert, update form in place of a row in a focus and for case of empty result. The repeat template contains four templates for each case as discussed above The template[if-not-exists] will be rendered when no data found The template[edit] will be displayed when edit button is selected The template[add] will be always displayed, if specified The template[browse] is a one per row to show the content on each row The buttons for scrolling as [ds]_next and [ds]_prev must be defined with these suffixes. The above applies to [ds]_edit, [ds]_delete and [ds]_select. In other words some buttons in data-set must have special names. Order Entry Form using VSPX controls Fri, 27 Dec 2019 14:12:54 GMT Order Entry Form Example The form accepts data for entering an order into the demo database. The arguments contain the customer id, item to order and quantity. The web page will take the data and execute a procedure via custom on-post handler. It will display the status of the execution. XForms 1.0 rendering Fri, 27 Dec 2019 14:12:54 GMT Rendering VSPX form controls as XForms 1.0 components Preliminaries The VSPX (Virtuoso Server Pages Extensions) framework allows form controls to be rendered as XForms 1.0 components. This approach take an advantage to check input field's data-type and to restrict value using XML-Schema constraints. Thus it's possible to make user agent performs input validation before sending a data back to server. It's IMPORTANT that this approach is only possible with browsers that have a plug-in or natively supports XForms 1.0. VSPX to XForms input rendering This example works with IE6 or greater with FormsPlayer installed. The example shows turning on the flag for XForms rendering : "connection_set ('RenderXForms', 1)" In the simple form all generic input controls are represented. When submit is performed, data as XML document will be sent back to server and will be prepared on server side as well-known 'params' array. As can be seen the XForms rendering do not require any changes to existing VSPX pages (except logic to turn it on). XML data binding Fri, 27 Dec 2019 14:12:54 GMT Using XML data for VSPX data-binding Preliminaries Usually data-bound controls as data-list, data-set etc. are using a relational data (from tables, local or remote). But in some cases data is available as XML, which is most convenient to use as such instead of filling and using an intermediate table as data source. For this cases VSPX components (which allows data-binding) supports special set of attributes (see documentation for details). With these attributes it is possible to bind XML data to the control's value, row-set etc. Repeatable content based on XML data The following approaches are demonstrated: Binding a XML data to VSPX components, instead of using relational data Using XML manipulation routines to insert update or delete XML data. In details example itself shows: Filling a select list from XML document Filling a repeatable control (data-set) with XML data. Custom ordering functionality in repeatable control, using XML manipulation routines. VSPX tree control Fri, 27 Dec 2019 14:12:54 GMT Directory tree browser Vertical oriented tree To display any data which can be represented as tree hierarchy, the vspx:tree control can be used. In it's forms it may be represented as vertical or horizontal one. The following example show directory structure of the VSPX tutorials on local file system. The vspx:tree control have three important attributes: root - This is a name of PL procedure which must return nodes under root of tree child-function - This evaluated on a node must return children nodes or empty if it's a leaf start-path - This expression or constant is passed to the root function In our example the root and child functions returns a array of strings per directory or file, the '.' and '..' are omitted. In interest also are two special containers and one place-holder: leaf-template - the content of this template will be instantiated and rendered when current position in the tree is a leaf. node-template - this will be instantiated and rendered on nodes, per each node. The place of next node is designated with "node" placeholder. node - place-holder to mark-up place where child content must be instantiated. In that control like as in data-set may have special button suffixed with '[name of tree control]_toggle'. This will be rendered as other submit buttons (in our case it have image appearance), but it will have special function to expand or collapse the branch. VSPX tab control Fri, 27 Dec 2019 14:12:54 GMT Tab desk Example The example presents vspx:tab control. It's used to show simultaneously content of one child container at time. The child container must be vspx:template, they are used to encapsulate other controls. The "style" attribute on "tab" controls designate automatic generation of select list to control switching between templates. In interest is also "initial-active" attribute, this is used to activate one of templates initially. The value of that attribute needs to be the name of the template to be activated on first go. VSPX login control Fri, 27 Dec 2019 14:12:54 GMT Simple login dialog Login example The vspx:login is a special control, it may occur inside VSPX page only once. In it's representation it may be a visual or it may be a hidden depending of intended purpose. The purposes of that control are two: to verify login credentials and to ask user to enter a login. On pages that are authorized the control is hidden, but in case login fails, redirect will be made to a page which will ask for login. Reasonable question is what kind of authorization is supported? The answer is: HTTP Digest, URL poisoning and with Cookies. As Digest and Cookie are not well supported in world of browsers the most effective way is URL poisoning. The attributes on vspx:login control are: mode - designate type of authorization : "digest", "url" or "cookie". In out example it would be the "url" realm - this is a unique string within applications space. This is used to distinguish logins from one application to other. In other words: area of usability of performed login. user-password - name of PL function. This function is used when the mode is "digest". As digest do not send clear-text passwords this is used to retrieve from some source the password on server side. user-password-check - this is PL function which is used to check password for given user. It's used when "cookie" and "url" authorization is performed. In our example the setup script defines both functions: for digest and URL poisoning, so as exercise the type can be changed to "digest" and appropriate attribute to be set. Also please note that digest on Netscape (up to 7.0) or Mozilla browsers will not function properly as they have a defect in digest handling. But anyway on IE5.0 or greater this can be experimented. The following children elements are interesting: template[if-no-login] - the content of it will be displayed when login failed. It may have special attribute "redirect" which will cause redirect to another page. template[if-login] - the content will be shown if request is authorized. login-form - this is a special form to ask user for entering the credentials. It may have defaults, but special content is also possible as in that example. As note we should say that login-form contains special buttons and fields named "username", "password" and "login". These are used to represent custom login form. These must be with the exactly that names. And one vspx:button with special function - "logout", it is used to terminate the current session. The logout button may appear in any place of login control but it's usually in if-login template. Finally we should notice that when login control is used the connection variables and persistent page variables can be used. (for more details see vspx:variable and connection_set () , conenction_get () functions) VSPX browse button control Fri, 27 Dec 2019 14:12:54 GMT Pop-up select list Example This example repeats the VX-S-3(data-set), but it also introduce the vspx:button with special functions browse and select. These buttons are to make inter-page communication, in our case to establish the foreign key relation ship between Products and Categories tables from Northwind demo database. The browse button represents a HTML button which will pop-up the window to make selection. The special attributes selector and child-window-options are used to indicate which link should be used for pop-up and how to display the child browser window. The selector window (child) is also an data-set over Categories table and contains special button with name of data-set control suffixed with '_select'. This is a Java script button which will return back to parent window the selected data and will close the window after selection is made. Both buttons have as children elements vspx:field, these are markers to the buttons which control value and must be used to link both pages. The name attribute of these is the same of the control which needs to be selected or filled with the data. In that way this is a exception of unique names in the page. Please note that both controls instruct VSPX compiler to add client-side Java script functions to maintain functionality. Hence disabling the Java script on browser will made these to stop working. In our example the discussed functionality is demonstrated with buttons Browse in rows to insert and when do an update of products page. Hitting on one of these will pop-up a window to select appropriate foreign key value. VSPX controls Fri, 27 Dec 2019 14:12:54 GMT Collection of VSPX controls Examples All the standard VSPX base controls (including but not limited to buttons, drop-down lists and tab controls etc) are listed in the table below with invocation and source code revealing hyperlinks. The pages source code of each control is optionally vieweable by clicking the filename hyperlink in the "View Source" column. To execute each of these vspx pages click on the "run" hyperlink in the "Action" column. VSPX macros Fri, 27 Dec 2019 14:12:54 GMT Using macro expansion Example In the first example of this section VX-S-1 we mentioned that except vspx:include there is more powerful feature for macro expansion. This feature is explained here. The idea is to have two more source files named style and decoration. They are assigned to the target page via vspx:page attributes "decor" and "style" respectively. The way these are working is the following: before any compilation phase the decor file will be expanded with page itself (see placeholder element). After that the style will be applied and result will be saved in an intermediary file named as original with .vspx-m. As a last step of process would be the page compilation of the intermediary file. This step will generate also a SQL script for page class and it's member functions definitions. The last step of page compilation is execution of the .vspx-sql script and hence creation of objects into the server memory. The example extends the formsty.vspx page with expansion of formdecor.vspx file and make rendition before compilation with formsty.xsl. In that way we can make similar pages with very simple structure, which are with same style and appearance. Also we can divide VSPX page design from functionality. Mapping Requests to Resources Fri, 27 Dec 2019 14:12:54 GMT General information about the virtual host/directory mechanism Listening Interface Concepts A single Virtuoso server can accept HTTP requests on multiple interfaces. Listening interfaces are defined via a virtual directory mechanism (not based on INI setting). Virtual directory operation can be stopped or started without restarting the server engine. The request accepted on a given interface can be processed in a separate Web space. Virtual Host The term Virtual Host refers to the practice of maintaining more than one server on one machine, as differentiated by their apparent host name. For example, it is often desirable for companies sharing a web server to have their own domains, with web servers accessible as www.company1.com and www.company2.com, without requiring the user to know any extra path information. The Virtual host can be IP-based or non-IP. The IP-based (named in this document as multihosting) refers to the practice of making one machine listen on different interfaces and respond with different pages. The non-IP (named virtual hosting) refers to the practice where one machine is allocated more than one DNS alias. The web content served can then be based on the alias that the client contacted, as identified by the 'Host' HTTP header field. A single Virtuoso server can map requests into multiple spaces of web pages based on the interface to which the requests come (multihosting) or on the Host HTTP/1.1 header (virtual hosting). A single physical interface can map multiple virtual hosts. The virtual host name must be defined also in Domain Name Server as an alias of the official host name. Attributes Logical Path - The path part from URL which user-agent wants. Mapped Path - Defacto location of requested Web resource. Is in DAV - The Virtuoso server has space for Distributed Authoring & Versioning (DAV see: rfc2518 for details) under "/DAV" URL. The logical path can me mapped in to this space. Default page - The name of page or resource on Web server to show if a directory/folder is requested. It applies to the entire subdirectory tree. Is browseable - If no default page specified or page does not exist, then show directory content. Warning: This setting can raise security problems, because all directory content will be shown. Security The Web server has access to the file system directory (see ServerRoot INI setting) using the privileges of the user who is running it. Access to the WebDAV repository can be restricted to only special accounts, as each resource/folder can have different permissions applied. Execution in a mapped path can be enabled/disabled. Basic and Digest HTTP authentication schemes can be used. HTTPS listeners can be started. User-agent's certificate can be requested and checked. Authentication Function An application dependant PL function for HTTP authentication can be defined for each path mapping. The authentication function can be used to restore session variables. The built-in authentication functions can be used. Request Postprocessing Function An application dependant PL function can be defined for each path mapping to store the session variables (in session table). Database User Accounts for execution of active content Database User Account for VSP: For each path mapping, a different Database account can be supplied. The VSP will be executed on behalf of this account. Database user account for SOAP: For each path mapping, the SOAP calls can be assign to a different Database account. The WSDL schema will show only PL procedures granted to this account. Example Listen host & Virtual host mappings It is possible to have a mapping in the file system /www1/ for http://www.a.com/ requests. In this case we will specify the listen host www.a.com (the port default is 80), logical path / and physical location /www1/. In some cases more than one web server is needed on the same machine. A second DNS alias www.b.com can be routed to the www.a.com. A mapping for this alias can then be: listen host is again www.a.com but virtual host is www.b.com and physical location can be a /www2/ under HTTP root directory. When a User-Agent requests the http://www.b.com/ it will send a 'Host' header field, in this field value will be 'www.b.com'. The web server will find a second map and will try to process the pages under /www2/. Finding the closest applicable mapping Its possible to define more than one mapping for one virtual/listen host combination. In this case the closest match to the request is used. For example with the following mappings: Logical PathPhysical Path www.a.com//www/a www.a.com/a/www/b Gets the following mapping: RequestPhysical Path http://www.a.com/a//www/b http://www.a.com/other/www/a/other The Web server will find the closest path match when processing the logical to physical mapping. Examples of Mapping Fri, 27 Dec 2019 14:12:54 GMT Creating a virtual directory with default page Preliminaries The virtual path can be defined to have a default page. The default page will be displayed if no file is requested. Sub directories of the defined mapping, inherit the default page name mapping. The particular URL can be retrieved with integrated HTTP client as a string. The integrated HTTP client can be invoked with the http_get() function. Example description This example defines a virtual directory with a default dynamic page. A URL is prompted for. If it is found then the header and content is loaded and displayed. An error is reported if the URL cannot be found. Examples of Mapping Fri, 27 Dec 2019 14:12:54 GMT Creating a virtual directory to proxy to another server Preliminaries The Virtuoso Web server can act as a proxy server for HTTP requests. If request from a user-agent is a proxy request, then the Web server will try to retrieve the URL, and will send the response and entity body back to the user-agent. The virtual directory mapping can be setup when physical location is a Web server. The local URL will then be treated by the Web server as a proxy request. Login to the Conductor UI using the dba account. Example virtual directory setup to another HTTP server Go to "Web Application Server" tab and then go to the "Virtual Domains & Directories" tab. From the given list of HTTP Hosts click the icon infront of the Interface value. Click the "Add new directory" link. Choose the "Proxy server" type and press the button "Next>>". Enter "/proxy" for Virtual directory path, "http://[desired_host:port]/" for Proxy to, and then press the "Save Changes" button. To test the new directory: enter the "http://your_host:port/proxy" in browser. If all is ok, the content of the web tutorial directory is shown. Equivalent SQL commands to above Connect to the Virtuoso server via ISQL utility as DBA user. Create the virtual directory with physical path "http://host:port/" SQL> vhost_define (vhost=>'*ini*',lhost=>'*ini*',lpath=>'/proxy',ppath=>'http://host:port/'); Examples of Mapping Fri, 27 Dec 2019 14:12:54 GMT Setting up a Secure Directory Preliminaries Space on the Web server can be explicitly mapped for SSL (HTTPS) connections. To start HTTPS listener, the server needs a valid certificate and private key pair. Using the Virtual Directories UI Login to the Conductor UI using the dba account. Go to "Web Application Server" tab and then go to the "Virtual Domains & Directories" tab. In the empty fields below the list of HTTP Listeners enter: In the "HTTP Host" field the qualified name of the host. In the "Interface" field the qualified name of the interface to listen to. In the "Port" field the port number to listen on. Press the "Add" button. Define the HTTP root location of this host. The root location can be mapped in file system, DAV or proxy server. In this example we will define a map in filesystem. Click the icon in front of the Interface value. Click the "Add new directory" link. Create a "/ssl" directory under the HTTPServer ServerRoot directory. This directory will be used to create the new mapping. Choose the "File System" type and press the button 'Next>>'. Enter for "Path" "/ssl" and enter "/ssl/" (or select this directory with "Browse" button) in the "Physical path" location. If you wish to make entire site to be executable specify the VSP user. (See also: VS-B-1 example) Select the "SSL" as "Security method" Enter for authentication options the files for the certificate and the private key of the server https_cert=PATH_TO_THE_CERTIFICATE; https_key=PATH_TO_THE_PRIVATE_KEY; Press the "Save Changes" button. If needed, more path mapping can be added to that defined. To test the definition enter http://[yourhost:port]/ in location box of your browser. Equivalent SQL commands for above Connect to the Virtuoso server via ISQL utility as DBA user. Define a virtual directory mapping for the host alias: SQL> vhost_define (vhost=>'[yourhost]:4333',lhost=>'[yourhost]:4333', lpath=>'/',ppath=>'/ssl/', def_page=>'index.html', is_brws=>1, sec=>'SSL', auth_opts=>vector ('https_cert','PATH_TO_THE_CERTIFICATE', 'https_key','PATH_TO_THE_PRIVATE_KEY')); Note that in the sample SQL script, 'localhost' is used instead of 'yourhost'. This MUST be replaced with the official host name. Also needs certificate an private keys to be in place, before trying this example; PATH_TO_THE_CERTIFICATE and PATH_TO_THE_PRIVATE_KEY MUST be replaced with actual path to these files. Examples of Mapping Fri, 27 Dec 2019 14:12:54 GMT Using the HTTPS client certificates Preliminaries The Web server can be setup to check the HTTPS client certificate The HTTPS client must have installed a X.509 certificate. Using the Virtual Directories UI Login to the Conductor UI using the dba account. Go to "Web Application Server" tab and then go to the "Virtual Domains & Directories" tab. In the empty fields below the list of HTTP Listeners enter: In the "HTTP Host" field the qualified name of the host. In the "Interface" field the qualified name of the interface to listen to. In the "Port" field the port number to listen on. Press the "Add" button. Define the HTTP root location of this host. The root location can be mapped in file system, DAV or proxy. This example uses the filesystem. Create a "/ssl_cv" directory under the HTTPServer ServerRoot directory. This will be used for the new mapping. Click the icon in front of the Interface value. Click the "Add new directory" link. Choose the "File System" type and press the button 'Next>>'. Enter for "Path" "/ssl_cv" and enter "/ssl_cv/" (or select with "Browse" button this directory) in the "Physical path" location. If you wish to make entire site to be executable specify the VSP user. (See also: VS-B-1 example) Select the "SSL" as "Security method" Enter for authentication options the files for the certificate and the private key of the server: https_cert=PATH_TO_THE_CERTIFICATE; https_key=PATH_TO_THE_PRIVATE_KEY; https_cv=PATH_TO_THE_CA_LIST; https_cv_depth=2; Press the "Save Changes" button. If needed, more path mapping can be added to the defined. To test the definition enter http://[yourhost:port]/ in location box of your browser. Equivalent SQL commands for above Connect to the Virtuoso server via ISQL utility as DBA user. Define a virtual directory mapping for the host alias: SQL> vhost_define (vhost=>'[yourhost]:4334',lhost=>'[yourhost]:4334', lpath=>'/',ppath=>'/ssl_cv/', def_page=>'index.html', is_brws=>1, sec=>'SSL', auth_opts=>vector ('https_cert','PATH_TO_THE_CERTIFICATE', 'https_key','PATH_TO_THE_PRIVATE_KEY', 'https_cv', 'PATH_TO_THE_CA_LIST', 'https_cv_depth', 1)); Note that in the sample SQL script, 'localhost' is used instead of 'yourhost'. This can be replaced with the official host name. Examples of Mapping Fri, 27 Dec 2019 14:12:54 GMT Multiple interfaces setup Preliminaries The Web server can listen on multiple physical interfaces. Requests for each interface can be dispatched to a separate directory. Using the Virtual Directories UI Login to the Conductor UI using the dba account. Go to "Web Application Server" tab and then go to the "Virtual Domains & Directories" tab. In the empty fields below the list of HTTP Listeners enter: In the "HTTP Host" field the qualified name of the host. In the "Interface" field the qualified name of the interface to listen to. In the "Port" field the port number to listen on. Press the "Add" button. Create a "/www2" directory under the HTTPServer ServerRoot directory. This will be used for the new mapping. Click the icon in front of the Interface value. Click the "Add new directory" link. Choose the "File System" type and press the button "Next>>". Enter for "Path" "/www2" and enter "/www2/" (or select with "Browse" button the same directory) in the "Physical path" location. To give execute permission, specify the VSP user. (See also: VS-B-1 example) Press the "Save Changes" button. Repeat this setup for another interface, directing to a different path (for example WebDAV repository). Testing the Virtual Directories To test the definition enter http://[first_interface:port]/ in location box of your browser. After this try http://[second_interface:port]/ Note that you may test this using official host name and localhost. The local loopback is also a possibility for a second interface. Equivalent SQL commands for above Connect to the Virtuoso server via ISQL utility as the DBA user. Define a virtual directory mapping for the host alias: SQL> vhost_define (vhost=>'[first interface]:4444',lhost=>'[first interface]:4444', lpath=>'/',ppath=>'/www2/', def_page=>'index.html', is_brws=>1); SQL> vhost_define (vhost=>'[second interface]:4444',lhost=>'[first interface]:4444', lpath=>'/',ppath=>'/DAV/', is_dav=>1, def_page=>'index.html', is_brws=>1); Control of the Web Request Log Fri, 27 Dec 2019 14:12:54 GMT HTTP requests logging Preliminaries It is possible to log HTTP requests. The log file can be analyzed with the Conductor UI, such as the Analog utility, going to the "System Admin" tab, then to the "Monitor" tab and then to the "Log Viewer" sub-tab. HTTP logging is enabled by setting the HTTPLogFile parameter in the [HTTPServer] section of the database INI file. The HTTPLogFile must be set to the path of the HTTP server log. For example: [HTTPServer] .... HTTPLogFile = ./http.log .... Log file format CLIENT_IP AUTH_TYPE AUTH_ID [DD/MMM/YYYY:HH:MM:SS +ZZZZ] "HTTP REQUEST" HTTP_RESPONSE CONTENT_LENGTH Here is an example: 127.0.0.1 Basic test_user [02/May/2001:11:05:25 +0200] "GET / HTTP/1.0" 200 2186 Basics Fri, 27 Dec 2019 14:12:54 GMT Introduction to HTTP session management Preliminaries The HTTP protocol does not define a session management To make a HTTP session few options are possible: To set a cookie, but this feature is not supported in all browsers. To use the opaque value of the digest authentication, it is also not supported in all user-agents The most common way for doing this is to pass an URL variable (http://host:port/path?variable=value) to keep the session id; this is usually named "URL-poisoning". The Virtuoso HTTP session management consists of functions for session variables manipulation and an ability to define a pre- and post-processing function. Also there is pre-defined table WS.WS.SESSION, which could be used in various applications to keep session data. There are special functions to store/retrieve/restore a variables into the memory. These can be used to persist/restore the session variables. For more details see: Session Management section in Virtuoso HTTP Server documentation. Session Table The Virtuoso server offers a built-in session table. Application developers can also use their own table. CREATE TABLE WS.WS.SESSION ( S_ID varchar, -- session id S_EXPIRE datetime, -- when it expires S_VARS long varchar, -- serialized value of session variables S_REQUEST_UNDER_RELOGIN long varchar, -- serialized value of request status upon re-login detected S_REALM varchar, -- authentication realm S_IS_DIGEST integer, -- flag for digest authentication S_DOMAIN varchar, -- authentication domain S_NONCE varchar, -- nonce value S_OPAQUE varchar, -- opaque value S_STALE varchar, -- stale value S_QOP varchar, -- qop value S_ALGORITHM varchar, -- algorithm name S_NC integer, -- nonce count primary key (S_REALM, S_ID)) Session Table handling To set, clear, or preset the in-memory based session table, the following functions are available. connection_set() - sets the connection variable. connection_get() - get a connection variable state. connection_vars() - get all connection variables. connection_vars_set() - clear and set the session variables. connection_is_dirty() - indicate state of the session variables (whether changed during the session). Common Web application framework The next examples demonstrates this three techniques for passing the session id to the VSPs Every application have a startup page with links to login and register a new account Once registered or logged in, the user will be redirected to the default page, that retrieves a session and variable increase it. Also they have a authentication hook and post processing hook. These PL hooks are used to restore and save respectively the session variables. The sessions are kept in the WS.WS.SESSION table. Note that not all columns are used in particular application. The full set of columns are used only in session with digest authentication example. Basics Fri, 27 Dec 2019 14:12:54 GMT Url poisoning example The default URL poisoning scheme There is an authentication function that restores the session variables from a session table. There is a post processing function to save the session variables into a session table. An authentication function will try to get a URL parameter named "sid", if there is a session table row corresponding to it. The state of session variables is read into memory with connection_vars_set(). The post processing function updates the session table, saving all session variables available with connection_vars(). Example Description Using the built-in session table this web application saves the state between sessions. It has a front page with a two links "register" and "login". The register page will ask for the user id and for a password. The login page will ask for user id and password which are checked against an application dependant users table. Both pages will do a redirect message with the newly generated session id, to the default application page. The application pages (except front, login and register pages) can be placed under a separate directory. The directory containing the VSP application must be setup as executable with authentication and post processing hooks defined. The redirection to the application pages is made with URL parameter "sid" (the session id). The session id must be transferred between pages for the restoration of session variables. Each load of the default application page will restore the session variables, and will display the number increased by one. If the session expires, a redirect to the login page will be performed. Step by step overview The following sections describe the complete set of steps to make the application work. Most of this details also apply to the cookie and digest examples. Authentication hook The authentication hook will get the 'sid' parameter using the get_keyword(). If there is no row in the session table, it redirects to the login page. If a row exists, then increase the expiry time, and restore the session variables with connection_vars_set(). If the authentication hook gets a 'logoff', then the session record is removed from the session table. The browser is redirected to the login page. Post processing function The 'sid' is read from session variables using connection_get(), as this is faster than from the URL parameters. Check for change of the session variables with connection_is_dirty(). If there is a change then serialize and store them into the session table. All variables are read with connection_vars(). At the end of the post-processing hook clear the in-memory variables to avoid reading from other HTTP client by using connection_vars_set(null). Login, Default & Registration pages The login page will check user & password against user-defined table (APP_USER) and if it matches, the new session will be created. When starting a new session, the 'sid' connection variable is also setup to be available in the post-processing hook. After a new session is done, there is a redirect using the header 'Location' to the default page. Note the Location URL contains the 'sid' parameter' (see line 61 of vs_u_2.sql) When the default page is called the authentication hook is already executed and session variables are in memory. Therefore it is only necessary to get with connection_get() and set (if needed) with connection_set(). In this example, there is a 'ctr' variable that is a counter. It increases with each page reload. The logout link passes another URL parameter 'logoff', this is also handled in the authentication hook. Basics Fri, 27 Dec 2019 14:12:54 GMT Cookie example Preliminaries The cookies can be used to keep session id between two HTTP requests. If the target browser can work with cookies, this method can be used instead of URL poisoning. Session state in a cookie example On login or register, the set-cookie header writes a new session id. The authentication function extracts the cookie value from the HTTP header. If the session id is not valid, then the browser is redirected to the login page. The post processing function is the same as in URL poisoning example. Basics Fri, 27 Dec 2019 14:12:54 GMT Digest example Preliminaries The Digest HTTP authentication can have the attributes kept between sessions. If the target browser supports the Digest authentication, the opaque attribute can be used for the session id. The Virtuoso server has a predefined authentication hook for digest authentication. Digest authentication is held in WS.WS.DIGEST_AUTH. Basics Fri, 27 Dec 2019 14:12:54 GMT SSL example Preliminaries The Virtuoso Web server can be set up for HTTPS listening, for increased security. Passing the session id as a cookie or a URL parameter over HTTP connection is not secure. Example This example uses the most common URL poisoning over SSL connection. This example repeats the example VS-U-2, but result of VSP pages is transferred over SSL. Make sure that files containing server certificate/key data exists in the server working directory. The following files are required for the example: virtuoso_cert.pem - server certificate virtuoso_key.pem - server private key The example script defines and starts a HTTPS server on port 4333. Exercises Fri, 27 Dec 2019 14:12:54 GMT How to maintain a cursor state Cursor state examples These examples have a scrollable page for browsing user records. Each uses a PL scrollable cursor, and keeps the bookmark in the session state. Data is taken from the demo database tables. These examples demonstrate static, keyset and dynamic cursors. Using XSLT to Format Output Fri, 27 Dec 2019 14:12:54 GMT Using XSLT to Format Output Example This example renders XML with XSLT, and demonstrates the following: Shows the style sheet in a database table as well as in the file system. Shows use of the http_xslt() function to process XML with an XSL. Resolving the stylesheet reference, e.g. virt://, DAV resident sheets. Changing the stylesheet and when the sheet changes it is automatically detected. Affecting the output character set. Specifying parameters to the output xslt run. Using XSLT to Format Output Fri, 27 Dec 2019 14:12:54 GMT Using XSLT to Format Output XSLT Example This example uses an XSLT to customize a view of a table. The XSL demonstrates xsl:output to create the output. The http_xslt() does not make the XSL-T transformation. It only registers the content as XML such that when the document is requested by the client, the server will transform it with XSL-T. Example explained string_output () - creates a string session. select ... for xml auto element - Is the SQL/XML query over target table(s). xml_auto() - This executes the above query, and stores the resultant XML document (entities) in the string session allocated by string_output(). string_output_string() - converts the string session to 'normal' string. http_xslt() - defines the XSL-T stylesheet for transformation of the XML content, which is stored in internal string session of the Web server. Using xslt() in VSPs Fri, 27 Dec 2019 14:12:54 GMT An alternative of the http_xslt() Example This example displays user data using XSLT to customize the look. The result is the same as in VS-X-2, but XSL-T transformation is done in the VSP. The http_xslt() can be replaced (for main functionality) by the following: xml_tree_doc() over an XML document xslt() with XSL-T stylesheet URI and result from xml_tree_doc() http_value() with result from xslt() The above describes the steps that the web server makes in the VSP execution when http_xslt() is called. This is not a direct equivalent, because Content-Type is not manipulated, as it is with http_xslt(). This means that web server can setup a Content-Type if it's not specified, otherwise it is specified in xsl:output element. The same is true for encoding. If it is necessary to manipulate content-type with xsl:output, then use xml_tree_doc_media_type() to retrieve the media type from the XML entity, produced from xml-tree_doc(), and manually set 'Content-Type' header with http_header(). The above steps are useful for VSP&XSLT understanding, but in practice the http_xslt() is more suitable. The http_xslt() is most appropriate if all content that produces a VSP should be transformed. In the case where a piece of XML data is to be inserted in the middle of the HTML part of VSP, it cannot be done with http_xslt(). It may only be done with the step-by-step way above. DAV Security Model Fri, 27 Dec 2019 14:12:54 GMT DAV Maintenance & Security Preliminaries A resource has a group and an owner user, just like files in a Unix file system. A resource has flags determining the read, write, and execute privileges of it's owner, other members of the owner's group, and all other users on it. Additionally it has a free text indexing flag. Collections are resources also. These have the same flags but the free text index flag is treated differently. DAV server asks for authentication in the following situations: on the read operation if URL is not public readable on the write operations if URL is not public writable The read operations are GET, POST, PROPFIND, HEAD The write operations are LOCK, PUT, MOVE, COPY, DELETE, PROPPATCH The Webdav admin account has full access rights to the Webdav repository, regardless of privilege flags. The server will try to match the user to resource owner, second match to the group ownership, and last to the additional groups membership. If the URL is public readable, the request will be processed without asking for authentication. The special flag in permissions can be set to the no-index, index, index recursively. On resources, the last two settings act in the same way: if the resource is a text document, the content will be free text indexed, otherwise not. On collections, the 'no-index' will stop indexing of all direct and indirect members. The 'index this' flag will cause indexing only over direct members (resources). The 'index recursively' will allow free-text indexing of all direct and indirect members. The values indicated in the WebDAV content management UI are N, T and R for the no-index, index, index recursively respectively. DAV Properties Fri, 27 Dec 2019 14:12:54 GMT DAV properties - PROPFIND and PROPPATCH DAV properties Every collection resource has standard (computed) properties, and can have user-defined properties. Computed Properties The computed properties are set by DAV server. The user-agents do not handle it. The computed resources are in the DAV name space. The computed properties are: creationdate (#PCDATA) - when created getcontentlength (#PCDATA) - length of the content getcontenttype (#PCDATA) - mime type of the content getetag (#PCDATA) - Etag of the resource getlastmodified (#PCDATA) - when the resource is modified lockdiscovery (activelock)* - active lock information resourcetype ANY - type of the resource (applicable only for collections) supportedlock (lockentry)* - what lock supported User Defined Properties For other application specific purposes the PROPPATCH request can be used to set other properties. The Virtuoso WebDAV server process by special way the following properties. xml-sql - text of the SQL query to produce an XML document. xml-sql-root - the root element name of the produced XML document. xml-stylesheet - the URL of the associated XSL-T style-sheet. xml-sql-dtd - the external DTD link or 'on' in case of inline DTD. xml-sql-schema - the external XMLSchema link. xper - persistent XML storage. Property handling If an XML document has a property xml-stylesheet, then the retrieved content will be transformed and sent instead of the original document content. The xml-sql and xml-sql-root work together. If the resource has these properties, and the content length is 0, then WebDAV server will execute the SQL query (see xml_auto()), and the generated XML document will be sent to the user-agent. If no xml-sql-root is associated, then the root element will be defaulted to the 'document'. The xper property signals to the server that each member of the collection must be stored as XML persistent. If the xper property is removed from a collection, then each currently stored persistent XML document will revert to a normal text/xml at the next update. Each xper property will be removed. Example PROPFIND Request PROPFIND /DAV/images/davadmin.jpg HTTP/1.1 Host: localhost:6666 Content-Type: text/xml Depth: 1 Content-Length: 269 Authorization: <?xml version="1.0" encoding="utf-8"?> <propfind xmlns="DAV:"><prop> <getcontentlength xmlns="DAV:"/> <getlastmodified xmlns="DAV:"/> <displayname xmlns="DAV:"/> <executable xmlns="http://apache.org/dav/props/"/> <resourcetype xmlns="DAV:"/> </prop></propfind> Response HTTP/1.1 207 Multi-Status Server: Virtuoso Content-type: text/xml; charset="utf-8" Content-Length: 652 <?xml version="1.0" encoding="utf-8"?> <D:multistatus xmlns:D="DAV:"> <D:response xmlns:lp0="DAV:" xmlns:i0="DAV:"> <D:href>/DAV/images/davadmin.jpg</D:href> <D:propstat> <D:prop> <lp0:getcontentlength>5725</lp0:getcontentlength> <lp0:getlastmodified>Mon, 14 May 2001 13:26:54 GMT</lp0:getlastmodified> <D:resourcetype/> </D:prop> <D:status>HTTP/1.1 200 OK</D:status> </D:propstat> <D:propstat> <D:prop> <i0:displayname/> <i0:executable/> </D:prop> <D:status>HTTP/1.1 404 Not Found</D:status> </D:propstat> </D:response> </D:multistatus> Example PROPPATCH Request PROPPATCH /bar.html HTTP/1.1 Host: www.foo.com Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:propertyupdate xmlns:D="DAV:" xmlns:Z="http://www.w3.com/standards/z39.50/"> <D:set> <D:prop> <Z:authors> <Z:Author>Jim Whitehead</Z:Author> <Z:Author>Roy Fielding</Z:Author> </Z:authors> </D:prop> </D:set> <D:remove> <D:prop><Z:Copyright-Owner/></D:prop> </D:remove> </D:propertyupdate> Response HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:" xmlns:Z="http://www.w3.com/standards/z39.50"> <D:response> <D:href>http://www.foo.com/bar.html</D:href> <D:propstat> <D:prop><Z:Authors/></D:prop> <D:status>HTTP/1.1 424 Failed Dependency</D:status> </D:propstat> <D:propstat> <D:prop><Z:Copyright-Owner/></D:prop> <D:status>HTTP/1.1 409 Conflict</D:status> </D:propstat> </D:response> </D:multistatus> DAV Properties Fri, 27 Dec 2019 14:12:54 GMT SQL/XML documents in DAV Preliminaries The SQL query can be transformed into an XML document with xml_auto() for example. The SQL/XML documents are automatically generated resources, based on a SQL query. Two types of SQL/XML documents can be defined in the WebDAV repository: Persistent documents and Immediate transformation. Persistent Documents The persistent SQL/XML documents have the same behavior as text/xml documents: They have a mime type of text/xml, and have a content. The content can be refreshed with a scheduled event. The content is free-text indexed Immediate Transformation The SQL/XML documents with immediate transformation are formed as they are requested. The content is empty Hence the content is not free-text indexed Properties Both resources have a property xml-sql. The value of the property is the SQL query string. If content length is zero and the xml-sql property is set, then the server will do an immediate transformation. Both resources have xml-sql-root, xml-sql-dtd, and xml-sql-schema properties (see also vs-d-2). SQL/XML resource example The example SQL script creates a few SQL/XML resources. Click here for resources made in /DAV/vs_d_3/ DAV Special URI's Fri, 27 Dec 2019 14:12:54 GMT DAV Special URI's WebDAV parameters The WebDAV server has the following special URL parameters: XPATH - the XPATH query to perform against the existing XML document set_tag - the root XML element (default is 'document') result_tag - the elements tag Preparation This example uses the SQL/XML documents generated by VS-D-3. Example with result_tag From within a browser do an XPATH query for a subset of attributes. Use the following URL: http://host:port/DAV/vs_d_3/URLMultiTable.xml?XPATH=/root/Customers/@CustomerID&result_tag=id Or click this relative link. Expected result with result_tag For browsers such as Opera and Netscape, view the source of the result page to see the XML. For browsers capable of rendering the XML, such as Internet Explorer 5+, the XML result will be shown. This excerpt from the expected output shows the xml document containing the CustomerID only: <?xml version="1.0" encoding="ISO-8859-1"?> <document> <id> ALFKI</id> <id> ANATR</id> <id> ANTON</id> <id> AROUT</id> <id> BERGS</id> <id> BLAUS</id> <id> BLONP</id> <id> BOLID</id> <id> BONAP</id> ... </document> Example with set_tag Similar to previous example, but replacing result_tag with the set_tag parameter. Enter this URL into a browser: http://host:port/DAV/vs_d_3/URLMultiTable.xml?XPATH=/root/Customers[@CustomerID+like+'A*']/@CustomerID&set_tag=id Or click this relative link. Note: the XPATH queries can only be performed against the persistent storage. Expected result with set_tag <?xml version="1.0" encoding="ISO-8859-1"?> <id> ALFKIANATRANTONAROUT</id> Example with set_tag and result_tag Similar to previous example, but adding result_tag parameter. Enter this URL into a browser: http://host:port/DAV/vs_d_3/URLMultiTable.xml?XPATH=/root/Customers[@CustomerID+like+'A*']/@CustomerID&set_tag=id&result_tag=p Or click this relative link. Note: the XPATH queries can only be performed against the persistent storage. Expected result with set_tag and result_tag <?xml version="1.0" encoding="ISO-8859-1"?> <id> <p> ALFKI</p> <p> ANATR</p> <p> ANTON</p> <p> AROUT</p> </id> DAV Free Text Index Fri, 27 Dec 2019 14:12:54 GMT DAV Free Text Index : general Real time index mode The WebDAV content is free-text indexed on all documents with a text content. The documents may have their indexing disabled by turning off the indexing flag. (see DAV security) By default the WebDAV content is in real time mode. That means after insert/update/delete the content immediately will be indexed. The real time mode will update the free text index as soon as the indexed resources change. Advantage is that a text search query can be performed immediately after an action. This will however take substantially longer if any significant number of resources are regularly updated. Batch Mode indexing In this mode, changes of the WebDAV content are logged for later indexing. The index is updated periodically, at approximately the specified period (in minutes), if allowed by other background tasks. The index refresh period is a scheduled event period to refresh the free-text index in batch mode. To switch between modes in the Conductor UI, go to the "Web Application Server" tab, then go to the "Content Management" tab and then go to the "Text Triggers" sub-tab. This can also be achieved using a sql command. For example to turn batch mode on for 7 minute updates use: SQL> DB.DBA.vt_batch_update ('WS.WS.SYS_DAV_RES', 'ON', 7); Example The demonstration allows the mode to be switched. Resource content can be created and tested. Content Types and Names Fri, 27 Dec 2019 14:12:54 GMT Mapping between resource content types, and name extensions Preliminaries The user-agents (browsers) may supply the content-type for an uploaded resource. A resource in the WebDAV repository can have a supplied content-type associated to the resource. If the content type is not supplied, the WebDAV server does a mapping from file extension to mime type. Mapping table is held in WS.WS.SYS_DAV_RES_TYPES and used by http_mime_type() function. Using Conductor UI can be defined additional MIME type: Go to the "Web Application Server" tab, then go to the "Content Management" tab and then go to the "Resource Types" sub-tab. Here press the "Create New Type" button. Mime lookup example The example requests a file, then the name of the file will be matched against the mime types table. The resulting mime type is displayed. DAV Tables Fri, 27 Dec 2019 14:12:54 GMT Complete description for all DAV tables DAV Tables The WebDAV DB schema is detailed in the vs_d_7.sql that creates each table. The schema is available from a shipped database, as it is automactically generated if it does not exist. Exercises Fri, 27 Dec 2019 14:12:54 GMT Simple DAV Report Generation Example of making XML reports in DAV The example makes XML reports on the Demo database and inserts them into a user's DAV folder. The application will take a user registration, and make a DAV account Enter parameters for a query, e.g. product group for tracking sales A resulting XML report is put in the user's created DAV collection. Once the report is made a HTTP redirect occurs to the new resource. Note that the login for DAV will be different from the application's login. This is OK in this context. Control Web server threads Fri, 27 Dec 2019 14:12:54 GMT Web server threads monitor Preliminaries The HTTP requests are processed by HTTP server threads. The HTTP threads are configurable in the INI file. Hence they are a limited number. A VSP execution can run in the background by using http_flush(). Pending HTTP requests can be monitored (including the background tasks). Pending HTTP requests can be aborted with http_kill(). Thread killing example Run the long_task.vsp to start a thread that takes a long time. This will start another thread to run vs_c_1_sample_1.vsp All pending tutorial HTTP requests will be listed. The long_task thread can then be killed by using the link. Importing Web Content Fri, 27 Dec 2019 14:12:54 GMT Importing Web Content Importing Web Content Default traversal algorithm of the web robot. Keep into the queue only the start link Get the oldest entry from the queue (for the given target) and mark as 'pending' Retrieve the link Parse the page and extract the URLs Apply the "Traverse and do not traverse" rules Insert the new entries in the queue Mark queue entry as 'retrieved' Repeat from step 2, if there are more 'waiting' entries, otherwise finish Traverse and do not traverse links Traverse - this is a semicolon separated string which contains the path masks (the like predicate chars are applicable). Any link that matches any of these masks will be added to the queue for processing, but only if it doesn't match the do not traverse masks. Do not traverse - the format of the string is the same (semicolon separated), but the masks mean the opposite. If any link matches the rule it will be skipped from processing. Tables of the Web Robot -- Target site definition create table WS.WS.VFS_SITE ( VS_DESCR varchar, -- human readable description VS_HOST varchar, -- target host name VS_URL varchar, -- start URL path VS_INX varchar (5),-- reserved VS_OWN integer, -- local WebDAV owner of the retrieved content VS_ROOT varchar, -- local WebDAV collection destination VS_NEWER datetime, -- update only newer than (this date) VS_DEL varchar, -- delete local resource if removal on target detected VS_FOLLOW varchar, -- walk on this links VS_NFOLLOW varchar, -- do not walk on this links VS_SRC varchar, -- retrieve images VS_OPTIONS varchar, -- if target wants authentication the uid/pwd are stored VS_METHOD varchar, -- use WebDAV or traditional HTTP method VS_OTHER varchar, -- walk on foreign links primary key (VS_HOST, VS_ROOT)); create index VS_HOST_ROOT on WS.WS.VFS_SITE (VS_HOST, VS_URL, VS_ROOT) ; -- Queue table create table WS.WS.VFS_QUEUE ( VQ_HOST varchar, -- target host name VQ_TS datetime, -- date and time of adding into the queue VQ_URL varchar, -- target URL path VQ_ROOT varchar, -- local WebDAV folder destination VQ_STAT varchar (15), -- status VQ_OTHER varchar, -- retrieved from other site primary key (VQ_HOST, VQ_URL, VQ_ROOT)); create index VQ_HOST_ROOT_STAT on WS.WS.VFS_QUEUE (VQ_HOST, VQ_ROOT, VQ_STAT); create index VQ_HOST_ROOT on WS.WS.VFS_QUEUE (VQ_HOST, VQ_ROOT); create index VQ_HOST_TIME on WS.WS.VFS_QUEUE (VQ_HOST, VQ_ROOT, VQ_TS); create index VQ_TS on VFS_QUEUE (VQ_TS) ; -- Retrieved URLs table create table WS.WS.VFS_URL ( VU_HOST varchar, -- target host name VU_URL varchar, -- retrieved URL path VU_ROOT varchar, -- local WebDAV folder destination VU_CHKSUM varchar, -- content checksum VU_ETAG varchar, -- target's ETag VU_CPTIME datetime, -- retrieval date and time VU_OTHER varchar, -- retrieved from other site primary key (VU_HOST, VU_URL, VU_ROOT)); create index VU_HOST_ROOT on WS.WS.VFS_URL (VU_HOST, VU_ROOT) ; Hooks for Parametizing the Web Robot The custom queue hook can be used to extract next entry from the robot's queue and follow a custom algorithm. The prototype of the hook is: create procedure DB.DBA.VFS_HOOK (in host varchar, in collection varchar, out url varchar, in data any) { -- choose an entry from queue (may use the user-specific date passed as 'data' variable) -- mark as 'pending' -- set the 'url' from the chosen entry -- return 1 on success or 0 if no more entries } ; Web Index Example Example does a breadth first traversal of all reachable sites. To actually get some links retrieved change all the occurences of www.foo.bar to a site of your choice. The site to process are separately maintained in an 'interesting sites' list. The example runs on multiple threads. The interface can start n threads running the robot. There is a web page showing the running status, e.g. number of pages fetched in the last minute. A stop button will kill http threads running the web robot. Important: The example requires a license to run, due to multiple web threads. Blog application Fri, 27 Dec 2019 14:12:52 GMT Blog application Overview The application allow users to post messages to a Weblog servers using XML-RPC protocol. It can work locally where as server is used one running the application. Also it demonstrate usage of VSPX calendar, dataset and login controls. The demo also shows usage of blogger API. Application pages The application has the following pages: Login This page allow existing Web users to login to the application. Furthermore these credentials will be used to authenticate against Weblog server. When user is authenticated the request will be redirected to the home page. Configuration This page is accessible via "Settings" link of home page (see below). It allows users to configure parameters for blogger API request as "appkey", "blogID" and target server endpoint. It's vital for application to set these properly before trying any aother action on home page. Home This page allows users to enter a new message, to edit an existing or see in archive organized by date. To look at the archive calendar control is used for navigation. Please note that this application limits number of messages shown at screen for brevity; so as exercise it can be edited to show number of messages entered on that page in special box. Weblog Bridge Fri, 27 Dec 2019 14:12:52 GMT Synchronizing local Blog storage with multiple Blog servers via Blogger APIs Example The demo shows a way to replicate a blog messages to multiple destinations. The destinations are configurable via "Blogger Brigde" link of blogging page. A destination server *MUST* support one of following APIs: blogger, metaWeblog or Movable Type. To select a blog from target the URL, Username and password must be entered before "Fetch" button clicked. You may choose one of BLOGs listed in pop-up window. Once you have defined a Bridge target, you can verify the bridging with post via main page. Note that bridge will post the messages with it's own application key ; so that message will not be replicated. if you are choosed the same server and blog, messages will appear twise as original will be replicated. Making a dynamic blog posts Fri, 27 Dec 2019 14:12:52 GMT Making a dynamic blog posts using XML templates Overview This demo makes a Weblog and posts into it using Metaweblog API two dynamic posts The dynamic posts contains XML template(s) which will be executed at render time. The first post makes a SQL quesry on Demo Database table 'Shippers' and inserts a table into the user's weblog. The second post contains a XML Template containing a XQuery statement. It will render a table containing names from simple opml.xml file. The following is a post content containing a XML Template with SQL Query: <table border="1"> <sql:query xmlns:sql="urn:schemas-openlink-com:xml-sql" > select 1 as tag , null as parent, CompanyName as [tr!1!td!element] from Demo.demo.Shippers for xml explicit </sql:query> </table> The following is a post content containing a XML Template with XQuery: <div> <sql:xquery xmlns:sql="urn:schemas-openlink-com:xml-sql" sql:context="http://localhost:8890/tutorial/apps/blog_query/"> <![CDATA[ <table border="1"> { for $o in document ("opml.xml")//outline return <tr><td>{ string ($o/@text) }</td></tr> } </table> ]]> </sql:xquery> </div> The result from execution can be seen at http://host:port/weblog/bloguser/bloguser-blog-0. Note that demo's initial state MUST be set before hitting this link. Application "Forums" Fri, 27 Dec 2019 14:12:52 GMT Application "Forums" Overview The "Forums" is a World Wide Web application for posting, reading and searching of messages. It is developed under Virtuoso VDBMS using Virtuoso Server Pages (VSP) and server-side XSL-T transformation. The messages are classified by interest to forums and sub-forums. The posting is allowed only for the registered users. The registration is done by registration form. Every registered user can create a new theme, post messages to an existing theme or reply to a message. Unregistered users can search and browse and read the existing themes and messages. VSP is used to produce an XML document. This is then transformed to HTML using server side XSL-T transformation. The design and functionality of this application are separate. The design and appearance of the application depends only on the XSL-T style-sheets. Session management is based on URL (poisoning) and persistent HTTP session variables. The messages are stored in the Database as XML documents, with a text index over them. Application pages The application has the following pages: home.vsp - the main page: Shows the forums with the following information: Forums: name of the forum with link to the relevant sub-forums. Total: total of the messages for this forum; New: new messages for the current forum for the last one day; Last msg.: last inserted message to the forum; Total users: the count of all users at the current moment who are registered at the forums; Options: Login if the user is already registered in the forums; Registration: to add a new user; Search: to search in the messages; subforums.vsp - Shows the sub-forums of the current forum with the following information: Subforum: name of the sub-forum with link to the relevant themes. Total: total of the messages for this forum; New: new messages for the current forum for the last one day; Last msg.: last inserted message to the forum; Options: Login if the user is already registered in the forums; Registration: to add a new user; Search: to search in the messages; Forums path: links to the home page and to the forum to which belong the current sub-forums; forum.vsp - Shows themes of the current sub-forum with the following information: Theme: name of the theme with link to its messages. Total: total of the messages for this theme; New: new messages for the current theme for the last one day; Last msg.: last inserted message to the theme; Options: Login if the user is already registered in the forums; Registration: to add a new user; Search: to search in the messages; Forums path: links to the home page, to the forum and to the sub-forum to which belong the current themes; thread.vsp - Shows the messages of the current theme with the following information: Message: name of the messages with link to its properties / text, author / and when the link is activated, the same page is present, but with the tree of the messages for which the current message is parent. Author: the name of the author, posted the current messages; Date of inserting: date of posting the messages; Options: Login if the user is already registered in the forums; Registration: to add a new user; Search: to search in the messages; Forums path: links to the home page, to the forum and to the sub-forum to which belong the current message, also for the current messages which is parent for the other messages, its name is only presented, and lower you go in the tree, you can go back using this path. Remarks If you are not logged in, you can go on all the pages of the site, but if you want to insert new theme, or new message, you have to login, and automatically the login page is displayed. When you are successfully login, you go directly to the form for inserting messages/themes. If you aren't logged-in, the name anonymous is displayed, instead of your email, if you were logged in. When you use the search option, you can search in 3 main parts: Theme title: title of message which is title of theme; Message title: title of message which has theme as parent theme; Message body: body of the messages which has as a parent different themes; When the search result is displayed, there info how many hits are found, and the result are displayed as following: Message title: the title of the current message / when you search in message body, its title is displayed /; Time: date of inserting of the message or theme; Author: the author of the message or the theme; Home: link to the home page; User info: if logged in, then the current email, otherwise anonymous. Installation Copy /forums and /xslt to the HTTP ServerRoot Execute def.sql script via isql tool with dba privileges. Example: [isql tool directory]\isql [server ip or hostname]:[port] dba dba Connected to OpenLink Virtuoso VDBMS Driver: 02.10.2018 OpenLink Virtuoso ODBC Driver OpenLink Interactive SQL (Virtuoso), version 0.9849b. Type HELP; for help and EXIT; to exit. SQL>load c:\temp\def.sql; Done. -- 20 msec. . . . Done. -- 20 msec. . . . Done. -- 20 msec. Important: Make sure there are no errors. Execute func.sql script. Example: SQL>load c:\temp\func.sql; Done. -- 20 msec. . . . Done. -- 20 msec. . . . Done. -- 20 msec. Important: Make sure there are no errors. Check the installation: http://[server ip or hostname]:[port]/forums/home.vsp Blog application Fri, 27 Dec 2019 14:12:52 GMT Consuming a RSS2 feeds Example The application allow users to retreive a RSS2 documents and render as Weblog. The RSS2 file will be transformed to a Updategram and stored in a local table. Also it demonstrates the usage of VSPX calendar used for navigation. The application contains a simple RSS2 generator, used to present a BLOG data on local server. The data on local server can be entered using the BLOG application Editing the Demo Database data Fri, 27 Dec 2019 14:12:54 GMT Using VSPX controls to edit the Demo Database data Simple application to edit countries data from Demo Database The following approaches are demonstrated: Listing the data with data-set Editing the data with form controls inline images in from blob data In details example itself shows: How to build simple application to list a data. To edit and add strings and large objects. SOAP services Fri, 27 Dec 2019 14:12:53 GMT Amazon API demo Preliminaries The online retailer Amazon.com has provided developers with an interface, that will allow them to do product searches based on a keyword, and a base category. The API is used either by a SOAP call or by a fetch of a XML document. Amazon.com suggests you to download the developer kit. However this is optional, as it is not necessary to run the following OpenLink tutorial. A developer key is required to access the service. One may be applied for at the Amazon.Com Web API page. The service requests may be configured in various ways by the parameters supplied to the API. Example Product search using SOAP API In the SQL setup file, the SOAP call is prepared by the function call to soap_wsdl_import() which reads in the web service ".wsdl" file from Amazon.com. Enter the Developer Key, result type, root node for the search, and the keyword to be searched for. Hit the search button to get the products matching the keyword. This example uses the "heavy" mode of results, that contains the full customer reviews. A local stylesheet is applied to the result for either an XML or HTML view. SOAP & WSDL service Fri, 27 Dec 2019 14:12:53 GMT Stock Quotes Service incorporating AJAX Example This example repeats the example SO-S-7, however client is using AJAX. The AJAX based client retrieves the XML data from Virtuoso SOAP service, and makes a client side XSL-T transformation. SOAP & WSDL service Fri, 27 Dec 2019 14:12:53 GMT Email Address Validation Service Example overview This example demonstrates: The use of raw TCP session operations: ses_connect(), ses_disconnect(), ses_read_line(), ses_write(). A SOAP call. Using the SMTP protocol for email verification. Processing the results with an XSL-T engine. Example Setup The service is prepared by loading the SQL file. This performs the following: Define a stored procedure for the SOAP service that opens a TCP session, and makes a SMTP exchange without sending a mail body to the server. Read responses from the server and makes an XML document. The SOAP service is achieved by defining the /email_service URL to have same functionality as using soap_server() function call. SOAP & WSDL service Fri, 27 Dec 2019 14:12:53 GMT Global provinces and administrative divisions lookup service incorporating AJAX Example This example repeats the SO-S-11, however client is using AJAX. Note: The tables and procedures are used from SO-S-11 example, so run SO-S-11 first. The SOAP & WSDL service are achieved by defining the /SOAP_SO_S_11 URL to have same functionality as using soap_server() and soap_wsdl() calls. SOAP & WSDL service Fri, 27 Dec 2019 14:12:53 GMT Web Registration form exploiting global provinces and administrative divisions lookup service Example overview This example demonstrates: Fetching a two-dimensional array from a SOAP service to populate a provinces list box. The clients in this case is using AJAX. Example This example uses the SO-S-11 for initial setup, and demonstrates making a simple registration form. Note: The tables and procedures are used from SO-S-11 example, so run SO-S-11 first. The SOAP & WSDL service are achieved by defining the /SOAP_SO_S_11 URL to have same functionality as using soap_server() and soap_wsdl() calls. Simple usage of the SOAP service Fri, 27 Dec 2019 14:12:53 GMT Order Entry Service Example The service function accepts data for entering an order into the demo database. The arguments contain the customer id, item to order and quantity. The response is an element with price and expected delivery date, 10 days forward. The function creates a SOAP exception if the customer is not found in the database. The web page will take the data and call the service on the local server. It will display the in and out going messages, including envelopes. SOAP services Fri, 27 Dec 2019 14:12:53 GMT Google API demo Preliminaries This example demonstrates the ability to access the SOAP API provided by Google. The Google API has three services: Search for text on the web. Check details of a page cached by Google. Find correct spelling for a partial word. The service requests may be configured in various ways by the parameters supplied to the API. Google Registration Google API home page http://www.google.com/apis/ has details about the services offered by Google. You must register with Google to be authorized to use the API. You can sign up for a new account from the Google API home page. Verify your email address by accessing a page, as indicated in the email sent by Google. Collect the license key in a subsequent email from Google. Search Demo Enter the registration key for your personal Google account. The key is stored in a browser cookie, and is loaded when the tutorial is run again. Check the box if you wish to view the result as raw XML format. Enter some text to be searched, and press the search button. The raw XML result shows the overview of the search results. If XML view is not checked, then only the number of pages found is shown. Enter a url of a page that is likely to be cached by Google. Then press the button to get the details of this page. The raw XML result will contain the page typically encoded in Base64. If XML view is not checked, then only the size of the page is shown. Enter one or more words to have the spelling verified. A partial word is possible. Then press the button to verify the spelling. The raw XML result shows the suggested spelling. If XML view is not checked, then only the suggested spelling is shown. SOAP services Fri, 27 Dec 2019 14:12:53 GMT Yahoo GeoCode API demo Overview This example demonstrates how to use Yahoo GeoCode API as a local SOAP service. For more information on Yahoo GoeCode API visit: http://developer.yahoo.net/maps/rest/V1/geocode.html Breakdown In the initial state we create a simple procedure that: takes input parameters as described by Yahoo GoeCode API page. Generates URL and calls it. returns the XML result formated throught raw.xsl. Create SOAP_SO_S_27 user and grant the procedure to it. The SOAP service is achieved by defining the /SOAP_SO_S_27 URL to have same functionality as using soap_server() function call. The client uses AJAX to call the service and show the result. SOAP services Fri, 27 Dec 2019 14:12:53 GMT Google Maps API demo Overview This example demonstrates how to implement Google Maps API using XML and Asynchronous RPC ("AJAX"). For more information on Google Maps API visit: http://www.google.com/apis/maps/documentation/ Breakdown In the Initial state we will extend the Demo.demo.Customers table with some new fields (Longitude and Latitude). Then we will use Yahoo GeoCode API to find Longitude, Latitude values for the customers addresses and store the values in the database. The data_xml.vsp page generates XML from that table similar to the one described in Google Maps API Documentation. We have extend it a little bit to have information for the Customer Name and Address. Click on the 'googlemaps.vsp' Run link to see the generated Google Map. You can click on the markers to view additional information. SOAP & WSDL service Fri, 27 Dec 2019 14:12:53 GMT Stock Quotes service SOAP Server setup An executable virtual directory is needed to create a SOAP based service. The service in practice is a PL procedure or group of PL procedures. In this example the PL module contains a single procedure. The procedure makes a request to the quotes.nasdaq.com. The retrieved XML document is returned as a string. VSP page for WSDL generation: For this example it is so_s_7_wsdl.vsp. A WSDL response is made and sent to the client. VSP for SOAP server: The SOAP server can be invoked using a soap_server() call. The so_s_7_server.vsp page shows setup of the SOAP server using the soap_server(). Example Virtuoso client invoked from VSP Virtuoso client is invoked from the VSP page so_s_7_client.vsp. This page accepts an issuer code and processes it with the Virtuoso SOAP client function - soap_call(). The soap method in this request is the name of the procedure defined in Step 2 above. The result from the SOAP request will be transformed with an XSL-T style-sheet, and sent to the browser as an HTML document. Example AJAX SOAP client invoked from JavaScript The "nasdaq_ajax.html" (listed below) contains a JavaScript code used to invoke SOAP client. This client will invoke the Virtuoso SOAP service as defined above. The JavaScript code uses XMLHttpRequest object. Invoking the operation via VB.NET application The following example demonstrates the usage of the Microsoft .NET against Virtuoso's SOAP service as defined in 'Server Setup': 1. Open a new VB.NET project for Console Application. 2. Add a web reference to the Virtuoso WSDL end point (http://[host:port]/xml-soap/services.wsdl). 3. Drag and drop the VirtuosoSOAP() from Class wizard in routine code. Sub Main() Dim soap As New WebReference1.VirtuosoDB_DBA_NasdaqQuotes() Dim result As String Dim sty As New Xml.Xsl.XslTransform() result = soap.get_NasdaqQuotes("YHOO") sty.Load("http://[host:port]/tutorial/services/so_s_7/sr.xsl") Dim strReader As New IO.StringReader(result) Dim xpDoc As New Xml.XPath.XPathDocument(strReader) Dim arg As New Xml.Xsl.XsltArgumentList() Dim strWriter As New IO.StringWriter() sty.Transform(xpDoc.CreateNavigator(), arg, strWriter) System.Console.WriteLine(strWriter.ToString) End Sub SOAP & WSDL Fri, 27 Dec 2019 14:12:53 GMT Exchange Rate Conversion service Exchange Rate Conversion Example This example is an exchange calculator in two versions: based on VSP and soap_call() and another AJAX version based on WebService Behaviour. A virtual directory is configured to respond to SOAP service requests, which are handled in the context of the assigned SQL user. The example defines the following service descriptions and links: A SOAP directory of 'exchange' for describing exch's procedures. The WSDL file will be located at http://hostname:[port]/exchange/services.wsdl The server-based webservices file is exchange_rates.vsp, while the AJAX one is exchange_rates_ajax.html. Click on the 'Run' links to experience the demo. Note: loading the exchange.sql file will take some time, as it accesses a foreign host. SOAP services Fri, 27 Dec 2019 14:12:53 GMT Contact Details Extraction Service Example overview This example demonstrates: Fetching HTML from a foreign host as specified by the user. Rendering the page with regexp_match() to extract the contacts information. For example, it take information from sequences like: "quoted text" said John Smith, Manager at A Company. Making a Web search with the company name to find the domain. Making an email address from contact name, and domain name. A SOAP call. Processing the 4 dimensional array in the AJAX based client. XSL transformation. Example Setup The service is prepared by loading the SQL file. This performs the following: Define a SOAP type for 4 dimensional array. Define a stored procedure for the SOAP service that queries, web target and makes the contact info. The SOAP service is achieved by defining the /SOAP_SO_S_19 URL to have same functionality as using soap_server() function call. Example Operation Get a page from the URL. Substitute characters " as 0x94 etc. Remove <i>, <b>, <strong> elements. Take out CR/LF. Make breaks before <P and <H elements. Parse the page to have consistent escapes such as &quote; . If the above fails then achieve the same with substitutions. Have a function to return a regular expression(s) by given level of recursion. Have a recursive function which gets a regular expression based on depth and apply it against the text. If match found skip rest of pattern matching. If not, apply the next pattern. When contact matches name, title and company, the item will be added to a result array. Company of the result will be searched via Google to find 'home page' or 'welcome'. The top most result link from Google will be parsed to extract the name of the site ie. domain name part. The email will be composed as FirtsName.LastName@domain . A multidimensional array will be produced containing the name, company, title and email. Loop over the resulting array, and make an XML document. Render the XML to the HTML using XSL-T sheet. Invoking the operation via VB.NET application The following example demonstrates the usage of the Microsoft .NET against Virtuoso's SOAP service as defined in 'Server Setup': 1. Open a new VB.NET project for Console Application. 2. Add a web reference to the Virtuoso WSDL end point (http://[host:port]/SOAP_SO_S_19/services.wsdl). 3. Drag and drop the VirtuosoSOAP() from Class wizard in routine code. Sub Main() Dim soap As New WebReference1.VirtuosoSOAP() Dim result As String() Dim len, i As Integer result = soap.ExContacts("http://www.openlinksw.com/press/oplappl4.htm") len = result.Length - 1 For i = 0 To len Step 5 System.Console.WriteLine("Name: " + result(i)) System.Console.WriteLine("Title: " + result(i + 1)) System.Console.WriteLine("Company: " + result(i + 2)) System.Console.WriteLine("Email: " + result(i + 3)) System.Console.WriteLine("Home page: " + result(i + 4)) System.Console.WriteLine("") Next i End Sub Making XML Reports Fri, 27 Dec 2019 14:12:54 GMT Making simple XML report XML report example The example shows a sales report by customer and product category for a given time period. The FOR XML and XSLT is used to render it. A form is used to define start and end dates. The data is taken from the demo tables. This is an example of xml_auto() on a vsp page with an xslt template. It shows how xml_auto_dtd(), and xml_auto_schema() can be used to describe the output. Making XML Reports Fri, 27 Dec 2019 14:12:54 GMT Inline DTD example Inline DTD XML report The example shows a sales report by customer and product category for a given period of time. The FOR XML and XSLT is used to render it. A form is used to define start and end dates. The data is taken from the demo tables. This is an example of xml_auto() on a vsp page with an xslt template. It shows how xml_auto_dtd(), and xml_auto_schema() can be used to describe the output. XML for Analysis Fri, 27 Dec 2019 14:12:53 GMT XML for Analysis Example The Virtuoso server can act as XML for Analysis (XMLA) tabular data provider. XML for Analysis is a SOAP based XML API, designed specifically for data access interaction between a client application and a data provider working over the Web. The client application can do discovery of data provider information and execute of SQL statements. The result sets from server to client can be Multidimensonal and Tabular, at current state only Tabular is supported. To setup an virtual directory to act as XMLA data provider, it needs to be defined as SOAP one and Discover and Execute procedures needs to be granted to the user account for SOAP execution. The example shows how SOAP enabled virtual directory can be exposed for XMLA. The SQL statements for setting up the virtual directory are shown in the .sql file In addition to the virtual directory setup, there is a grant to the Northwind Customers table to be able to invoke select on that table via Execute method. The example XMLA client is a simplest browser of XMLA provider It allows to browse the data, do execute of SQL statements and such To try the example do load the script, start the VSP example and follow the steps Making a freetext trigger Fri, 27 Dec 2019 14:12:55 GMT Freetext triggers example Example This example adds an XML content trigger to the data of XS-S-1. The main features of this example are: Display a list of documents held in a table. Add a new document or delete an existing one. Define a trigger. Show the hits found by the triggers. Document upload and list page The URI for the document is entered, and the system goes to retrieve it using xml_uri_get(). The document is inserted into a table. If the document is HTML it is converted to XHTML with xml_tree() HTML mode. If the HTML is not in a valid format or the document at the URI is not found, an error is reported. There is a list of the rows in the documents table. Each row has a delete button, to remove the document. Trigger definition page The triggers page allows triggers to be added and deleted. When a trigger is deleted the hits are also deleted. Some pre-existing triggers look for text of specific tags in the XS-S-1 material. Hits page The hits are listed on this page. The hits page has a delete all button, to remove the hits. Encodings in HTTP, XML XSL-T Fri, 27 Dec 2019 14:12:55 GMT Encodings in HTTP, XML XSL-T Treatment of the <?xml > notation Each external parsed entity may begin with a text declaration: <?xml versioninfo encoding_declaration > Each external parsed entity in an XML document may use a different encoding for its characters. The encoding declaration instructs the XML parser which encoding to use to parse the entity. encoding="encoding name" The xsl:output element's options The xml output method outputs the result tree as a well-formed XML external general parsed entity. The html output method outputs the result tree as HTML. The text output method outputs the result tree by outputting the string-value of every text node in the result tree in document order without any escaping. Parsing the XML documents with specified encoding If the encoding is specified in the XML document (in xml header), it is used. If not in the document, but in "default encoding" argument, then the argument's value is used. If no argument, the session should be used only for HTML, but for XMLs the standard requires UTF-8. So when a tree comes from xslt the xsl:output is reflected there for use when serializing. Examples The example in the SQL script demonstrates using the encodings and languages with free-text search over indexed data. The first example accepts text from the user and maps this to any selected encoding and returns the text in another encoding. The selection box of input and output encodings is used to transfer the narrow character data. The second example sends the text of the XS-S-1 data to the user agent in a selectable encoding, using an XSL-T transformation. The last example shows how the text can be effected by the HTTP 'Content-Type' header defining the charset. In this example current charset is set with 'set charset=...' statement. This invokes sending a 'charset' mime attribute to the user-agent. DTD validation Fri, 27 Dec 2019 14:12:55 GMT DTD Validation example Example This sample uses the DTDs generated based on FOR XML query to verify another FOR XML query result. The interface allows selection of a query for the DTD and a query for the XML document. The interface has check boxes controlling each aspect of DTD validation (see the documentation about each of them). The submit button combines the DTD and the XML document, verifies them and produces a result page showing the error messages. Processing a large XML files Fri, 27 Dec 2019 14:12:55 GMT XML persistent storage Preliminaries The PL varchar variable has a limit of 10Mb. This means that variables that may contains a large document for XML processing cannot keep over 10Mb data. Using a temp file with xml_persistent does not have this limit. The xml_persistent() can process the large documents using the temporary file for storing the data. Caution: Paths used in that sample are evaluted in the server file system. Specify correct server filesystem paths. Example The example converts a file to persistent XML and back to a file. The file is then traversed by XSLT and the result is stored into a string output. This is then stored into a file. The input of the sheet is checked against a DTD. The page shows these steps and the lengths of the files and intermediate data. The data is an excerpt of dmoz with some extra repetition to make 5MB of data. This is not itself above the varchar limit but is large enough for this example. The results can be seen in the result file in the directory. The vsp page will show fragments of the data, e.g. part of the first subtree. RDF NET Fri, 27 Dec 2019 14:12:53 GMT RDF NET Example RDF NET RDF NET SPARQL Query on PHP ODBC Hosting Demo Fri, 27 Dec 2019 14:12:53 GMT Demonstrates the use of a PHP script hosted in Virtuoso to execute SPARQL queries against Virtuoso's RDF Triplestore. Note, this demo leverages PHP's ODBC based data access layer and Virtuoso's ability to execute SPARQL via its SQL query processor. PHP script calling ODBC This demo shows simple ODBC functions being used in a PHP script: odbc_connect(), odbc_exec(), odbc_result_all() and odbc_tables(). The demo makes sparql queries on Virtuoso's RDF database using "sparql select" syntax. The data is loaded on tutorial vad installation time by the sparql_demo. RDF data import on PHP ODBC Hosting Demo Fri, 27 Dec 2019 14:12:53 GMT Demonstrates the use of a PHP script hosted in Virtuoso to import RDF data using SPARQL sponger. Note, this demo leverages PHP's ODBC based data access layer and Virtuoso's ability to execute SPARQL via its SQL query processor. PHP page invoking the SPARQL sponger This demo demonstrates the use of PHP script hosted in Virtuoso to import RDF data using SPARQL sponger. Note, this demo leverages PHP's ODBC based data access layer and Virtuoso's ability to execute SPARQL via its SQL query processor. This demo presents a PHP form to the user to enter a URL. The form action (buton click) will perform import of RDF data. Note: this tutorial is limitied to no more than 10 MB files to be imported. Also note that pinging the service is not needed if [SPARQL] INI section has PingService = http://rpc.pingthesemanticweb.com/ setting. Importing RDF data using SPARQL query Fri, 27 Dec 2019 14:12:53 GMT RDF data import using SPARQL sponger. VSPX page invoking the SPARQL sponger This demo presents a VSPX-based form for entering an URL. The form's submit (button click) will perform a SPARQL query with sponge parameters and will ping pingthesemanticweb.com upon success. Note that pinging the service is not needed if [SPARQL] INI section have PingService = http://rpc.pingthesemanticweb.com/ setting. RDF Cartridges Fri, 27 Dec 2019 14:12:53 GMT This article explains how to develop and test a custom RDF Cartridge. Concept RDF cartridges provide a modular approach to RDF oriented entity extraction and ontology mapping as part of a Linked Data production pipeline. Typical sources include (X)HTML pages, images, Office documents and PDF documents amongst others. Cartridges expose their functionality to service consumers via the Virtuoso Sponger ("Sponger"), a middleware layer that extracts and delivers RDF to other Virtuoso components such as the Web Crawler and SPARQL Query Process. In addition it is directly exposed as a REST-style Web Service for external applications and services to exploit. A Cartridges is comprised of an initialization PL procedure (hook) and an entity extractor and mapper. The entity extractor and mapping component can be developed using PL, C or any external language supported by Virtuoso via the Virtuoso Server Extensions APIs. Once the cartridge has been developed, it is plugged into the Virtuoso Sponger by adding a record to the table DB.DBA. DB.DBA.SYS_RDF_MAPPERS. How Cartridges Work: SPARQL Query Processing When a SPARQL query is dispatched to Virtuoso, it invokes the Sponger during the act of graph or resource URI dereferencing i.e. it actually crawls the Web, locates a resource via it's URI/IRI (using a variety of RDF discovery heuristics), and then differences the data that the URI exposes. If RDF is discovered, the cartridges play no role. On the other hand, if RDF isn't discovered the Sponger will look in the DB.DBA.SYS_RDF_MAPPERS table (in RM_ID order), and for every matching URI or MIME type pattern (depending on RM_TYPE column value) it will invoke the associated cartridge by invoking the hook procedure. If the hook returns zero the next cartridge will be tried. If the result is negative the process stops, instructing the SPARQL engine that nothing was retrieved. If the result is positive the process stops, this time instructing the SPARQL engine that RDF data was successfully retrieved. PL hook requirements Every PL function used to plug a cartridge into the SPARQL engine must have the following parameter signature: in graph_iri varchar: the local storage graph IRI in new_origin_uri varchar: target information resource URI in destination varchar: the target graph IRI inout content any: the content of the information resource retrieved for dispatch to the Sponger inout async_queue any: an asynchronous queue, can be used for background processing (if required) inout ping_service any: the value in the [SPARQL] section of a Virtuoso instance (i.e PingService? INI parameter) which is enables RDF triple propagation and notification to pinger services such as http://pingthesemanticweb.com inout api_key any: a plain text id single key value or serialized vector of keys, basically the value of RM_KEY column of the DB.DBA.SYS_RDF_MAPPERS table, which is used for handling of API keys for 3rd party Web Services. Note: the names of the parameters are not important, but their order and presence are vital. Implementation In the example script we implement a basic cartridge which maps a text/plain mime type to an imaginary ontology, which extends the class Document from FOAF with properties 'txt:UniqueWords?' and 'txt:Chars', where the prefix 'txt:' we specify as 'urn:txt:v0.0:'. To test the cartridge we just use /sparql endpoint with option 'Retrieve remote RDF data for all missing source graphs' to execute: select * from <URL-of-a-txt-file> where { ?s ?p ?o } It is important that the SPARQL_SPONGE role needs to be granted to "SPARQL" user account (or any other account bound to SPARQL functionality) in order to enable persistence to local storage. If the above is set correctly then you can just hit this link. More complex examples can be found in the rdf_cartridges package implementation. RDF Cartridges Fri, 27 Dec 2019 14:12:53 GMT This article explains how to implement a Python based RDFa Cartridge based on pyRDFa library. Setting up server This tutorial explain steps to use the Python language to extend the Virtuoso Sponger. The server must have installed latest Python hosting plugin. When it is installed and registered in the configuration file a new function python_exec will be available for developers. Setup the Virtuoso server INI to include python module [Plugins] LoadPath = ../lib Load1 = Hosting, hosting_python.so ... The python_exec takes following arguments: code - a string containing the Python code function_name - a string containing the name of Python function to be executed param1 : a string containing first parameter param2 : a string containing second parameter as many parameters as Python function has The Python based function must return a single string value. Setting up environment Before to write cartridge you need to setup Python environment. To do this you need to download and install rdflib, pyRDFa. Read the pyRDFa paper for what additional libraries are needed. If your Python installation have Zope support, you should disable the zope interfaces in rdflib. This is needed because Python C-API expirence problems when using sub modules within C code. In order to disable you can comment out following lines in [rdflib_home]/rdflib/__init__.py : 36 #from rdflib.interfaces import IIdentifier, classImplements 37 #classImplements(URIRef, IIdentifier) 38 #classImplements(BNode, IIdentifier) 39 #classImplements(Literal, IIdentifier) then do: perl setup.py build perl setup.py --user install RDF Cartridge implementation notes The implementation consist of two steps: Make a copy of the localRDFa.py and use as template to run pyRDFa extractor over single string stream. The details can be seen in source of pyRDFa.py code attached to this tutorial. Make a Virtuoso/PL based stored procedure to call the Pyhton based extractor. The source of this function can be seen in rdf_cartridge.sql script. The stored procedure is used to do two main operations: to call 'processString' Python function inside pyRDFa.py script and to load the result in the Virtuoso RDF store. Another important item is to register the cartridge with Sponger. this is done by insert statement into DB.DBA.SYS_RDF_MAPPERS table. Note that in this example the new cartridge will be disabled if you run that code, if you want to enable and test the cartridge the flag in RM_ENABLED column must be 1. or enable the crtridge via conductor. Using HTTP client to perform FOAF+SSL connection Fri, 27 Dec 2019 14:12:53 GMT Using HTTP client to perform FOAF+SSL connection Example In order to have the rest of examples of this section working, the following steps must be performed. Setup the ODS and Policy Manager packages. Follow instructions on Setting-Up issuer CA Follow instructions on Virtuoso Authentication Server UI In above step register your WebID with secure SPARQL endpoint. Note: "sparql-ssl" endpoint is alias of "sparql-webid" endpoint. Export your certificate and key containing the WebID mentioned before from browsers key store as PKCS#12 package. Run the register_cert.vsp to import your key into Virtuoso Server PKI repository. Run the foaf_ssl_client.vsp. SMTP client Fri, 27 Dec 2019 14:12:53 GMT Simple mail composer Example This example uses the smtp_send() function for sending emails. The demo page accepts mail server address, sender, recipient and message body. The 'Send' button causes the composed simple email message to be sent to the mail server. SMTP local mailer Fri, 27 Dec 2019 14:12:53 GMT Storing incoming mail into the DataBase Installation instructions The Virtuoso server can store the incoming mail into the database using it's own local mailer implementation. The following sections detail the configuration of each type of mail environment. Replacing procmail as default handler in sendmail configurations Copy virt_mail to /usr/bin/virt_mail Copy odbc_mail.default.ini to /etc/odbc_mail.ini IMPORTANT: Make sure /etc/odbc_mail.ini is NOT GROUP/WORLD writable, otherwise virt_mail will fail to run. Edit /etc/odbc_mail.ini and change the login settings to match your current database installation. If you don't have or want to use procmail, comment out the "Fallback" setting in the [Deliver] section. Edit /etc/sendmail.cf. Change: Mlocal, P=/usr/bin/procmail, F=lsDFMAw5:/|@qSPfhn9, S=10/30, R=20/40, T=DNS/RFC822/X-Unix, A=procmail -Y -a $h -d $u into: Mlocal, P=/usr/bin/virt_mail, F=lsDFMA5:/|@qSPhn9, S=10/30, R=20/40, T=DNS/RFC822/X-Unix, A=virt_mail -c /etc/odbc_mail.ini -l $u -s $g NOTE: The changes to the F= setting involve removing both the 'w' and 'f' flags. The removal of the 'w' flag affects lookups in /etc/passwd, which are no longer required if all mail drops go into the database. The default ini file is set up to maildrop to procmail, which will perform this check correctly. Per-user database maildrops under sendmail Copy odbc_mail.default.ini to ~the_user_name/.odbc_mail.ini IMPORTANT: Make sure the .odbc_mail.ini is NOT GROUP/WORLD writable, otherwise virt_mail will fail to run. Put at the end of ~the_user_name/.procmailrc something like: :0: | /usr/bin/virt_mail -c .odbc_mail.ini -l the_user_name replacing the_user_name with the user you're setting up. Note: the '-l ..' parameter is used to relate the local recipient to the database user for which the maildrop is done. See the remarks in the odbc_mail.default.ini file. Adjust the parameters in .odbc_mail.ini to match your configuration IMPORTANT - also disable Fallback delivery in .odbc_mail.ini Comment out the "Fallback =" entry in the .odbc_mail.ini or set it to something that doesn't involve procmail. Otherwise, this could lead to drop loops. Per-user database maildrops under qmail Copy odbc_mail.default.ini to ~the_user_name/.odbc_mail.ini IMPORTANT: Make sure the .odbc_mail.ini is NOT GROUP/WORLD writable, otherwise virt_mail will fail to run. If you're setting up a .qmail, simply do something like | /usr/bin/virt_mail -m qmail -c .odbc_mail.ini If you're setting up .qmail-default or .qmail-<some_alias_name>, make sure you adjust the RemovePrefix accordingly in the odbc_mail.ini. This also works if a single user is receiving mail for an entire (virtual) domain. If you want to configure qmail so that user 'db' gets all mail for example.com, do this: Create a new user db in /etc/passwd etc. Remove example.com from /var/qmail/control/locals Add to /var/qmail/controls/virtualdomains: example.com:db Adjust /var/qmail/users/assign accordingly: =db:db:<uid>:<gid>:<home>::: +db-:db:<uid>:<gid>:<home>:-:: or run qmail-pw2u < /etc/passwd > /var/qmail/users/assign then run qmail-newu and restart qmail In ~db/.qmail-default, put: | /usr/bin/virt_mail -m qmail -c .odbc_mail.ini In .odbc_mail.ini, set RemovePrefix=db- Now, mail to info@example.com will be delivered to the qmail alias db-info@example.com and is stored into the database for user 'info'. Adjust the parameters in .odbc_mail.ini to match your configuration Per-user database maildrops under courier Copy odbc_mail.default.ini to ~the_user_name/.odbc_mail.ini IMPORTANT: Make sure the .odbc_mail.ini is NOT GROUP/WORLD writable, otherwise virt_mail will fail to run. If you're setting up a .courier, simply do something like | /usr/bin/virt_mail -mcourier -c .odbc_mail.ini If you're setting up .courier-default or .courier-<some_alias_name>, make sure you adjust the RemovePrefix accordingly in the .odbc_mail.ini. Note 1: Although courier is very similar to qmail in this respect, it is different from qmail in how it handles exit codes. If you use -mqmail while running under courier, you'll get the wrong exit codes, so mail is bounced instead of retried. Note 2: If delivering to multiple recipients in a .courier file, make sure the virt_mail is specified first. This is because if the virt_mail fails with a temporary error, the other recipients will get another drop when courier re-attempts to deliver the mail. Right: | /usr/bin/virt_mail -mcourier -c .odbc_mail.ini ./Maildir Wrong: ./Maildir | /usr/bin/virt_mail -mcourier -c .odbc_mail.ini Adjust the parameters in .odbc_mail.ini to match your configuration EXIM Here are code snippets for Exim that perform maildrops into the odbc database. ## IN TRANSPORT SECTION # Delivers into the database odbc: driver = pipe command = /usr/bin/virt_mail \ -c /etc/odbc_mail.ini \ -s "${if def:return_path{$return_path}{MAILER-DAEMON}}" \ -l "$local_part" user = USERNAME return_path_add delivery_date_add prefix = suffix = temp_errors = 73 : 74 : 75 return_fail_output # NOTE: Make sure the USERNAME in the 'user = USERNAME' setting matches # the owner of /etc/odbc_mail.ini, because this file must have mode 0600. # Consider creating a new user account for this delivery only. # You should specify 'user = root' here only if Fallback delivery is # configured in /etc/odbc_mail.ini (for procmail fallback delivery # for instance) ## IN DIRECTORS SECTION # Attempts delivery of all mail into the database to_db: driver = smartuser transport = odbc require_files = /etc/odbc_mail.ini # # uncomment line below to deliver all mail to db-XXX into the database, for any # value of XXX. For this to work, set "RemovePrefix = db-" in # the [Translate] section in /etc/odbc_mail.ini #prefix = db- Text triggers notification Fri, 27 Dec 2019 14:12:53 GMT Using the SMTP client function for free-text triggers notification Example The SMTP client function can be used for automatic responses and notifications for DB events. The example shows mail delivery code for the hit notifications on the text triggers in DAV. When a free-text trigger query is defined to make an email notification, the trigger will have an email address stored in the column TTH_NOTIFY of the HITS table. The notification is a separate procedure that opens a cursor over the hits table. For every non-empty recipient, a message is sent. Note that in this example the mail server passed to the smtp_send() is null. This means that the default mail server from virtuoso.ini will be used for making the SMTP connection. Mail notification Fri, 27 Dec 2019 14:12:53 GMT Automatic reply to mail message Example The example shows an automatic reply to the sender. If the message contains a valid XML structure describing the order SOAP request, it will add the order to the demo tables and reply with a success message. If there is no valid structure, it will reply with a failure notice. The web page contains configuration instructions. It is possible to define the mail account on the server for processing these messages. An example SMTP send command is : smtp_send ( null, 'imitko@localhost', 'dav@localhost' , 'Subject: SOAPMethodName: #new_order\r\n\r\n <?xml version=\'1.0\' ?> <SOAP:Envelope xmlns:xsi=\'http://www.w3.org/1999/XMLSchema-instance\' xmlns:xsd=\'http://www.w3.org/1999/XMLSchema\' xmlns:SOAP=\'urn:schemas-xmlsoap-org:soap.v1\' xmlns:dt=\'urn:schemas-microsoft-com:datatypes\'> <SOAP:Body> <new_order> <_CustomerID>CENTC</_CustomerID> <_EmployeeID>1</_EmployeeID> <_ShipVia>3</_ShipVia> <_RequiredDate>2001-05-31</_RequiredDate> <_ProductID>26</_ProductID> <_Quantity>1</_Quantity> <_Discount>0.300000</_Discount> </new_order> </SOAP:Body> </SOAP:Envelope>' ); MIME messages Fri, 27 Dec 2019 14:12:53 GMT Rendering MIME message as HTML Example This example renders a MIME tree as HTML. The messages are from a designated POP server. The retrieved messages are stored into a local table without deleting from the origin server. The web page has a function for clearing the operation. MIME messages Fri, 27 Dec 2019 14:12:53 GMT Creating a simple MIME message Example The example builds a multipart MIME message and sends it to an external mailbox. The page will accept the recipient, text and a single file upload. It will make these into a MIME message to be sent. The mail server is specified on the form. POP3 server Fri, 27 Dec 2019 14:12:53 GMT Storing mails in local POP3 server Example The example inserts data into the tables used by the local POP3 server, including user accounts. Data imported from another POP3 server is made available. NNTP get messages Fri, 27 Dec 2019 14:12:53 GMT Get messages from NNTP server Preliminaries The nntp_get() function can read the following information: List of news groups on a server. Length and Range of message numbers within a group. Message headers. Message body can be read with nntp_get() or nntp_id_get(). Newsgroup message read example Display group list from an external NNTP server. Display last 20 message headers from the selected newsgroup. Display any selected message using nntp_get() or nntp_id_get(). NNTP messages Fri, 27 Dec 2019 14:12:53 GMT Creating a simple NNTP message Newsgroup message write example The example builds an NNTP message and sends it to an external NNTP server. The form accepts the news server, newsgroup name and message body. IBuySpy application Fri, 27 Dec 2019 14:12:52 GMT Running ASPX based applications Overview The goal of that demo is to demonstrate ability of Virtuoso server to host ASP.NET projects The IBuySpy application is ASP.NET based solution for making a portal applications The demo uses Virtuoso as hosting environment and Database back-end It may re-configured easy to use MS SQL server as back-end The Database connection options are two Virtuoso .NET client Virtuoso OLEDB provider Installation This demo can be started only on Virtuoso server running over Windows OS environment If you are going to try application using MS SQL Server back-end, the IBuySpy application must be downloaded from www.ibuyspy.com and installed. The Mobile Internet Toolkit (MMIT 1.0), available from www.asp.net must be installed. Go to the folder vsp/IBuySpy under installation directory and unpack one of the .ZIP archives, depending of provider type : OLEDB or .NET provider. Please note that Store application is available only with .NET provider only. The content of archive must be extracted under vsp/IBuySpy, so if all is ok the PortalCSVS subdirectory must appear. If you are not running Virtuoso demo instance, the supplied SQL scripts must be loaded via ISQL tool using DBA account. In this case also needs to define a virtual directory pointing to the (HTTP root)/IBuySpy/PortalCSVS and (HTTP root)/IBuySpy/StoreCSVS. (See web applications tutorial how to make a executable virtual directory) If you are running Virtuoso demo instance, the scripts are already loaded and virtual directory is created. Edit the Web.config file under vsp/IBuySpy/PortalCSV directory and change the address of Virtuoso server location (host name and ODBC/SQL port) in the appSettings section, key="ConnectionString" element The Portal application Web UI is accessible through the http://[host:port]/PortalCSVS/ Also the Store application Web UI is accessible through the http://[host:port]/StoreCSVS/ PetShop application Fri, 27 Dec 2019 14:12:52 GMT Running ASPX based applications Overview The PetShop application developed by Microsoft using ASP .Net and C# used in this tutorial is another demonstration of Virtuoso's ability to host ASP .Net projects. This ASP .Net data driven shopping cart application for browsing and adopting Pets utilizes Virtuoso's 3rd Party hosting feature as well as the Virtuoso database as the data store. This demonstration is completely configurable and can be modified easily to change the data store to Microsoft SQL Server. Prerequisites The following prerequisites should be used to make sure your computer has the appropriate operating system and software to demonstrate the PetShop application using Virtuoso running on the Windows. Windows 2000/XP Virtuoso Universal Servers Microsoft ASP .Net enabled binary Microsoft ASP .Net Framework SDK Installation and Configuration This demonstration is based on the Virtuoso Universal Server running in a Windows operating system environment and includes configuration steps to run the PetShop application. If you have installed the demonstration database and have an environment already running the Virtuoso demo instance, the SQL scripts and configuration files are already loaded and the virtual directory has been created as part of the installation. If you are not running in this environment perform the following steps to demonstrate the PetShop Application In the folder vsp/Petshop under the Virtuoso Universal Server installation directory unpack and extract the OLEDB the .ZIP archive. Register the PetShop.Components.dll as COM object using regsvcs utility, which is required to start the application. Create the PetShop database schemas (MSPetShop and MSPetShopOrders), including tables and stored procedures and populate the databases using the following supplied SQL scripts located in the PetShop\DatabaseScripts\SQL subdirectory. These scripts can be loaded using the OpenLink Virtuoso Interactive SQL Interface (ISQL) tool available from the OpenLink Virtuoso start menu using the DBA account. CreateDBLogin1.sql CreateTables1.sql CreateTables2.sql LoadTables1.sql Define a new virtual directory pointing to the (HTTP root)/PetShop/Web. (For instructions on creating an executable virtual directory see the Web applications tutorials (LINK)) Edit two connection strings in Web.config file which is located under the vsp/PetShop/Web directory. Add two entries with same values for the address set to the Virtuoso server location (host name and ODBC/SQL port), the account and password (UID and PWD) and the change the name of each of the databases; one for "MSPetShop" and one for MSPetShopOrders the appSettings section, key="ConnectionString" element Example: <add key="ConnString1" value="HOST=localhost:1112;UID=petshop;PWD=password;Database=MSPetShop" /> <add key="ConnString2"value="HOST=localhost:1112;UID=petshop;PWD=password;Database=MSPetShopOrders" /> Once configured, the PetShop application Web UI will be accessible from the URL http://[host:port]/PetShop/ Configuration Options Database The PetShop application is designed to be configurable and is easily modified. Should you choose to switch the database data store to Microsoft SQL Server, you will need to install the complete PetShop application, which can be downloaded from http://www.gotdotnet.com/team/compare/petshop.aspx. Limits/Restrictions In Virtuoso, the PetShop application is available only with .NET provider. Integrating Common Language Runtime Objects with Virtuoso Fri, 27 Dec 2019 14:12:52 GMT Hosting .Net Web Services in Virtuoso. Overview This tutorial demonstrates Web Services hosted on Virtuoso. The Web Service was created using MS Visual Studio. Prerequisites The following prerequisites ensure the usability of these tutorial demos on Windows Windows .NET Runtime and Frameworks .Net Runtime and Framework SDK (if you seek to write your own Objects for integration with Virtuoso) Virtuoso Universal Server for Windows with .NET CLR Hosting Tutorial Example Please follow the steps below to maximize the value of this tutorial: Click on the "Set Initial State" link which registers the two C# classes within Virtuoso. Click on the "ho_s_12.sql" link to see the code behind this step. Click on the "Run" links to execute the demos. Demo Breakdown "ho_s_12.sql" performs the following steps: Defines a Virtual Directory called "asmx_tutorial". Imported WSDL to define types needed for virtuoso soap client. Defines a procedure to return soap cal result using previously defined types. The "asmx_tutorial.vsp" shows all end-points URLs defined from the Web Service. Basic ASP.NET Hosting Demo Fri, 27 Dec 2019 14:12:52 GMT Hosting standard ASP.NET controls within Virtuoso. Overview The HO-S-6 tutorial shows all the ASP.NET standard controls hosted inside Virtuoso's DAV repository and accessible via its HTTP server. Prerequisites The following prerequisites should be used to ensure that your computer has the appropriate operating system and software to run the Virtuoso 3rd Party Hosting HO-S-6 tutorial on Windows 2000, XP or operating systems capable of running Mono. Windows or Linux Virtuoso Universal with support for Microsoft .NET and Mono Hosting enabled. Microsoft .NET Runtime or Mono Runtime Microsoft .NET Frameworks (specifically ASP.NET) or Mono's ASP.NET Frameworks (this is part of the Mono bundle included in the Virtuoso installer) Tutorial Example All the standard ASP.NET base controls (including but not limited to buttons, drop-down lists and tab controls etc) are listed in a table with invocation and source code revealing hyperlinks. The C# source code of each control is optionally vieweable by clicking the matching hyperlink in the "View Source" column. To execute each of these aspx pages click on the "run" hyperlink in the "Action" column. For troubleshooting tips, refer to the "Environment Setup" section in "Runtime hosting" chapter of the Virtuoso documentation. DataGrid ASP.NET Hosting Demo Fri, 27 Dec 2019 14:12:52 GMT A databound ASP.NET page hosted within Virtuoso's WebDAV repository Overview This tutorial is a demonstration of how Virtuoso hosts the ASP.NET and ADO.NET Frameworks as implemented by Microsoft.NET and Mono. The demo consists of a DataGrid control which uses ADO.NET and Virtuoso's managed Data Provider to retrieve data from the local Virtuoso database hosting this tutorial application. Prerequisites The following prerequisites should be used to ensure computer has the appropriate operating system and software to run the Virtuoso 3rd Party Hosting HO-S-7 tutorial on Windows 2000, XP or operating systems capable of running Mono. (See the Mono project home page for information regarding Mono developed by Ximian). Virtuoso Universal Servers Microsoft ASP .Net or Mono ECMA-CLI enabled binary CLR from Microsoft ASP .Net Framework SDK Review the documentation on CLR Hosting setup in the Runtime Hosting, chapter 15 of the Virtuoso documentation Tutorial Example The HO-S-7 tutorial uses the C# bound .aspx page to demonstrate data retrieval via ADO.NET, and data display using the standard ASP.NET DataGrid control. The source code for the DataGrid control ("VirtSample.aspx") is viewable by clicking the associated hyperlink in the "View Source" column, and can be executed by clicking the "Run" hyperlink in the "Action" column.. Notes In this tutorial, the data provider being used is the Virtuoso.NET managed provider, which is installed as part of the Virtuoso installation process. To run this tutorial, the demo instance requires an Access Control List file modification (in this case the .INI file associated with the demo database instance); this involves adding a section-key-value to "DirsAllowed" section-key that points to the location of the OpenLink.Data.Virtuoso.dll assembly (which hosts the managed data provider) Simply append the file reference "../bin/OpenLink.Data.Virtuoso.dll" to the last entry for the section-key "DirsAllowed". If you have changed the password for "demo" SQL account (you are encouraged to do this at installation time), you will need to Edit the connection string in the Web.config file associated with this application domain and change the password (PWD) in key="ConnectionString" element which is part of the appSettings section, e.g.: <add key="ConnectionString" value="HOST=localhost:1112;UID=demo;PWD=demo;Database=demo" /> The Web.config file is located in one of the following locations depending on the CLR being used for the demonstration [http_root]/vad/vsp/tutorial/hosting/ho_s_7/Web.config if you are using server hosting MS.NET CLR. mono/lib/mono/machine.config if you are using server-hosting ECMA-CLI (Mono). For troubleshooting tips, refer to the "Environment Setup" section in "Runtime Hosting", chapter 15 in the Virtuoso documentation. PHP ODBC Hosting Demo Fri, 27 Dec 2019 14:12:52 GMT Use of ODBC from within a PHP script hosted in Virtuoso PHP script calling ODBC This demo shows simple ODBC functions being used in a PHP script: odbc_connect(), odbc_exec(), odbc_result_all() and odbc_tables(). The WebCalendar application is an Open-Source implementation of a multi-user web-calendar in PHP, released under the terms of the GPL; the project homepage is hosted on SourceForge.net. We include it here as an example of how to take an existing PHP application designed to run with Apache against mysql, postgresql or ODBC database backends, and host it within Virtuoso. The default username and password are admin/admin. The "Set the initial state" SQL files must be executed prior to running the demo. The file create_local_dsn.sql will create a local DSN named "Local Virtuoso Tutorial HO-S-30", which will be used for connecting the database. For troubleshooting please read the "Environment Setup" section in "Runtime hosting" chapter from documentation. Integrating Perl Scripts with Virtuoso Fri, 27 Dec 2019 14:12:52 GMT Using Perl code to extend Virtuoso. Overview The following tutorial demonstrates how Virtuoso can be extended through the use of Perl. The demonstrations in this section highlight transparent integration (hosting) between Virtuoso and the Perl Runtime. Prerequisites The following prerequisites ensure the usability of these tutorial demos on any platform with a Perl runtime: Perl 5.6 or higher for UNIX platforms or ActivePerl 5.8 or higher for Windows platforms The DBI and DBD::ODBC Perl modules MUST be installed in order to run second example. (reffer to your Perl distribution documentation how to install them if they are not already installed) Perl should be compiled with -Dusemultiplicity Virtuoso Universal Server with Perl Runtime Hosting module Tutorial Example The following tutorial shows how Perl scripts using CGI.pm are executed within Virtuoso HTTP server. Please follow the steps below to maximize the value of this tutorial: Click on the "Run" links to actually experience the demo Integrating Python Scripts with Virtuoso Fri, 27 Dec 2019 14:12:52 GMT Using Python code to extend Virtuoso. Overview The following tutorial demonstrates how Virtuoso can be extended through the use of Python. The demonstrations in this section highlight transparent integration (hosting) between Virtuoso and the Python Runtime. Prerequisites The following prerequisites ensure the usability of these tutorial demos on any platform with a Python runtime: Python 2.2 Python should be compiled to have lybpython2.2 as a shared object Python should be compiled with -DWITH_THREADS Virtuoso Universal Server with Python Runtime Hosting module Tutorial Example The following tutorial shows how Python scripts using cgi.py are executed within Virtuoso HTTP server. Please follow the steps below to maximize the value of this tutorial: Click on the "Run" links to actually experience the demo Integrating Ruby Scripts with Virtuoso Fri, 27 Dec 2019 14:12:52 GMT Using Ruby code to extend Virtuoso. Overview The following tutorial demonstrates how Virtuoso can be extended through the use of Ruby. The demonstrations in this section highlight transparent integration (hosting) between Virtuoso and the Ruby Runtime. Prerequisites The following prerequisites ensure the usability of these tutorial demos on any platform with a Ruby runtime: Ruby 1.8.2 or higher Ruby should be compiled to have libruby.1.8 as a shared object Virtuoso Universal Server with Ruby Runtime Hosting module Tutorial Example The following tutorial shows how Ruby scripts using cgitest.rb are executed within Virtuoso HTTP server. Please follow the steps below to maximize the value of this tutorial: Click on the "Run" links to actually experience the demo Basic JSP Hosting Demo Fri, 27 Dec 2019 14:12:52 GMT Hosting JSP controls within Virtuoso. Overview The HO-S-17 tutorial shows JSP hosting. Prerequisites * * Tutorial Example To execute each of these jps pages click on the "run" hyperlink in the "Action" column. For troubleshooting tips, refer to the "Environment Setup" section in "Runtime hosting" chapter of the Virtuoso documentation. W3C XML Query Workgroup Testsuite Fri, 27 Dec 2019 14:12:54 GMT W3C XML Query Workgroup Testsuite Filter WebDAV content content by XQuery Fri, 27 Dec 2019 14:12:54 GMT fn:collection usage example Preliminary XQuery collection function can be used to get all parsed documents in collection. Virtuoso engine supports several types of collections: http://local.virt/DAV/PATHTO - local DAV collection. Contains all documents in DAV collection with path "PATHTO". http://host:port/path - any other URL that can be used to access remote WebDAV collections In this example collection function is used to filter local blog entries and all cached blog entries from subscriptions. search.vsp uses this collection to filter blogs by XPath exression. For instance, search.vsp with '//a' expression returns all link from all blogs. text.vsp uses collection function to search blogs which contain some word. Note, it uses "contains" predicate to search blogs, this means it is case sensitive. Prerequisites This example needs the following VAD packages to be installed: Conductor Framework Briefcase Feed Manager Weblog If you do not have permissions to install the above please ask the administrator. The VAD installation can be done via Conductor (if it's installed) or via ISQL tool using vad_install() API function. For more details on vad installation please read the user manual. Important: before to run any of the actions bellow you need to setup a ODS account (or use tutorial_demo with password secret). In both cases you will need to login in ODS and create instances of the Briefcase, Feed Manager and Weblog applications. Using the Feed Manager you should subscribe to some news feeds in RSS, Atom or RDF format. Using the Briefcase you can upload some sample data in the account's home directory. Using the Weblog, make few sample blog posts. Example overview This example demonstrates: XQuery collection function XPath extension functions WebDAV Resource Filtering and WebDAV Extension Types (DETs) Example Operation Login into ODS using the link bellow, after successfull authentication the ODS login will redirect browser back to this page Using the link 'Run' start the search.vsp Initially you will have the ODS account's home directory set as a base, so you can change it using the browse button If you don't have initial data loaded or data which not satisfies the conditions, the query execution will be produce empty result. Example Setup The demo support functions are prepared by loading the supplied SQL file How to run the examples In order to enter the initial data via ODS you need to login and create instances via ODS. After entering the initial data, you will need to go back to this page. If you already done this just skip this step In order to run the examples, you need to login in the Web Applications. To login you can use the already defined user "tutorial_demo" with password "secret" case sensitive. When you click the "Run" link of the search.vsp file the browser will be redirected to ODS login page. After succefull login the browser will be redirected back to this page. Filter blogs content by XQuery Fri, 27 Dec 2019 14:12:54 GMT collection usage example Example collection description XQuery collection function can be used to get all parsed documents in collection. Virtuoso engine supports several types of collections: http://local.virt/DAV/PATHTO - local DAV collection. Contains all documents in DAV collection with path "PATHTO". http://..... - any other URI relates to remote DAV collections In this example collection function is used to concatenate the entries from several RSS feed files and show their titles and link to the articles. example.vsp uses this collection to filter blogs by XPath exression. For instance, example.vsp with '//link' expression returns all link from all feeds. Click on the "Set initial state" link to load the XML files in /DAV/feeds/xq_s_2a/ DAV Collection. Click on the "Run" link to experience the demo. Please note that some of the options query files loaded in demo XQ-S-2. Slashdot RSS feed retrieval Fri, 27 Dec 2019 14:12:54 GMT document usage example Example document description XQuery document function can be used to get a parsed document via URL. In this example the document is used to retreive the Slashdot RSS feed and convert the contents into a feed index. Click on the "Set initial state" link to load the slash.xml file in /DAV/xmlsql/ DAV Collection with execute permisions. Click on the "Run" link and the browser will be redirected to /DAV/xmlsql/slash.xml?contenttype=text/html. OPML file generation from XHTML source Fri, 27 Dec 2019 14:12:54 GMT document usage example Example The demo retrieve a HTML pages containing attendees or bloggers listings and convert them to OPML. The conversion is done with XQuery and user-defined XPath functions to resolve the feeds URLs. The demo also retrieve few OPML files and re-construct them having the feeds URLs if they are missing. When setting the initial state, the demo starts to retrieve pages from the different sites. It could take a long time depending on the Internet connection of the machine that Virtuoso is running on. It is safe to leave the pop-up open without waiting it to finish and press on the "Run" links, however if this is the first time you run the initial state, the demo will show only partial results. Once the feeds are resolved they will be cached locally in a database table and the generated OPML files will be stored as a WebDAV resources. The following are source references used in the demo: http://wiki.techcrunch.com/third_meetup http://news.com.com/html/ne/blogs/CNETNewsBlog100.opml http://conferences.oreillynet.com/pub/w/23/speakers.html http://conferences.oreillynet.com/pub/w/38/speakers.html http://www.alwayson-network.com/comments.php?id=10852_0_11_0_C http://www.gnomedex.com/holdings/br_2005%20Gnomedexers.opml http://www.web2con.com/pub/w/40/speakers.html http://www.thenewpr.com/wiki/pmwiki.php?pagename=Resources.CEOBlogsList http://nwr.cowblock.net/index.php?action=list http://okrasoup.typepad.com/black_looks/2005/05/naija_blogs.html http://allafrica.com/afdb/blogs/blogafrica.opml SPARQL Query Language Fri, 27 Dec 2019 14:12:54 GMT SPARQL Query Language Demo Tutorial Description The following tutorial depends on the sparql_demo_dav.vad package, which is preinstalled in the demo db. If you are running demo database or have installed sparql_demo_dav.vad package try this link /sparql_demo/. If not run your demo db and point your browser to http://[host]:[port]/sparql_demo/ Linked Data Fri, 27 Dec 2019 14:12:53 GMT Getting Yourself a Linked Data URI in 5 minutes or less Concept This demonstration guides you through the process of creating presence on the Semantic Web by creating a Linked Data URI. There are simple instructions: Downloading Virtuoso (Commercial or Open Source) Download and install Virtuoso installation archives Download and install OpenLink Data Spaces (ODS) installation packages (VADs) Start with OpenLink Virtuoso Build OpenLink Virtuoso OpenLink Virtuoso User Guide Simple steps registering ODS user Go to ODS Framework Click Sign Up Register either using the sample form or with existing OpenID Import data to your ODS profile using the "Import" feature Go to Edit profile Open Import page Enter FOAF Url or choose LDAP server Import RSS Feed in your Dataspace Go to Feed Manager Click Admnistration Click Subscribe Now view the link: http://[host:port]/dataspace/person/[username]