www.openlinksw.com
docs.openlinksw.com

Book Home

Contents
Preface

Administration

Database Server Administration
HTML based Administration Console (Conductor) Guide
Virtuoso Conductor Administration Runtime Hosting Web Services WebDAV Administration Internet Domains XML Services Query Tools Replication & Synchronization Database Administration Conductor News Server Administration

6.2. HTML based Administration Console (Conductor) Guide

This section describes how to administer the Virtuoso server from the Conductor interface. It primarily allow users to administer the server while giving access to many of the features that Virtuoso has to offer providing many conceptual demonstrations and introductions.

Most of the pages from the administration interface are provided to help administrators quickly and easily tune the Virtuoso server or navigate the various interfaces and features that Virtuoso has to offer.

6.2.1. Virtuoso Conductor Administration

The Main Navigation Bar provides different tabs that allow you to administrate your Virtuoso server or use one of the provided samples.

Navigation
Figure: 6.2.1.1. Navigation

From "System Admin" you can view and change the Conductor Dashboard, manage user accounts; scheduler; Virtuoso Server parameter and Access Control Settings. You can also install /upgrade /uninstall Virtuoso packages and Monitor Virtuoso Server Statistics.

System Administration
Figure: 6.2.1.2. System Administration

From "Database" you can administrate your database, manage the Virtuoso Relational Database System, administrate views, tables, stored procedures, trigger definitions, user define types, backups.

Database Administration
Figure: 6.2.1.3. Database Administration

From "Web Application Server" you can configure Virtuoso's WebDAV, and HTTP Server functionality, which includes management of Virtual Domains & Directories.

Web Application Server Administration
Figure: 6.2.1.4. Web Application Server Administration

From "XML" you can query Relational and XML Data using SQL, XQUERY, XPATH, and FREE TEXT.

Query Tools
Figure: 6.2.1.5. Query Tools

From "Web Services" you can add/ edit/ remove Web Services Endpoints, perform WSDL Import/Export, manage your BPEL processes.

web Services
Figure: 6.2.1.6. web Services

From "Replication" you can create Snapshot Replications to copy sections of the Database to remote locations or use Transactional Replication to keep Virtuoso Servers in sync over a definable interval.

Replication
Figure: 6.2.1.7. Replication

From "RDF" you can execute/save/load SPARQL queries, add/edit RDF Mapping.

RDF
Figure: 6.2.1.8. RDF

Virtuoso's NNTP support which includes linking third-party NNTP servers into Virtuoso and controlling access to these servers.

NNTP Administration
Figure: 6.2.1.9. NNTP Administration

6.2.2. Runtime Hosting

The runtime hosting interfaces require Mono/CLR and Java extension servers.

6.2.2.1. Loaded Modules

You can view Loaded Modules list and each Module you can "Unload". Also you can browse for Module and examine its content.

Loaded Modules
Figure: 6.2.2.1.1. Loaded Modules

6.2.2.2. Import Files

To import files click the "Browse" button and select the class you want to import. Then click the "Add to list" button.

Import Files
Figure: 6.2.2.2.1. Import Files

6.2.2.3. Modules Grants

In order to change grants to a particular Module, select the desired grant value from the "Grant to" list and click the "Add" button.

Modules Grants
Figure: 6.2.2.3.1. Modules Grants


6.2.3. Web Services

6.2.3.1. Import Targets

Virtuoso can be set up to retrieve content from external web sites and host it in its own WebDAV repository via this page.

Web Robot - Target
Figure: 6.2.3.1.1. Web Robot - Target

Target Description lets you provide a friendly description for the target that you are defining.

Target URL is the url of the web site that you are trying to retrieve content from. Only the hostname should be provided here, along with the protocol. For example http://www.myhost.com.

Login name on target is the username for accessing the remote server, if required.

Login password on target is the password for the login name above.

Copy to Local DAV collection is the name of the collection (folder) where retrieved content will be stored in Dav.

Single page download radio button specifies whether Virtuoso will retrieved linked content also.

Local Resources Owner The DAV user that will be the owner of the content that will copied to DAV.

The Download only newer than field allows you to specify a datetime value to prevent Virtuoso downloading files that are older than that datetime.

Use the Follow Links Matching field to limit the content that is downloaded by specify pattern matching criteria.

Do NOT follow links matching allows you limit content by specifying what files not to download.

Download Images radio buttons to allow Virtuoso to pull down image type also. You may want to prevent this if you are more interested in the textual content rather than bandwidth draining images.

Use WebDAV methods can be checked if the host is known to support WebDAV methods. This would enable better copying of sites that support DAV.

Delete if Remove on Remote is Detected can be switched on so that when Virtuoso synchronizes its content with that on the remote host it will check for files that have been removed on the remote and remove them from the local copy also.

Store metadata* when checked offers to be stored respectively metadata from FOAF, RDF, RSS/RDF and GRDLL data depending on which check-box is checked.

When all details have been completed press the Add (or Update if updating) button to submit the web robot task to the queue.


6.2.3.2. Import Queues

The "Imported Queues" page shows you a list of web copy targets that have been enlisted with the Virtuoso Server, and a list of web robot update schedules. Several options are available for each item listed: Start, Update, Schedule, Reset, and Stop. You can configure the scheduled update interval by pressing the Schedule link and entering a value in minutes. Once that is done you can start the schedule by pressing the Start link. You make a manual update of the content by pressing the Update link. You can stop the scheduled updates taking place by pressing the Stop link. To reset the details of the web copy item press the Reset link.

Web Robot - Queues
Figure: 6.2.3.2.1. Web Robot - Queues

6.2.3.3. Retrieved Sites

You can view a list of the links retrieved from the web copy from this page. You are also able to remove some of the content from this page by following the Edit link.

Web Robot - Retrieved Links
Figure: 6.2.3.3.1. Web Robot - Retrieved Links

