activerdf 1.0

data/lib/active_rdf/objectmanager/resource.rb

@@ -0,0 +1,325 @@
+# Represents an RDF resource and manages manipulations of that resource,
+# including data lookup (e.g. eyal.age), data updates (e.g. eyal.age=20),
+# class-level lookup (Person.find_by_name 'eyal'), and class-membership
+# (eyal.class ...Person)
+#
+# Author:: Eyal Oren
+# Copyright:: (c) 2005-2006
+# License:: LGPL
+
+require 'active_rdf'
+require 'objectmanager/object_manager'
+require 'objectmanager/namespace'
+require 'queryengine/query'
+
+# TODO: add unit test to validate class construction and queries on them
+module RDFS
+  class RDFS::Resource
+    # adding accessor to the class uri:
+    # the uri of the rdf resource being represented by this class
+    class << self
+      attr_accessor :class_uri
+    end
+
+    # uri of the resource (for instances of this class: rdf resources)
+    attr_reader :uri
+
+    # creates new resource representing an RDF resource
+    def initialize uri
+      raise ActiveRdfError, "creating resource <#{uri}>" unless uri.is_a?(String)
+
+#      $log.debug "RDFS::Resource new: initializing new Resource with #{uri}"
+      @uri = uri
+    end
+
+    # setting our own class uri to rdfs:resource
+    # (has to be done after defining our RDFS::Resource.new
+    # because it cannot be found in Namespace.lookup otherwise)
+    self.class_uri = Namespace.lookup(:rdfs, :Resource)
+
+    #####                        ######
+    ##### start of instance-level code
+    #####                        ######
+
+    # a resource is same as another if they both represent the same uri
+    def ==(other)
+      if other.respond_to?(:uri)
+        other.uri == self.uri
+      else
+        false
+      end
+    end
+    alias_method 'eql?','=='
+
+    # overriding hash to use uri.hash
+    # needed for array.uniq
+    def hash
+      uri.hash
+    end
+
+    # overriding sort based on uri
+    def <=>(other)
+      uri <=> other.uri
+    end
+
+    #####                   	#####
+    ##### class level methods	#####
+    #####                    	#####
+
+    # returns the predicates that have this resource as their domain (applicable
+    # predicates for this resource)
+    def Resource.predicates
+      domain = Namespace.lookup(:rdfs, :domain)
+      Query.new.distinct(:p).where(:p, domain, class_uri).execute || []
+    end
+
+    # manages invocations such as Person.find_by_name
+    def Resource.method_missing(method, *args)
+      method_name = method.to_s
+
+      $log.debug "RDFS::Resource: method_missing on class: called with method name #{method}"
+
+      # extract predicates on which to match
+      # e.g. find_by_name, find_by_name_and_age
+      if match = /find_by_(.+)/.match(method_name)
+        # find searched attributes, e.g. name, age
+        attributes = match[1].split('_and_')
+
+        # get list of possible predicates for this class
+        possible_predicates = predicates
+
+        # build query looking for all resources with the given parameters
+        query = Query.new.distinct(:s)
+
+        # add where clause for each attribute-value pair,
+        # looking into possible_predicates to figure out
+        # which full-URI to use for each given parameter (heuristic)
+
+        attributes.each_with_index do |atr,i|
+          possible_predicates.each do |pred|
+            query.where(:s, pred, args[i]) if Namespace.localname(pred) == atr
+          end
+        end
+
+        # execute query
+        $log.debug "RDFS::Resource: method_missing on class: executing query: #{query}"
+        return query.execute
+      end
+
+      # otherwise, if no match found, raise NoMethodError (in superclass)
+      $log.warn 'RDFS::Resource: method_missing on class: method not matching find_by_*'
+      super
+    end
+
+    # returns array of all instances of this class (e.g. Person.find_all)
+    # (always returns collection)
+    def Resource.find_all
+      query = Query.new.distinct(:s).where(:s, Namespace.lookup(:rdf,:type), class_uri)
+      if block_given?
+        query.execute do |resource|
+          yield resource
+        end
+      else
+        query.execute(:flatten => false)
+      end
+    end
+
+    #####                         #####
+    ##### instance level methods	#####
+    #####                         #####
+
+    # manages invocations such as eyal.age
+    def method_missing(method, *args)
+      # possibilities:
+      # 1. eyal.age is a property of eyal (triple exists <eyal> <age> "30")
+      # evidence: eyal age ?a, ?a is not nil (only if value exists)
+      # action: return ?a
+      #
+      # 2. eyal's class is in domain of age, but does not have value for eyal
+      # explain: eyal is a person and some other person (not eyal) has an age
+      # evidence: eyal type ?c, age domain ?c
+      # action: return nil
+      #
+      # 3. eyal.age = 30 (setting a value for a property)
+      # explain: eyal has (or could have) a value for age, and we update that value
+      # complication: we need to find the full URI for age (by looking at
+      # possible predicates to use
+      # evidence: eyal age ?o  (eyal has a value for age now, we're updating it)
+      # evidence: eyal type ?c, age domain ?c (eyal could have a value for age, we're setting it)
+      # action: add triple (eyal, age, 30), return 30
+      #
+      # 4. eyal.age is a custom-written method in class Person
+      # evidence: eyal type ?c, ?c.methods includes age
+      # action: inject age into eyal and invoke
+
+      # maybe change order in which to check these, checking (4) is probably
+      # cheaper than (1)-(2) but (1) and (2) are probably more probable (getting
+      # attribute values over executing custom methods)
+
+      $log.debug "RDFS::Resource: method_missing on instance: called with method name #{method}"
+
+      # are we doing an update or not?
+      # checking if method ends with '='
+
+      if method.to_s[-1..-1] == '='
+        methodname = method.to_s[0..-2]
+        update = true
+      else
+        methodname = method.to_s
+        update = false
+      end
+
+      candidates = if update
+                      class_level_predicates
+                    else
+                      direct_predicates
+                    end
+    
+    # checking possibility (1) and (3)
+    candidates.each do |pred|
+      if Namespace.localname(pred) == methodname
+        # found a property invocation of eyal: option 1) or 2)
+        # query execution will return either the value for the predicate (1)
+        # or nil (2)
+        if update
+          # TODO: delete old value if overwriting
+          # FederiationManager.delete(self, pred, nil)
+
+          # handling eyal.friends = [armin, andreas] --> expand array values
+          args.each do |value|
+            FederationManager.add(self, pred, value)
+          end
+          return args
+        else
+          # look into args, if it contains a hash with {:array => true} then
+          # we should not flatten the query results
+          return get_property_value(pred, args)
+        end
+      end
+    end
+    
+    raise ActiveRdfError, "could not set #{methodname} to #{args}: no suitable predicate found. Maybe you are missing some shcema information?" if update
+
+    # get/set attribute value did not succeed, so checking option (2) and (4)
+    
+    # checking possibility (2), it is not handled correctly above since we use
+    # direct_predicates instead of class_level_predicates. If we didn't find
+    # anything with direct_predicates, we need to try the
+    # class_level_predicates. Only if we don't find either, we
+    # throw "method_missing"
+    candidates = class_level_predicates
+
+    # if any of the class_level candidates fits the sought method, then we
+    # found situation (2), so we return nil or [] depending on the {:array =>
+    # true} value
+    if candidates.any?{|c| Namespace.localname(c) == methodname}
+      return_ary = args[0][:array] if args[0].is_a? Hash
+      if return_ary
+        return []
+      else
+        return nil
+
+      end
+    end
+
+    # checking possibility (4)
+    # TODO: implement search strategy to select in which class to invoke
+    # e.g. if to_s defined in Resource and in Person we should use Person
+    $log.debug "RDFS::Resource: method_missing on instance: branch selected: execution of custom class method"
+    self.class.each do |klass|
+      if klass.instance_methods.include?(method.to_s)
+        _dup = klass.new(uri)
+        return _dup.send(method,*args)
+      end
+    end
+
+    # if none of the three possibilities work out, we don't know this method
+    # invocation, but we don't want to throw NoMethodError, instead we return
+    # nil, so that eyal.age does not raise error, but returns nil. (in RDFS,
+    # we are never sure that eyal cannot have an age, we just dont know the
+    # age right now)
+    nil
+  end
+
+  # returns classes to which this resource belongs (according to rdf:type)
+  def class
+    types.collect do |type|
+      ObjectManager.construct_class(type)
+    end
+  end
+
+  def type
+    get_property_value(Namespace.lookup(:rdf,:type))
+  end
+
+  # overrides built-in instance_of? to use rdf:type definitions
+  def instance_of?(klass)
+    self.class.include?(klass)
+  end
+
+  # returns all predicates that fall into the domain of the rdf:type of this
+  # resource
+  def class_level_predicates
+    type = Namespace.lookup(:rdf, 'type')
+    domain = Namespace.lookup(:rdfs, 'domain')
+    Query.new.distinct(:p).where(self,type,:t).where(:p, domain, :t).execute || []
+  end
+
+  # returns all predicates that are directly defined for this resource
+  def direct_predicates(distinct = true)
+    if distinct
+      q = Query.new.distinct(:p)
+    else
+      q = Query.new.select(:p)
+    end
+    q.where(self,:p, :o).execute(:flatten => false) || []
+  end
+
+  def property_accessors
+    direct_predicates.collect {|pred| Namespace.localname(pred) }
+  end
+
+  # returns all rdf:types of this resource
+  def types
+    type = Namespace.lookup(:rdf, :type)
+
+    # we lookup the type in the database
+    types = Query.new.distinct(:t).where(self,type,:t).execute(:flatten => false)
+
+    # if we dont know it, we return Resource (as toplevel)
+    # this should in theory actually never happen (since any node is a rdfs:Resource)
+    # but could happen if the subject is unknown to the database
+    # or if the database does not support RDFS inferencing
+    return [Namespace.lookup(:rdfs,"Resource")] if types.empty?
+    return types
+  end
+
+  # alias include? to ==, so that you can do paper.creator.include?(eyal)
+  # without worrying whether paper.creator is single- or multi-valued
+  alias include? ==
+
+  # returns uri of resource, can be overridden in subclasses
+  def to_s
+    "resource: #{uri}"
+  end
+
+  def label(*args)
+    label = get_property_value(Namespace.lookup(:rdfs,:label)) || Namespace.localname(self)
+
+		# empty labels are not useful: replace them by localname
+		label = Namespace.localname(self) if label.empty?
+
+		# if we have no localname, use full uri
+		label = uri if label.empty?
+
+		label
+  end
+
+  private
+  def get_property_value(predicate, args=[])
+    return_ary = args[0][:array] if args[0].is_a?(Hash)
+    flatten_results = !return_ary
+    Query.new.distinct(:o).where(self, predicate, :o).execute(:flatten => flatten_results)
+  end  
+end
+end

