One of the simplest configurations is a repository that just stores RDF data in main memory without applying any inferencing. This is also by far the fastest type of repository that can be used. The following code creates and initializes a non-inferencing main-memory repository:

import org.openrdf.repository.Repository;
import org.openrdf.repository.sail.SailRepository;
import org.openrdf.sail.memory.MemoryStore;

...

Repository repo = new SailRepository(new MemoryStore());
repo.initialize();

The constructor of the SailRepository class accepts any object of type Sail, so we simply pass it a new main-memory store object (which is, of course, a Sail implementation). Following this, the repository needs to be initialized to prepare the Sail(s) that it operates on.

The repository that is created by the above code is volatile: its contents are lost when the object is garbage collected or when your Java program is shut down. This is fine for cases where, for example, the repository is used as a means for manipulating an RDF model in memory.

Different types of Sail objects take parameters in their constructor that change their behaviour. The MemoryStore for example takes a data directory parameter that specifies a data directory for persisent storage. If specified, the MemoryStore will write its contents to this directory so that it can restore it when it is re-initialized in a future session:

File dataDir = new File("C:\\temp\\myRepository\\");
Repository repo = new SailRepository( new MemoryStore(dataDir) );
repo.initialize();

As you can see, we can fine-tune the configuration of our repository by passing parameters to the constructor of the Sail object. Some Sail types may offer additional configuration methods, all of which need to be called before the repository is initialized. The MemoryStore currently has one such method: setSyncDelay(long), which can be used to control the strategy that is used for writing to the data file, e.g.:

File dataDir = new File("C:\\temp\\myRepository\\");
MemoryStore memStore = new MemoryStore(dataDir);
memStore.setSyncDelay(1000L);

Repository repo = new SailRepository(memStore);
repo.initialize();

A Native RDF Repository does not keep its data in main memory, but instead stores it directly to disk (in a binary format optimized for compact storage and fast retrieval). It is an efficient, scalable and fast solution for RDF storage of datasets that are too large to keep entirely in memory.

The code for creation of a Native RDF repository is almost identical to that of a main memory repository:

import org.openrdf.repository.Repository;
import org.openrdf.repository.sail.SailRepository;
import org.openrdf.sail.nativerdf.NativeStore;


...
File dataDir = new File("/path/to/datadir/");
Repository repo = new SailRepository(new NativeStore(dataDir));
repo.initialize();

By default, the Native store creates a set of two indexes (see Section 6.6.2, “Native store configuration”). To configure which indexes it should create, we can either use the NativeStore.setTripleIndexes(String) method, or we can directly supply a index configuration string to the constructor:

import org.openrdf.repository.Repository;
import org.openrdf.repository.sail.SailRepository;
import org.openrdf.sail.nativerdf.NativeStore;


...
File dataDir = new File("/path/to/datadir/");
String indexes = "spoc,posc,cosp";
Repository repo = new SailRepository(new NativeStore(dataDir, indexes));
repo.initialize();

As we have seen, we can create Repository objects for any kind of back-end store by passing them a reference to the appropriate Sail object. We can pass any stack of Sails this way, allowing all kinds of repository configurations to be created quite easily. For example, to stack an RDF Schema inferencer on top of a memory store, we simply create a repository like so:

import org.openrdf.repository.Repository;
import org.openrdf.repository.sail.SailRepository;
import org.openrdf.sail.memory.MemoryStore;
import org.openrdf.sail.inferencer.fc.ForwardChainingRDFSInferencer;

...

Repository repo = new SailRepository(
                          new ForwardChainingRDFSInferencer(
                          new MemoryStore()));
repo.initialize();

Each layer in the Sail stack is created by a constructor that takes the underlying Sail as a parameter. Finally, we create the SailRepository object as a functional wrapper around the Sail stack.

The ForwardChainingRDFSInferencer that is used in this example is a generic RDF Schema inferencer; it can be used on top of any Sail that supports the methods it requires. Both MemoryStore and NativeStore support these methods. However, a word of warning: the Sesame inferencers add a significant performance overhead when adding and removing data to a repository, an overhead that gets progressively worse as the total size of the repository increases. For small to medium-sized datasets it peforms fine, but for larger datasets you are advised not to use it and to switch to alternatives.

