Overview (marklogic-jena 3.0.3 API)

Packages
Package	Description
com.marklogic.semantics.jena	Contains the core class for marklogic-jena, `MarkLogicDatasetGraph`, as well as a Factory and Exceptions.
com.marklogic.semantics.jena.client	Contains classes that interact with the MarkLogic Java Client API.
com.marklogic.semantics.jena.engine	Jena extensions that wire MarkLogic functionality into Jena's query processing and graph manipulation APIs.

MarkLogic Jena

marklogic-jena enables applications based on Apache Jena 2.13 to use MarkLogic as a persistence layer for triples, and as a source for SPARQL queries. In addition to basic support for graph CRUD and SPARQL query and update, marklogic-jena also exposes the following MarkLogic capabilities to the Jena framework:

Transactions
Variable bindings
Inference (ruleset configuration)
Combination of SPARQL with MarkLogic document query
Optimized pagination of SPARQL result sets

Before Starting

Ensure that you have the following information available for a MarkLogic instance:

hostname
port of an application server
credentials to read/write/administer the database as needed

If you need something to help you configure and deploy MarkLogic application servers, try ml-gradle. Note: If you are starting with 8.0-4 MarkLogic installation on your local machine, the configuration of ml-gradle out of the box will set up a test server for you.

The API

Jena uses a com.hp.hpl.jena.sparql.core.DatasetGraph to model a set of RDF graphs. To create a DatasetGraph that accesses MarkLogic, use MarkLogicDatasetGraph. You may make a DatasetGraph instance from a Java Client API Database Client, or directly from the five-argument factory method.

import com.hp.hpl.jena.sparql.core.DatasetGraph;
import com.marklogic.client.DatabaseClient;
import com.marklogic.client.DatabaseClientFactory;
import com.marklogic.client.DatabaseClientFactory.Authentication;
import com.marklogic.semantics.jena.MarkLogicDatasetGraph;
import com.marklogic.semantics.jena.MarkLogicDatasetGraphFactory;
...

String host = "localhost";
String port = 9999;
String username = "username";
String password = "password";

// either make a DatabaseClient first
DatabseClient client = DatabaseClientFactory.newClient(
    host, port, username, password, Authentication.DIGEST);
    
DatasetGraph dsg;
dsg = MarkLogicDatasetGraphFactory.createDatasetGraph(client);

// or create dsg directly
dsg = MarkLogicDatasetGraphFactory.createDatasetGraph(
    host, port, username, password, Authentication.DIGEST);

// Do things with your DatasetGraph

Graph operations

Use Jena's CRUD operations to store, retrieve, merge or delete Graphs on the MarkLogicDatasetGraph.

Node graphNode = NodeFactory.createURI("http://example.org/graphs/charles");

String turtle = "@prefix foaf:  ."
        + "@prefix :  ."
        +":charles a foaf:Person ; "
        + "        foaf:name \"Charles\" ;"
        + "        foaf:knows :jim ."
        + ":jim    a foaf:Person ;"
        + "        foaf:name \"Jim\" ;"
        + "        foaf:knows :charles .";

// make grpah locally
Graph graph = GraphFactory.createDefaultGraph();
RDFDataMgr.read(graph,  new StringReader(turtle), "", Lang.TURTLE);

// store in MarkLogic
dsg.addGraph(graphNode,  graph);

// Make a triple by hand
Graph moreTriples = GraphFactory.createDefaultGraph();
moreTriples.add(new Triple(
        NodeFactory.createURI("http://example.org/charles"),
        NodeFactory.createURI("http://example.org/hasDog"),
        NodeFactory.createURI("http://example.org/vashko")));

// merge it with the graph in MarkLogic
dsg.mergeGraph(graphNode, moreTriples);

// get the merged graph
Graph retrievedGraph = dsg.getGraph(graphNode);

// remove the graph
dsg.removeGraph(graphNode);

// remove all graphs
dsg.clear();

SPARQL Queries

QueryExecution execution = QueryExecutionFactory.create(
                "PREFIX foaf:  "
                +"select ?aname ?bname where { ?a foaf:knows ?b ."
                + "                    ?a foaf:name ?aname ."
                + "                    ?b foaf:name ?bname }", dsg.toDataset());
int n = 1;
for (ResultSet results = execution.execSelect();
        results.hasNext();
        n++) {
    QuerySolution solution = results.next();
    System.out.println("Solution #" + n ": "
            + solution.get("aname").asLiteral().getString()
            +" knows " 
            + solution.get("bname").asLiteral().getString());
}
dsg.close();

SPARQL Update

String insertData = "PREFIX foaf:  "
        + "PREFIX :  "
        +"INSERT DATA {GRAPH :g1 {"
        + ":charles a foaf:Person ; "
        + "        foaf:name \"Charles\" ;"
        + "        foaf:knows :jim ."
        + ":jim    a foaf:Person ;"
        + "        foaf:name \"Jim\" ;"
        + "        foaf:knows :charles ."
        + "} }";

UpdateRequest update = UpdateFactory.create(insertData);
UpdateProcessor processor = UpdateExecutionFactory.create(update, dsg);
processor.execute();

update = UpdateFactory.create("PREFIX :  DROP GRAPH :g1");
processor = UpdateExecutionFactory.create(update, dsg);
processor.execute();
dsg.close();