data/lib/active_rdf/queryengine/query.rb

@@ -0,0 +1,166 @@
+# Represents a query on a datasource, abstract representation of SPARQL features
+# is passed to federation/adapter for execution on data
+#
+# Author:: Eyal Oren
+# Copyright:: (c) 2005-2006
+# License:: LGPL
+require 'active_rdf'
+require 'federation/federation_manager'
+
+# TODO add log for every method which constitues to the query
+
+class Query
+  attr_reader :select_clauses, :where_clauses, :keywords, :limits, :offsets
+  bool_accessor :distinct, :ask, :select, :count, :keyword
+
+  def initialize
+    $log.debug "Query: initializing"
+    distinct = false
+		limit = nil
+		offset = nil
+    @select_clauses = []
+    @where_clauses = []
+		@keywords = {}
+  end
+
+	def clear_select
+    $log.debug "Query: clearing select query"
+		@select_clauses = []
+		distinct = false
+	end
+
+  def select *s
+    @select = true
+    s.each do |e|
+      @select_clauses << parametrise(e) 
+    end
+		# removing duplicate select clauses
+		@select_clauses.uniq!
+    $log.debug "Query: the current select clauses are: #{@select_clauses.join(', ')}"
+    self
+  end
+
+  def ask
+    @ask = true
+    $log.debug "Query: the current select clauses are: #{@select_clauses.join(', ')}"
+    self
+  end
+
+  def distinct *s
+    @distinct = true
+    select(*s)
+  end
+  alias_method :select_distinct, :distinct
+
+	def count *s
+		@count = true
+		select(*s)
+	end
+
+	def limit(i)
+		@limits = i 
+		self
+	end
+
+	def offset(i)
+		@offsets = i
+		self
+	end
+
+  def where s,p,o
+		case p
+		when :keyword
+			# treat keywords in where-clauses specially
+			keyword_where(s,o)
+		else
+			# remove duplicate variable bindings, e.g.
+			# where(:s,type,:o).where(:s,type,:oo) we should remove the second clause, 
+			# since it doesn't add anything to the query and confuses the query 
+			# generator. 
+			# if you construct this query manually, you shouldn't! if your select 
+			# variable happens to be in one of the removed clauses: tough luck.
+			
+      unless s.respond_to?(:uri)
+    		unless s.class == Symbol
+    		  $log.debug "Query: where: got a Subject which is no Symbol, and no RDFS::Resource, but is instead: #{s}"
+          raise(ActiveRdfError, "cannot add a where clause, in which s is not a resource and not a variable")
+    		end
+      end
+      unless p.respond_to?(:uri)
+    		unless p.class == Symbol
+    		  $log.debug "Query: where: got a Predicate which is no Symbol, and no RDFS::Resource, but is instead: #{p}"
+          raise(ActiveRdfError, "cannot add a where clause, in which s is not a resource and not a variable")
+    		end
+      end
+      
+			@where_clauses << [s,p,o].collect{|arg| parametrise(arg)}
+		end
+    self
+  end
+
+	# adds keyword constraint to the query. You can use all Ferret query syntax in 
+	# the constraint (e.g. keyword_where(:s,'eyal|benjamin')
+	def keyword_where s,o
+		@keyword = true
+		s = parametrise(s)
+		if @keywords.include?(s)
+			@keywords[s] = @keywords[s] + ' ' + o
+		else
+			@keywords[s] = o
+		end
+		self
+	end
+
+# this is not normal behaviour, the method is implemented inside FacetNavigation
+#	def replace_where_clause old,new
+#		return unless where_clauses.includes?(old)
+#		where_clauses.delete(old)
+#		where_clauses.insert(new)
+#	end
+
+  # execute query on data sources
+  # either returns result as array
+  # (flattened into single value unless specified otherwise)
+  # or executes a block (number of block variables should be
+  # same as number of select variables)
+  #
+  # usage: results = query.execute
+  # usage: query.execute do |s,p,o| ... end
+  def execute(options={:flatten => true}, &block)
+    $log.debug "Query: executing query: #{self.inspect}"
+    
+    if block_given?
+      FederationManager.query(self) do |*clauses|
+        block.call(*clauses)
+      end
+    else
+      FederationManager.query(self, options)
+    end
+  end
+
+  def to_s
+		if ConnectionPool.read_adapters.empty?
+			inspect 
+		else
+			ConnectionPool.read_adapters.first.translate(self)
+		end
+  end
+
+  def to_sp
+		require 'queryengine/query2sparql'
+		Query2SPARQL.translate(self)
+  end
+
+  private
+  def parametrise s
+    case s
+    when Symbol
+			s
+      #'?' + s.to_s
+    when RDFS::Resource
+      s
+    else
+      '"' + s.to_s + '"'
+    end
+  end
+end