Working with remote repositories is just as easy as working with local ones. We can simply use a different Repository object, the HTTPRepository, instead of the SailRepository class.

A requirement is of course that there is a Sesame 2 server running on some remote system, which is accessible over HTTP. For example, suppose that at http://example.org/openrdf-sesame/ a Sesame server is running, which has a repository with the identification 'example-db'. We can access this repository in our code as follows:

import org.openrdf.repository.Repository;
import org.openrdf.repository.http.HTTPRepository;

...

String sesameServer = "http://example.org/openrdf-sesame/";
String repositoryID = "example-db";

Repository repo = new HTTPRepository(sesameServer, repositoryID);
repo.initialize();

The Repository API offers various methods for adding data to a repository. Data can be added by specifying the location of a file that contains RDF data, and statements can be added individually or in collections.

We perform operations on a repository by requesting a RepositoryConnection from the repository. On this RepositoryConnection object we can perform various operations, such as query evaluation, getting, adding, or removing statements, etc.

The following example code adds two files, one local and one available through HTTP, to a repository:

import org.openrdf.OpenRDFException;
import org.openrdf.repository.Repository;
import org.openrdf.repository.RepositoryConnection;
import org.openrdf.rio.RDFFormat;
import java.io.File;
import java.net.URL;

...

File file = new File("/path/to/example.rdf");
String baseURI = "http://example.org/example/local";

try {
   RepositoryConnection con = repo.getConnection();
   try {
      con.add(file, baseURI, RDFFormat.RDFXML);

      URL url = new URL("http://example.org/example/remote.rdf");
      con.add(url, url.toString(), RDFFormat.RDFXML);
   }
   finally {
      con.close();
   }
}
catch (OpenRDFException e) {
   // handle exception
}
catch (java.io.IOEXception e) {
   // handle io exception
}

More information on other available methods can be found in the javadoc reference of the RepositoryConnection interface.

The Repository API has a number of methods for creating and evaluating queries. Three types of queries are distinguished: tuple queries, graph queries and boolean queries. The query types differ in the type of results that they produce.

The result of a tuple query is a set of tuples (or variable bindings), where each tuple represents a solution of a query. This type of query is commonly used to get specific values (URIs, blank nodes, literals) from the stored RDF data. SPARQL SELECT queries are tuple queries.

The result of graph queries is an RDF graph (or set of statements). This type of query is very useful for extracting sub-graphs from the stored RDF data, which can then be queried further, serialized to an RDF document, etc. SPARQL CONSTRUCT and DESCRIBE queries are graph queries.

The result of boolean queries is a simple boolean value, i.e. true or false. This type of query can be used to check if a repository contains specific information. SPARQL ASK queries are boolean queries.

Note: Sesame 2 currently supports two query languages: SeRQL and SPARQL. The former is explained in Chapter 11, The SeRQL query language (revision 3.1), the specification for the latter is available online. In this chapter, we will use SPARQL queries in our examples.

import java.util.List;
import org.openrdf.OpenRDFException;
import org.openrdf.repository.RepositoryConnection;
import org.openrdf.query.TupleQuery;
import org.openrdf.query.TupleQueryResult;
import org.openrdf.query.BindingSet;
import org.openrdf.query.QueryLanguage;

...

try {
   RepositoryConnection con = repo.getConnection();
   try {
	  String queryString = "SELECT ?x ?y WHERE { ?x ?p ?y } ";
	  TupleQuery tupleQuery = con.prepareTupleQuery(QueryLanguage.SPARQL, queryString);

	  TupleQueryResult result = tupleQuery.evaluate();
	  try {
			BindingSet bindingSet = result.next();
			Value valueOfX = bindingSet.getValue("x");
			Value valueOfY = bindingSet.getValue("y");

			// do something interesting with the values here...
	  }
	  finaly {
	      result.close();
	  }
   }
   finally {
      con.close();
   }
}
catch (OpenRDFException e) {
   // handle exception
}

List<String> bindingNames = result.getBindingNames();
while (result.hasNext()) {
   BindingSet bindingSet = result.next();
   Value firstValue = bindingSet.getValue(bindingNames.get(0));
   Value secondValue = bindingSet.getValue(bindingNames.get(1));

   // do something interesting with the values here...
}

