Library Version 12.1.3.0

Setup the SPARQL Service
Prev | Chapter 2. Setup RDF Graph | Next

## Setup the SPARQL Service

Setting up a SPARQL endpoint using the RDF Graph feature involves creating and deploying a Web Application Archive (WAR) file into a server J2EE container. The RDF Graph feature supports Apache Jena Joseki, an open source SPARQL server that supports the SPARQL protocol and SPARQL queries to create this web application archive.

The following sections explain how to set up a SPARQL service using the bundled web application archive in either Apache Tomcat or Oracle WebLogic Server.

The RDF Graph feature's release package includes a bundled web application archive (joseki.war). Details on how to build a web application archive (joseki.war) for a previous release of the Oracle NoSQL Database or for modification purposes can be found in Generating a New SPARQL Service WAR file.

### Deploy joseki.war

The following steps describe how to deploy the prebundled joseki.war into Apache Tomcat or Oracle WebLogic Server.

1. Ensure that you have downloaded and unzipped the RDF Graph release package for the Oracle NoSQL Database, as explained in Setup the System Environment.

2. Extract the `joseki-config.ttl` file located in the joseki.war using the following commands:

       cd /tmp/jena_adapter/war
       jar xf joseki.war joseki-config.ttl

3. Modify Apache Jena Joseki's configuration file (joseki-config.ttl) to specify the store name, host name, and host port for accessing an Oracle NoSQL database. This data will be used by the SPARQL Service endpoint to establish connections to the Oracle NoSQL Database and execute update and query operations. For detailed information about this configuration, Configuring an Oracle NoSQL Database connection in the SPARQL service.

4. Rebuild joseki.war by updating the `joseki-config.ttl` as follows:

       jar uf joseki.war joseki-config.ttl

5. Deploy the joseki.war into the selected J2EE container.

### Use Apache Tomcat

This section describes how to deploy the SPARQL Service endpoint using Apache Tomcat 7.0. Apache Tomcat is an open source web server implementing Java Servlet and JavaServer Pages (JSP) and providing an HTTP web server environment to run Web applications. Further information and support on Apache Tomcat can be found in http://tomcat.apache.org/.

1. Download and install Apache Tomcat 7.0. For details see http://tomcat.apache.org/tomcat-7.0-doc/index.html.