6.2.3.4. Export

You can export content from the WebDAV repository. Note that you can only export content that has been retrieved using Virtuoso's Web Robot.

When you click the "Export" link for a retrieved collection, you will be presented with a form for selecting the export target location. Choose the export method: either File System or DAV by clicking the "External WebDAV Server URL" check-box. This lets you indicate to the remote target where to store the exported content. Then type the target URL to an existing location on the server. Finally press the Export button to export. A confirmation will be supplied once the operation is complete.

Web Robot - Exporting Content
Figure: 6.2.3.4.1. Web Robot - Exporting Content
Note:

If is not checked the "External WebDAV Server URL" check-box, i.e. you are selecting the filesystem method, then you are restricted to Virtuoso targets. However WebDAV methods can be applied to any WebDAV server. WebDAV methods assume that the target is publicly available for writing.


6.2.3.5. Access Control

From "System Admin"/"Access Controls" you can manage Rules and ACL respectively for HTTP, News and Proxy.

Access Control Lists
Figure: 6.2.3.5.1. Access Control Lists

For each of the tabs "HTTP", "NEWS", "PROXY" the created rules will be shown in a list with Filter, Access, Destination, Object, Mode, Rate values. You can also add/delete rules, re-arrange rules order.

Access Control List for HTTP
Figure: 6.2.3.5.2. Access Control List for HTTP

Click the link "Edit" for a rule. Then specify the filter and access values.

Access Control Lists
Figure: 6.2.3.5.3. Access Control Lists

6.2.3.6. Import WSDL

From "Web Services" / "WSDL Import/Export" you can provide a URL to a WSDL description. In return Virtuoso will automatically provide a wrapper for the services available, hence stored procedures and user-defined types that are callable within Virtuoso while the processing and mechanics of the services are actually handled at the source.

WSDL Import
Figure: 6.2.3.6.1. WSDL Import

After Virtuoso examines the supplied URL to a WSDL you are presented with the source code for the PL wrappers and Virtuoso user-defined types to be created. You have the chance to edit the code for more specific needs and then you can either save this to a file for later work, or execute it in Virtuoso to create the procedures and types.

WSDL Import
Figure: 6.2.3.6.2. WSDL Import

Any errors in the code will be highlighted if you try and execute it.

If you wish to save the file the appropriate file system ACLs must be in place for the destination.



6.2.4. WebDAV Administration

DAV, or WebDAV, is a protocol for Web-based Distributed Authoring and Versioning. The location where content items are placed is called the repository. Content elements are called documents, corresponding to files, and folders/collections, corresponding to directories. Collectively these documents and folders (collections) are known as resources.

Virtuoso implements the DAV protocol, allowing you to create and manage resources either directly through repository manipulations or indirectly, through a variety of WebDAV services.

6.2.4.1. DAV Resource Types

To make sure that when Virtuoso serves files to client user agents the type of file is conveyed properly so that the right application can be used with that file a list or file types are maintained in the server. This list is used when sending any content via the HTTP server which include content in DAV and under VSP.

DAV Resource Types
Figure: 6.2.4.1.1. DAV Resource Types

The Web Application Server/Content Management/Resource Types page shows the list of currently defined resource types in the Virtuoso server. You can edit or remove these types by using the action links on the right most column of the list next to the type applicable.

Add new types by typing the details into the fields provided and pressing the Save button.


6.2.4.2. Content Management

The content management page gives you an interface to the WebDAV repository resources. From here you can navigate or create directories, commonly referred to as collections or folders in DAV, alter properties, upload or remove files, or edit documents.

The Repository tab lists the current location within the tree and the current login name. The root of the repository is usually /DAV/.

Content Management
Figure: 6.2.4.2.1. Content Management
6.2.4.2.2. Resource Names

Resource names are given with collection (folder) names listed first, then individual documents. Permissions on resources are presented in a style similar to Unix, with (r)ead, (w)rite, and e(x)ecute permissions listed for the resource owner (the user), the resource's group, and for the general public. If a permission is present, the letter is shown; if not, it is replaced with a dash.


6.2.4.2.3. Resource Permissions

Unlike Unix, the Repository does not use the designation 'd' for directories, which in DAV are more commonly referred to as collections. Collections are distinguished by a different icon - a folder-like icon - and by having the type named "collection".

In addition, the permissions string has a trailing letter designating the indexing status of the resource. This letter is 'n' to designate that indexing is off, 'r' for recursive indexing, and 't' for direct indexing.


6.2.4.2.4. Resource User and Group

By default, the user and group of a DAV resource are those set by the service that created the resource, or they are the ID and primary group of the user who was logged in when the resource was created.


6.2.4.2.5. Resource Size

The size of a document resource is its size in disk bytes. Note that this does not necessarily correspond to characters displayed on the screen because of encodings. For example, the HTML token &-a-m-p-semicolon is five bytes on disk but displays as a single screen character.


6.2.4.2.6. Resource Type

The type of a resource is always "collection" for collections (folder). For documents it can be any of the known resource types (see Resource Types below). The resource type is usually based on the resource's extension; for example, .xml files are usually assumed to be text/xml. If Virtuoso does not recognize the extension of a resource, it assigns the default type of application/octet-stream.


6.2.4.2.7. Editing Properties

Within the Content Management screen, you can change any of the properties of a resource, other than its name, by selecting the resource via the checkbox to the left of the icon, and pressing the "Properties" button.

XML documents also permit you to edit their XML properties specifically. This can be done on any document of type text/xml by clicking on the icon for the document.

Properties

When clicked this button from the bottom of the page, you can edit the properties for one or a group of resources which should be selected. The name of a resource cannot be changed.

The owner, group, permissions, and indexing controls on this form apply to the appropriate properties of resources, as documented above. Changes to the type of a collection (folder) are ignored.

