Redleaf

Version: 0.0.1

Design Overview

This is an overview of the design of Redleaf, where it differs from the Redland library’s API, along with links into the appropriate Guided Tour page that provides examples and covers the topic in greater detail.

Redland Library Classes

The Redleaf classes follow the basic design of the Redland library, from which it derives most of its underlying functionality, with a few changes. Here’s the class layout borrowed from The Design and Implementation of the Redland RDF Application Framework:

The classes that make up the Redland library.

Redleaf Library Classes

Redleaf simplifies the view of the library somewhat, hiding Stream and the collection classes behind more-familiar Ruby interfaces, removing the need to construct intermediate instances of Query and Serializer, and mapping Node and URI objects to and from native Ruby objects:

How Redland classes map to Redleaf ones.

A simplified view of the classes you’ll use in Redleaf looks something like this:

Redleaf classes.

Nodes

The biggest change is that Redleaf is written with the idea that you will want to use regular Ruby values for statement values in the Graph, not instances of a specialized “node” type that you have to wrap and unwrap yourself.

To facilitate this, Redleaf provides a mapping of some of the more common Ruby classes to types in the XML Schema namespace, and a way to extend the conversion system with your own datatypes. It also uses the standard-library URI class instead of a Redland-specific one, and translates Strings containing URIs in most places where a URI is expected.

Type-conversion and blank nodes are covered in the Node Type System section.

Other Changes

Beyond that, the changes are pretty minor.

• There are several shortcuts and convenience methods for creating triples without instantiating each Redleaf::Statement individually; there’s a whole chapter about Statements that covers that.
• The Redland Model class is called Redleaf::Graph (though there’s an alias to Redleaf::Model if you really want it). Working With Graphs in the guided tour covers most of what you need to know to get started.
• The Redland Storage class is called Redleaf::Store, and is covered in the Triple Stores section of the tour.
• Most of the Redland “Support Classes”, and the Stream, Serializer, and Query classes don’t have corollaries in Redleaf; they are used behind the scenes.
  • The Redland Query class is used by the #query method of the Graph class, but it doesn’t have a corollary in Redleaf; the conversion to the appropriate data structure is done for you from a String, and #query returns a Redleaf::QueryResult object that encapsulates the results. This is covered by the Querying section of the Graphs chapter.
  • The Redland URI class, and the Node class and its subclasses are all converted to and from —Ruby objects as mentioned above (covered in The Node Type System).
  • Iteration uses Ruby’s Enumerable interface, so there’s no need for an explicit Iterator class. Some fancy things you can do with iteration are highlighted in the section on Searching Graphs.
  • Serialization is all handled behind the scenes, so there’s no Redleaf Serializer class; see the serialization section of Working With Graphs for more.

Higher-Level Abstractions

I’ve tried to make the basic library easy to use for people who just want to start playing with triples, and also expose as much of Redland’s power as possible for people who are more familiar with it. There’s still a ways to go in both regards, but Redleaf is also intended to be a way that you can integrate RDF into your code without having to necessarily know or care about the particulars of Graphs and Stores, and several experimental higher-level utilities are planned to help with this.

Archetypes

Archetypes are a way to build up functionality in Ruby classes by allowing you to mix in RDF Vocabularies. It’s still experimental, and the implementation is subject to change, but there’s a page on the project site that will eventually be merged with this manual that you can read if you’re interested.

Reasoners

One of the most useful and unique things about data stored in RDF format is the ability to fill in new information via inference, and to do that, most RDF systems come with one or more reasoners you can use to augment the explicit statements in your graph. We plan to eventually include a reasoning engine with Redleaf; our notes on the subject can be found