GettingStartedGuide

This guide shows you:

• how to install ActiveRDF
• how to use it to read and write to a triple store
• how to use it inside of a Ruby on Rails web application

If you have general questions about ActiveRDF, please first read the FrequentlyAskedQuestions. For a general introduction into the Semantic Web, please read our short introduction of ActiveRDF and RDF concepts.

Installation

ActiveRDF requires a recent Ruby version, we recommend Ruby 1.8.4.

• On Linux install the Ruby package of your distribution
• on Windows use the Ruby one-click installer
• on Mac OS X follow the relevant steps of this guide.

After installing Ruby, just follow these steps:

1. If you don’t have rubygems, install it:
   1. download the rubygems archive
   2. unpack
   3. run “ruby setup.rb”
2. Install the ActiveRDF gem: “gem install activerdf”
3. Install one or more adapters, e.g. “gem install activerdf_rdflite”

Available Adapters

Adapter	Recommended for	Dependencies	Operations	Supported OS	Further information
SPARQL	to access somebody else’s data (on a SPARQL endpoint)	none	read-only	Linux, Mac OS X, Windows	SPARQL tutorial and specification
RDFLite	if you need read and write access	sqlite3, the sqlite3 gem, and ferret if installed	read and write, fulltext search	Linux, Mac OS X and Windows	sqlite and ferret
Redland	full RDF parsing and SPARQL querying	up-to-date Redland, Raptor and Rasqal	read and write	Linux, Mac OS X with some effort, and possibly on Windows	redland and the ruby bindings

Installation Instructions for each Adapter

Sparql Adapter

run “gem install activerdf_sparql”, that’s all.

RDFLite Adapter

1. install the dependencies:
   • for sqlite3 use at least version 3.3.0
   • Linux: get the sqlite3, sqlite3-dev and ruby-dev packages and “gem install sqlite3-ruby”
   • Windows: just “gem install sqlite3-ruby” and select the windows version
   • Mac OS X: follow the Linux instructions, using fink or installing from source
2. run “gem install activerdf_rdflite”

Redland Adapter

1. install the dependencies:
• Linux: get the librdf0 and librdf-ruby packages at least version 1.0.4-1
• Mac OS X: use fink, see linux
• Windows: we haven’t tried this yet
1. run “gem install activerdf_redland”

Where to get some data

In order to get started with ActiveRDF, you are going to need some data to experiment on. See IntroRDF on why you have to use a triple store with either real data or at least schema data in order for ActiveRDF to work.

If you have no own data you can just use the SPARQL adapter and connect to one of the SPARQL endpoints mentioned here. If you install the RDFLite or Redland adapter, you should have some RDF data of your own, or you can load a publicly available RDF file.

Freely available RDF data:

• source of data is a list of some SPARQL endpoints and RDF data files
• rdfdata.org is a really big list, check out the elvis impersonators
• sparql endpoints on esw wiki another good list of live SPARQL endpoints

Usage

You can follow along these instructions on an interactive Ruby shell, which you can open on the command line with “irb”. Or you can see the whole sequence of instructions here.

Loading ActiveRDF

To use ActiveRDF, load its Ruby library (which will magically load all installed ActiveRDF adapters):

require 'rubygems'
require 'active_rdf'

Connecting to a Data Source

Now you have to connect to a data source, either a SPARQL endpoint or a RDF data file. You can do any of the following:

Connect to the public URL of a SPARQL endpoint with the SPARQL adapter:

ConnectionPool.add_data_source :type => :sparql, :results => :sparql_xml,
 :url => "http://m3pe.org:8080/repositories/test-people" 

Or access a local, in-memory triple store with the RDFLite adapter:

adapter = ConnectionPool.add_data_source :type => :rdflite

Or access a local, in-memory triple store with the Redland adapter:

adapter = ConnectionPool.add_data_source :type => :redland

And, unless you’re using the SPARQL adapter, load the example data set, which you can download here:

adapter.load "/tmp/test_person_data.nt"

Namespaces in ActiveRDF

In common RDF usage you dont use long URIs like “http://activerdf.org/test/eyal”. The part of the URI in front of the last ”/” or ”#” is the namespace of the URI. The trailing part of the URI after the namespace, then is called the local name. You can define an abbreviation for each namespace, which is called the prefix.

For our example we assigne the prefix “test” to the namespace “http://activerdf.org/test/”. We then can abbreviate the URI “http://activerdf.org/test/eyal” as “test:eyal”.