The "Property" control permits you to change or add additional properties. There is a pulldown of predefined XML-related properties, or you may create your own property.


WebDAV Properties

This control permits you to manipulate the specific properties of XML documents. Existing properties are shown with their values, and can be removed. New properties can be added.

XML-related properties are generally set by specific XML-related services and do not need to be edited directly by users; however, this interface provides a quick means to correct a minor typo or other change without re-running the entire service. For example, you can change the xml-sql-root property, which controls the name of the root XML element for the document.



6.2.4.2.8. Adding New Resources

Resources may be added to the repository in two ways: by uploading files or by creating new collections (folders). Buttons for both these methods are on the page.

The "Create Folder" button brings up a form in which you can specify the name of the collection (folder), its owner and group, and the initial permissions. You may also turn on indexing for the folder's contents at this point.

The "Upload File" button brings up a form in which you can specify the name and location of a file on your local computer that is to be copied into the DAV repository. You need to specify the name of the resource in the repository and give it a type. You can also set the basic repository properties here.

WebDAV Symbolic Linking

WebDAV symbolic linking, also known as DAV redirection, is another method for accessing content from your DAV repository. Instead of directly copying or creating resources, as described above, symbolic linking permits you to create a reference to a resource. In this sense it is similar to the "Create Shortcut" feature of Windows, "Make Alias" on MacOS, and the "ln -s" command on Unix systems.

This capability enables Virtuoso users to import resources from a plethora of sites such as webzine articles and keep references to these imported resources in sensible locations for future reference.

In the Virtuoso Conductor WebDAV Content Manager, links appear and are accessed just as you would see a created resource. Their Type is Link:<Target> where the target is the URL of the resource being linked.

To create a link, you first navigate to the DAV Repository location where you want the alias to reside. Then click the Create Link button at the bottom-right of the screen. This brings you to a screen where you can specify the Link Name, as it will appear in your DAV Repository. The Link to field can be given a full URL, as in the example below, or you can use the Browse button to target a resource elsewhere in the DAV.

Linked resources do not permit direct Edit operations. You can change the Target by editing the redirectref property of the link. To view the resource, simply click its Name.

Examples:

If I wish to keep a link to the article found at <URL: http://www.xml.com/pub/a/2001/10/17/slippery-soap.html> I would simply click the Add Link button, type a useful local name, such as "Slippery SOAP article" and paste the URL into the Link to field.

More interesting, I could set up a Web Data Import for the target <URL: http://news.cnet.com/news/0-1277-210-7545619-1.html?tag=bt_bh>

When this URL target is imported, Virtuoso will replicate the traversal path within the DAV repository that results in multiple access point locations for each import. Using the symbolic link feature, we are able to map the actual documents imported to a common location without encountering problems related to component references, embedded links, etc.




6.2.4.3. Free Text

6.2.4.3.1. Indexing Mode

When files are inserted into Virtuoso's WebDAV repository, if their type is a type of text file such as plain text TXT, XML, or HTML, then they may be automatically free text indexed.

By default files are automatically free text indexed as they are inserted into Virtuoso. This is very convenient but can be time consuming if you frequently insert or update text files. For this reason Virtuoso can be set to index in batch mode at a particular interval in minutes.

DAV Free Text Index Configuration
Figure: 6.2.4.3.1.1. DAV Free Text Index Configuration

To change the free-text index mode to batch mode check the check-box and provide a non-zero time interval (in minutes). Press the Accept button to save the changes into the server.




6.2.5. Internet Domains

6.2.5.1. HTTP Virtual Directories

From Virtual Domains & Directories you can define Virtual HTTP directories. Virtual Directories let you define multiple HTTP server listeners in Virtuoso for either the same network interface or another one. Virtual directories can respond logically to a name or directly by IP address. Both types as well as default responses can be defined here.

Each virtual directory can also have HTTP maps defined for it. This allow you to set logical paths on an HTTP directory to point to specific directories available to Virtuoso through the file system or DAV.

You can also publish stored procedures to a SOAP defined directory during the virtual directory definition.

Virtual Directories
Figure: 6.2.5.1.1. Virtual Directories

Click on the Add New Site button to start adding a new Virtual Web Site and its directories.

Virtual Directories: Site Details
Figure: 6.2.5.1.2. Virtual Directories: Site Details

When adding or editing a web site you must supply a host.domain name, which will be used to match again incoming requests to produce the correct response, the IP address of the network interface, to set-up the listener on, and the TCP port number that will be used to listen for incoming requests. Although Virtuoso will be listening on the specified interface you can set up multiple sites on this interface. The site required by client web browsers will be determined by the host name specified in the request. This provides the virtual site.

Click on "New Directory" to continue.

Virtual Directories Mappings
Figure: 6.2.5.1.3. Virtual Directories Mappings

Before the directory settings are configured you can select from a few types to help configure the details to follow quicker and easier. For SOAP virtual directories this step is particular useful.

Select "Type" and then click "Next" to continue.

Virtual Directories
Figure: 6.2.5.1.4. Virtual Directories

The "Virtual Directory Information" tab lets you configure most aspects of the virtual directory.

The default directory checkbox can be checked if you want the site being defined to act as the default site for the interface. This means that if a request is made to the interface that does not match a hostname defined for the interface, the default will be returned.

Logical Path will be the path that Virtuoso will respond to for this virtual directory mapping. This is what will be placed on the URL. Physical Path or URL is what Virtuoso will actually supply the content from. In either case you can use the Browse buttons to traverse the file systems graphically. Use the WebDAV Source Checkbox to instruct Virtuoso to use the WebDAV store for the physical location. "Default Page" will be returned if no page is specified in the incoming URL.

Note:

Virtual directories for SOAP must always use a physical path of /SOAP/.

