{toc}
h1. Access Methods
GraphDB version is packaged as a Storage and Inference Layer (SAIL) for [Sesame version 2.x|http://www.openrdf.org/] and makes extensive use of the features and infrastructure of Sesame, especially the RDF model, RDF parsers and query engines. Inference is performed at load time, where the explicit and inferred statements are stored in highly-optimised data structures. The inferred closure is updated through inference at the end of each transaction that modifies the repository.
GraphDB implements the Sesame SAIL interface, so that it can be integrated with the rest of the Sesame framework, e.g. the query engines and the web user interface tools. A typical user application uses GraphDB directly through the Sesame SAIL API. When a GraphDB repository is exposed using the Sesame HTTP Server, users can manage the repository through the Sesame Workbench Web application, or with other tools that can integrate with Sesame, e.g. ontology editors like TopBraid Composer.
However, GraphDB-SE can also be used with the [Jena|http://jena.sourceforge.net/] framework, which is achieved with a customised Jena/Sesame/GraphDB-SE adapter component.
Sesame comprises a large collection of libraries, utilities and APIs, but the important components for this section are:
* the Sesame classes and interfaces (API) that provide uniform access to SAIL components from multiple vendors/publishers;
* the Sesame server and workbench Web applications (Java Enterprise Edition servlet components, referred to on the diagram below as "Sesame Web UI").
This section describes using the Sesame API to create and access GraphDB repositories, both on the local file-system and remotely via the Sesame HTTP server, plus a brief introduction is given to the Sesame workbench Web application, which provides many repository management functions through a convenient user interface. This is followed by information on using GraphDB-SE with Jena and some related components, i.e. [ARQ|http://jena.sourceforge.net/ARQ/] and [Joseki|http://www.joseki.org/].
h1. Sesame Application Programming Interface (API)
Programmatically, GraphDB is used via the Sesame Java framework of classes and interfaces. Documentation for these interfaces (including Javadoc) can be found at [http://www.openrdf.org|http://www.openrdf.org]. Code snippets in the following sections are taken from (or are variations of) the GettingStarted example program that comes with the GraphDB distribution.
h2. Using the Sesame API to access a local GraphDB repository
With Sesame 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. The example repository configuration from the getting-started example program looks like this:
{code}@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 "owlim" ;
rdfs:label "GraphDB Getting Started" ;
rep:repositoryImpl [
rep:repositoryType "openrdf:SailRepository" ;
sr:sailImpl [
sail:sailType "owlim:Sail" ;
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#" .
]
].
{code}.
The Java code to use the configuration to instantiate a repository and get a connection to it is as follows:
{code:title=Example Java code to create a repository|borderStyle=solid}Graph graph = ...;
Resource repositoryNode = ...;
// Create a manager for local repositories
RepositoryManager repositoryManager = new LocalRepositoryManager(new File("."));
repositoryManager.initialize();
// Create a configuration object from the configuration graph
// and add it to the repositoryManager
RepositoryConfig repositoryConfig = RepositoryConfig.create(graph, repositoryNode);
repositoryManager.addRepositoryConfig(repositoryConfig);
// Get the repository to use
Repository repository = repositoryManager.getRepository("owlim");
// Open a connection to this repository
RepositoryConnection repositoryConnection = repository.getConnection();
// ... use the repository
// Shutdown connection, repository and manager
repositoryConnection.close();
repository.shutDown();
repositoryManager.shutDown();
{code}Note that the code to parse this file and find the 'root' node for the configuration can be found in the getting-started program.
The procedure is as follows: instantiate a local repository manager with the data directory to use for the repository storage files (repositories will store their data in their own sub-directory from here), add a repository configuration for the desired repository type to the manager, '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 getting-started application for examples.
h2. Using the Sesame API to access a remote GraphDB repository
The Sesame 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. All that is required to connect to and use a remote repository instead of a local one, is to replace the local repository manager for a remote one. The URL of the Sesame 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 getting-started example program, although a correct URL must be specified:
{code:title=Example to create a connection to a remote repository|borderStyle=solid}RepositoryManager repositoryManager =
new RemoteRepositoryManager( "http://192.168.1.25:8080/openrdf-sesame" );
repositoryManager.initialize();
{code}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-logging-1.1.1.jar}}
* {{commons-codec-1.3.jar}}
h1. Managing repositories with the Sesame Workbench
The [installation section|GraphDB-SE Installation] explains how to set up a GraphDB repository that is exposed via the Sesame HTTP Server. In summary, the Sesame Server and Workbench applications are deployed to a Tomcat instance and the necessary library files (GraphDB, Lucene, etc) are copied to the correct locations. After this, the Sesame console application is used with the {{owlim.ttl}} repository template file to connect to the Sesame server and create a repository instance.
When the Sesame server is running, it will show a welcome message at the following URL:
{noformat}http://<hostname|ip_address>:8080/openrdf-sesame{noformat}The server has a simple user interface that shows status, logging and configuration information.
The workbench application, however, provides most repository management functions and is available from the following URL:
{noformat}http://<hostname|ip_address>:8080/openrdf-workbench{noformat}The workbench lists repositories and their namespaces, allows for the addition and deletion of statements, and provides a query interface for SPARQL and SeRQL query languages. However, the list of repository types is currently hard-coded in the workbench, so a GraphDB repository must still be created using the Sesame console application, as described in the [installation section|GraphDB-SE Installation].
h1. SPARQL endpoint
The Sesame HTTP server is a fully fledged SPARQL endpoint - the Sesame HTTP protocol is a super-set of the [SPARQL 1.1 protocol|http://www.w3.org/TR/sparql11-protocol/] - that 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 when deployed using the Sesame HTTP server, i.e. the openrdf-sesame Web application.
h1. Graph Store HTTP Protocol
T1he SPARQL 1.1 Graph Store HTTP Protocol is fully supported for direct and indirect graph names. The [W3C working draft|http://www.w3.org/TR/sparql11-http-rdf-update/] has the most details, although further information can be found in the [Sesame user guide|http://openrdf.callimachus.net/sesame/2.7/docs/users.docbook?view].
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.
h1. Using GraphDB-SE with Jena
[Jena|http://jena.sourceforge.net/] is a Java framework for building Semantic Web applications. It provides a programmatic environment for RDF, RDFS, OWL and SPARQL and includes a rule-based inference engine. Access to GraphDB-SE via the Jena framework is achieved with a special adapter, which is essentially an implementation of the Jena [ARQ|http://jena.sourceforge.net/ARQ/] interface that provides access to individual triples managed by a GraphDB-SE repository through the Sesame API interfaces.
{note}
The GraphDB specific Jena adapter can only be used with 'local' repositories, i.e. not 'remote' repositories that are accessed using the Sesame HTTP protocol.
{note}
The Jena adapter for GraphDB-SE is not a general purpose Sesame adapter and cannot be used to access any Sesame compatible repository, because it utilises an internal GraphDB-SE API to provide more efficient methods for processing RDF data and evaluating queries.
The adapter comes with its own implementation of a Jena 'assembler' factory to make it easier to instantiate and use with those related parts of the Jena framework, although one can instantiate an adapter directly by providing an instance of a Sesame SailRepository (a GraphDB-SE GraphDBRepository implementation). Query evaluation is controlled by the [ARQ|http://jena.sourceforge.net/ARQ/] engine, but specific parts of a Query (mostly batches of statement patterns) are evaluated natively through a modified StageGenerator plugged into the Jena runtime framework for efficiency. This also avoids unnecessary cross-API data transformations during query evaluation.
The Jena adapter can be used as follows, where a 'repositoryConnection' is obtained as in the example in the Sesame section above:
{code}import com.ontotext.jena.SesameDataset;
// Create the DatasetGraph instance
SesameDataset dataset = new SesameDataset(repositoryConnection);
{code}From now on the SesameDataset object can be used through the Jena API as regular Dataset, e.g. to add some data to it one could do something like the following:
{code}Model model = ModelFactory.createModelForGraph(dataset.getDefaultGraph());
Resource r1 = model.createResource("http://example.org/book#1");
Resource r2 = model.createResource("http://example.org/book#2");
r1.addProperty(DC.title, "SPARQL - the book")
.addProperty(DC.description, "A book about SPARQL");
r2.addProperty(DC.title, "Advanced techniques for SPARQL");
{code}The performance of GraphDB-SE when used through Jena is quite similar to using it through the Sesame APIs. For most of the scenarios and tasks GraphDB-SE can deliver considerable performance improvements when used as a replacement for Jena's own native RDF backend TDB. More information is provided on the [GraphDB through Jena Performance page|http://www.ontotext.com/owlim/owlim-jena-performance.html].
h1. Access Methods
GraphDB version is packaged as a Storage and Inference Layer (SAIL) for [Sesame version 2.x|http://www.openrdf.org/] and makes extensive use of the features and infrastructure of Sesame, especially the RDF model, RDF parsers and query engines. Inference is performed at load time, where the explicit and inferred statements are stored in highly-optimised data structures. The inferred closure is updated through inference at the end of each transaction that modifies the repository.
GraphDB implements the Sesame SAIL interface, so that it can be integrated with the rest of the Sesame framework, e.g. the query engines and the web user interface tools. A typical user application uses GraphDB directly through the Sesame SAIL API. When a GraphDB repository is exposed using the Sesame HTTP Server, users can manage the repository through the Sesame Workbench Web application, or with other tools that can integrate with Sesame, e.g. ontology editors like TopBraid Composer.
However, GraphDB-SE can also be used with the [Jena|http://jena.sourceforge.net/] framework, which is achieved with a customised Jena/Sesame/GraphDB-SE adapter component.
Sesame comprises a large collection of libraries, utilities and APIs, but the important components for this section are:
* the Sesame classes and interfaces (API) that provide uniform access to SAIL components from multiple vendors/publishers;
* the Sesame server and workbench Web applications (Java Enterprise Edition servlet components, referred to on the diagram below as "Sesame Web UI").
This section describes using the Sesame API to create and access GraphDB repositories, both on the local file-system and remotely via the Sesame HTTP server, plus a brief introduction is given to the Sesame workbench Web application, which provides many repository management functions through a convenient user interface. This is followed by information on using GraphDB-SE with Jena and some related components, i.e. [ARQ|http://jena.sourceforge.net/ARQ/] and [Joseki|http://www.joseki.org/].
h1. Sesame Application Programming Interface (API)
Programmatically, GraphDB is used via the Sesame Java framework of classes and interfaces. Documentation for these interfaces (including Javadoc) can be found at [http://www.openrdf.org|http://www.openrdf.org]. Code snippets in the following sections are taken from (or are variations of) the GettingStarted example program that comes with the GraphDB distribution.
h2. Using the Sesame API to access a local GraphDB repository
With Sesame 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. The example repository configuration from the getting-started example program looks like this:
{code}@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 "owlim" ;
rdfs:label "GraphDB Getting Started" ;
rep:repositoryImpl [
rep:repositoryType "openrdf:SailRepository" ;
sr:sailImpl [
sail:sailType "owlim:Sail" ;
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#" .
]
].
{code}.
The Java code to use the configuration to instantiate a repository and get a connection to it is as follows:
{code:title=Example Java code to create a repository|borderStyle=solid}Graph graph = ...;
Resource repositoryNode = ...;
// Create a manager for local repositories
RepositoryManager repositoryManager = new LocalRepositoryManager(new File("."));
repositoryManager.initialize();
// Create a configuration object from the configuration graph
// and add it to the repositoryManager
RepositoryConfig repositoryConfig = RepositoryConfig.create(graph, repositoryNode);
repositoryManager.addRepositoryConfig(repositoryConfig);
// Get the repository to use
Repository repository = repositoryManager.getRepository("owlim");
// Open a connection to this repository
RepositoryConnection repositoryConnection = repository.getConnection();
// ... use the repository
// Shutdown connection, repository and manager
repositoryConnection.close();
repository.shutDown();
repositoryManager.shutDown();
{code}Note that the code to parse this file and find the 'root' node for the configuration can be found in the getting-started program.
The procedure is as follows: instantiate a local repository manager with the data directory to use for the repository storage files (repositories will store their data in their own sub-directory from here), add a repository configuration for the desired repository type to the manager, '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 getting-started application for examples.
h2. Using the Sesame API to access a remote GraphDB repository
The Sesame 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. All that is required to connect to and use a remote repository instead of a local one, is to replace the local repository manager for a remote one. The URL of the Sesame 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 getting-started example program, although a correct URL must be specified:
{code:title=Example to create a connection to a remote repository|borderStyle=solid}RepositoryManager repositoryManager =
new RemoteRepositoryManager( "http://192.168.1.25:8080/openrdf-sesame" );
repositoryManager.initialize();
{code}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-logging-1.1.1.jar}}
* {{commons-codec-1.3.jar}}
h1. Managing repositories with the Sesame Workbench
The [installation section|GraphDB-SE Installation] explains how to set up a GraphDB repository that is exposed via the Sesame HTTP Server. In summary, the Sesame Server and Workbench applications are deployed to a Tomcat instance and the necessary library files (GraphDB, Lucene, etc) are copied to the correct locations. After this, the Sesame console application is used with the {{owlim.ttl}} repository template file to connect to the Sesame server and create a repository instance.
When the Sesame server is running, it will show a welcome message at the following URL:
{noformat}http://<hostname|ip_address>:8080/openrdf-sesame{noformat}The server has a simple user interface that shows status, logging and configuration information.
The workbench application, however, provides most repository management functions and is available from the following URL:
{noformat}http://<hostname|ip_address>:8080/openrdf-workbench{noformat}The workbench lists repositories and their namespaces, allows for the addition and deletion of statements, and provides a query interface for SPARQL and SeRQL query languages. However, the list of repository types is currently hard-coded in the workbench, so a GraphDB repository must still be created using the Sesame console application, as described in the [installation section|GraphDB-SE Installation].
h1. SPARQL endpoint
The Sesame HTTP server is a fully fledged SPARQL endpoint - the Sesame HTTP protocol is a super-set of the [SPARQL 1.1 protocol|http://www.w3.org/TR/sparql11-protocol/] - that 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 when deployed using the Sesame HTTP server, i.e. the openrdf-sesame Web application.
h1. Graph Store HTTP Protocol
T1he SPARQL 1.1 Graph Store HTTP Protocol is fully supported for direct and indirect graph names. The [W3C working draft|http://www.w3.org/TR/sparql11-http-rdf-update/] has the most details, although further information can be found in the [Sesame user guide|http://openrdf.callimachus.net/sesame/2.7/docs/users.docbook?view].
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.
h1. Using GraphDB-SE with Jena
[Jena|http://jena.sourceforge.net/] is a Java framework for building Semantic Web applications. It provides a programmatic environment for RDF, RDFS, OWL and SPARQL and includes a rule-based inference engine. Access to GraphDB-SE via the Jena framework is achieved with a special adapter, which is essentially an implementation of the Jena [ARQ|http://jena.sourceforge.net/ARQ/] interface that provides access to individual triples managed by a GraphDB-SE repository through the Sesame API interfaces.
{note}
The GraphDB specific Jena adapter can only be used with 'local' repositories, i.e. not 'remote' repositories that are accessed using the Sesame HTTP protocol.
{note}
The Jena adapter for GraphDB-SE is not a general purpose Sesame adapter and cannot be used to access any Sesame compatible repository, because it utilises an internal GraphDB-SE API to provide more efficient methods for processing RDF data and evaluating queries.
The adapter comes with its own implementation of a Jena 'assembler' factory to make it easier to instantiate and use with those related parts of the Jena framework, although one can instantiate an adapter directly by providing an instance of a Sesame SailRepository (a GraphDB-SE GraphDBRepository implementation). Query evaluation is controlled by the [ARQ|http://jena.sourceforge.net/ARQ/] engine, but specific parts of a Query (mostly batches of statement patterns) are evaluated natively through a modified StageGenerator plugged into the Jena runtime framework for efficiency. This also avoids unnecessary cross-API data transformations during query evaluation.
The Jena adapter can be used as follows, where a 'repositoryConnection' is obtained as in the example in the Sesame section above:
{code}import com.ontotext.jena.SesameDataset;
// Create the DatasetGraph instance
SesameDataset dataset = new SesameDataset(repositoryConnection);
{code}From now on the SesameDataset object can be used through the Jena API as regular Dataset, e.g. to add some data to it one could do something like the following:
{code}Model model = ModelFactory.createModelForGraph(dataset.getDefaultGraph());
Resource r1 = model.createResource("http://example.org/book#1");
Resource r2 = model.createResource("http://example.org/book#2");
r1.addProperty(DC.title, "SPARQL - the book")
.addProperty(DC.description, "A book about SPARQL");
r2.addProperty(DC.title, "Advanced techniques for SPARQL");
{code}The performance of GraphDB-SE when used through Jena is quite similar to using it through the Sesame APIs. For most of the scenarios and tasks GraphDB-SE can deliver considerable performance improvements when used as a replacement for Jena's own native RDF backend TDB. More information is provided on the [GraphDB through Jena Performance page|http://www.ontotext.com/owlim/owlim-jena-performance.html].