activerubic 0.8.0 → 0.8.1

data/lib/active_rubic.rb

@@ -3,8 +3,7 @@
 #
 # The engines are also attempted to be drop-in replaceable by offering an abstraction method find(). see ActiveRubic::Base for the API reference.
 # - some of it is still undocumented!!
-
-
+#
 # The supported backends currently include:
 #
 # - ActiveRecord
@@ -21,7 +20,7 @@
 # http://openlab.savonia-amk.fi/wiki/images/1/12/Rubics_cube.png
 # 
 # Authors:: Mikael Lammentausta, Lauri Miettinen
-# Copyright:: Copyright (c) 2007 Savonia University of Applied Sciences
+# Copyright:: Copyright (c) 2007-2008 Savonia University of Applied Sciences
 # License:: MIT
 #
 # = Examples
@@ -239,25 +238,11 @@
 #  => ["Kuopion museo"]
 #
 ############################################################################
-
-RUBIC_VERSION = '0.8.0'
-
 module ActiveRubic
-  VERSION = RUBIC_VERSION
-  class ActiveRubicError < StandardError #:nodoc:
-  end
-  class AdapterNotSpecifiedError < ActiveRubicError # :nodoc:
-  end
-  class AdapterNotFoundError < ActiveRubicError # :nodoc:
-  end
-  class ConnectionNotEstablishedError < ActiveRubicError #:nodoc:
-  end
-  class ConnectionFailedError < ActiveRubicError #:nodoc:
-  end
-  class RubicNotFoundError < ActiveRubicError #:nodoc:
-  end
+  VERSION = '0.8.1'
 end
 
+RUBIC_VERSION = ActiveRubic::VERSION
 
 ### the data sources that will be queried
 RUBIC_DATASTORES = [ :jena, :joseki, :mysql, :lucene, :geolucene ] unless defined? RUBIC_DATASTORES
@@ -265,6 +250,20 @@ RUBIC_DATASTORES = [ :jena, :joseki, :mysql, :lucene, :geolucene ] unless define
 # unused
 RUBIC_CONNECTION_ADAPTERS = [ :rubinstein ] unless defined?(RUBIC_CONNECTION_ADAPTERS)
 
+# 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_rubic/'
+$: << this_dir + '/active_rubic/objectmanager'
+$: << this_dir + '/active_rubic/objectmanager'
+$: << this_dir + '/active_rubic/objectmanager/rdf'
+$: << this_dir + '/active_rubic/objectmanager/owl'
+$: << this_dir + '/active_rubic/active_rubinstein'
+RUBIC_HOME = this_dir #unless defined? RUBIC_HOME
+
+#################################################
+
 ### set environment
 if defined? RAILS_ROOT
   RUBINSTEIN_HOME = RAILS_ROOT + '/lib/rubinstein' unless defined? RUBINSTEIN_HOME
@@ -274,7 +273,7 @@ else
     if ENV['RUBINSTEIN_HOME'] then
       RUBINSTEIN_HOME = ENV['RUBINSTEIN_HOME']
     else
-      # using File.dirname causes /usr/bin/rake to break the system.
+      # File.dirname($0) will kill /usr/bin/rake
       RUBINSTEIN_HOME = File.dirname($0)
     end
   end
@@ -288,12 +287,19 @@ else
   end
 end
 
-### load logger + Rubinstein libraries
-unless (( defined? @@log ) || ( defined? logger ))
-  require RUBINSTEIN_HOME + '/lib/logger'
-  load_logger
+#################################################
+
+def load_adapter s
+  begin
+    require s
+  rescue Exception => e
+    @@log.error "Could not load adapter #{s}: #{e}"
+  end
 end
 
+#################################################
+# load standard classes that need to be loaded at startup
+
 require 'rubygems'
 
 ### load the DRb server functions
@@ -301,9 +307,15 @@ require 'drb/drb'
 #   require 'thread'
 #   require 'gen'
 
+### load logger + Rubinstein libraries
+unless (( defined? @@log ) || ( defined? logger ))
+  require RUBINSTEIN_HOME + '/lib/logger'
+  load_logger
+end
+
+# Load ActiveRDF, and immediately after this update the Namespace class to the patched version that support various abstractions and URI rules.
 require 'active_rdf'
-# load the namespace patch to ActiveRDF
-require RUBIC_HOME + '/lib/objectmanager/namespace'
+require RUBIC_HOME + '/objectmanager/namespace'
 
 # Namespace configuration
 require RUBINSTEIN_HOME + '/config/namespaces'
@@ -311,6 +323,8 @@ require RUBINSTEIN_HOME + '/config/namespaces'
 ### load helper methods
 require RUBINSTEIN_HOME + '/lib/helpers'
 
