# Joseki Configuration

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:

- Attached Models: details of hosted RDF models.
- Query processors: functions to execute request in the various the query languages available.

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

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.

### Header Section

    @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 Section

    ## 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:

- The server will return N3 with MIME type text/plain unless the client specifically asks for a known type. This means a web browser will display the results of a query request in text form.
- The HTTP response has cache-control set to "no-cache" so that intermediate web proxies and web caches should not keep copies of responses. Restarting a server, with a changed configuration will immediately show up.

### Model Section

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 ;
        .

## External URLs for models

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.

## Adding databases

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.

## RDFS and OWL data

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> ;
        . . .

## Defining a binding and a processor inline

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.

## More on Fetch Operations

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.