NG4J - Named Graphs API for Jena

• Graph-centric and quad-centric methods for manipulating sets of Named Graphs
• In-memory or database-persisted graphset storage
• Semantic Web Client Library which represents the complete Semantic Web as a single RDF graph
• Viewing graphsets as Jena models and Jena graphs
• Provenance-enabled Jena statements
• Querying of Named Graphs with the SPARQL query language
• Integrated parser and serializer for the TriG and TriX syntaxes including TriX syntactic extensions
• API support for the Semantic Web Publishing (SWP) vocabulary
• Creation and verification of graph signatures using X.509 certificates
• Directory reader and writer for importing and exporting graph sets as sets of classic RDF files.

Contents

1. Introduction
   1. Named Graphs
   2. NG4J
2. Usage Examples
   1. Operations on GraphSet and Model Level
   2. Querying Named Graphs with SPARQL
   3. Using Database Persistence
   4. Semantic Web Publishing (SWP) API and Digital Signatures
   5. Semantic Web Client Library
3. Download
4. Acknowledgements
5. Feedback

1. Introduction

This section gives an introduction into the ideas behind Named Graphs and the NG4J API.

1.1 Named Graphs

The Semantic Web can be seen as a collection of RDF graphs. The RDF recommendation explains the meaning of any one graph, and how to merge a set of graphs into one, but does not provide suitable mechanisms for talking about graphs or relations between graphs. But the ability to express metainformation about graphs is required for:

• Data syndication systems need to keep track of provenance information, and provenance chains.
• Restricting information usage: Information providers might want to attach information about intellectual property rights or their privacy preferences to graphs in order to restrict the usage of published information.
• RDF repository housekeeping: Triple stores need mechanisms to replace and update parts of their content.
• Access control: A triple store may wish to allow fine-grain access control, which appears as metadata concerning the graphs in the store.
• Signing RDF graphs: For signing RDF graphs it is necessary to keep the graph that has been signed distinct from the signature, and other metadata concerning the signing, which may be kept in a second graph.
• Expressing propositional attitudes such as modalities and beliefs.
• Scoping assertions and logic where logical relationships between graphs have to be captured.

RDF reification has well-known problems in addressing these use cases. To avoid these problems several authors propose quads, consisting of an RDF triple and a further URIref or blank node or ID. The proposals vary widely in the semantic of the fourth element, using it to refer to information sources, to model IDs or statement IDs or more generally to "contexts". Named Graphs propose a general and simple variation on RDF, using sets of named RDF graphs.

The name of a graph may occur either in the graph itself, in other graphs, or not at all. Graphs may share URIrefs but not blank nodes. Named Graphs can be seen as a reformulation of quads in which the fourth element's distinct syntactic and semantic properties are clearly distinguished, and the relationship to RDF's triples, abstract syntax and semantics is clearer.

Further details about Named Graphs are found in:

• W3C Named Graphs Website
• Jeremy Carroll, Chris Bizer, Pat Hayes, Patrick Stickler: Named Graphs, Provenance and Trust.

1.2 NG4J - Named Graph API for Jena

The Named Graphs API for Jena (NG4J) is an extension to the Jena Semantic Web toolkit for parsing, manipulating and serializing sets of Named Graphs. NG4J is an exerimental implementation of the new syntaxes (TriX, TriG) developed within the Semantic Web Interest Group. Its purpose is to have something for playing around with the new technologies.

Jena and the Model and Graph layers

Jena is a two-layered framework. Developers usually work with the Model layer, using types like Model, Statement and Resource. The Model layer is designed to be convenient to use for application programmers.

Beneath lies the Graph layer, whose most important types are Graph, Triple and Node. It offers functionality similar to the Model layer, but is less convenient to use for an application programmer, and is easier to work with when you design Jena system components like triple stores or inference engines.

NG4J lies between those two layers, using parts of both. Only a part of its functionality is exposed at the Model layer, by the NamedGraphModel class. The graph-centric and quad-centric methods are exposed directly on the Graph Layer.

Working with NamedGraphs and Quads

The basic idea of the NG4J API is to have a NamedGraphSet which represents a collection of Named Graphs. It can can be manipulated by adding and removing entire Graphs, or by working with individual Quads. The NamedGraph object wraps existing Jena graphs, meaning that GraphMem, GraphRDB and GraphD2RQ can be reused.

Working with Models and Resources

