Peruser Application Configuration
Once you've got a Peruser deployment set up and running, and you've looked at some sample applications, you'll be ready to start creating your own. This page gives you an overview of the ways you can combine different kinds of configuration and data files to create the application behavior you want. If you're trying to get your installation working, to customize Peruser java code or otherwise to push some boundaries, you may want to look into System Configuration.
Most Peruser applications are deployed using Cocoon. Each such application you are working on will get its own directory under app in your peruser installation. When you run ant tasks such as deploy-into-cocoon, all changes in your apps are copied from your peruser installation into your cocoon deployment (inside your servlet container). In most cases, these changes take affect immediately, without restarting your servlet container. This behavior of course helps provide a rapid development experience, which is one of our design goals for Peruser.
Cocoon Configuration
If it runs under cocoon, your application will need to have a sitemap.xmap file, which defines the core rules for how your application translates input HTTP requests into cocoon pipeline executions, which may include execution of various Peruser features. Usually you will want your pipelines to use PeruserTransformer (see below) to invoke some RDF functionality (including semantic model queries, inference, merges, etc.), and perhaps some XSLT, SQL, and/or Java functionality as well. The possibilities are well-nigh endless! But whatever you do, the sitemap.xmap will be a core artifact for you to manage, and it is up to you how to balance the growth and complexity of your sitemap vs. other kinds of artifacts in your toolkit.
In your sitemaps you have the power to configure and use instances of PeruserTransformer. How to do this is a rather large topic, so we have devoted a separate page to it:
Configuring and Using the PeruserTransformer
In addition to the PeruserTransformer, you can access the results of Peruser opertaions in your sitemap using the PeruserInputModule, which is handy when you need to pass the result of an RDF query as a parameter to another transformer (rather than through the XML pipeline). For example, you could determine the filename of an XSLT stylesheet using the result of an RDF query in this way.
PeruserInputModule is included in Peruser 2.1.1, but it is not hooked up to any query features. You can configure it via the sitemap, but you will have to hack the java code in order to make it do anything. It is like a bathtub in a house under construction, with water attached, but no hookup to the drain. Bring a bucket!
XML and XSLT Configuration
Cocoon and XSLT go together like peanut butter and jelly. You place your XSLT artifacts in a subdirectory of your app called xslt, and invoke them using <transformer> blocks in your cocoon pipelines, as you would in any other cocoon application. These transformations are useful for producing HTML or TXT output from XML, of course, but also for performing a number of transformations from one XML format to another. A common pattern you see in Peruser applications is that XML is output from some process (e.g. a SPARQL query), and then transformed into input for another processing stage: perhaps a SQL query using SQL Transformer, or simply to pull in contents from some remote REST web services using the CInclude transformer. Cocoon also enables aggregation of multiple intermediate XML results into a single document stream, which may then be further transformed, queried, etc.
If you have a large number of XSLT artifacts, there is no problem with splittling them across multiple directories or creating as deep a hierarchy as you need. It is also possible to import one XSLT transformation into another one, using xsl:import or xsl:include instructions. Paths to these transformations will be resolved relative to the location of the enclosing transformation.
It is common to pull in XML configuration or content files at various stages in your pipelines. You will see directory names like xml, config_xml, test_xml for this purpose.
RDF Configuration
Regardless of whether you're creating a cocoon app, a console application, or a standalone server, you will almost certainly need some RDF oriented artifacts in your app. These come in several forms, easily identified by their file suffixes.
- RDF model (data) files
- .ttl - turtle syntax files, useful for creating small models by hand.
- .n3 - N3 syntax files, which are similar to turtle syntax.
- .rdf - RDF/XML syntax files, usually managed with tools such as Protege.
- .owl - RDF/XML serializations of the OWL (description logic) dialect of RDF, usually managed with tools such as Protege.
- .rdfs - RDF/XMLserializations of the RDFS (frame schema) dialect of RDF, usually managed with tools such as Protege.
- SPARQL query files - identified with the extensions .sparql and .rq (no difference between these extensions or any others; simply a matter of convention ).
- Inference rule files - identified with the .grr extension used to run the Jena Generic Rule Reasoner to infer arbitrary triples from your models, using forward, bacward, or hybrid reasoning strategies.