The configuration file states which models this server is hosting, what their external URL should be, what operations can be performed on each model as well as defining some properties of the server itself. The functionality of a server is controlled by the additional modules it loads during start up.
The important concepts are:
See also the page on running a Joseki server for
how a Joseki server finds it configuration file. The simplest way is to
place it in the etc/ directory.
The configuration file is in RDF. This document walks through an example below, discussing each of the features. The example uses N3 because it can give a more readable layout but the server determines the syntax of its actual configuration file based on the file extension: .n3 for N3, .nt for N-TRIPLES, and RDF/XML for anything else. See also Notation3 specification.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . @prefix module: <http://joseki.org/2003/06/module#> . @prefix joseki: <http://joseki.org/2003/07/configuration#> . <> rdfs:comment "Server configuration and data source mapping".
Some initial declaration of namespaces and a comment about this file. The namespace for terms defined is http://joseki.org/2003/07/configuration; the namespace http://joseki.org/2003/06/module is for loadable modules.
## Server configuration
<> rdf:type joseki:JosekiServer ;
joseki:josekiSchema joseki: ;
joseki:alsoInclude <file:etc/joseki-defs.n3> ;
joseki:serverDebug "true" ;
joseki:useContentType "application/rdf+xml" ;
.
The description of the server itself – <> is "this" document. The server configuration
is a resource with type joseki:JosekiServer.
The joseki:alsoInclude property identifies another file of convenience
declarations; this is an import mechanism and the referenced RDF is also read
into the configuration model.
joseki:useContentType sets the default MIME type to be used when
the client does not specify one. Known MIME types are
"application/rdf+xml", "application/n3" and "application/n-triples".
Debugging mode currently controls:
Having set up the server we attach the models to the server:
<http://server/model>
a joseki:AttachedModel ;
joseki:attachedModel <file:Data/test_data.n3> ;
These statements identify the type ('a' is N3 shorthand for rdf:type) and describe where the data for the model
should come from. In this case, it is a file which expected to be in
N-Triples syntax
(the file extension is ".nt").
The URL for the model will depend on how and where the web server was run. The
"http://server/"
is replaced by the root of the URLs for this web application or the host name for
a standalone server (the standalone server mounts the Joseki web application at
"/"). It's like http://localhost/.
Next, we define the query operations this model supports:
joseki:hasQueryOperation joseki:BindingGET ;
joseki:hasQueryOperation joseki:BindingFetchClosure ;
joseki:hasQueryOperation joseki:BindingRDQL ;
Each attached model has a number of query and other operation bindings. A query language binding defines the local name for the query language and the processor code to be used in processing queries in that language. We use the common definitions here for three query processors over HTTP GET, first plain GET which will return the whole model (just as if you had put the RDF file at this URL with a regular web server); the second allows a fetch request on a resource in the model and wil return all the information (the bNode closure of the graph rooted at the resource) about the resource, and the third allows RDQL queries on the model.
Suppose we are running standalone on host josekihost port 2020. The URL for this model is http://josekihost:2020/model. A fetch request might look like:
GET /model?lang=fetch&r=http://example.org/jena/resource1 HTTP/1.1 Host:josekihost:2020
See the section on the protocol.
Next, we add some other operations: we allow queries to be done by HTTP POST (such as ones too large for a GET) and to allow a "ping" of the model:
joseki:hasOperation joseki:BindingQueryModel ;
joseki:hasOperation joseki:BindingPing ;
.
and there's a final '.' because that's the end of statements about this resource.
So the complete configuration for this model is:
<http://server/model>
a joseki:AttachedModel ;
joseki:attachedModel <file:Data/test_data.n3> ;
joseki:hasQueryOperation joseki:BindingGET ;
joseki:hasQueryOperation joseki:BindingFetchClosure ;
joseki:hasQueryOperation joseki:BindingRDQL ;
joseki:hasOperation joseki:BindingQueryModel ;
joseki:hasOperation joseki:BindingPing ;
.
The configuration name for a model is http://server/modelname
(mode name may be a path). This not the external URL that the client will use.
In fact, there are several URLs that will go to the same model because the host
server in a URL can be identified as a DNS name, a full DNS name, IP address or
be localhost. For example, http://jena/ (if DNS domain is hpl.hp.com),
http://jena.hpl.hp.com/, http://jena.hpl.hp.com./ (final dot)
and http://192.6.10.31/ all go to the same place. DNS CNAMEs and URL redirection
complicate the matter still further.
When Joseki is deployed under a web application server, the web application name and the server path are inserted into the name. Typically under Tomcat, the URL will look like:
http://host/joseki/model
because the web application name is "joseki" by default. If it is deployed as the root web application, as is the case in the standalone server, no webapp name appears in the external URL.
A persistent Jena store can be used as the source of the RDF:
<http://server/db>
a joseki:AttachedModel ;
joseki:attachedModel <jdbc:mysql://host/db> ;
joseki:user "test" ;
joseki:password "password" ;
joseki:dbModelName "model_name" ;
joseki:dbType "MySQL" ;
joseki:dbDriver "com.mysql.jdbc.Driver" ;
joseki:hasQueryOperation joseki:BindingRDQL ;
joseki:hasOperation joseki:BindingPing ;
joseki:hasOperation joseki:BindingQueryModel ;
.
It is probably not a good idea to allow plain GET requests on a database. It might result in very large results.
So far, attached models have just provided RDF data. If an RDFS vocabulary or OWL ontology is associated with the attached model, then a suitable reasoner is choosen to wrap the data and the attached model has both ground and inferred RDF statements. Queries then execute against the inference model, not the ground data.
If the joseki:vocabulary property is used, it is an RDFS model:
<http://server/model>
a joseki:AttachedModel ;
joseki:attachedModel <file:somedata.nt> ;
joseki:vocabulary <file:vocab.n3> ;
. . .
If the joseki:ontology property is used, it is an OWL model:
<http://server/model>
a joseki:AttachedModel ;
joseki:attachedModel <file:somedata.nt> ;
joseki:ontology <file:ontology.rdf> ;
. . .
Only one of joseki:vocabulary and joseki:ontology
can be used on a single attached model. An explicit ontology document manager
can be specified (see
Jena ontology
documentation for full details of Jena Ontology and Reasoning support).
<http://server/model>
a joseki:AttachedModel ;
joseki:attachedModel <file:somedata.nt> ;
joseki:ontology <file:ontology.rdf> ;
joseki:ontDocumentManager <file:ontdocmgr.rdf> ;
. . .
A configuration does not have to use the standard terms in joseki-defs.n3. Here
is an example of a binding and a processor defined inline.
joseki:hasOperation
[ joseki:operationName "ping" ;
module:interface joseki:OpPing ;
module:implementation
[ module:className
"org.joseki.server.processors.PingProcessor" ]
] ;
This is a "ping" over HTTP POST on a model. This inline verstion is illustrative. There is a defintion of this in the standard definitions file.
The RDF to return about a resource is determined by the exact fetch modules loaded. Modules are the extension mechanism whereby a Joseki server can load additional functionality. A few fetch modules are provided in the distribution.
There is a general fetch query operation handler, which takes descriptions of fetch modules to load:
<http://server/model>
a joseki:AttachedModel ;
joseki:attachedModel <file:Data/test_data.n3> ;
joseki:hasQueryOperation joseki:BindingFetchClosure ;
. . .
# From joseki-defs.n3 ...
joseki:BindingFetchClosure
a module:ModuleBinding ;
joseki:queryOperationName "fetch" ;
module:implementation joseki:ImplQueryOperationFetch ;
module:interface joseki:QueryOperationFetch ;
module:module joseki:FetchModuleClosure ;
.
joseki:FetchModuleClosure
a module:ModuleBinding ;
module:interface joseki:FetchClosure ;
module:implementation
[ module:className
"org.joseki.server.processors.fetch.FetchClosure" ] ;
.
Inline, the same functionality can be specified as:
<http://server/model>
a joseki:AttachedModel ;
joseki:attachedModel <file:data.nt> ;
joseki:hasQueryOperation
[ joseki:queryOperationName "fetch" ;
module:implementation joseki:ImplQueryOperationFetch ;
module:interface joseki:QueryOperationFetch ;
module:module
[ module:interface joseki:FetchClosure ;
module:implementation
[ module:className
"org.joseki.server.processors.fetch.FetchClosure"
] ;
] ;
. . .
This declares the standard fetch engine implementation –
joseki:ImplQueryOperationFetch – as a query operation of a model.
The fetch engine will load the additional module with class FetchClosure.