Conductor's Hosted Domains and Virtual Directories screen
Location: " response headers
* Every rewrite rule is uniquely identified internally (using IRIs).
* Two types of rule are supported, based on the syntax used to describe the source URL pattern matching - sprintf-based and regex-based.
* Rewrite rule list
* A named ordered-list of rewrite rules or rule lists where rules of the list are processed from top to bottom or in line with processing pipeline precedence instructions
* Configuration API
* Defines functions for creating, dropping, and enumerating rules and rule lists.
* Virtual hosts and virtual paths
* URL rewriting is enabled by associating a rewrite rules list with a virtual directory
Each of these elements is described in more detail below, although complete descriptions of the features or functions in question are not given. The intention here is to provide an overview of Virtuoso's URL rewriting capabilities and their application to deploying Linked Data. Please refer to the [[http://docs.openlinksw.com/virtuoso/][Virtuoso Reference Documentation]] for full details.
#AncmozTocId254803
---+++ Conductor UI for the URL Rewriter
Virtuoso is a full-blown HTTP server in its own right. The HTTP server functionality co-exists with the product core (i.e. DBMS Engine, Web Services Platform, DB.DBA.HTTP_PATH . Virtual directories can be administered in three basic ways:
* Using the Visual Administration Interface via a Web browser;
* Using the functions vhost_define() vhost_remove() HTTP_PATH url_rewrite /' after the host:port fields to the end of the URL.
* The input is [[http://en.wikipedia.org/wiki/Url_normalization][normalized]] .
* The input is matched against the rule's regex. If the match fails, the rule is not applied and the next rule is tried. If the match succeeds, the result is a vector of values.
* If the URL contains a query string, the names and values of the parameters are decoded by split_and_decode() POST method, the value of a named parameter in the body of the POST request; or
* if a parameter value cannot be derived from one of these sources, the rule is not applied and the next rule is tried.
Note:DB.DBA.URLREWRITE_APPLY |
To check which version of the Demo VAD is installed, or to upgrade it, refer to the Conductor's 'VAD Packages' screen, reachable through the 'System Admin' > 'Packages' menu items.
The latest VADs for the closed source releases of Virtuoso can be downloaded from the [[https://virtuoso.openlinksw.com/download/][downloads area]] of the |
Customers, Orders, Employees, Products, Product Categories, Shippers, Countries, Provinces etc.
Northwind is installed with a preconfigured Linked Data View and a set of preconfigured URL rewrite rules that collectively expose RDF based entity graphs and URLs of (X)HTML web pages that describe the back-end relational data.
An Linked Data View over relational data is a named collection (graph) of RDF records (triples) derived from an RDBMS-to-RDF source data map exposed via a Virtuoso Quad Store. The process of declaring Linked Data Views over RDBMS data using the Virtuoso Meta-schema Language is described in detail in our [[http://virtuoso.openlinksw.com/Whitepapers/pdf/Virtuoso_SQL_to_RDF_Mapping.pdf][Linked Data Views of SQL]] white paper.
To view the Northwind entity graph in RDF format, starting with the entity "ALFKI", simply place the following document URL into the [[http://demo.openlinksw.com/ode][OpenLink Data Explorer]] :
http://demo.openlinksw.com/Northwind/Customer/ALFKI ALFKI" by pointing your Web browser to the same URL. (The details of these URLs will be explained shortly; for now they are presented purely as pointers to illustrate example data available from Northwind.)
#AncmozTocId132652
---++++ Configuring Rewrite Rules using Conductor
The steps for configuring URL Rewrite rules via the Virtuoso Conductor are as follows:
1 Click to the "Web Application Server" > "Virtual Domains & Directories" tabs.
cURL " or any other HTTP-based user agent.
#AncmozTocId76317
---++++ Dissection of Northwind Rewrite Rules Configured using Conductor
The screenshots above show the default Northwind rewrite rules. Let's analyze what they are doing.
#AncmozTocId475034
---+++++ Regex Rule for RDF Requests
The regex rule for handling RDF/XML or N3 representation requests specifies a 'Request Path Pattern' of (/[^#]*). Recall that the input path is the portion of the input URL from the first '/' after the host:port fields to the end of the normalized URL. So, given a request for http://demo.openlinksw.com/Northwind/Customer/ALFKI /Northwind/Customer/ALFKI. Parentheses in the pattern collect the results of the pattern matching into parameters. Each successive pair of parentheses denotes a parameter, referred to elsewhere in the rewrite rule as $U1, $U2, $U3, ... , or $s1, $s2, $s3, ... , etc. These parameters can then be used to substitute a part of the input path that was matched into the new URL being composed. The parameter markers $U1 and $s1 (likewise $U2 and $s2 etc.) identify the same pattern segment in the request path pattern. The only difference between them is how the matched text is encoded when it is inserted into the new URL. The 's' format specifier inserts the matched text as is, whereas the 'U' format specifier causes the inserted text to be URL encoded.
Content types specified in the request's Accept header and matched by the 'Accept Header Request Pattern' are available for substitution into the rewritten URL through the $accept variable.
Rather than hardcoding host names and ports, the rules are made more generic by using the convenience macro URIQADefaultHost ^{URIQADefaultHost}^ DefaultHost virtuoso.ini. "DefaultHost www.example.com:8890".
#AncmozTocId409168
---+++++ Constructing the Destination Path Format
The parameter markers, variables and macros just described provide the building blocks for constructing the 'Destination Path Format' which serves as a template for the rewritten URL. It must be stressed that it is not necessary to URL-encode the Destination Path Format by hand. You need only write the underlying CONSTRUCT or DESCRIBE SPARQL query. When defining a new Destination Path Format, click on the SPARQL button to enable a text box (shown below) into which you can enter the base SPARQL query which will describe the entity being dereferenced. On clicking the 'Format' button to return, the SPARQL query will be expanded into a full query string, including a result-set format-specifier, and URL-encoded automatically. For example, the base query:
The pre-configured DESCRIBE query for Northwind describes two entities:and foaf:Document) that has the entity ALFKI" to expose the deeper entity graph that describes the entity "ALFKI#this". |
/about/html/http://^{URIQADefaultHost}^$s1 /about/html/ redirects the client to the [[http://virtuoso.openlinksw.com/Whitepapers/pdf/sponger_whitepaper_10102007.pdf][Virtuoso Sponger]] proxy interface. The Sponger itself is a highly customizable RDFizer. Virtuoso reserves two paths for the proxy service, '/about/rdf/' and '/about/html/'. (Note: These proxy paths have since been augmented to support a richer slash URI scheme for identifying format variants. Please refer to [[VirtDeployingLinkedDataGuide_AppendixB][Appendix B]] for more details.)
The web service takes the target URL following the proxy path and either returns the content "as is" or tries to transform it to RDF. The RDF graph derived from the sponging process is then rendered in one of the RDF serialization formats (RDF/XML or N3) or HTML depending on whether the request specified /about/rdf/ or /about/html/. Thus, the proxy service can be used as middleware for enabling RDF based exploration of non-RDF sources using dedicated RDF browsers or standard (X)HTML browsers.
The mechanism through which Virtuoso composes an HTML rendering of RDF data (whether this be a native RDF description, or one extracted by the Sponger) is via the "description.vsp" rendering template, a specialized [[http://docs.openlinksw.com/virtuoso/vsp1.html][Virtuoso Server Page]] specifically aimed at RDF-model-based resource description. The "description.vsp" template is described in more detail in Appendix A. A usage example covering the description of the entity <http://demo.openlinksw.com/Northwind/Customer/ALFKI#this> 
Exporting Rewrite Rules from a Script
Use the function |
vhost_define() opts parameter. opts is of type ANY, e.g. a vector of field-value pairs. Numerous fields are recognized for controlling different options. The field value url_rewrite DB.DBA.URLREWRITE_DROP_RULE DB.DBA.URLREWRITE_CREATE_SPRINTF_RULE DB.DBA.URLREWRITE_CREATE_REGEX_RULE DB.DBA.URLREWRITE_DROP_RULELIST DB.DBA.URLREWRITE_CREATE_RULELIST DB.DBA.URLREWRITE_ENUMERATE_RULES DB.DBA.URLREWRITE_ENUMERATE_RULELISTS URLREWRITE_CREATE_REGEX_RULE() rule_iri VARCHAR
* The rule's name / identifier
allow_update INTEGER
* Indicates whether the rule can be updated. 1 indicates yes; 0 indicates no. The update is subject to the following rules:
* If the given rule_iri rule_iri allow_update rule_iri allow_update nice_match VARCHAR
* A regex match expression to parse the URL into a vector of occurrences.
nice_params ANY
* A vector of the names of the parsed parameters. The length of the vector should be equal to the number of '(...)' specifiers
in the format string.
nice_min_params INTEGER
* Used to specify the minimum number of sprintf format patterns to be matched in order to trigger the given rule. It only
affects sprintf rules and has no effect for regex rules.
target_compose VARCHAR
* A regex compose expression for the URL of the destination page.
target_params ANY
* A vector of names of parameters that should be passed to the compose expression (target_compose $1, $2 and so on.
target_expn VARCHAR
* Optional SQL text that should be executed instead of a regex compose call.
accept_pattern VARCHAR
* A regex expression to match the HTTP Accept header
do_not_continue INTEGER
* If the given rule satisfies the match conditions, 1 signifies do not try the next rule from same rule list, and 0 signifies try the
next rule.
http_redirect_code INTEGER
* NULL or the integer values 301, 302, 303, or 406, are currently allowed. If a 3xx redirect code is given, an HTTP redirect
response will be sent back to client. If NULL is specified, the server will process the redirect internally.
http_headers VARCHAR
* HTTP headers to supply with the rewritten request.
#AncmozTocId878640
---++++ Dissection of Northwind Rewrite Rules Configured using Virtuoso PL
Having briefly outlined the URL Rewriting API, we return now to the Northwind rule configuration script listed earlier.
At the start of the script, we define a virtual directory in order to turn on URL rewriting through vhost_define() /Northwind on the virtual host defined by vhost, before redefining the logical path. vhost specifies the host name sent to a user-agent in an HTTP response. This must be a valid fully-qualified host name or alias and port separated by ':'. This parameter accepts the special value '*ini* virtuoso.ini file.
The /Northwind virtual directory is mapped to a DAV folder (indicated by is_dav /DAV/home/demo. The machine hosting the virtual directory listens on the IP address and port specified by lhost (i.e. listen host). Like vhost, this accepts the special value '*ini* dba'.
URL rewriting is enabled through the url_rewrite opts vector; the URL rewriter will use the rule list named demo_nw_rule_list1 URLREWRITE_CREATE_RULELIST demo_nw_rule1 demo_nw_rule2 URLREWRITE_CREATE_REGEX_RULE demo_nw_rule2 (/[^#]*)' specified for #). The corresponding occurrence is named 'path' in the nice_params target_compose +' or '%20', the reserved character '#' is [[http://en.wikipedia.org/wiki/Percent-encoding][percent-encoded]] as '%23' and the '%' character itself is escaped by '%'.
Removing the URL encoding and the final format specifier ('&format=%U'), the SPARQL DESCRIBE query being built takes the form:
DESCRIBE <http://^{URIQADefaultHost}^%U#this> <http://^{URIQADefaultHost}^%U> FROM <http://^{URIQADefaultHost}^/Northwind> %U or %s , as opposed to $U1, $U2, ... or $s1, $s2, ... in Conductor). Here, the two sprintf-like format characters %U are placeholders which receive the first two entries in the target_params path'. In our example, the value of 'path' would be '/Northwind/Customer/ALFKI'.
The query response format is controlled by the format query parameter. In the format specifier ('&format=%U') at the end of the constructed query string, the third placeholder '%U' receives the value of the third entry in the target_params *accept* *accept* Accept header matched against accept_pattern Accept header specified MIME types of 'application/rdf+xml, application/xml' and the accept_pattern (text/rdf.n3)|(application/rdf.xml)', then the '*accept* application/rdf+xml'.
The other rule, demo_nw_rule1 demo_nw_rule2 303 to the client when the rewrite rule is applied.
|
Internal Rewrites vs External Redirects
External redirect : Tells the client to ask for the requested content again using a new URL and HTTP request. An external redirect is indicated by one of the HTTP response codes: 301 - Moved permanently (for permanent redirection) Internal rewrite/redirect : Gets the content for the requested URL from a different server file path than implied by the requested URL. |
description.vsp via the Sponger proxy interface.
System Tables Supporting URL Rewriting
If you need to check your rewrite rule definitions, an alternative to inspecting them using Conductor is to query Virtuoso's system tables directly. The relevant system tables for URL rewriting are |
