Comparing version 20 and version 19 back

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 [[IntroRDF|introduction]] of ActiveRDF and RDF concepts. 

h1. 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":http://Rubyforge.org/frs/?group_id=167
* on Mac OS X follow the relevant steps of "this guide":http://hivelogic.com/articles/2005/12/01/Ruby_rails_lighttpd_mysql_tiger.

After installing Ruby, just follow these steps:

# If you don't have rubygems, install it: 
## download "the rubygems archive":http://Rubyforge.org/frs/?group_id=126
## unpack 
## run "ruby setup.rb"
# Install the ActiveRDF gem: "gem install activerdf"
# Install one or more adapters, e.g. "gem install activerdf_rdflite"

h2. 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":http://www.xml.com/pub/a/2005/11/16/introducing-sparql-querying-semantic-web-tutorial.html and "specification":http://www.w3.org/TR/rdf-sparql-query/|
|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":http://www.sqlite.org/ and "ferret":http://ferret.davebalmain.com/|
|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":http://librdf.org/ and the "ruby bindings":http://librdf.org/docs/Ruby.html|

h2. Installation Instructions for each Adapter

h3. Sparql Adapter

run "gem install activerdf_sparql", that's all.

h3. RDFLite Adapter

# install the dependencies:
** Linux: get the sqlite3, sqlite3-dev and ruby-dev packages and "gem install sqlite3-Ruby --source code.whytheluckystiff.net"
** Windows: just "gem install sqlite3-ruby --source code.whytheluckystiff.net" and select the windows version, it contains the DLLs for Windows. 
** Mac OS X: follow the Linux instructions, using fink or installing from source. But it really works :)
# run "gem install activerdf_rdflite"

h3. Redland Adapter

# 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
# run "gem install activerdf_redland"

h2. 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":http://rdfabout.net/data.xpd is a list of some SPARQL endpoints and RDF data files
* "rdfdata.org":http://www.rdfdata.org/data.html is a really big list, check out the elvis impersonators
* "sparql endpoints on esw wiki":http://esw.w3.org/topic/SparqlEndpoints another good list of live SPARQL endpoints

h1. 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 [[GettingStartedCode|here]].

h2. Loading ActiveRDF

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

    require 'rubygems'
    require 'active_rdf'

h2. 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":http://activerdf.org/data/test_person_data.nt:
adapter.load "/tmp/test_person_data.nt"

h2. 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'

h2. 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}"


h2. 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"
 

h2. 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 = RDFS::Resource.new 'http://paul.stadig.name/'
 
 # we cannot predicate until we first save the object
 paul.save
 
 # now we can predicate
 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 predicate's value will immediately add a triple to the database even though you have not called 'save'.

h2. 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_:

 

  
   
  

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

 


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!