The Sesame Cookbook has moved to my new site: http://rivuli-development.com/
The Sesame framework includes a set of parsers and writers called Rio. Rio (a rather imaginative acronym for "RDF I/O") is a toolkit that can be used independently from the rest of Sesame. In this recipe, we will take a look at various ways to use Rio to parse from or write to an RDF document. I will show how to do a simple parse and collect the results, how to count the number of triples in a file, how to convert a file from one syntax format to another, and how to dynamically create a parser for the correct syntax format.If you use Sesame as a triplestore (via the Repository API), then typically you will not need to use the parsers directly: you simply supply the document (either via a URL, or as a File, InputStream or Reader object) to the RepositoryConnection and the parsing is all handled internally. However, sometimes you may want to parse an RDF document without immediately storing it in a triplestore. For those cases, you can use Rio directly.
The Rio parsers all work with a set of Listener interfaces that they report results to: ParseErrorListener, ParseLocationListener, and RDFHandler. Of these three, RDFHandler is the most useful one: this is the listener that receives parsed RDF triples. So we will concentrate on this interface here.
The RDFHandler interface is quite simple, it contains just five methods: startRDF, handleNamespace, handleComment, handleStatement, and endRDF. Rio also provides a number of default implementations of RDFHandler, such as RDFInserter, which immediately adds any received RDF triples to its supplied RepositoryConnection, and StatementCollector, which stores all received RDF triples in a Java Collection. Depending on what you want to do with parsed statements, you can either reuse one of the existing RDFHandlers, or, if you have a specific task in mind, you can simply write your own implementation of RDFHandler. Here, I will show you some simple examples of things you can do with RDFHandlers.
Collecting all parsed triples in a List
As a simple example of how to use Rio, we parse an RDF document and collect all the parsed statements in a Java List object. For this, we need the following ingredients:
- an RDF file;
- a RDFParser object;
- a RDFHandler object.
java.net.URL documentUrl
= new URL("http://example.org/example.ttl");
= new URL("http://example.org/example.ttl");
InputStream inputStream = documentUrl.openStream();
We now have an open InputStream to our RDF file. Now we need a RDFParser object that reads this InputStream and creates RDF statements out of it. Since we are reading a Turtle file, we create a TurtleParser object:
RDFParser rdfParser = new TurtleParser();
(note: all Rio classes and interfaces are in package org.openrdf.rio or one of its subpackages)
We also need an RDFHandler which can receive RDF statements from the parser. Since we just want to create a Java List of Statements for now, we'll just use Rio's StatementCollector:
java.util.ArrayList myList = new ArrayList();
StatementCollector collector = new StatementCollector(myList);
rdfParser.setRDFHandler(collector);
Finally, we need to set the parser to work:
try {
rdfParser.parse(inputStream, documentURL.toString());
}
catch (IOException e) {
// handle IO problems (e.g. the file could not be read)
}
catch (RDFParseException e) {
// handle unrecoverable parse error
}
catch (RDFHandlerException e) {
// handle a problem encountered by the RDFHandler
}
After the parse() method has executed (and provided no exception has occurred), the list myList will be filled by the StatementCollector. As an aside: you do not have to provide the StatementCollector with a list in advance, you can also use an empty constructor and then just get the collection, using StatementCollector.getStatements() .
Using your own RDFHandler: counting statements
As a simple example of writing your own RDFHandler, suppose you want to simply count the number of triples in the RDF file. You could of course use the above code for this, adding all triples to a List, and then just checking the size of the List. However, this will get you into trouble when you are parsing very large RDF files: you might run out of memory. And in any case: creating and storing all these Statement objects just to be able to count them seems a bit of a waste. So instead, we will create our own RDFHandler, which just counts the parsed RDF statements and then immediately throws them away.
To create your own RDFHandler implementation, you can of course just create a class that implements the RDFHandler interface, but a useful shortcut is to instead create a subclass of RDFHandlerBase. This is a base class that provides dummy implementations of all interface methods. The advantage is that you only have to override the methods in which you need to do something. Since what we want to do is just count statements, we only need to override the handleStatement method. Additionaly, we of course need a way to get back the total number of statements found by our counter.
class StatementCounter extends RDFHandlerBase {
private int countedStatements = 0;
@Override
public void handleStatement(Statement st) {
countedStatements++;
}
public int getCountedStatements() {
return countedStatements;
}
}
Once we have this, our custom RDFHandler class, we can supply that to the parser instead of the StatementCollector, and we're done.
Converting RDF serialization formats
A useful trick with Rio is to pipeline parsers and writers. Since all Rio RDFWriters are in fact RDFHandler implementations, you can directly supply them to a parser, thus creating a very simple syntax convertor.
Say, you have a file in Turtle format, and you want to convert it to RDF/XML. Simply create a TurtleParser as shown above, and provide it with a RDFXMLWriter, which is an RDFHandler implementation that writes the received RDF statements to an outputstream in RDF/XML format.
Creating the right parser for the right format
In the examples sofar, we have created a parser by simply using the constructor of the specific format's parser class. In other words: our program code assumes that the input file is a Turtle file, so we just create a new TurtleParser object. However, you may not always know in advance what exact format the RDF file is in. What then? Fortunately, Rio has a couple of useful features to help you.
The Rio class is a factory class which can create a RDFParser object given a specific RDFFormat. RDFFormat is a set of constants defining the available serialization formats. It also has a couple of utility methods for guessing the correct format, given either a filename or a MIME-type. For example, to get back the RDF format for our Turtle file, we could do the following:
RDFFormat format = RDFFormat.forFileName(documentURL.toString());
This will guess, based on the extension of the file (.ttl) that the file is a Turtle file and return the correct format. We can then use that with the Rio factory class to create the correct parser dynamically:
RDFParser rdfParser = Rio.createParser(format);
As you can see, we still have the same result: we have created an RDFParser object which we can use to parse our file, but now we have not made the explicit assumption that the input file is in Turtle format: if we would later use the same code with a different file (say, a .owl file - which is in RDF/XML format), it would still work.
Summary
I have tried to show a couple of useful ways to employ Rio in practice. It is a versatile set of streaming RDF parsers and writers that can be easily used in your own programs, and it can be used separately from the rest of the Sesame framework. Of course, more could be said about it (for example, how to configure its error handling, datatype verification, and so on), but that's for next time and/or the comments. Enjoy! And any feedback on these recipes is of course much appreciated.
