sign in
Home | Updates | Pages | Users | Admin | Help

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 Ruby (1.8.4 and later are recommended) and an adapter, which allows it to connect to your data. (Just like Ruby on Rails requires a database for data persistance, ActiveRDF requires a triple store, which is the way to persist RDF data.)

ActiveRDF is currently supported on Linux, Mac OS X and Windows.

Installation of ActiveRDF and of the adapters is not exactly a walk in park, it requires compilation of a few libraries, if you are not using Linux.

Following, you will find a table, listing the different available adapters for ActiveRDF, together with information, helping you to decide, which one to use.

After that, you will find detailed installation instructions for Linux, Mac OS X and Windows.

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 (version 3.3 or higher), the sqlite3-ruby gem, and ferret if installed read and write, fulltext search Linux, Mac OS X and Windows sqlite and ferret
Redland parsing external RDF, large data sets and performance up-to-date Redland, Raptor and Rasqal read and write Linux, Mac OS X. Windows does not work right now, see below for details. redland and the ruby bindings
Sesame2 (in beta) large data sets and performance, will support inferencing in the future Java SDK, JRuby, and in depth knowledge of JRuby and Sesame 2, Installation description read and write works everywhere, where Java works, deployment of Jruby, ActiveRDF, Sesame2 and Rails as a single .war for your J2EE server might be possible in the future Sesame 2 and JRuby

Installation Instructions for each Operating System

Notes about the instructions:
  • there might be a missing step in the redland mac os x instructions, which I could not reconstruct. Please add it, if you figure out that something is missing.
  • installation of redland on windows was not possible for me, due to an error when compiling the redland language bindings. If you find a solution, please add it.
  • unpacking of tar.gz files is done with “tar xvf ”
  • if ruby gems asks you which version of a gem to install, chose the newest on, and only choose the windows one if you are on windows

Linux

Installing on Linux is the easiest, compared to the other OSs, because current versions of the required libraries are provided by all major Linux distributions.

Ruby and Rubygems

Ruby version 1.8.4 or higher is recommended.

Install the packages named “ruby” and “ruby-dev” or similar. You also need rubygems, which might be available as a distribution package, or by manual installation:
  1. download the rubygems archive
  2. unpack and enter the directory
  3. run “ruby setup.rb”

Note: on Ubuntu Feisty the required packages are named: ruby1.8, ruby1.8-dev and rubygems

ActiveRDF base gem (required)

gem install activerdf

Sparql Adapter

gem install activerdf_sparql

RDFLite Adapter

The RDFLite adapter is based on SQLite3, and requires version 3.3 or higher.

  1. Make sure you have these packages (or simliarly named) installed with a version number higher then 3.3 : sqlite3, sqlite3-dev, sqlite3-ruby
  2. run “gem install activerdf_rdflite”

Note: on Ubuntu Feisty the required packages are named: libsqlite3-0, libsqlite3-dev and libsqlite3-ruby1.8

Redland Adapter

  1. Install the redland library which usually is contained in the packages named: librdf0 and librdf-ruby (or similar). The should be at least version 1.0.4-1 or higher if available.
  2. run “gem install activerdf_redland”

Note: on Ubuntu Feisty the required packages are named: librdf0, librdf0-dev and librdf-ruby

Ruby on Rails

If you need Ruby on Rails, you can install it with: 
gem install rails --include-dependencies -y

Mac OS X

Installation has only been tested on Mac OS X 10.4, although it might be possible on previous versions.

You will have to use fink and install fink packages, if available, but you also might still have to additionally compile libraries form source.

That means that you will have to install Xcode from the Apple Developer Tools. This requires a free registration on the Apple Developer Site, and is a 950 MB download.

An alternative is to use MacPorts, find a detailed howto after the Fink explaination.

Fink

Install fink as described on the fink homepage

  1. download the fink dmg and mount it
  2. run the pkg installer inside the dmg
  3. now run these commands in a terminal
    1. fink scanpackages; find index
    2. sudo fink selfupdate (we need the newest version of fink)
    3. sudo fink configure (you have to enable the unstable tree here, because it contains the source packages of the newest libraries)
    4. sudo fink selfupdate (another update)
  4. edit your $HOME/.profile and add these lines:
export PATH=/usr/local/bin:$PATH
export DYLD_LIBRARY_PATH=/usr/local/lib

now close all of your terminals, and reopen them, to make sure you have the new environment

Ruby and Rubygems

The ruby version of Mac OS X is to old, so we will use the newest ruby package of fink, which is in the unstable tree.

sudo fink install ruby ruby-dev rubygems-rb18

MacPorts

You can follow the more detailed instructions on the main help if you’re lost.

  1. Download macports: http://svn.macports.org/repository/macports/downloads/MacPorts-1.4.0/
  2. Run the binary installer inside the .dmg
  3. edit your $HOME/.profile and add these lines:
export PATH=/opt/local/bin:/opt/local/sbin:$PATH
export DISPLAY=:0.0

The second one is required is you want to use X11 (and have installed it)

Ruby and Rubygems

Install it from port with the following command.

sudo port install rb-rubygems