The physical path of /SOAP/ does not need to exist in the filesystem under the VSP-root directory for normal SOAP operation. If it does existing it can be used to answer non-SOAP requests. Thus, configuring the virtual directory for SOAP with a "Default Page" can be used to avoid SOAP clients receiving HTTP 404 errors when testing the SOAP endpoint using standard HTTP only. Some SOAP applications assume the SOAP endpoint is down if they received HTTP 404 without checking the SOAP endpoint itself.

The permissions panel lets you choose whether to enable various abilities in the directory.

In the SOAP Options section you can publish or unpublish procedures and/or templates, both native and remote to the virtual directory using the Publish/Unpublish buttons respectively. The SOAP Options text-area allows you to specify other SOAP options such as DIME encapsulations and WS-security settings. These options are supplied as name=value pairs terminated with a semi-colon and a carriage-return. Here is an example of the options used for the default Interop test based demo virtual directory:

Namespace=http://soapinterop.org/;
MethodInSoapAction=no;
ServiceName=InteropTests;
HeaderNS=http://soapinterop.org/echoheader/;
CR-escape=yes;
See Also:

For a list of available SOAP Options review the end section of the SOAP chapter: Optional Parameters to the SOAP Endpoint.

The Authentication Options panel lets you define the authentication rules for the Virtual Directory.

Once the form details have been completed press on the Add button to save the them and proceed to configure mappings for the directory.

Virtual Directories Mappings
Figure: 6.2.5.1.5. Virtual Directories Mappings

This screen lists mappings that have been defined for the virtual site. If you have just created a fresh site then only one line will be displayed. The "Add Virtual Directory" button will let you define more. Back returns you to the start page, Edit and Delete allow you to edit or remove existing mappings as their link suggests.

See Also:

Virtual Directories

For example, here are the basic steps to be performed, in order to mount FS folder to DAV:

Suppose there is a folder with name "test" in your FS and it is under the root of the ServerRoot defined in your virtuoso ini file.

Also suppose in the folder "test" there is a file index.html with simple content:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
  <head>
    <title>OpenLink Virtuoso Conductor Simple Test</title>
  </head>
  <body>
    <table cellspacing="0" cellpadding="0" border="1" width="50%">
      <tr>
       <td><b>Name</b></td><td></b>State</b></td>
      </tr>
      <tr>
       <td>Simple test for mounting FS to DAV</td><td>Successful.</td>
      </tr>
    </table>
  </body>
</html>
  

Install the Conductor package

Go to http://host:port/conductor and login as dba user.

Go to Web Application Server -> Virtual Domains & Directories.

Mount FS to DAV
Figure: 6.2.5.1.6. Mount FS to DAV

For your {Default Web Site} click the link "New Directory".

Check the check-box "Type" and select from the drop-down list "Filesystem".

Mount FS to DAV
Figure: 6.2.5.1.7. Mount FS to DAV

Click "Next"

In the shown form: Enter for the field "Path": mytest; Enter for the field "Physical path": /test; Enter for the field "Default page": index.html; Check the check-box "Allow Directory Browsing"; Leave the rest of the fields with their default values.

Click "Save Changes"

Mount FS to DAV
Figure: 6.2.5.1.8. Mount FS to DAV

From your browser access the url: http://host:port/mytest/

As result the content of the index.html file will be shown:

Mount FS to DAV
Figure: 6.2.5.1.9. Mount FS to DAV


6.2.6. XML Services

6.2.6.1. SQL-XML Statements

Go to XML/SQL-XML and enter a SQL to XML statement in the SQLX or SQL-XML Query text-area:

For example:
SELECT "product".ProductID AS "id",
  "product".ProductName AS "name"
FROM
  "Demo"."demo"."Products" as "product"
FOR XML AUTO ELEMENT
SQL-XML Statements
Figure: 6.2.6.1.1. SQL-XML Statements

Type the root XML element name into the Root Element field. The results of the query will be contained within this root element.

Type the full path and resource name where you want your XML resource to reside under WebDAV in the WebDAV Resource path for the result field. Collection(s) described in the full path must already exist.

You may use the Browse button next to the WebDAV Resource path for the result field to navigate existing WebDAV collections (folders) or resources to store the result of query.

From the "Stored Queries" tab if you choose a resource that already exists as a query in WebDAV resource, after click the "Edit" link, the form will automatically acquire the details from the query.

If an XSLT transformation should be performed on retrieval time then you may either type the location of the stylesheet in the Stylesheet field or press the Browse button next to it to search for a valid XSLT stylesheet from the WebDAV repository.

Provide the appropriate WebDAV owner and group of stored result using the drop downs provided.

Select appropriate permissions for the stored result.

The query can be set to update itself at specific intervals of time or execute every time the resource is retrieved. If Persist XML is checked the query will be executed on Update every 10 minutes by default.

Press the Execute button to execute the statement and store as a WebDAV resource. Use Reset to clear the form

If you want to build a schema definition for the result then press the Create XML Schema radio-button.

Virtuoso can provide the generated XML output with a full DTD for the data. Press Create External DTD to enable this option for the query.


6.2.6.2. XQuery Search

Go to XML / XQuery /Xquery Basic.

XQuery Document Search applies the XPATH expression to every realized XML contained within the Query Scope to qualify search hit results. Note that this does not include XML Views unless persistent.

XPATH Query of DAV
Figure: 6.2.6.2.1. XPATH Query of DAV

Choose the Scope of Query from within the WebDAV repository. You may define the scope as either No Context, DAV Resource (file), DAV Collection (folder), External Document URL, External Collection URL or Database Table. Use the Browse button to browse the contents of WebDAV to make a selection. The query will then be confined to the selected resource or collection and its children. Then Click the button "Next" in order to continue.

XPATH Query of DAV
Figure: 6.2.6.2.2. XPATH Query of DAV

Enter that XPATH query expression into the text area that you wish to interrogate your WebDAV XML documents with. e.g. //* or //title