+#################################################
+
 ### start ActiveRubic
 begin
 
@@ -324,10 +338,10 @@ begin
 
       ### load the base
       @@log.rubic " => loading ActiveRubinstein"
-      require RUBIC_HOME + '/lib/active_rubinstein/base'
+      require RUBIC_HOME + '/active_rubinstein/base'
 
       @@log.rubic " => loading ActiveRubic"
-      require RUBIC_HOME + '/lib/active_rubic/base'
+      require RUBIC_HOME + '/active_rubic/base'
 
       @@log.debug " => including ActiveRubinstein to ActiveRubic::Base"
       ActiveRubic::Base.class_eval do
@@ -339,11 +353,11 @@ begin
 
       ### load models
       @@log.rubic " * loading ActiveRDF extensions"
-      require RUBIC_HOME + '/lib/objectmanager/rdfs/resource'
-      require RUBIC_HOME + '/lib/objectmanager/rdfs/image' # should be in the schema
-      require RUBIC_HOME + '/lib/objectmanager/owl/class'
-      require RUBIC_HOME + '/lib/objectmanager/owl/thing'
-      require RUBIC_HOME + '/lib/objectmanager/owl/object_property'
+      require RUBIC_HOME + '/objectmanager/rdfs/resource'
+      require RUBIC_HOME + '/objectmanager/rdfs/image' # should be in the schema
+      require RUBIC_HOME + '/objectmanager/owl/class'
+      require RUBIC_HOME + '/objectmanager/owl/thing'
+      require RUBIC_HOME + '/objectmanager/owl/object_property'
 
       ### load the backend libraries only when required
       unless @@in_daemon_mode then
@@ -362,4 +376,19 @@ rescue
 #   raise ActiveRubic::ActiveRubicError, $!
 end
 
-# EOF
+module ActiveRubic
+  class ActiveRubicError < StandardError #:nodoc:
+  end
+  class AdapterNotSpecifiedError < ActiveRubicError # :nodoc:
+  end
+  class AdapterNotFoundError < ActiveRubicError # :nodoc:
+  end
+  class ConnectionNotEstablishedError < ActiveRubicError #:nodoc:
+  end
+  class ConnectionFailedError < ActiveRubicError #:nodoc:
+  end
+  class RubicNotFoundError < ActiveRubicError #:nodoc:
+  end
+end
+
+# EOF

data/lib/active_rubic/base.rb