In ActiveRDF you have to register your namespaces, and tell ActiveRDF to construct corresponding Ruby modules and classes. But the benefit of this, is that you can use namespaces and local names just as intuitively in ActiveRDF as you can use them in RDF.

 # register the test namespace to the specified URI
 Namespace.register :test, 'http://activerdf.org/test/'

 # and now construct the necessary Ruby Moduls and Classes
 ObjectManager.construct_classes

To get an instance of test:person, use:

eyal = TEST::Person.new 'http://activerdf.org/test/eyal'

Read-Only Access

The following examples access the the data without changing it:

 # we can access all RDF properties of a person as Ruby attributes:
 eyal = TEST::Person.new 'http://activerdf.org/test/eyal'
 puts eyal.age
 puts eyal.eye
 puts eyal.class

 # lets create an instance of one of the classes, that were constructed in that 
 # way armin will be of rdfs:type test:person
 armin = TEST::Person.new 'http://armin-haller.com/#me'

 # now lets search for something in the triple store
 all_resources = RDFS::Resource.find_all

 # print all the people, and their friends
 all_people = TEST::Person.find_all
 all_people.each do |person|
     puts "#{person} has #{person.eye} eyes" 
 end

 # find all people aged 27
 almost_thirties = TEST::Person.find_by_age(27)
 puts "the following people are almost thirty: #{almost_thirties}" 

Write Access

After loading a RDF data file with the RDFLite or Redland Adapter, you can do the following:

 # we want to access the properties of this URI    
 eyal = RDFS::Resource.new 'http://activerdf.org/test/eyal'

 # now we can read the age associated with eyal
 puts eyal.age
 # prints "27" 

 # lets try to write a new age
 eyal.age = 18

 # if we now output the age again, there will be two values for it
 # because there is no way to decide which one is the real age
 # however, this behaviour might change in the future..
 puts eyal.age  # prints "18,27" 
 

Creating New Resources

The process for creating a new resource in the database is slightly different:

 # we want to add a new person to the database
 paul = TEST::Person.new 'http://paul.stadig.name/'

 # we cannot set properties until we first save the object
 paul.save

 # now we can set properties
 paul.eye = 'blue'
 

The thing to note is that a resource will not be added to the database unless and until you call ‘save’. However, setting a property’s value will immediately add a triple to the database even though you have not called ‘save’.

The Semantic Web on Rails

Well, all of the previous stuff was pretty cool, but a lot of you are probably just waiting for the main act of the evening. Lets put the Semantic Web on Rails!

You of course need to have Ruby and Rails installed, usually you only need to run “gem install rails—include-dependencies”.

Go to a directory and tell rails to make the standard application skeleton:

 rails semweb-on-rails
 cd semweb-on-rails

Open config/environment.rb, which is responsible for the environment of the web app, go to the end of the file and enter the following, to load ActiveRDF and open the connections to your data sources:

 require 'active_rdf'
 ConnectionPool.add_data_source :type => :sparql, :results => :sparql_xml,
 :url => "http://m3pe.org:8080/repositories/test-people" 

Generate a controller, which we will just call say:

ruby script/generate controller Say

We want to use information about persons in our app, so we will need a model class to access all persons. We will also have to declare the namespace of the model class in the RDF triple store. Create and open the file app/models/person.rb:

 Namespace.register :test, 'http://activerdf.org/test/'
 ObjectManager.construct_classes

 class TEST::Person < RDFS::Resource
 end

The controller of course has to now about the model class Person, so we have to add a declaration to the controller, and we want do define a few objects, so that our view has something to show for all the hard work we have done so far. Open the file app/controllers/say_controller.rb:

 class SayController < ApplicationController
      model :person
      def hello
             @time = Time.now
             @eyal = TEST::Person.new 'http://activerdf.org/test/eyal'
      end
 end

And finally we create the view, which will access the objects created in the controller. Create and open the file app/views/say/hello.rhtml:

 <html>

  <head>
   <title>Hello, Semantic Web on Rails!</title>
  </head>

  <body>
   <h2>It is now <%= @time %></h2>.
   <p> we have <%= pluralize(TEST::Person.find_all.size, 'person')%></p>
   <p> Eyal is <%= @eyal.age %> years old.</p>
  </body>

 </html>

All we now have to do, is start the app:

ruby script/server

Now say hello to the Semantic Web on Rails, and open http://localhost:3000/say/hello in your browser!