Using GraphDB with the RDF4J API

This section describes how to use the RDF4J API to create and access GraphDB repositories, both on the local file-system and remotely via the RDF4J HTTP server.

RDF4J comprises a large collection of libraries, utilities and APIs. The important components for this section are:

  • the RDF4J classes and interfaces (API), which provide a uniform access to the SAIL components from multiple vendors/publishers;
  • the RDF4J server application.

RDF4J API

Programmatically, GraphDB can be used via the RDF4J Java framework of classes and interfaces. Documentation for these interfaces (including Javadoc). Code snippets in the following sections are taken from (or are variations of) the developer-getting-started examples, which come with the GraphDB distribution.

Accessing a local repository

With RDF4J 2, repository configurations are represented as RDF graphs. A particular repository configuration is described as a resource, possibly a blank node, of type: http://www.openrdf.org/config/repository#Repository.
This resource has an id, a label and an implementation, which in turn has a type, SAIL type, etc. A short repository configuration is taken from the developer-getting-started template file repo-defaults.ttl
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix rep: <http://www.openrdf.org/config/repository#>.
@prefix sr: <http://www.openrdf.org/config/repository/sail#>.
@prefix sail: <http://www.openrdf.org/config/sail#>.
@prefix owlim: <http://www.ontotext.com/trree/owlim#>.

[] a rep:Repository ;
  rep:repositoryID "graphdb-repo" ;
  rdfs:label "GraphDB Getting Started" ;
  rep:repositoryImpl [
    rep:repositoryType "openrdf:SailRepository" ;
    sr:sailImpl [
      sail:sailType "graphdb:FreeSail" ;
      owlim:ruleset "owl-horst-optimized" ;
      owlim:storage-folder "storage" ;
      owlim:base-URL "http://example.org/owlim#" ;
      owlim:repository-type "file-repository" ;
      owlim:imports "./ontology/owl.rdfs" ;
      owlim:defaultNS "http://example.org/owlim#" .
    ]
  ].

The Java code that uses the configuration to instantiate a repository and get a connection to it is as follows:

// Instantiate a local repository manager and initialize it
RepositoryManager repositoryManager = new LocalRepositoryManager(new File("."));
repositoryManager.initialize();

// Instantiate a repository graph model
TreeModel graph = new TreeModel();

// Read repository configuration file
InputStream config = EmbeddedGraphDB.class.getResourceAsStream("/repo-defaults.ttl");
RDFParser rdfParser = Rio.createParser(RDFFormat.TURTLE);
rdfParser.setRDFHandler(new StatementCollector(graph));
rdfParser.parse(config, RepositoryConfigSchema.NAMESPACE);
config.close();

// Retrieve the repository node as a resource
Resource repositoryNode = GraphUtil.getUniqueSubject(graph, RDF.TYPE, RepositoryConfigSchema.REPOSITORY);

// Create a repository configuration object and add it to the repositoryManager
RepositoryConfig repositoryConfig = RepositoryConfig.create(graph, repositoryNode);
repositoryManager.addRepositoryConfig(repositoryConfig);

// Get the repository from repository manager, note the repository id set in configuration .ttl file
Repository repository = repositoryManager.getRepository("graphdb-repo");

// Open a connection to this repository
RepositoryConnection repositoryConnection = repository.getConnection();

// ... use the repository

// Shutdown connection, repository and manager
repositoryConnection.close();
repository.shutDown();
repositoryManager.shutDown();

The procedure is as follows:

  1. Instantiate a local repository manager with the data directory to use for the repository storage files (repositories store their data in their own subdirectory from here).
  2. Add a repository configuration for the desired repository type to the manager.
  3. ‘Get’ the repository and open a connection to it.

From then on, most activities will use the connection object to interact with the repository, e.g., executing queries, adding statements, committing transactions, counting statements, etc. See the developer-getting-started examples.

Note

Example above assumes that GraphDB-Free edition is used. If using Standard or Enterprise editions, a valid license file should be set to the system property graphdb.license.file

Accessing a remote repository

The RDF4J server is a Web application that allows interaction with repositories using the HTTP protocol. It runs in a JEE compliant servlet container, e.g., Tomcat, and allows client applications to interact with repositories located on remote machines. In order to connect to and use a remote repository, you have to replace the local repository manager for a remote one. The URL of the RDF4J server must be provided, but no repository configuration is needed if the repository already exists on the server. The following lines can be added to the developer-getting-started example program, although a correct URL must be specified:

RepositoryManager repositoryManager =
        new RemoteRepositoryManager( "http://192.168.1.25:7200" );
repositoryManager.initialize();

The rest of the example program should work as expected, although the following library files must be added to the class-path:

  • commons-httpclient-3.1.jar
  • commons-codec-1.10.jar

SPARQL endpoint

The RDF4J HTTP server is a fully fledged SPARQL endpoint - the RDF4J HTTP protocol is a superset of the SPARQL 1.1 protocol. It provides an interface for transmitting SPARQL queries and updates to a SPARQL processing service and returning the results via HTTP to the entity that requested them.

Any tools or utilities designed to interoperate with the SPARQL protocol will function with GraphDB because it exposes a sparql compliant endpoint.

Graph Store HTTP Protocol

The Graph Store HTTP Protocol is fully supported for direct and indirect graph names. The SPARQL 1.1 Graph Store HTTP Protocol has the most details, although further information can be found in the RDF4J Server REST API.

This protocol supports the management of RDF statements in named graphs in the REST style, by providing the ability to get, delete, add to or overwrite statement in named graphs using the basic HTTP methods.