You can get a Jena model view on a NamedGraphSet, which can be used like a normal Jena model. The Jena Statements returned by this model or its resources can be casted to NamedGraphStatements. NamedGraphStatements can provide provenance information about the Named Graphs in which they are contained.

API Overview

The tables below give an overview about NG4J's main interfaces and their most important methods. See JavaDoc for details about all methods.

2. Usage Examples

2.1 Operations on GraphSet and Model Level

////////////////////////////////////////////////
//         Operations on GraphSet Level
////////////////////////////////////////////////

// Create a new graphset
NamedGraphSet graphset = new NamedGraphSetImpl();

// Create a new NamedGraph in the NamedGraphSet
NamedGraph graph = graphset.createGraph("http://example.org/persons/123");

// Add information to the NamedGraph
graph.add(new Triple(Node.createURI("http://richard.cyganiak.de/foaf.rdf#RichardCyganiak"),
        Node.createURI("http://xmlns.com/foaf/0.1/name") ,
        Node.createLiteral("Richard Cyganiak", null, null)));

// Create a quad
Quad quad = new Quad(Node.createURI("http://www.bizer.de/InformationAboutRichard"),
        Node.createURI("http://richard.cyganiak.de/foaf.rdf#RichardCyganiak"),
        Node.createURI("http://xmlns.com/foaf/0.1/mbox") ,
        Node.createURI("mailto:richard@cyganiak.de"));

// Add the quad to the graphset. This will create a new NamedGraph in the
// graphset.
graphset.addQuad(quad);

// Find information about Richard across all graphs in the graphset
Iterator it = graphset.findQuads( 
        Node.ANY, 
        Node.createURI("http://richard.cyganiak.de/foaf.rdf#RichardCyganiak"),
        Node.ANY,
        Node.ANY);

while (it.hasNext()) {
    Quad q = (Quad) it.next();
    System.out.println("Source: " + q.getGraphName());
    System.out.println("Statement: " + q.getTriple());
    // (This will output the two statements created above)
}

// Count all graphs in the graphset (2)
System.out.println("The graphset contains " + graphset.countGraphs() + " graphs.");

// Serialize the graphset to System.out, using the TriX syntax
graphset.write(System.out, "TRIX", null);

////////////////////////////////////////////////
//         Operations on Model Level
////////////////////////////////////////////////

// Get a Jena Model view on the GraphSet
Model model = graphset.asJenaModel("http://example.org/defaultgraph");

// Add provenance information about a graph
Resource informationAboutRichard = model.getResource("http://www.bizer.de/InformationAboutRichard");
informationAboutRichard.addProperty(model.createProperty("http://purl.org/dc/elements/1.1/author"), "Chris Bizer");
informationAboutRichard.addProperty(model.createProperty("http://purl.org/dc/elements/1.1/date"), "09/15/2004");

// Get a Jena resource and statement
Resource richard = model.getResource("http://richard.cyganiak.de/foaf.rdf#RichardCyganiak");

NamedGraphStatement mboxStmt = 
        (NamedGraphStatement) richard.getProperty(model.getProperty("http://xmlns.com/foaf/0.1/mbox"));

// Get an iterator over all graphs which contain the statement.
it = mboxStmt.listGraphNames();

// So who has published my email address all over the Web??!?
while (it.hasNext()) {
    Resource g = (Resource) it.next();
    System.out.println();
    System.out.println("GraphName: " + g.toString());
    System.out.println("Author: " + 
        g.getProperty(model.getProperty("http://purl.org/dc/elements/1.1/author")).getString());
    System.out.println("Date: " + 
        g.getProperty(model.getProperty("http://purl.org/dc/elements/1.1/date")).getString());
}

// Serialize the model to System.out, using the TriG syntax
model.write(System.out, "TRIG", "http://richard.cyganiak.de/foaf.rdf");

When run, the example code will write this output to System.out.

2.2 Querying Named Graphs with SPARQL

The SPARQL RDF query language supports queries on sets of named graphs. The GRAPH keyword can be used to select a specific graph, or to bind to a variable the names of all graphs whose contents match a query pattern:

PREFIX foaf: <http://xmlns.com/foaf/0.1/>
SELECT ?otherFoafFile
WHERE {
  GRAPH <http://example.org/my-foaf.rdf> {
    ?me foaf:mbox <mailto:me@example.org> .
  }
  GRAPH ?otherFoafFile {
    ?otherFoafFile foaf:maker ?someone
    ?someone foaf:knows ?me .
  }
}