The Root Element field allows you specify the name of the root element to contain document element matches for each document found. This aids stylesheet design.

Choose an Output Style Sheet by either typing its URL or using Browse to select an XSL resource from WebDAV. You only need to specify a style sheet if you want to transform your XML results using XSLT.

Click the button "Next" in order to continue.

Choose an Store into location by either typing its URL or using Browse to select a DAV resource from WebDAV

Set Permissions for the output result. Check "r" for read rights for Group and Users in order to view later the saved xml file.

You may want to Replace the existing resource by checking the shown check-box with this label.

Choose Output Type that you wish to obtain. Persist XML should be selected with Update interval im minutes or if you want to be created as XML Template, fill in the "Create as XML Template Description" field.

Click the button "Save".

XPATH Query of DAV
Figure: 6.2.6.2.3. XPATH Query of DAV
XPATH Query of DAV
Figure: 6.2.6.2.4. XPATH Query of DAV

If for location you have chosen /DAV/xmlsql/xquery.xml, you can view the saved file accessing the url: http://host:port/DAV/xmlsql/xquery.xml

XPATH Query of DAV
Figure: 6.2.6.2.5. XPATH Query of DAV


6.2.7. Query Tools

6.2.7.1. Relational Data using SQL

Conductor Interactive SQL allows you to quickly and directly query Virtuoso using SQL. It offers Save and Load facilities which allow SQL queries to be saved as an XML template, and read back later. With a query in the SQL Statement box click on the Execute for the results which will in the "Base" tab with option to return back to the query area. The Clear clears the SQL Statement text box.

Querying Relational Database Using SQL
Figure: 6.2.7.1.1. Querying Relational Database Using SQL
Results
Figure: 6.2.7.1.2. Results

Specify the location for the file to be saved to by selecting the "WebDAV source" or "Local file" check-box.

Saving SQL in an XML Template
Figure: 6.2.7.1.3. Saving SQL in an XML Template

Click the "Browse" button. As result will be opened the Virtuoso WebDAV/File Browser where you should define the XML template based on the SQL Query. Specify a Root Element that will contain the resulting XML tree. Specify the file name and location of the XML Template.


6.2.7.2. XML Data Using XQuery

The Conductor Interactive XQuery facility allows you to create, execute, save and reload queries using the evolving W3C XML Query (XQuery) Language. Virtuoso currently supports the 1.0 version of this language.

This language uses XPath-like expressions, as well as a set of functions and operators, to permit effective parallel searching of a set of XML documents. Where XPath works with one XML "tree", XQuery searches a "forest". The result is an XML document.

In order to create an XQuery you must both create the query statement – by typing or pasting it into the text box – and specify the document context. Since Virtuoso's XQuery implementation operates over XML data in relational tables, this means the tables and columns that are to be searched.

Note that the XQuery language also allows a query to specify all or part of the document context for the query. In the example below we will see how these can interact. The user interface form permits you to select a table – either one of the XQuery test data tables that come with Virtuoso, or the WS.WS.SYS_DAV_RES table, which stores Virtuoso's WebDAV Repository content.

The form specifies a Key Column and a Data Column. For the sample tables, the values for these are filled in for you. The Path is prepended to any document() function specified in the query text to find Key column values of XML trees against which the query is to be run.

Once a query has been written and debugged, it can be saved by pressing the Save button. This brings you to the form for saving a query as an XML Template in the DAV repository.

Pressing the Execute button causes the query result (an XML tree) to be shown on the page below the Statement type-in box.

XQuery Test File Example

In this example, we will query the table XQuery test files table, with "name" as the key column and "text" as the data column.

The query text, shown below, is a sample query from the W3C's XML Query Use Cases document (http://www.w3.org/TR/xmlquery-use-cases). This query contains a document() call specifying a document named "bib.xml". In order to have the query run properly, we first set the Path form value to "xqdemo/". This causes the query to find all rows in the table XQ.XQ.TEST_FILES that have the value "xqdemo/bib.xml" in their Name column.

<bib>
   {
   for $b in document("bib.xml")/bib/book
   where $b/publisher = "Addison-Wesley" and $b/@year > 1991
   return
      <book year = {$b/@year}>
         {$b/title}
      </book>
   }
</bib>
XQuery Test File Results
Figure: 6.2.7.2.1. XQuery Test File Results


6.2.8. Replication & Synchronization

6.2.8.1. Snapshot Replication

Conductor "Replication" offers manage Virtuoso Replication. You are offered with "Basic", "Incremental", "Bidirectional Snapshot" and "Transactional" sub-tabs-

From Replication/Basic/Query(Table select)to local to replicate local table(s) to another data source click Create New Snapshot and follow the wizard.

To copy the changes from the local table to the remote select some replications and press Synchronize

To drop the replication definition without dropping the destination table select some replications and press Remove

To drop the replication definition and the destination table select some replications and press Remove & Drop Remote

To copy the changes from the local table to the remote automatically select some replications, enter minutes in Scheduled Interval and press Schedule

To remove scheduled update select the replications enter 0 in "Scheduled Interval" and press Schedule

Snapshot Replication
Figure: 6.2.8.1.1. Snapshot Replication
Snapshot Replication
Figure: 6.2.8.1.2. Snapshot Replication
Snapshot Replication
Figure: 6.2.8.1.3. Snapshot Replication
Snapshot Replication
Figure: 6.2.8.1.4. Snapshot Replication
Snapshot Replication
Figure: 6.2.8.1.5. Snapshot Replication
Snapshot Replication
Figure: 6.2.8.1.6. Snapshot Replication
Snapshot Replication
Figure: 6.2.8.1.7. Snapshot Replication

6.2.8.2. Transactional Replication

6.2.8.2.1. Publications

The Transaction Publication screen lists publications. You can add, edit or remove publications as necessary, each time using the guide-lines of the wizard.