2. Go to the web application directory of Apache Tomcat Server and copy the joseki.war file as follows. This operation will unpack the war file and deploy the web application. (For information about deploying web application in Apache Tomcat, please refer to http://tomcat.apache.org/tomcat-7.0-doc/deployer-howto.html.

       cd $CATALINA_BASE/webapps
       cp -rf /tmp/jena_adapter/joseki.war $CATALINA_HOME/webapps

3. Verify your deployment by using your Web browser to connect to a URL in the following format (assume that the Web application is deployed at port 8080):

   http://<hostname>:8080/joseki

   You should see a page titled Oracle NoSQL Database SPARQL Service Endpoint using Joseki, and the first text box should contain an example SPARQL query.

4. Click `Submit Query`.

You should see a page titled Oracle NoSQL Database SPARQL Endpoint Query Results. There may or may not be any results, depending on the underlying semantic model against which the query is executed.

### Use Oracle WebLogic Server

This section describes how to deploy the SPARQL Service endpoint using Oracle WebLogic Server 12c. For information about Oracle WebLogic Server please refer to http://www.oracle.com/technology/products/weblogic/.

1. Download and Install Oracle WebLogic Server 12c Release 1 (12.1.1). For details, see http://www.oracle.com/technology/products/weblogic/ and http://www.oracle.com/technetwork/middleware/ias/downloads/wls-main-097127.html.

2. Go to the auto-deploy directory of the WebLogic Server installation and copy files, as follows. (For information about auto-deploying applications in development domains refer to the following document: http://docs.oracle.com/cd/E24329_01/web.1211/e24443/autodeploy.htm)

       cd <domain_name>/autodeploy
       cp -rf /tmp/joseki.war <domain_name>/autodeploy

   In the preceding example, <domain_name> is the name of a WebLogic Server domain.

   Note that you can run a WebLogic Server domain in two different modes: development and production. However, only development mode allows you use the auto-deployment feature.

3. Verify your deployment by using your Web browser to connect to a URL in the following format (assume that port 7001 is used):

   http://<hostname>:7001/joseki

   You should see a page titled Oracle NoSQL Database SPARQL Service Endpoint using Joseki, and the first text box should contain an example SPARQL query.

4. Click `Submit Query`.

   ### Note

   You should see a page titled Oracle NoSQL Database SPARQL Endpoint Query Results. There may or may not be any results, depending on the underlying semantic model against which the query is executed.

By default, the `joseki-config.ttl` file contains an oracle-nosql:Dataset definition using all graphs stored in the Oracle NoSQL Database. The following snippet shows the configuration.

    <#oracle> rdf:type oracle-nosql:Dataset;
    joseki:poolSize 3;  ## Number of concurrent connections allowed
                        ## to this dataset.
    oracle-nosql:connection  ## NoSQL connection
    [
    rdf:type oracle-nosql:NoSQLConnection;
    oracle-nosql:hostName "localhost";
    oracle-nosql:storeName "mystore";
    oracle-nosql:hostPort "5000";
    ];
    oracle-nosql:allGraphs [] .       ## Graph descriptions

The `oracle-nosql:allGraphs` predicate denotes that the SPARQL Service endpoint will serve queries using all named graphs (including the default graph) stored in an Oracle NoSQL Database. You can also specify the rulebase(s) to use when serving queries. In the following example, the `oracle:ruleBaseID` predicate denotes that the SPARQL Service endpoint should serve queries using all named graphs (including asserted and inferred triples marked with the rulebase ID 1.

    <#oracle> rdf:type oracle-nosql:Dataset;
    joseki:poolSize 3;  ## Number of concurrent connections allowed
                        ## to this dataset.
    oracle-nosql:connection  ## NoSQL connection
    [
    rdf:type oracle-nosql:NoSQLConnection;
    oracle-nosql:hostName "localhost";
    oracle-nosql:storeName "mystore";
    oracle-nosql:hostPort "5000";
    ];
    oracle-nosql:allGraphs [ oracle-nosql:ruleBaseID "1" .  ] .
    ## Graph descriptions

If you require the SPARQL Service endpoint to serve queries using only a specified set of graph names, then use the `oracle-nosql:namedGraph` predicate instead of `oracle-nosql:allGraphs`. Further details can be found in Configuring the SPARQL Service: Oracle NoSQL Database.

You can add a few example triples and quads to test the named graph functions using the following Java code snippet:

    public static void main(String[] args) throws Exception
    {
    String szStoreName  = args[0];
    String szHostName   = args[1];
    String szHostPort   = args[2];

    System.out.println("Create Oracle NoSQL connection");
    OracleNoSqlConnection conn  =
    OracleNoSqlConnection.createInstance(szStoreName,
                                         szHostName,
                                         szHostPort);
    System.out.println("Create Oracle NoSQL graph and dataset ");
    OracleGraphNoSql graph = new OracleGraphNoSql(conn);
    DatasetGraphNoSql datasetGraph = DatasetGraphNoSql.createFrom(graph);

    // Close graph, as it is no longer needed
    graph.close();

    // add data to the bob named graph
    datasetGraph.add(new Quad(
            Node.createURI("http://example.org/bob"), // graph name
            Node.createURI("urn:bob"),
            Node.createURI("http://xmlns.com/foaf/0.1/name"),
            Node.createLiteral("Bob")));

    // add data to the alice named graph
    datasetGraph.add(new Quad(
            Node.createURI("http://example.org/alice"), // graph name
            Node.createURI("urn:alice"),
            Node.createURI("http://xmlns.com/foaf/0.1/name"),
            Node.createLiteral("Alice")));
    ds.close();
    conn.dispose();
    }

After inserting the quads, go to http://<hostname>:7001/joseki (Oracle WebLogic Server) or http://<hostname>:8080/joseki (Apache Tomcat), type the following SPARQL query, and click `Submit Query`:

    SELECT ?g ?s ?p ?o
    WHERE
    { GRAPH ?g
       { ?s ?p ?o}
    }

The result should be an HTML table with four columns and two sets of result bindings.

This page also contains a JSON Output option. If this option is selected (enabled), the SPARQL query response is converted to JSON format.

### Configuring an Oracle NoSQL Database connection in the SPARQL service

To configure the connections to the Oracle NoSQL Database, you must modify Apache Jena Joseki's configuration file (`joseki-config.ttl`) file located in `/tmp/joseki.war` to include the store name, host name, and host port to access the Oracle NoSQL Database. This data is used by the SPARQL Service endpoint to establish connections to the Oracle NoSQL Database and execute update and query operations.

To define this data, refer to the `oracle-nosql:connection` predicate in the `joseki-config.ttl`. This predicate denotes that the SPARQL service endpoint will connect to an Oracle NoSQL Database named <store_name> accessible through the host name <host_name> and port <host_port>. The following snippet shows the configuration.

    <#oracle> rdf:type oracle-nosql:Dataset;
    joseki:poolSize 1;  ## Number of concurrent connections allowed to
                        ## this data set.
    oracle-nosql:connection  ## NoSQL connection
    [
    rdf:type oracle-nosql:NoSQLConnection;
    oracle-nosql:hostName <host_name>;
    oracle-nosql:storeName <store_name>;
    oracle-nosql:hostPort <host_port>;
    ];
    ...

### Configuring the SPARQL Service: Oracle NoSQL Database

By default, the SPARQL Service endpoint assumes that queries are going to be executed against all named graphs (including the default graph) stored in the specified Oracle NoSQL database. Users can configure these settings to serve queries using only the default graph or a subset of named graphs by editing the `joseki-config.ttl` configuration file, which is in `<domain_name>/autodeploy/joseki.war`.

The supplied `joseki-config.ttl` file includes a section similar to the following for the Oracle NoSQL Database data set:

    #
    ## Datasets
    #
    [] ja:loadClass
    "oracle.spatial.rdf.client.jena.assembler.OracleAssemblerVocab" .

    oracle-nosql:Dataset rdfs:subClassOf ja:RDFDataset .

    <#oracle> rdf:type oracle-nosql:Dataset;
    ## Number of concurrent connections allowed to this dataset.
    joseki:poolSize 1;

    oracle-nosql:connection  ## connection to an Oracle NoSQL Database
     	[
    rdf:type oracle-nosql:NoSQLConnection;
    oracle-nosql:hostName "localhost";
      		oracle-nosql:storeName "mystore";
           oracle-nosql:hostPort "5000";
    ];

    oracle-nosql:allGraphs [] .

In this section of the file, you can:

- Modify the `joseki:poolSize` value, which specifies the number of concurrent connections allowed to this Oracle NoSQL data set (<#oracle> rdf:type oracle-nosql:Dataset;), which points to various RDF models in the Oracle NoSQL Database.

- Specify the default graph used to serve queries using the property `oracle-nosql:defaultGraph` as follows:

      <#oracle> rdf:type oracle-nosql:Dataset;
      joseki:poolSize 1; ## Number of concurrent connections allowed to
                         ## this data set.
      oracle-nosql:connection  ## NoSQL connection
      [
      rdf:type oracle-nosql:NoSQLConnection;
      oracle-nosql:hostName "localhost";
      oracle-nosql:storeName "mystore";
      oracle-nosql:hostPort "5000";
      ];
      oracle-nosql:defaultGraph [] .

- The `oracle:defaultGraph` predicate denotes that the SPARQL Service endpoint should serve queries using the default graph (consisting of triples that have no or NULL graph names), if stored in the Oracle NoSQL Database.

- If you require the SPARQL service endpoint to serve queries using asserted and inferred triples from a default graph, you should specify the rulebase ID of the inferred triples. The `oracle:ruleBaseID` predicate denotes that the endpoint should include all triples marked with the specified rulebase ID.

- For example, the following specifies rulebase ID 1 for the default graph.

      oracle-nosql:defaultGraph [
      	oracle-nosql:ruleBaseID "1" .
      ] .

- Specify a subset of named graphs that the SPARQL Service endpoint will use to serve queries. For example, you can specify two named graphs called <http://G1> and <http://G2> as follows:

      <#oracle>> rdf:type oracle-nosql:Dataset;
      joseki:poolSize 1; ## Number of concurrent connections allowed to
                         ## this data set.
      oracle-nosql:connection  ## NoSQL connection
      [
      rdf:type oracle-nosql:NoSQLConnection;
      oracle-nosql:hostName "localhost";
      oracle-nosql:storeName "mystore";
      oracle-nosql:hostPort "5000";
      ];

       oracle-nosql:namedGraph [ oracle-nosql:graphName <http://G1> ] .
       oracle-nosql:namedGraph [ oracle-nosql:graphName <http://G2> ] .

- The `oracle-nosql:namedGraph` predicate denotes that the SPARQL Service endpoint should serve queries using the named graph with a graph name denoted by `oracle-nosql:graphName`, if stored in the Oracle NoSQL Database. In this example, the SPARQL Service endpoint will only serve queries using two named graphs <http://G1> and <http://G2>. This way, any triple belonging to a different named graph will not be considered.

- If you require the SPARQL service endpoint to serve queries using asserted and inferred triples of a named graph, you should specify the rulebase ID of the inferred triples. The `oracle:ruleBaseID` predicate denotes that the endpoint should include all triples marked with the specified rulebase ID. For example, the following specifies that a rulebase ID, identified with 1, should be used in conjunction with named graph <http://G1>.

      oracle-nosql:namedGraph [
      	oracle-nosql:graphName <http://G1> ;
          oracle-nosql:ruleBaseID "1" .
      ] .

- Note that when using this configuration, one can still use SPARQL Update requests to create new graphs or add data to named graphs. However, queries against named graphs not specified in this configuration will not return any matches.

Prev | Up | Next
Chapter 2. Setup RDF Graph | Home | Chapter 3. Connect to NoSQL Database