The first part reads my FOAF file and selects the resource representing me (by matching my email address). The second part finds and returns all FOAF files whose makers claim to know me. Note that all the files in question must have been loaded into the graph set before the query is executed.

As an alternative approach, NG4J also includes a Semantic Web Client that tries to load files transparently from the Web as required to answer a query.

Here's the code for running a SPARQL query against a NamedGraphSet:

Query sparql = QueryFactory.create(
        "SELECT * WHERE { GRAPH ?graph { ?s ?p ?o } }");
QueryExecution qe = QueryExecutionFactory.create(
        sparql, new NamedGraphDataset(set));
ResultSet results = qe.execSelect();
while (results.hasNext()) {
    QuerySolution result = results.nextSolution();
    RDFNode graph = result.get("graph");
    RDFNode s = result.get("s");
    RDFNode p = result.get("p");
    RDFNode o = result.get("o");
    System.out.println(graph + " { " + s + " " + p + " " + o + " . }");
}

This will run the query and print the results.

2.3 Using Database Persistence

NamedGraphSets can be stored in a relational database. As of NG4J v0.9, HSQLDB, MySQL, Oracle, PostgreSQL, and Apache Derby are supported. To create a persistent NamedGraphSet, you have to set up a java.sql database connection and create a new NamedGraphSetDB instance:

String URL = "jdbc:mysql://localhost/db_name";
String USER = "username";
String PW = "mypassword";
Class.forName("com.mysql.jdbc.Driver");
Connection connection = DriverManager.getConnection(URL, USER, PW);
NamedGraphSet set = new NamedGraphSetDB(connection);
// ...
set.close();

The resulting NamedGraphSet can be used just like a normal in-memory NamedGraphSet.

Optionally, you can specify a table prefix that will be stuck in front of all database table names. This allows multiple NamedGraphSets to coexist in the same database. There's also a method for deleting sets from the database.

NamedGraphSet set = new NamedGraphSetDB(connection, "myapp");
// ...
NamedGraphSetDB.delete(connection, "myapp");

2.4 Semantic Web Publishing (SWP) API and Digital Signatures

Working with Digital Signatures and Named Graphs

The Semantic Web Publishing Vocabulary (SWP) is used for publishing Named Graphs on the Web. It allows authorities to indicate whether they assert or quote a graph and to sign graphs using digital signatures. More information about the SWP vocabulary is available on the TriQL.P Trust Architecture page.

The SWP API in NG4J builds on the NamedGraphSet inferface. Named Graphs are asserted or quoted by an SWPAuthority, a service or person that is able to publish information. The authority must have a valid X.509 certificate in order to be able to sign Named Graphs.

Signing Named Graphs

The general algorithm for signing and recording the digital signature of a Named Graph is as follows:

• Take a Named Graph and find its canonical representation (see Jeremy Carroll: Signing RDF Graphs).
• Using a common secure hash (SHA-1 or stronger), record the digest of the canonical Named Graph.
• We place the digest into a separate Named Graph which we call a Warrant Graph. Besides asserting or quoting the original graph, the Warrant Graph also asserts itself. More on Warrant Graphs in section 5 of the Named Graphs paper.
• Finally, take the canonical representation of the Warrant Graph and sign it with the SWPAuthority's private key, using a common secure method (SHA1WithDSA or SHA1WithRSA). Add the signature to the Warrant Graph.
• Now, the signed Warrant Graph can be published.

Verifying Signatures

Named Graph digital signatures can be verified in the following manner:

• Retrieve the Named Graph's Warrant Graph and extract the digital signature and X.509 certificate. We retrieve the X.509 certificate, because we want to have access to the SWPAuthority's public key.
• Verify the signature on the Warrant Graph using the public key. If this verification succeeds, we know that the SWPAuthority has published the Named Graph.
• Again, find the Named Graph's canonical representation and its digest.
• Compare the digest to the one recorded int the Warrant Graph. If they don't match, then the Named Graph has changed it's contents since it was signed. We count this as a verification failure.
• If the digests did match, verification was successful.

Usage Example

SWPNamedGraphSet set = new SWPNamedGraphSetImpl();
	
//Create an SWPAuthority so we can assert/quote graphs
SWPAuthority auth = new SWPAuthorityImpl();

// set the email addr of the authority (FOAF vocabulary)
auth.setEmail("mailto:rowland@grid.cx");

// set the ID of the authority
auth.setID(Node.createURI("http://grid.cx/rowland"));