data/lib/active_rdf/queryengine/query2jars2.rb

@@ -0,0 +1,27 @@
+# Translates abstract query into jars2 query
+# ignores ASK queries
+#
+# Author:: Eyal Oren
+# Copyright:: (c) 2005-2006
+# License:: LGPL
+require 'active_rdf'
+
+
+class Query2Jars2
+	def self.translate(query)
+		str = ""
+		if query.select?
+			# concatenate each where clause using space: s p o
+			# and then concatenate the clauses using dot: s p o . s2 p2 o2 .
+			str << "#{query.where_clauses.collect{|w| w.collect{|w| '?'+w.to_s}.join(' ')}.join(" .\n")} ."
+			# TODO: should we maybe reverse the order on the where_clauses? it depends 
+			# on Andreas' answer of the best order to give to jars2. Users would 
+			# probably put the most specific stuff first, and join to get the 
+			# interesting information. Maybe we should not touch it and let the user 
+			# figure it out.
+		end
+		
+		$log.debug "Query2Jars2: translated #{query} to #{str}"
+		return str
+	end
+end

data/lib/active_rdf/queryengine/query2sparql.rb

@@ -0,0 +1,51 @@
+# translates abstract query into SPARQL that can be executed on SPARQL-compliant data source
+#
+# Author:: Eyal Oren
+# Copyright:: (c) 2005-2006
+# License:: LGPL
+require 'active_rdf'
+
+
+class Query2SPARQL
+  def self.translate(query)
+    str = ""
+    if query.select?
+      distinct = query.distinct? ? "DISTINCT " : ""
+			select_clauses = query.select_clauses.collect{|s| construct_clause(s)}
+
+      str << "SELECT #{distinct}#{select_clauses.join(' ')} "
+      str << "WHERE { #{where_clauses(query)} }"
+    elsif query.ask?
+      str << "ASK { #{where_clauses(query)} }"
+    end
+    
+    $log.debug "Query2SPARQL: translated the query to #{str}"
+    return str
+  end
+
+  private
+  # concatenate each where clause using space (e.g. 's p o')
+  # and concatenate the clauses using dot, e.g. 's p o . s2 p2 o2 .'
+  def self.where_clauses(query)
+		where_clauses = query.where_clauses.collect do |triple|
+			triple.collect {|term| construct_clause(term)}.join(' ')
+		end
+    "#{where_clauses.join('. ')} ."
+  end
+
+	def self.construct_clause(term)
+		case term
+		when Symbol
+			'?' + term.to_s
+		when RDFS::Resource
+			'<' + term.uri + '>'
+		else
+			term.to_s
+		end
+	end
+	
+  #declare the class level methods as private with these directives
+  private_class_method :where_clauses
+  private_class_method :construct_clause
+	
+end

