Running Ripple

Getting the software

There are several ways to get going with Ripple:

Download

The quickest way to get a standalone distribution of Ripple is to [download the latest release](https://github.com/joshsh/ripple/archives/master download). After downloading, unpack the archive and navigate into the ripple directory.

Build from source

The Ripple implementation is hosted here on GitHub. To build the latest:

1. check out the source code:

git clone git://github.com/joshsh/ripple.git

2. navigate into the top-level directory

cd ripple

3. build with Maven:

mvn clean install

Importing with Maven

To import Ripple into another (Java- and Maven-based project), add the following to your Maven POM:

    <repositories>
        ...
        <repository>
            <id>fortytwo</id>
            <name>fortytwo.net Maven repository</name>
            <url>http://fortytwo.net/maven2</url>
        </repository>
        ...
    </repositories>

    <dependencies>
        ...
        <dependency>
            <groupId>net.fortytwo.ripple</groupId>
            <artifactId>ripple-blueprints</artifactId>
            <version>0.7-SNAPSHOT</version>
        </dependency>
        ...
    </dependencies>

Notes:

1. this imports the ripple-blueprints module, which in turn depends on most of the other Ripple modules, including Blueprints support, LinkedDataSail, and the Ripple command line. If you don't need everything, you can substitute the artifactId with the name of another module such as ripple-demo (LinkedDataSail and the command line only), ripple-sesame (RDF-based model and query engine, but no command line and no Linked Data), or even ripple-core (Ripple core primitives, support for pipes and filters).
2. this imports the latest snapshot build of Ripple. If you're not feeling so adventurous, you can use the latest stable version (see the downloads section or browse the Maven repository) instead.

The Ripple command line

To start the Ripple command line interpreter:

1. get or build a Ripple distribution, as above
2. cd into the ripple/ripple-demo directory
3. execute the script ./ripple.sh
4. from here, you can evaluate expressions and issue commands. For example, type 2 3 add.
5. to exit Ripple, type @quit

Embedded Ripple

Query pipes

Configuration

Using NativeStore instead of MemoryStore

Be default, Ripple uses a Sesame MemoryStore to collect the Linked Data that you stumble upon. When Ripple quits, that collection is lost.

You can run Ripple using NativeStore (as well as other Sail implementations) instead of MemoryStore, which will store the Linked Data cache in a local directory. When you quit Ripple, the collection will remain in that directory, and will be available in subsequent sessions. Make sure to @quit instead of unix kill so that Ripple can shut down the NativeStore.

Ripple uses a NativeStore when the java property net.fortytwo.ripple.demo.linkedDataSailBaseSail is set to org.openrdf.sail.nativerdf.NativeStore. When set, the java property net.fortytwo.ripple.demo.nativeStoreDirectory needs to point to a local directory to use as a NativeStore.

The easiest way to pass these properties to Ripple is to put them into a file and pass the filename to ripple.sh:

desktop-native-store.properties:

# Aggregate linked RDF data on the fly.
net.fortytwo.ripple.demo.sailType = net.fortytwo.linkeddata.sail.LinkedDataSail

# Use Sesame NativeStore for persistent storage of aggregated data.
net.fortytwo.ripple.demo.linkedDataSailBaseSail = org.openrdf.sail.nativerdf.NativeStore
net.fortytwo.ripple.demo.nativeStoreDirectory = /Users/lebot/Desktop/ripple-store 

# invoke with ./ripple.sh this-file.properties

./ripple.sh desktop-native-store.properties

When you don't specify a required property, Ripple falls back on its default configuration.

The Ripple command line

...

Some programs are simply convenient aliases for long, messy URIs:

@define beijing: <http://dbpedia.org/resource/Beijing>

That last list wraps the DBpedia resource for Beijing with a handy name. You can dequote the list and begin exploring the Linked Data neighborhood of the resource like so:

:beijing.

If you traverse to other resource URIs which have been identified with Beijing:

@prefix owl: <http://www.w3.org/2002/07/owl#>
:beijing. owl:sameAs?

...you will discover a place hierarchy in GeoNames which you can explore using regular expression syntax:

@prefix geonames: <http://www.geonames.org/ontology#>
:beijing. owl:sameAs? geonames:parentFeature* geonames:name. distinct.

This gives you the following result (if not, tap the up key to repeat the query; any bad links encountered on the first try will be skipped the next time around):

  [1]  "Beijing"
  [2]  "Beijing Shi"
  [3]  "China"
  [4]  "Asia"
  [5]  "Earth"

Our path is becoming a little complex for copy-and-paste, so let's @define a new program:

@define place hierarchy:    \
    place owl:sameAs?       \
    geonames:parentFeature* \
    geonames:name. distinct.

Note that the @prefix commands for the owl and geonames namespaces are required for this to work properly. Now you can refer to your path by name, and apply it to Beijing:

:beijing. :hierarchy.

If you have the URI for another place in DBpedia or GeoNames, you can re-use the program:

@define spokane: <http://sws.geonames.org/5811696/>
:spokane. :hierarchy.

After one or more runs, this gives you the following result:

  [1]  "Spokane"
  [2]  "Spokane County"
  [3]  "Washington"
  [4]  "United States"
  [5]  "North America"
  [6]  "Earth"