If you encounter an error with a gem install command like: from /opt/local/lib/ruby/vendor_ruby/1.8/rubygems/custom_require.rb:27:in `require’

Install it from the source:

wget http://rubyforge.org/frs/download.php/20989/rubygems-0.9.4.tgz
tar -xvzf rubygems-0.9.4.tgz
cd rubygems-0.9.4
sudo ruby setup.rb

After this you can clean these files and continue.

ActiveRDF base gem (required)

sudo gem install activerdf --include-dependencies -y

Sparql Adapter

sudo gem install activerdf_sparql

RDFLite Adapter

Neither the SQLite which comes with Mac OS X, nor the one in fink is version 3.3 or higher, so we will have to compile it from source.

  1. download the newest sqlite-x.y.z.tar.gz from the sqlite downloads
  2. unpack and enter the directory
  3. execute
./configure --disable-tcl && make && sudo make install
  1. now install the ruby bindings for sqlite3: “sudo gem install sqlite3-ruby”
  2. and install the ActiveRDF adapter itself: “sudo gem install activerdf_rdflite”

Sqlite3 has now been installed in /usr/local/ so it is essential, that you changed your shell environment, as described earlier.

Redland Adapter

Redland is not available as part of Mac OS X or fink, so we have to compile it ourselves.

Warning: There might be a tiny step missing here, which I could not reproduce when experimenting with the redland installation. If you find anything missing here, please add it. But it all worked on my machine in the end :)

  1. download the newest redland and redland bindings tar.gz from the redland sourceforge site
  2. unpack redland and enter the directory
  3. run
./configure && make && sudo make install
  1. unpack the redland bindings and enter the directory
  2. run
./configure --with-ruby && make && sudo make install
  1. install the ActiveRDF adapter: “sudo gem install activerdf_redland”

Redland has now been installed in /usr/local/ so it is essential, that you changed your shell environment, as described earlier.

Ruby on Rails

If you want to install ruby on rails, then just do: 
sudo gem install rails --include-dependencies -y

Windows

Installation has only been tested on Windows XP, but it probably is the same on Windows Vista.

You will need to install cygwin to compile libraries from source. All commands have to be executed inside the cygwin shell, and not the windows command shell.

Cygwin

The cygwin installer interface sucks.

  1. go to the Cygwin page and download the setup.exe
  2. create a directory called “cygwin” on your first harddrive, place the setup.exe there, and execute it
  3. click on the “Next” button, until you are presented with a list of mirrors.
    1. Select one of the mirrors (select it, so it is highlighted in blue).
    2. now enter the url “ftp://sunsite.dk/projects/cygwinports” in the text field in the lower part of the window.
    3. Click the add button.
    4. Now locate the entry which you just created in the upper part of the window, and select it (so it is highlighted in blue).
    5. Click the “next” button.
  4. When presented with a list of packages, select the button in the top right corner, and press it once only. The caption should change to “all”. You can now see all packages in alphabetic order.
  5. Select the packages: gcc-core, gcc-c++, make, wget, vim, perl and also libsqlite3 and libsqlite3-devel and libxml2 and libxml2-devel
  6. click next until the packages are installed.

All of the next steps have to executed in a cygwin shell, so open one now.

Ruby and Rubygems

The ruby version of cygwin is not adequate, so we will install ruby form source:

  1. download the newest ruby-x.y.z.tgz from the official ruby downloads
  2. unpack and enter the directory
  3. execute ”./configure && make && make install”
  4. download the newest rubygems-x.y.z.tgz from the rubygems site
  5. unpack and enter the directory
  6. execute “ruby setup.rb”

ActiveRDF base gem (required)

gem install activerdf --include-dependencies -y

Sparql Adapter

gem install activerdf_sparql

RDFLite Adapter

Sqlite3 has been installed, if you installed all the packages listed in the cygwin installation section. They are not part of the official cygwin packages, but are released on the mirror that you added. Now only the ruby bindings have to be installed:

  1. execute “gem install sqlite3-ruby”
  2. now edit this file: /usr/local/lib/ruby/gems/1.8/gems/sqlite3-CHANGE-ME/lib/sqlite3/driver/dl/api.rb
  3. scroll down a little to the architecture switch case, and add these lines:
when /i386-cygwin/ 
    "cygsqlite3-0.dll"
Now install the rdflite adapter: 
gem install activerdf_rdflite --include-dependencies -y

When you use RDFLite there will be a warning about DLLs in cygwin, which you have to ignore for now.

Redland Adapter

Redland must be installed from source.

Warning: According to the Redland homepage, compilation with cygwin is possible, but I did not succeed with compiling the redland bindings. If you manage to compile the redland bindings with cygwin, please fix the instructions here.

  1. download the newest redland, redland-bindings, raptor and rasqal tar.gz files from the redland download page.
  2. unpack raptor, enter the directory and execute: ”./configure && make && make install”
  3. unpack rasqal, enter the directory and execute: ”./configure && make && make install”
  4. unpack redland, enter the directory and execute: ”./configure && make && make install”
  5. unpack the redland bindings, enter the directory and execute:
./configure --with-ruby && make && make install

Ruby on Rails

If you need Ruby on Rails, then install it:

gem install rails --include-dependencies -y

Check your installation.

Now it is time to check if your stuff actually works. Here are tiny test files for each adapter. They can be executed on every operating system, and contain the source code from the examples below.

Sparql Adapter

Download the example code and execute it with “ruby activerdf_example_sparql.rb”. If everything is up and working, you should see some text output and no errors.

RDFLite Adapter

Download the example code and the example data file and place it in the same directory as the example code.

Now execute the code with “ruby activerdf_example_rdflite.rb”. If everything is up and working, you should see some text output and no errors.

Redland Adapter

Download the example code and the example data file and place it in the same directory as the example code.

Now execute the code with “ruby activerdf_example_redland.rb”. If everything is up and working, you should see some text output and no errors.

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:

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!

Advanced Semantic Rails

If you want to look at some real code, which uses ActiveRDF and Rails do build a full semantic web application, you can start looking at the SIOC explorer application at https://launchpad.net/sioc-ex


Powered by JunebugWiki v0.0.31 Page last edited by benjaminheitmann on June 30, 2008 07:43 AM (diff)
Version 31 «oldernewer»currentversions