@@ -0,0 +1,357 @@
+module ActiveRubic
+
+  # = Methods
+  #
+  # == find() 
+  # accepts two type of queries
+  # - an RDFS::Resource object, with options that specify the requested value
+  # - action; a Ruby Symbol
+  #
+  # actions are defined in storage-specific objects:
+  # - ActiveRubinstein::Base,
+  # - ActiveRubinstein::SparqlFormulator
+  # - ActiveRubinstein::JenaQuery
+  # - ActiveRubinstein::LuceneSearcher
+  # - ActiveRubinstein::JosekiQuery
+  #
+  # == search()
+  # string query from Lucene indices
+  #
+  # == sparql()
+  # accepts a Ruby Query and executes it to storages that accept SPARQL
+  #
+  # EXAMPLES:
+  # -  ActiveRubic::Base.find( subject, :label, :from => :jena )
+  # - this is the function called by RDFS::Resource.label
+  #
+  # - ActiveRubic::Base.sparql( Query.new.distinct( :gp ).where( :gp, GEO::point, KUOPIO::kuopion_museo ) )
+  # - this is the function called by RDFS::Resource.geopoint
+  #
+  #############################################################################
+  class Base
+
+    def initialize # :nodoc:
+    end
+
+    unless defined? RAILS_ROOT
+      require RUBINSTEIN_HOME + '/lib/rails_database'
+      @@log.rubic " * connecting to Rails database.."
+      @@rails_db = RailsDB.new( 'precursor' )
+      @@log.rubic "@@rails_db = #{@@rails_db.inspect}"
+    else
+      @@log.rubic " * Running in Rails environment"
+    end
+
+    class << self # Class methods
+
+      public
+
+      # checks if the servers are alive, tries to re-initialize ActiveRubinstein once.
+      def check_connection( options={} )
+        begin
+          ActiveRubinstein::Base.new() if options[ :reinit_rubinstein ]
+          ActiveRubinstein::JenaQuery.server.ping
+        rescue
+          # try to re-initialize once
+          unless options[ :reinit_rubinstein ]
+            check_connection( :reinit_rubinstein => true )
+          else
+            raise ConnectionNotEstablishedError, $!
+          end
+        end
+      end
+
+      # Sets the Rubinstein query parameters.
+      #
+      # Parameters:
+      # - 1, lang (Hash; :lang => 'en')
+      def set_query_options( options={} )
+        lang = options[ :lang ]
+
+        # set the language by which Rubinstein queries.
+        if lang
+          @@log.rubic "Using language #{lang} (#{lang.class})" 
+          ActiveRubinstein::Base.set_language( lang )
+        end
+      end
+
+      # The main method for queries.
+      #
+      # options:
+      # - :data_stores = Array
+      # - :suffice_to = Array of data_stores that are trusted to return sufficient results. By default all data stores are untrusted to be complete, and the results of each are combined. The results of servers given in the Array.
+      # - :combine = Array of data stores that are queried and the results combined. If the trusted server returns results, trust that the contents is sufficient.
+      #
+      # EXAMPLES:
+      # - triple-based: find( RDFS::label, :subject => KUOPIO::kuopion_museo )
+      # - abstract: find( :images_of, :subject => KUOPIO::puijon_torni )
+      def find(*args)
+        options = extract_options_from_args!(args)
+#         validate_find_options(options)
+#         set_readonly_option!(options)
+        @@log.rubic " * Find: #{args}, #{options}"
+
+        case args.first
+          ###########################################
+#           when :first then find_initial(options)
+
+          ###########################################
+          when :all   then 
+            return serial_query_handler( :all, options )
+
+          ###########################################
+#          else              find_from_resources(args, options)
+          else
+            return serial_query_handler( args.first, options )
+        end
+      end
+
+      # Executes a SPARQL query on the backends that support this. calls serial_query_handler, which calls the query validator.
+      #
+      # EXAMPLES:
+      # - sparql( Query.new.distinct( :s ).where( :s, KUOPIO::isDesignedBy, TOIMIJAT::j_v_stromberg ) )
+      def sparql( query, *args, &block )
+        unless query.is_a? Query
+          @@log.error "The first parameter must be a Query"
+        else
+          options = extract_options_from_args!(args)
+          @@log.rubic " * Received SPARQL; options: #{options}"
+          @@log.query " * Sparql: #{query.to_sp}"
+          return serial_query_handler( query, options )
+        end
+      end
+      alias :find_by_sparql :sparql
+      alias :query  :sparql
+
+      # Counterpart to find(). Instead of resource-based queries, this method takes in strings and returns resources from Lucene indices.
+      #
+      # The indices are defined in Rubinstein/config/lucene_indices.rb
+      #
+      # Parameters:
+      # - 1  keywords (String)
+      # - 2  options  (Hash; 
+      #     :index => :images,
+      #     :limit => @@search_limit,
+      #     :score_limit => 0.0,
+      #     :original_keywords => search_string,
+      #     :from => :lucene | :geolucene
+      def search( keywords, options={} )
+        @@log.rubic " * Search: #{keywords}, #{options}"
+
+        options.update :lucene_branch => :standard
+        return ActiveRubinstein::LuceneSearcher.search( keywords, options )
+      end
+
+      private
+      
+      # checks if the data source can run this query.
+      def backend_can_execute?( query, backend )
+        if (( query.is_a? Query ) and ( backend == :lucene ))
+          return false
+        else
+          return true
+        end
+      end
+      
+      # runs a query on data stores sequentially. a huge method and perhaps should be split.
+      def serial_query_handler(query, options)
+        # query the data_stores set at options, (all by default)
+        data_stores = options[ :from ] || RUBIC_DATASTORES
+        data_stores = [ data_stores ] unless data_stores.is_a? Array
+      
+        # save the data stores to options
+        options.update( :data_stores => data_stores )
+      
+        limit = options[ :limit ]
+      
+        # If suffice_to is set, then do not begin any more data store queries after processing that storage.
+        first_sufficient_storage = options[ :suffice_to ] || data_stores.last
+      
+        @@log.deep "  => Querying data stores: #{data_stores.join(', ')}"
+        @@log.deep " - Will suffice to data from #{first_sufficient_storage}" if data_stores.size > 1
+        if !data_stores.include? first_sufficient_storage
+          @@log.warn " ! #{first_sufficient_storage} was set to suffice but is not within the data store list."
+        end
+      
+        ####################
+        ### EXECUTION LOOP
+        # loops each data store and combines the results. duplicates are checked.
+      
+        results = Hash.new
+      
+        ## TODO: handle TIMEOUT
+        ############################################################
+        begin
+          data_stores.each do |storage|
+            if backend_can_execute?( query, data_stores ) then
+              t1 = Time.now
+        
+              # Execute ###########################################
+              my_results = run_query( storage, query, options )
+              #####################################################
+        
+              # if results?
+              if ( !my_results.nil? && my_results.size > 0 ) then
+                results.update  storage => my_results
+                @@log.rubic "   => Got #{my_results.size} results from #{storage} in #{Time.now-t1} sec"
+              else
+                @@log.rubic "   => No results from #{storage} in #{Time.now-t1} sec"
+              end
+        
+              # no further queries, this data storage contains enough information
+              if ((storage == first_sufficient_storage) || (first_sufficient_storage == :first))
+                @@log.rubic "   ! as #{storage} is sufficient, no further data storages are queried." unless storage == data_stores.last
+                break # is taken by me
+              end
+        
+            end # if backend_can_execute?
+          end # data_stores.each
+        rescue
+          @@log.error $!
+        end
+            ############################################################
+      
+            # merge results from the hash to a single array
+            merge = Array.new
+            results.each_value do |q| q.uniq.each do |resource|
+      #               @@log.debug resource.inspect
+            merge << resource unless resource.nil?
+          end
+        end
+      
+        # returning nil causes not-so-well designed models to crash :)
+        if merge.nil? or merge.empty?
+          @@log.rubic "  => No results"
+          return Array.new
+      
+        ############################################################
+        else
+      
+          # merge arrays (flatten) and remove nils (compact)
+          # NOTE: running compact! here will cause nil results
+          merge.flatten!
+      
+          @@log.deep "  => #{merge.size} altogether"
+      
+          # only allow these objects in results.
+          allowed_classes = [
+            RDFS::Resource,
+            OWL::Class,
+            OWL::ObjectProperty,
+            OWL::Thing,
+            Image,
+            String
+          ]
+      
+          unfamiliar_classes = Array.new
+          results = Array.new
+      
+          merge.each do |resource|
+            if ( allowed_classes.include? resource.class ) then
+              results << resource
+            else
+              # unaccepted classes are collected just to inform the log reader.
+              unfamiliar_classes << resource.class
+            end
+          end
+      
+          # remove duplicates
+          results.uniq!
+      
+          # warning log
+          if unfamiliar_classes.any? then
+            @@log.warn " -- #{unfamiliar_classes.uniq.join(', ')} class types in results"
+            @@log.warn " -- Returning only #{allowed_classes.join(', ')}"
+          end
+      
+          @@log.rubic "  => TOTAL: #{results.size} unique results"
+        end
+        ############################################################
+      
+        # todo: insert limit into queries, this will do for now..
+        if limit then
+          @@log.deep " => Returning with limit #{limit}"
+          return results[ 0 .. (limit-1) ]
+        else
+          @@log.deep " => Returning all #{results.size}, no limit"
+          @@log.boulderdash results
+          return results
+        end
+      
+      end
+
+
+      def find_initial(options) # :nodoc:
+#           options.update(:limit => 1) unless options[:include]
+#           find_every(options).first
+      end
+
+      ########################################################################
+
+      # conducts the query to the correct backend handler.
+      #
+      # Parameters:
+      # - 1  storage (Symbol)
+      # - 2  query
+      # - 3  options (Hash)
+      def run_query( storage, query, options )
+        @@log.rubic "   => query: #{query} (#{query.class})"
+
+        case storage
+        when :mysql
+          return ActiveRubic::Cacher.read( query, options )
+
+        when :lucene
+          options.update :lucene_branch => :standard
+          return ActiveRubinstein::LuceneSearcher.execute( query, options )
+
+        when :geolucene
+          options.update :lucene_branch => :geolucene
+          return ActiveRubinstein::LuceneSearcher.execute( query, options )
+
+        when :jena
+          return ActiveRubinstein::JenaQuery.execute( query, options )
+
+        when :joseki
+          return ActiveRubinstein::JosekiQuery.execute( query, options )
+        end
+      end
+
+    protected
+
+      def extract_options_from_args!(args) #:nodoc:
+        args.last.is_a?(Hash) ? args.pop : {}
+      end
+
+    end
+  end
+end
+
+
+class Array
+
+  # enables randomizing
+  def randomize
+   arr = self.dup
+   self.collect { arr.slice!( rand( arr.length ) ) }
+  end
+
+  def randomize!
+   arr = self.dup
+   # bug here, the array size was halved
+   #result = arr.collect { arr.slice!( rand( arr.length ) ) }
+   result = self.collect { arr.slice!( rand( arr.length ) ) }
+   self.replace result
+  end
+
+end
+
+  #--
+  # ideas for future modules:
+  #               ActiveRubinstein::Virtuoso
+  #               ActiveRubinstein::MysqlCache
+  #               ActiveRubinstein::Terra # environment, the 'terrain'
+  #               ActiveRubinstein::Hidria # the Hidria spacefolk ;-)
+  #                                           ? => wikipedia
+  #
+  #++