// set the X.509 certificate using the users' PKCS #12 keystore
Certificate[] chain = de.fuberlin.wiwiss.ng4j.swp.utils.PKCS12Utils.getCertChain(keystore, password);
auth.setCertificate((X509Certificate )chain[0]);

String keystore = "/path/to/your/pkcs12/keystore";
String password = "passwd";

// Assert all graphs in the NamedGraphSet
// We provide an Authority, a Node specifying the signature algorithm (SHA1WithRSA),
// a Node specifying the digest method (SHA-1), a null list of properties,
// a path the a PKCS #12 keystore, and its password.
set.assertWithSignature(auth, 
			SWP.JjcRdfC14N_rsa_sha1, 
			SWP.JjcRdfC14N_sha1, 
			null, 
			keystore, 
			password);

// Verify all signatures in the NamedGraphSet
set.verifyAllSignatures();

// print out the resulting NamedGraphSet
set.write(System.out, "TRIG", "");

The output might look like this.

Manipulating PKCS #12 keystores

Unless you are willing to write certificate management tools yourself, using Bouncy Castle, Cryptix or IAIK, you will most likely want to use OpenSSL to generate and manage your certificates.

While OpenSSL provides a wide range of options got generating DSA and RSA keys with other features, it can be very cumbersome to use. Each OpenSSL distribution should contain a perl script called CA.pl which makes life a little bit easier.

Before you can generate your own certificates, you need to have a Certificate Authority (CA) that can be used to vouch for the veracity of your certificate. Unless you already have a CA, you will want to make your own.

Generating the CA: The CA can can be generated using the CA.pl script using the following command:

./CA.pl -newca

User certifcates can be generated by first creating a certificate request, to be signed by the CA:

./CA.pl -newreq
./CA.pl -sign

Once you have your certicate request signed, you can then package it into a PKCS #12 keystore. The following command will achieve this:

./CA.pl -pkcs12

You should now have a file called newcert.p12. This is the file that you should use as input to any of the methods in SWPNamedGraphSet.

2.5 Semantic Web Client Library

NG4J's Semantic Web Client Library represents the complete Semantic Web as a single set of named graphs. When queried, the SemanticWebClient dynamically retrieves information from the Semantic Web by dereferencing HTTP URIs, by following rdfs:seeAlso links, and by querying the Sindice search engine. It is described in a separate document: Semantic Web Client Library.

3. Download

• NG4J can be downloaded from Sourceforge: http://sourceforge.net/projects/ng4j/
• NG4J version 0.9 is designed to work with Jena 2.5.6, which is included with the NG4J distribution. Expect problems when using it with different versions of Jena.
• NG4J is licensed under the terms of the Berkeley Software Distribution (BSD) License.

4. Acknowledgements

NG4J is developed by:

• Chris Bizer (chris@bizer.de, www.bizer.de)
• Richard Cyganiak (richard@cyganiak.de, richard.cyganiak.de)
• Tobias Gauß (tobias.gauss@web.de)
• Olaf Hartig (hartig at informatik.hu.berlin.de, olafhartig.de)
• Jennifer P. Cormier (jennifer at atc-nycorp.com)

Lots of thanks to those who have contributed to the project:

• Rowland Watkins (erw01r at ecs.soton.ac.uk) for his work on the SWP API.
• Stelios Sfakianakis (ssfak at ics.forth.gr) for implementing the GRDDL support.
• Jesper Zedlitz (jesper at zedlitz.de) for his work on the unit tests and build system.
• Tim Pizey (tim.pizey at oucs.ox.ac.uk) for his work on Maven support.
• Hannes Mühleisen for his work on the RDFa support in the Semantic Web Client Library.

5. Support and Feedback

Additional information about NG4J is available on the project's wiki. See the MediaWiki Hosted Application at the NG4J SourceForge site http://sourceforge.net/apps/mediawiki/ng4j/.

We are interested in hearing about your opinion and your experience with NG4J. Please sent comments and bug reports to the NG4J-namedgraphs mailing list:

ng4j-namedgraphs@lists.sourceforge.net

The archives of the list are found at http://sourceforge.net/mailarchive/forum.php?forum=ng4j-namedgraphs
You can subscribe to the list at http://lists.sourceforge.net/lists/listinfo/ng4j-namedgraphs.

A maven generated Web site about the NG4J project is available at http://paneris.net/ng4j/index.html.

$Date: 2010/02/25 14:27:58 $
$Id: index.html,v 1.42 2010/02/25 14:27:58 hartig Exp $