Transaction Replication - Publications
Figure: 6.2.8.2.1.1. Transaction Replication - Publications

When creating a new publication you must supply a name. At this point you have the option to create an updateable publication - see the Bi-Directional Transactional Replication section for more details - which allows updates to come from subscribers rather than being limited to originating from the publisher only.

Transaction Replication - New Publication
Figure: 6.2.8.2.1.2. Transaction Replication - New Publication
Transaction Replication - List of Publications
Figure: 6.2.8.2.1.3. Transaction Replication - List of Publications

Once a new publication has been made you can add database objects to it using the Add ... buttons, or remove them by selecting their checkbox and using the Remove button. To add a new table to the publication click on Add Table/Procedure. Follow the wizard by choosing the appropriate database/catalog by clicking on its name, you will then be presented with the tables within it.

Transaction Replication - Publish Tables and Procedures
Figure: 6.2.8.2.1.4. Transaction Replication - Publish Tables and Procedures

Select the tables to publish using the checkboxes and press Add to Publication to add the tables and continue.

Once returned the publication screen, the published tables will be listed. Updatable publication will need conflict resolvers in case of conflicting data arriving from a subscriber. Click on the table name to manage the resolvers list.

Transaction Replication - Published Items
Figure: 6.2.8.2.1.5. Transaction Replication - Published Items

Use the Add/Remove to add or remove selected resolvers.

Click on New Resolver to add a new resolver. You have the following details to contend with:

Transaction Replication - Resolvers
Figure: 6.2.8.2.1.6. Transaction Replication - Resolvers
Transaction Replication - Advanced
Figure: 6.2.8.2.1.7. Transaction Replication - Advanced

6.2.8.2.2. Subscriptions

To add new subscription click at New Subscription and follow the wizard.

Click Edit to change properties.

To drop subscription click at link Drop.

To synchronize subscription click the Sync button.

To disconnect all subscriptions click at Disconnect all button.

To load image file click at Load image button and follow the wizard

Transaction Replication - Subscription
Figure: 6.2.8.2.2.1. Transaction Replication - Subscription
Transaction Replication - Subscription
Figure: 6.2.8.2.2.2. Transaction Replication - Subscription



6.2.9. Database Administration

6.2.9.1. Users & Group Accounts

From System Admin / user Accounts you can alter the users that can access the Virtuoso database. You may add a new user by clicking the "Create New Account" link, edit an existing user, or delete users. You can associate users with groups or make new groups.

Groups are created and function like normal user accounts. To define a group you simply create a new user, and then to make use of the group you assign users to that group from the drop down which will contain available groups.

To create a new user or group you must enter a username, password and confirm the password by retyping it in the fields provided. You may optionally specify a group and default qualifier. You can use groups to control access to a set of users by maintaining the permissions granted to the group for which they are members. Specifying a default qualifier allows you to specify the catalog or database for which queries will be run against that do not explicitly refer to a particular catalog or database.

You can import users by adding LDAP Servers(s) from the "LDAP Servers" tab, and then from the "LDAP Import" to specify from which LDAP server the import should be done.

Users Accounts
Figure: 6.2.9.1.1. Users Accounts

6.2.9.2. Databases

Each catalog (database) within Virtuoso will be listed under the Databases /Schema Objects. For each catalog you will be able to view and in some cases edit details about the tables, views, triggers, and store procedures stored within that catalog.

Viewing Tables details for the Demo catalogue in the Demo Database
Figure: 6.2.9.2.1. Viewing Tables details for the Demo catalogue in the Demo Database
Viewing Views details for the Demo catalogue in the Demo Database
Figure: 6.2.9.2.2. Viewing Views details for the Demo catalogue in the Demo Database
6.2.9.2.3. Demo Database Installation

The Virtuoso Demonstration database can be installed with the Conductor by navigating to the "System Admin" -> "Packages" tab where a list of available Virtuoso applications are displayed, one of which is for the "Demo" database package as shown below:

Install Demo db using Conductor UI: "System Admin" -> "Packages"
Figure: 6.2.9.2.3.1. Install Demo db using Conductor UI: "System Admin" -> "Packages"

Select the "Demo" package and click on the "Install" button to commence the installation process:

Install Demo db: confirmation
Figure: 6.2.9.2.3.2. Install Demo db: confirmation

Click on the "proceed" button to install the indicated "Demo Database" application package:

Install Demo db: proceed
Figure: 6.2.9.2.3.3. Install Demo db: proceed

Once installed the demo database schema can be viewed from the "Database" -> "Schema Objects" tab of the Conductor:

Install Demo db: view schema objects
Figure: 6.2.9.2.3.4. Install Demo db: view schema objects

6.2.9.2.4. Editing Triggers

For each table, Virtuoso gives you the ability to edit the triggers linked to that table, as well as adding new triggers. The link text "Triggers" is followed by a number in parentheses that tells you how many triggers exist associated with that table. If no number is shown, there are no triggers. Clicking on the text takes you to the trigger edit page.

The triggers page shows you the name of each trigger, an excerpt from the text of the trigger, and permits you to edit or drop the triggers. In the last column of the shown form there is a "New Trigger" link for creation of a new trigger.


6.2.9.2.5. Editing Stored Procedures

The stored procedures link shows a page of information about existing stored procedures for the database you are viewing. If there are stored procedures, you can see their names and text excerpts, and you may edit or drop them. Adding new stored procedures can be done via the ISQL command-line interface or from the "Create Procedure" link shown above the list of objects for the relevant database.

Viewing Stored Procedures details for the Demo catalogue in the Demo Database
Figure: 6.2.9.2.5.1. Viewing Stored Procedures details for the Demo catalogue in the Demo Database