import org.openrdf.query.resultio.sparqlxml.SPARQLResultsXMLWriter;

...

FileOutputStream out = new FileOutputStream("/path/to/result.srx");
try {
   SPARQLResultsXMLWriter sparqlWriter = new SPARQLResultsXMLWriter(out);

   RepositoryConnection con = myRepository.getConnection();
   try {
      String queryString = "SELECT * FROM {x} p {y}";
      TupleQuery tupleQuery = con.prepareTupleQuery(QueryLanguage.SERQL, queryString);
      tupleQuery.evaluate(sparqlWriter);
   }
   finally {
      con.close();
   }
}
finally {
   out.close();
}

import org.openrdf.query.GraphQueryResult;

GraphQueryResult graphResult = con.prepareGraphQuery(
QueryLanguage.SPARQL, "CONSTRUCT { ?s ?p ?o } WHERE {?s ?p ?o }".evaluate();

while (graphResult.hasNext()) {
   Statement st = graphResult.next();
   // ... do something with the resulting statement here.
}

import org.openrdf.rio.Rio;
import org.openrdf.rio.RDFFormat;
import org.openrdf.rio.RDFWriter;

...

RepositoryConnection con = repo.getConnection();
try {
   RDFWriter writer = Rio.createWriter(RDFFormat.TURTLE, System.out);

	con.prepareGraphQuery(QueryLanguage.SPARQL, 
	     "CONSTRUCT {?s ?p ?o } WHERE {?s ?p ?o } ").evaluate(writer);
}
finally {
   con.close();
}

RepositoryConnection con = repo.getConnection();
try {
   // First, prepare a query that retrieves all names of persons
   TupleQuery nameQuery = con.prepareTupleQuery(QueryLanguage.SPARQL,
         "SELECT ?name WHERE { ?person ex:name ?name . }");

   // Then, prepare another query that retrieves all e-mail addresses of persons:
   TupleQuery mailQuery = con.prepareTupleQuery(QueryLanguage.SPARQL,
         "SELECT ?mail WHERE { ?person ex:mail ?mail ; ex:name ?name . }");

   // Evaluate the first query to get all names
   TupleQueryResult nameResult = nameQuery.evaluate();
   try {
      // Loop over all names, and retrieve the corresponding e-mail address.
      while (nameResult.hasNext()) {
         BindingSet bindingSet = nameResult.next();
         Value name = bindingSet.get("name");

         // Retrieve the matching mailbox, by setting the binding for
			// the variable 'name' to the retrieved value. Note that we 
			// can set the same binding name again for each iteration, it will 
			// overwrite the previous setting.
         mailQuery.setBinding("name", name);

         TupleQueryResult mailResult = mailQuery.evaluate();

         // mailResult now contains the e-mail addresses for one particular person
         try {
            ....
         }
         finally {
            // after we are done, close the result
            mailResult.close();
         }
      }
   }
   finally {
      nameResult.close();
   }
}
finally {
   con.close();
}

ValueFactory factory = myRepository.getValueFactory();

// In this example, we specify the keyword string. Of course, this
// could just as easily be obtained by user input, or by reading from
// a file, or...
String keyword = "foobar";

// We prepare a query that retrieves all documents for a keyword.
// Notice that in this query the 'keyword' variable is not bound to
// any specific value yet.
TupleQuery keywordQuery = con.prepareTupleQuery(QueryLanguage.SPARQL,
      "SELECT ?document WHERE { ?document ex:keyword ?keyword . }");

// Then we set the binding to a literal representation of our keyword.
// Evaluation of the query object will now effectively be the same as
// if we had specified the query as follows:
//   SELECT ?document WHERE { ?document ex:keyword "foobar". }
keywordQuery.setBinding("keyword", factory.createLiteral(keyword));

// We then evaluate the prepared query and can process the result:
TupleQueryResult keywordQueryResult = keywordQuery.evaluate();

The RepositoryConnection can also be used for adding, retrieving, removing or otherwise manipulating individual statements, or sets of statements.

To be able to add new statements, we can use a ValueFactory to create the Values out of which the statements consist. For example, we want to add a few statements about two resources, Alice and Bob:

import org.openrdf.model.vocabulary.RDF;
import org.openrdf.model.vocabulary.RDFS;
...

ValueFactory f = myRepository.getValueFactory();

// create some resources and literals to make statements out of
URI alice = f.createURI("http://example.org/people/alice");
URI bob = f.createURI("http://example.org/people/bob");
URI name = f.createURI("http://example.org/ontology/name");
URI person = f.createURI("http://example.org/ontology/Person");
Literal bobsName = f.createLiteral("Bob");
Literal alicesName = f.createLiteral("Alice");

try {
   RepositoryConnection con = myRepository.getConnection();

   try {
      // alice is a person
      con.add(alice, RDF.TYPE, person);
      // alice's name is "Alice"
      con.add(alice, name, alicesName);

      // bob is a person
      con.add(bob, RDF.TYPE, person);
      // bob's name is "Bob"
      con.add(bob, name, bobsName);
   }
   finally {
      con.close();
   }
}
catch (OpenRDFException e) {
   // handle exception
}

Of course, it will not always be necessary to use a ValueFactory to create URIs. In practice, you will find that you quite often retrieve existing URIs from the repository (for example, by evaluating a query) and then use those values to add new statements. Or indeed, as we have seen in Section 8.1, “The RDF Model API”, for several well-knowns vocabularies we can simply reuse the predefined constants found in the org.openrdf.model.vocabulary package.

Retrieving statements works in a very similar way. One way of retrieving statements we have already seen actually: we can get a GraphQueryResult containing statements by evaluating a graph query. However, we can also use direct method calls to retrieve (sets of) statements. For example, to retrieve all statements about Alice, we could do:

RepositoryResult<Statement> statements = con.getStatements(alice, null, null, true);

The additional boolean parameter at the end (set to 'true' in this example) indicates whether inferred triples should be included in the result. Of course, this parameter only makes a difference if your repository uses an inferencer.

The RepositoryResult is an iterator-like object that lazily retrieves each matching statement from the repository when its next() method is called. Note that, like is the case with QueryResult objects, iterating over a RepositoryResult may result in exceptions which you should catch to make sure that the RepositoryResult is always properly closed after use:

RepositoryResult<Statement> statements = con.getStatements(alice, null, null, true);

try {
   while (statements.hasNext()) {
      Statement st = statements.next();

      ... // do something with the statement
   }
}
finally {
   statements.close(); // make sure the result object is closed properly
}

In the above method invocation, we see four parameters being passed. The first three represent the subject, predicate and object of the RDF statements which should be retrieved. A null value indicates a wildcard, so the above method call retrieves all statements which have as their subject Alice, and have any kind of predicate and object. The fourth parameter indicates whether or not inferred statements should be included or not.

Removing statements again works in a very similar fashion. Suppose we want to retract the statement that the name of Alice is "Alice"):