data/lib/active_rdf.rb

@@ -0,0 +1,48 @@
+# Loader of ActiveRDF library
+#
+# Author:: Eyal Oren and Renaud Delbru
+# Copyright:: (c) 2005-2006 Eyal Oren and Renaud Delbru
+# License:: LGPL
+
+# adding active_rdf subdirectory to the ruby loadpath
+file = File.symlink?(__FILE__) ? File.readlink(__FILE__) : __FILE__
+this_dir = File.dirname(File.expand_path(file))
+$: << this_dir
+$: << this_dir + '/active_rdf/'
+
+require 'active_rdf_helpers'
+require 'active_rdf_log'
+
+$log.info "ActiveRDF started, logging level: #{$log.level}"
+
+# load standard classes that need to be loaded at startup
+require 'objectmanager/resource'
+require 'objectmanager/namespace'
+require 'federation/connection_pool'
+require 'queryengine/query'
+require 'federation/active_rdf_adapter'
+
+def load_adapter s
+  begin
+    require s
+  rescue StandardError => e
+    $log.info "could not load adapter #{s}: #{e}"
+  end
+end
+
+require 'rubygems'
+#determine if we are installed as a gem right now:
+if Gem::cache().search("activerdf").empty?
+   #we are not running as a gem
+   $log.info 'ActiveRDF is NOT installed as a Gem'
+   load_adapter this_dir + '/../activerdf-rdflite/lib/activerdf_rdflite/rdflite'
+   load_adapter this_dir + '/../activerdf-redland/lib/activerdf_redland/redland'
+   load_adapter this_dir + '/../activerdf-sparql/lib/activerdf_sparql/sparql'
+   load_adapter this_dir + '/../activerdf-yars/lib/activerdf_yars/jars2'
+else
+   #we are indeed running as a gem
+   require 'gem_plugin'
+   $log.info 'ActiveRDF is installed as a Gem'
+   GemPlugin::Manager.instance.load "activerdf" => GemPlugin::INCLUDE
+end
+