Stored procedures may also refer to modules that contain a group of related stored procedures. These are created and edited as a group, rather than individually. An example of this is the module DB.DBA.AmazonSearchService, which contains procedures such as KeywordSearchRequest() and BrowseNodeSearchRequest().



6.2.9.3. External Data Sources

From Database / External Data Sources you will be able to manage the Virtual Database feature of Virtuoso. You are able to administer ODBC Data Sources, how to link remote tables and view, and already linked remote connections.

6.2.9.3.1. Data Sources

This tab shows you the available Data Sources. For these one, to which there is no connection, will be shown the link"Connect". For the datasource for which there is already established connection, will be shown the links "Link objects", "Change Credentials" and "Disconnect".

Remote Datasources connected to Virtuoso
Figure: 6.2.9.3.1.1. Remote Datasources connected to Virtuoso

If you need to alter the authentication details of a particular Data Source then select the "Change Credentials" link. If you want to link new objects, select the "Link objects" link.


6.2.9.3.2. Configure Data Sources

This section will allow you to configure the data sources themselves on the remote machine. The table that will be presented to you will contain both User and System data sources. You will be able to edit and create either User or System data sources, however, Virtuoso will only be able to use the User data sources that belong to the user that started the Virtuoso Server.

Configuring ODBC Datasources
Figure: 6.2.9.3.2.1. Configuring ODBC Datasources

Follow the buttons on the screen as to how you want to manage a data source. You can create new, edit or remove existing data sources.

Configuring A Virtuoso ODBC Datasources
Figure: 6.2.9.3.2.2. Configuring A Virtuoso ODBC Datasources

The Virtuoso Server can make use of File Data Sources too. This provides the usual associated conveniences. These enable you to migrate a Virtuoso database to another machine hosting the same ODBC Driver, Virtuoso then has enough information to connect using the installed driver to a remote data source, the tables would not need to be relinked. File DSN's are read from server's root directory. File DSN's can only be read if this directory is contained in the Virtuoso INI file parameter DirsAllows.

Note:

Windows NT or 2000 services by default start as the LocalSystem special user account. This account will not contain the same User DSNs as your own user. The Virtuoso service can be started with other users but you must be aware of any possible system permission problems. It is recommended that Virtuoso make use of System or File DSNs wherever possible.


6.2.9.3.3. External Linked Objects

This page will allow you to manage the remote objects that are linked into Virtuoso. You can unlink objects by selecting them and pressing the "Unlink selected" button.

Linking Tables from Remote Datasources
Figure: 6.2.9.3.3.1. Linking Tables from Remote Datasources

To link new tables into Virtuoso select "Link objects" link or go to the "Data Sources" tab. Click the "Connect" link for a data source. If this data source has been used before then the existing authentication details will automatically be provided. Otherwise you will have to provide these details in the username and password fields provided. When you are ready press the "Link objects" link.

As results you should be presented with list of available remote tables and optionally views and procedures. If the connection fails then an error will be returned to the top of the page instead. You should be able to link any of the listed tables or views into Virtuoso. In order for Virtuoso to be able to correctly query the underlying table it needs to be able to uniquely identify each row (record) within the table or view. Tables should always be created with a primary key, and details of which should be available from the data source. With a primary key available Virtuoso will be able to link the table in to the server easily. In some cases and certainly in the case of views Virtuoso may not be able to determine a primary key or what constitutes uniqueness in the table. On the right most column will be an action link to a page that allows you to alter the primary key information about the table or view that is to be linked. Some primary key information is italized to indicate the explicit definition of a primary key.

You will be required to enter primary key information for views before they can be linked.

Select the tables that you want to link into the Virtuoso Server by checking the check box on the left most column of the list for table or view in question. When you are ready press the Link ... button at the bottom of the page.

As result the selected tables will be linked and listed in the first list as Currently Linked.


6.2.9.3.4. Remote Procedures

In order to view the list of remote procedures, you should check the "Stored Procedures" check-box and click the button "Apply". As result the procedures that are already connected to Virtuoso will be shown with checked check-box. You can unlink these by selecting them and pressing the Unlink button.

To link new procedures into Virtuoso select the Data Source from the list of available n t ab "Data Sources". If this data source has been used before then the existing authentication details will automatically be provided. Otherwise you will have to provide these details in the username and password fields provided. When you are ready press the Link Objects link. The page will next require you to select the catalog/owner combination to refine the search list of procedures on the remote datasource. Check the check-box "Stored procedures" and click the "Apply" button to list the available stored procedures.

Linking Procedures from Remote Datasources
Figure: 6.2.9.3.4.1. Linking Procedures from Remote Datasources

When the page returns you will be presented with a list of available remote procedures. You should be able to link any of the listed procedures into Virtuoso.

Linking Procedures from Remote Datasources
Figure: 6.2.9.3.4.2. Linking Procedures from Remote Datasources

Select the procedures that you want to link into the Virtuoso Server by checking the check box on the left most column of the list for the procedure in question. When you are ready press the Link ... button at the bottom of the page.

You will be presented with a new page that lists the procedures chosen and the data type information regarding them. This gives you an opportunity to alter the data type mappings that Virtuoso will use both internally and for any future interactions with the SOAP server. If you do not want to specify any special type information the details can be left as default.

Linking Procedures from Remote Datasources
Figure: 6.2.9.3.4.3. Linking Procedures from Remote Datasources

For each remote procedure you have the option to change how they will be referenced within Virtuoso by making changes to the fields for Local Name, Database, and Schema. These fields define how you will find the linked procedure locally to Virtuoso only and do not affect the remote data source.

For each procedure there are radio buttons for selecting the PL Wrapper Requirements. This option is of particular importance for remote procedures capable of returning a resultset. Remote procedures can be linked using a Virtuoso PL wrapper meaning that Virtuoso procedure language code provides a mechanism for negotiating the result set. The available options are:

There is a description input box for you to write a description or comment for the linked procedure. This comment will only be applicable to procedures that are linked using a PL Wrapper, and is only directly applicable for PL Wrappers for SOAP execution.



6.2.9.4. Event Scheduler

The System Admin / Scheduler tab allows you to view, edit and remove events that can be scheduled to run from a particular time at a defined interval.

Event Scheduler
Figure: 6.2.9.4.1. Event Scheduler

To add a new scheduled event click the "Create New Event" link in tha last column of the shown form. The Event Name is a unique name required to uniquely identify each event. Start Time is when the event will be run for the first time and takes the form of a normal SQL timestamp value. Interval(minutes) is the length of time in minutes to wait to run the event again. SQL is a valid piece of SQL that you want to schedule to run. You can also check for "Enable Error Notification" and enter E-Mail for error notification.

Event Scheduler
Figure: 6.2.9.4.2. Event Scheduler

Events write possible error messages into the Virtuoso log file.


6.2.9.5. Virtuoso Configuration Editor

From System Admin/Parameters you can change the Virtuoso Configuration settings:

Virtuoso (virtuoso.ini) Configuration File Editor
Figure: 6.2.9.5.1. Virtuoso (virtuoso.ini) Configuration File Editor
Virtuoso (virtuoso.ini) Configuration File Editor
Figure: 6.2.9.5.2. Virtuoso (virtuoso.ini) Configuration File Editor
Virtuoso (virtuoso.ini) Configuration File Editor
Figure: 6.2.9.5.3. Virtuoso (virtuoso.ini) Configuration File Editor
Virtuoso (virtuoso.ini) Configuration File Editor
Figure: 6.2.9.5.4. Virtuoso (virtuoso.ini) Configuration File Editor
Virtuoso (virtuoso.ini) Configuration File Editor
Figure: 6.2.9.5.5. Virtuoso (virtuoso.ini) Configuration File Editor
Virtuoso (virtuoso.ini) Configuration File Editor
Figure: 6.2.9.5.6. Virtuoso (virtuoso.ini) Configuration File Editor
Virtuoso (virtuoso.ini) Configuration File Editor
Figure: 6.2.9.5.7. Virtuoso (virtuoso.ini) Configuration File Editor

6.2.9.6. Dashboard and Monitor

The System Admin/Dashboard consists of a collection of statistical information about your Virtuoso server. This includes general licensing information, locking, webserver hits statistics and more.

Dashboard
Figure: 6.2.9.6.1. Dashboard

The System Admin/Monitor shows in details statistical information about your server.

Monitor - General Information
Figure: 6.2.9.6.2. Monitor - General Information
Monitor - HTTP Usage
Figure: 6.2.9.6.3. Monitor - HTTP Usage
Monitor - Index Usage
Figure: 6.2.9.6.4. Monitor - Index Usage
Monitor - Profiling
Figure: 6.2.9.6.5. Monitor - Profiling


6.2.10. Conductor News Server Administration

6.2.10.1. Conductor Newsgroups Administration

From Conductor the NNTP tab allows you to view and configure Newsgroups associated with the Virtuoso News Server. Like Virtuoso's virtual database, Virtuoso can "link" in newsgroups from remote news servers. This interface allows you to view the configuration and control the newsgroups both local and remote.

The Virtuoso News server component will need to be enabled in the Virtuoso.ini file by specifying the NewsServerPort number.

The tab "NNTP Servers" shows list of the registered News servers.

News Server Administration
Figure: 6.2.10.1.1. News Server Administration

Click the "Edit" link to change the news server settings, or click the "Delete" link to remove the news server.

Edit News Server Properties
Figure: 6.2.10.1.2. Edit News Server Properties

Click the "Edit Groups" link for a current News Server in order to manage the list of available newsgroups.

News Groups List
Figure: 6.2.10.1.3. News Groups List

You can also update the cache list of newsgroups. Newsgroup names are (re)fetched in a batch background scheduled task. This is because the list can be very long or the connection to the news server could be slow. The status of the fetch is indicated in the grey bar at the foot of the newsgroup list table.

For each newsgroup listed for a news server you can update the messages fetched, view and edit the Properties of the group, or Remove the group from the list. Also you can get previous 500 messages or to get new messages by clicking the links at the bottom of the form shown below.

Manage subscribed for Newsgroup
Figure: 6.2.10.1.4. Manage subscribed for Newsgroup
6.2.10.1.5. Add Newsgroup

From the "NNTP Servers" tab click on the "Edit Groups" link for a registered News Server. Then click the Subscribe to newsgroups link to subscribe to newsgroups on the server.

Add Newsgroup
Figure: 6.2.10.1.5.1. Add Newsgroup

Once groups are selected you can use the Subscribe Selected button to add the groups.

Use the Back to servers list link to return to the News Servers List page.


6.2.10.1.6. Adding New News Server

From Conductor NNTP/NNTP Servers you can add remote servers. The values you need to provide in the form are as follows:

Server Address is the IP address or hostname of the external news server.

Server Port is the port number that the news server is listening on. By default news servers listen on port 119.

Username and Password allow you to provide login credentials if the server requires them.

News Server Administration
Figure: 6.2.10.1.6.1. News Server Administration

6.2.10.1.7. Viewing Newsgroups

You can view the messages of a newsgroup either using the Conductor UI going to NNTP/NNTP Servers/News Server/News Group, or using the ODS Framework UI. In the second case you need to have the ods_framework_dav.vad package and the ods_discussion_dav.vad package installed. Then you can go from ODS to tab "Discussions" where will be shown the list of available newsgroups. Each one has shown as link its name, which leads to page where are listed its messages.

View of messages in a newsgroup in ODS Discussions.
Figure: 6.2.10.1.7.1. View of messages in a newsgroup in ODS Discussions.


6.2.10.2. News Message Free Text Search

You can perform Free Text Search using the ODS search option.