con.remove(alice, name, alicesName);

Or, if we want to erase all statements about Alice completely, we can do:

con.remove(alice, null, null);

In the above example, we used a Graph (see Graph Javadoc) as a collection class for statements. The Graph class has several advantages over using just any old Collection class. First of all, it provides a match method that can be used to retrieve statements from the collection that match a specific subject, predicate and object. In addition, you can use GraphUtil to easily retrieve specific parts of information from the statement collection.

For example, imagine we have a Graph containing names and e-mails for several persons (using the FOAF vocabulary). To easily retrieve each e-mail address for each person, we can do something like this:

import org.openrdf.model.Graph;
import org.openrdf.model.Literal;
import org.openrdf.model.Resource;
import org.openrdf.model.util.GraphUtil;
import org.openrdf.model.vocabulary.RDF;
import org.openrdf.model.vocabulary.FOAF;

Graph graph = ... ; // we initialized our graph before (for example by doing a query on our repository)

for (Resource subject: GraphUtil.getSubjects(graph, RDF.TYPE, FOAF.PERSON)) {
   Literal nameOfSubject = GraphUtil.getUniqueObjectLiteral(graph, subject, FOAF.NAME); 
   Literal mboxOfSubject = GraphUtil.getUniqueObjectLiteral(graph, subject, FOAF.MBOX); 
}