Trippi 1.1.2

1. What is Trippi?

Trippi (pronounced, 'tri-pE) is a Java library providing a consistent, thread-safe access point for updating and querying a triplestore. It is similar in spirit to JDBC, but for RDF databases.

In addition to the API, the Trippi distribution comes with two higher-level applications for working with triplestores: A console and a web service. These are described in the following sections.

Trippi connectors currently exist for Sesame, Kowari, Oracle Spatial, and MPTStore. See the Trippi Implementation Guide for details on how to write a Trippi adapter for your own triplestore software.

2. Downloading and Installing

Download the latest release from SourceForge.
View the release notes.
Use the console to get familiar with Trippi.
Use Trippi in your application by including the appropriate libraries (see the lib/ directory) and using the Java API.
NOTE: To configure logging:
- If you don't already have Log4J set up for your project, edit the included log4j.xml and make sure it's in your CLASSPATH. For some help with Log4J configuration, see the Log4J XML Configuration Primer.
- If you're already using Log4J, add Trippi logging categories to your existing configuration, if desired.

3. Using the Console

The Trippi console is a text-oriented Java application for working with Trippi-enabled triplestores.

Creating a Model

A model is an RDF graph in a triplestore. To create a model using the Trippi console:

Go to the trippi distribution directory and start the console: trippi -c
Create a profile (connection settings for a specific triplestore) using the create command: create;
Respond to the prompts.

Once a profile is created, you can access it within the console using use myprofile;, where myprofile is the name you gave it when you created it.

You can also specify a profile when you start the console. Try this:

Exit the console: exit;
Start it again, specifying your profile name: trippi -c myprofile

The first time a profile is used in the console, the underlying RDF model is automatically created.

When working with a model in the console you can use the add command to add triples manually, or you can use the load command to load them from a file in one of several formats. The following illustrates both methods, and introduces the count and tripleform commands:

trippi/stest> add <urn:example:Chris> <urn:example:firstName> "Chris";

Adding 1 triples...OK

trippi/stest> add <urn:example:Chris> <urn:example:lastName> "Wilper"
> <urn:example:Chris> <urn:example:favoriteColor> "Orange";

Adding 2 triples...OK

trippi/stest> count;

Total Triples  : 3
Seconds Elapsed: 0.04

trippi/stest> tripleform;

Current Triple Result Format: Turtle
Formats Supported: N-Triples, Notation 3, RDF/XML, Turtle

trippi/stest> tripleform RDF/XML;

New Triple Result Format: RDF/XML

trippi/stest> load samples/routes/airports.xml;

Loading triples (in RDF/XML format) from samples/routes/airports.xml...OK

trippi/stest> count;

Total Triples  : 2371
Seconds Elapsed: 0.48

trippi/stest>

After running the above commands, try loading the other sample RDF/XML files in the samples/routes directory of the distribution. This data will be used for queries in the next section.

Dumping RDF from a Model

You have already seen how the tripleform command can be used to specify the triple format for loading RDF. The same command is used to set the serialization format for dumping triples from a model.

The following example sets the format to Turtle, then uses the dump command to serialize all triples to a file in the current directory:

trippi/stest> tripleform turtle;

New Triple Result Format: Turtle

trippi/stest> dump all-triples.turtle;

Dumping triples (in Turtle format) to all-triples.turtle...OK

Querying a Model

Trippi supports two broad types of queries: triple queries and tuple queries. To make effective use of Trippi, it's important to understand the difference.

A triple query is one that returns a series of RDF triples: Each response row consists of a subject, predicate, and an object.

A tuple query, on the other hand, returns responses that traditional database users will be more familiar with: Each response row is a map of name-value pairs.

SPO Queries

SPO (Subject, Predicate, Object) is a very simple triple query language. It is also the only query language that is guaranteed to be supported by every Trippi-enabled triplestore.

An SPO query consists of three tokens: an RDF subject, predicate, and object. Any (or all) of these tokens can be an asterisk, a wildcard meaning "any". The following example illustrates several different SPO queries.

trippi/stest> tripleform N-Triples;

New Triple Result Format: N-Triples

trippi/stest> triples spo <urn:example:Chris> <urn:example:firstName> *;

<urn:example:Chris> <urn:example:firstName> "Chris" .

Total Triples  : 1
Seconds Elapsed: 0.02

trippi/stest> triples spo <urn:example:Chris> * *;

<urn:example:Chris> <urn:example:firstName> "Chris" .
<urn:example:Chris> <urn:example:favoriteColor> "Orange" .
<urn:example:Chris> <urn:example:lastName> "Wilper" .

Total Triples  : 3
Seconds Elapsed: 0.03

trippi/stest> triples spo * <urn:example:favoriteColor> *;

<urn:example:Chris> <urn:example:favoriteColor> "Orange" .


Total Triples  : 1
Seconds Elapsed: 0.03

Note that the SPO query * * * can be used to list all triples in a model. This is the actual query used internally by the console to support the dump command.

Tuple Queries

Triplestores support a variety of languages that return rows of named values. The queries below illustrate a request for the same data, but from different triplestores (Kowari, then Sesame). The tupleform command is also introduced. You'll notice that it is similar to the tripleform command.

trippi> tupleform;

Current Tuple Result Format: TSV
Formats Supported: CSV, Simple, Sparql, TSV

trippi> tupleform simple;

New Tuple Result Format: Simple

trippi> use ktest;

Connecting to Kowari Test...OK

trippi/ktest> tuples
> itql
> select    $miles
>           $fromName
>           $toName
> from      <#ktest>
> where         $route <travel:miles>     $miles
>           and $miles <tucana:lt>        '36'      in <#xsd>
>           and $route <cyc:fromLocation> $from
>           and $route <cyc:toLocation>   $to
>           and $from  <dc:title>         $fromName
>           and $to    <dc:title>         $toName
> order by  $miles;

miles    : "15.0"^^xsd:double
fromName : "Berlin Tegel DE"
toName   : "Berlin Schoenefeld DE"

miles    : "15.0"^^xsd:double
fromName : "Berlin Schoenefeld DE"
toName   : "Berlin Tegel DE"

miles    : "31.0"^^xsd:double
fromName : "Rishiri JP"
toName   : "Wakkanai JP"

miles    : "31.0"^^xsd:double
fromName : "Wakkanai JP"
toName   : "Rishiri JP"

miles    : "35.0"^^xsd:double
fromName : "Cozumel MX"
toName   : "Cancun MX"

miles    : "35.0"^^xsd:double
fromName : "Cancun MX"
toName   : "Cozumel MX"

Total Tuples   : 6
Seconds Elapsed: 0.311

trippi/ktest> use stest;

Connecting to Sesame Test...OK

trippi/stest> tuples serql select miles, fromName, toName
> from   {route}    travel:miles     {miles},
>        {route}    cyc:fromLocation {fromLoc},
>        {route}    cyc:toLocation   {toLoc},
>        {fromLoc}  dc:title         {fromName},
>        {toLoc}    dc:title         {toName}
> where  miles < "36"^^xsd:double;

miles    : "15"^^xsd:double
fromName : "Berlin Tegel DE"
toName   : "Berlin Schoenefeld DE"

miles    : "15"^^xsd:double
fromName : "Berlin Schoenefeld DE"
toName   : "Berlin Tegel DE"

miles    : "35"^^xsd:double
fromName : "Cancun MX"
toName   : "Cozumel MX"

miles    : "35"^^xsd:double
fromName : "Cozumel MX"
toName   : "Cancun MX"

miles    : "31"^^xsd:double
fromName : "Rishiri JP"
toName   : "Wakkanai JP"

miles    : "31"^^xsd:double
fromName : "Wakkanai JP"
toName   : "Rishiri JP"

Total Tuples   : 6
Seconds Elapsed: 1.051

Triples From Tuples

Sometimes it is useful to derive triples from the results of a tuple query. One obvious example is extracting a subgraph. Another example is to transform an RDF graph to another form.

The README-sesame.txt and README-kowari.txt files in the samples/routes directory show how this can be done for each of these triplestores. Notice that Sesame includes a special construct command in the query language itself, whereas in the Kowari example, a tuples-to-triples template is provided and Trippi internally takes care of the conversion while iterating the results from the server.

4. Using the Query Web Service

The Trippi Web Service is a REST-oriented web service for providing read-only access to Trippi-enabled triplestores.

This guide will eventually explain how to use the service. In the meantime, see the Fedora Resource Index Search Service for a Fedora-oriented guide to the service.

5. Using the Java API

The main interfaces you work with in the Trippi API are TriplestoreReader, TriplestoreWriter, TripleIterator, and TupleIterator.

When working with individual triples, the JRDF API is used. This is a triplestore-neutral API that Trippi uses to represent Triples and RDF nodes.

Here is an example illustrating how to do an SPO query using Trippi with Sesame, and dumping the results to an RDF/XML file.


TriplestoreConnector sesame = null;
try {
    String sesameClassName = "org.trippi.impl.SesameConnector";
    Map sesameConfig = new HashMap();
    sesameConfig.put("storageType", "native");
    sesameConfig.put("dir", "/tmp/stest");
    sesameConfig.put("autoFlushDormantSeconds", "2");
    sesameConfig.put("autoFlushBufferSize", "1000");
    sesameConfig.put("bufferSafeCapacity", "2000");
    sesameConfig.put("bufferFlushBatchSize", "1000");

    TriplestoreConnector sesame = TriplestoreConnector.init(sesameClassName,
                                                            sesameConfig);
    TriplestoreReader sesameReader = sesame.getReader();

    TripleIterator triples = sesameReader.findTriples("SPO", 
                                                      "* * *",  // everything
                                                      -1,       // no limit
                                                      false);   // don't worry 
                                                                // about duplicates

    triples.toStream(new FileOutputStream(new File("all.xml")),
                     RDFFormat.RDF_XML);

} finally {
    if (sesame != null) {
        try { sesame.close(); } catch (Exception e) { }
    }
}

6. Known Issues / Bugs

Limited Transaction Support.
Transactions are typically used at a low level to implement the flushing of updates, but there is no exposure of the concept of a transaction at the public API level. Support for external transaction demarcation would involve significant API changes.