data/lib/active_rdf_helpers.rb

@@ -0,0 +1,12 @@
+# defining ActiveRDF errors
+class ActiveRdfError < StandardError
+end
+
+# adding bool_accessor to ruby
+class Module
+  def bool_accessor *syms
+    attr_accessor(*syms)
+    syms.each { |sym| alias_method "#{sym}?", sym }
+    remove_method(*syms)
+  end
+end

data/lib/active_rdf_log.rb

@@ -0,0 +1,43 @@
+require 'logger'
+
+$log =
+  begin
+    # us the rails logger if running under rails
+    RAILS_DEFAULT_LOGGER 
+  rescue NameError
+    unless ENV['ACTIVE_RDF_LOG'].nil?
+      # write to environment variable $RDF_LOG if set
+      Logger.new(ENV['ACTIVE_RDF_LOG'], 1, 100*1024) 
+    else
+      require 'tmpdir'
+      # else just write to the temp dir
+      Logger.new(Dir.tmpdir.to_s + "/activerdf.log", 1, 100*1024); 
+    end
+  end
+    
+# if user has specified loglevel we use that, otherwise we use default level
+# in the environment variable ACTIVE_RDF_LOG_LEVEL we expect numbers, which we 
+# have to convert
+if ENV['ACTIVE_RDF_LOG_LEVEL'].nil?
+  $log.level = Logger::WARN
+else
+  $log.level = ENV['ACTIVE_RDF_LOG_LEVEL'].to_i
+end
+
+class Logger
+  def debug_pp(message, variable)  
+    if variable.respond_to?(:join)
+      if variable.empty?
+        debug(sprintf(message, "empty"))
+      else 
+        debug(sprintf(message, variable.join(', ')))        
+      end
+    else
+      if variable.nil?
+        debug(sprintf(message, 'empty'))
+      else
+        debug(sprintf(message, variable))
+      end
+    end
+  end
+end