rdf-mapper 0.0.1

data/README.rdoc

@@ -0,0 +1,188 @@
+= RDFMapper -- Object-relation mapping for RDF data
+
+RDFMapper is an ORM[http://en.wikipedia.org/wiki/Object-relational_mapping]
+written in Ruby that is designed to play nicely with RDF data.
+
+== Features
+
+- 100% Ruby code based on a slim & smart {RDF.rb}[http://rdf.rubyforge.org/] library
+- All the usual Rails methods: find, create, belongs_to, has_many -- you name it
+- Built with performance in mind: all objects are lazy-loaded by default
+- Supports REST, SPARQL and ActiveRecord as RDF data sources
+- Supports XML, N-Triples and JSON out of the box
+
+== Installation
+
+The prefered method of installing RDFMapper is through its gem file (requires
+RubyGems[http://rubygems.rubyforge.org/wiki/wiki.pl]):
+
+  % [sudo] gem install rdf-mapper
+
+The latest version of RDFMapper can be found at
+
+* http://github.com/42cities/rdf-mapper
+
+
+== Contribute
+
+Please note that RDFMapper in under heavy development right now, it's not yet
+production safe. Any contribution (bug tickets, code patches) is more than
+welcome. Email us at team@42cities.com or submit a ticket on
+GitHub[http://github.com/42cities/rdf-mapper/issues]
+
+
+= 5-minute crash course
+
+=== Idea behind RDF models
+
+Models in RDFMapper are essentially RDF nodes that have an ID and at least one triple
+with an rdf:type predicate. Consider the following example:
+
+  <http://example.org/people/237643>   rdf:type       <http://www.example.org/schema#Person>
+  <http://example.org/people/237643>   example:name   "John Smith"
+  <http://example.org/people/237643>   example:age    "27"^^xsd:integer
+
+This set of triples defines a node (with an ID of <http://example.org/people/237643>)
+that has three 'attributes': `example:name`, `example:age`, and `rdf:type`. Now `rdf:type`
+predicate tells us that there's a class (<http://www.example.org/schema#Person>)
+with more or less predefined behavior. And our node (<http://example.org/people/237643>)
+is an instance of that class. We could replicate the same logic in Ruby:
+
+  class Person
+    attr_accessor :id
+    attr_accessor :name
+    attr_accessor :age
+  end
+  
+  person = Person.new
+  person.id = "http://example.org/people/237643"
+  person.name = "John Smith"
+  person.age = 27
+
+That's essentially what RDFMapper does. It accepts RDF triples (XML or N-triples),
+creates instances, assigns attributes and binds models together (via Rails-like
+belongs_to and has_many associations).
+
+
+=== Defining a model
+
+Before you start working with RDFMapper, you need to define at least one model. The only
+required setting is its namespace (think XML namespace) or type (think rdf:type). If you
+specify the namespace, it will be used by the model itself (to figure out its rdf:type)
+and by its attributes (to figure out RDF predicates).
+
+  class Person < RDFMapper::Model
+    namespace "http://example.org/#"
+    attribute :name,     :type => :text
+    attribute :homepage, :type => :uri, :predicate => 'http://xmlns.com/foaf/0.1/homepage'
+  end
+
+  Person.namespace        #=> #<RDF::Vocabulary(http://example.org/#)>
+  Person.type             #=> #<RDF::URI(http://example.org/#Person)>
+  
+  Person.name.type        #=> #<RDF::URI(http://example.org/#name")>
+  Person.homepage.type    #=> #<RDF::URI(http://xmlns.com/foaf/0.1/homepage)>
+
+For more information on {RDF::URI}[http://rdf.rubyforge.org/RDF/URI.html],
+{RDF::Vocabulary}[http://rdf.rubyforge.org/RDF/Vocabulary.html] and other
+classes within RDF namespace, refer to {RDF.rb documentation}[http://rdf.rubyforge.org/].
+
+
+=== Defining the data source
+
+By this moment you can work with RDFMapper models with no additional settings.
+However, if you want to load, save and search for your objects, you need to
+specify their data source. RDFMapper comes with 3 different flavors of data
+sources: REST, SPARQL and Rails.
+
+* SPARQL [read-only] -- the standard for RDF data.
+  RDFMapper will query specified SPARQL server over HTTP using standard SPARQL
+  syntax. Currently it supports only a few functions (no subqueries, updates,
+  aggregates, etc.)
+
+* REST [read-only] -- good old HTTP-based data
+  storage. It assumes that an object's ID (which is an URI) is the place to
+  look when you want to get object's properties. For example, if an object has
+  an ID `http://example.org/people/237643`, RDFMapper will download data from
+  this address and parse any RDF triples it finds along the way.
+
+* Rails [read/write] -- gets the data from an
+  ActiveRecord model (that is Rails model). This adapter assumes an RDFMapper
+  model has a 'mirror' ActiveRecord model with the same attributes and
+  associations.
+
+Assigning data source to a model is easy:
+
+  class Person < RDFMapper::Model
+    adapter :rails   # There should be a `Person` class that subclasses ActiveRecord::Base
+  end
+  
+  class Person < RDFMapper
+    adapter :rails, :class_name => 'Employee'   # ActiveRecord::Base model is called `Employee`
+  end
+
+  class Person < RDFMapper
+    adapter :sparql, {
+		:server => 'http://some-sparql-server.com'
+		:headers => { 'API-Key' => '89d7sfd9sfs' }
+	}
+  end
+
+
+=== Searching
+
+If you search objects by an ID, it's up to the adapter (REST, SPARQL, or Rails) to
+decide what type of ID it requires (an URI, a database column or something else).
+Check out the documentation for each adapter to see how works.
+
+  Person.all                                              #=> #<PersonCollection:23784623>
+  Person.find('132987')                                   #=> #<Person:217132856>
+  Person.find(:all, :conditions => { :name => 'John' })   #=> #<PersonCollection:32462387>
+
+Note, the objects above are not loaded. RDFMapper will load them once you
+access an attribute of a collection or an object. The following 3 objects are
+loaded instantly, since RDFMapper needs to figure out what their attributes are
+(in this case `nil?`, `name` and `length`).
+
+  Person.find('132987').nil?                                     #=> false
+  Person.find('132987').name                                     #=> "John"
+  Person.find(:all, :conditions => { :name => 'John' }).length   #=> 3
+
+You should take extra care when dealing with lazy-loaded models, since
+exceptions may occur when a model is not found:
+
+  Person.find('132987')         #=> #<Person:217132856>
+  Person.find('132987').name    #=> NoMethodError: undefined method `name' for nil:NilClass
+
+Instead, you should first check if a model exists:
+
+  @person = Person.find('132987')
+  @person.name unless @person.nil?
+
+
+=== Working with attributes
+
+Attributes in RDFMapper work just as you would expect them to work with just one
+small exception. Since any attribute of a model is essentially an RDF triple, you
+can access attributes by their predicates as well:
+
+  class Person < RDFMapper::Model
+    namespace "http://example.org/#"
+    attribute :name, :type => :text
+    attribute :homepage, :type => :uri, :predicate => 'http://xmlns.com/foaf/0.1/homepage'
+  end
+
+  instance = Person.new
+  instance.name                                   #=> "John Smith"
+  instance[:name]                                 #=> "John Smith"
+  instance['http://example.org/#name']            #=> "John Smith"
+  instance.homepage                               #=> #<RDF::URI(http://johnsmith.com/")>
+  instance['http://xmlns.com/foaf/0.1/homepage']  #=> #<RDF::URI(http://johnsmith.com/")>
+
+
+That's pretty much all you need to know. Go try and let us know what you think!
+
+== License
+
+RDFMapper is free and unencumbered public domain software. For more information,
+see http://unlicense.org or the accompanying UNLICENSE file.

data/UNLICENSE

@@ -0,0 +1,25 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, contact Alex Serebryakov [serebryakov@gmail.com]
+or visit <http://unlicense.org/>

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/lib/adapters/base.rb

@@ -0,0 +1,83 @@
+module RDFMapper
+  module Adapters
+    
+    autoload :Rails,  'lib/adapters/rails'
+    autoload :REST,   'lib/adapters/rest'
+    autoload :SPARQL, 'lib/adapters/sparql'
+    
+    ##
+    # Instantiates and returns an instance of an adapter. 
+    #
+    # @param [Symbol] name (:rails, :sparql, :rest)
+    # @param [Object] cls subclass of RDFMapper::Model
+    # @param [Hash] options options to pass on to the adapter constructor
+    #
+    # @return [Object] instance of an adapter
+    ##
+    def self.register(name, cls, options = {})
+      self[name].new(cls, options)
+    end
+    
+    ##
+    # Returns adapter's class based on specified `name` (:rails, :sparql, :rest)
+    #
+    # @return [Object]
+    ##
+    def self.[](name)
+      case name
+        when :rails   then Rails
+        when :sparql  then SPARQL
+        when :rest    then REST
+        else raise NameError, 'Adapter `%s` not recognized' % value.inspect
+      end
+    end
+    
+    ##
+    # Parent class for all adapters. Contains default constructor method
+    # and interface methods that each adapter should override.
+    ##
+    class Base
+      
+      ##
+      # All adapters implement Logger
+      ##
+      include RDFMapper::Logger
+
+      ##
+      # Adapter implementation should override this method
+      ##
+      def load(query)
+        raise NotImplementedError, 'Expected adapter to override `load`'
+      end
+
+      ##
+      # Adapter implementation should override this method
+      ##
+      def save(instance)
+        raise NotImplementedError, 'Expected adapter to override `save`'
+      end
+
+      ##
+      # Adapter implementation should override this method
+      ##
+      def reload(instance)
+        raise NotImplementedError, 'Expected adapter to override `save`'
+      end
+
+      ##
+      # Adapter implementation should override this method
+      ##
+      def update(instance)
+        raise NotImplementedError, 'Expected adapter to override `save`'
+      end
+      
+      ##
+      # Adapter implementation should override this method
+      ##
+      def create(instance)
+        raise NotImplementedError, 'Expected adapter to override `save`'
+      end
+      
+    end
+  end
+end

data/lib/lib/adapters/rails.rb

@@ -0,0 +1,307 @@
+module RDFMapper
+  module Adapters
+    ##
+    # [-]
+    ##
+    class Rails < Base
+      
+      ##
+      # [-]
+      ##
+      def initialize(cls, options = {})
+        @rdf, @options = cls, options
+        @options[:skip] ||= []
+        @options[:substitute] ||= { }
+        @options[:substitute][:id] ||= :uid
+      end
+
+
+      ##
+      # [-]
+      ##
+      def load(query)
+        @rdf.associations.values.select do |assoc|
+          assoc.belongs_to?
+        end.map do |assoc|
+          assoc.name
+        end.reject do |name|
+          @options[:skip].include?(name)
+        end.each do |name|
+          query.include!(name)
+        end
+        Query.new(query, @options).find
+      end
+      
+      ##
+      # [-]
+      ##
+      def save(instance)
+        if instance[:rails_id].nil?
+          obj = instance.class.find(instance.id.to_s).from(:rails)
+          instance[:rails_id] = obj.rails_id unless obj.nil?
+        end
+        if instance[:rails_id].nil?
+          create(instance)
+        else
+          update(instance)
+        end
+      end
+      
+      ##
+      # [-]
+      ##
+      def reload(instance)
+        query = RDFMapper::Scope::Query.new(instance.class, :conditions => { :id => instance.id })
+        Query.new(query, @options).find.first
+      end
+      
+      ##
+      # [-]
+      ##
+      def update(instance)
+        query = RDFMapper::Scope::Query.new(instance.class, :conditions => instance.attributes)
+        Query.new(query, @options).update
+      end
+      
+      ##
+      # [-]
+      ##
+      def create(instance)
+        query = RDFMapper::Scope::Query.new(instance.class, :conditions => instance.attributes)
+        Query.new(query, @options).create
+      end
+      
+      
+      private
+      
+      def check_for_rails_id(instance)
+      end
+
+      class Query
+        
+        include RDFMapper::Logger
+        
+        def initialize(query, options = {})
+          @query, @options = query, options
+          @rails = (@options[:class_name] || @query.cls.to_s.demodulize).constantize
+          setup_replacements
+        end
+        
+        ##
+        # [-]
+        ##
+        def update
+          record = @rails.update(@query[:rails_id], save_options)
+          record_attributes(record)
+        end
+        
+        ##
+        # [-]
+        ##
+        def create
+          record = @rails.create(save_options)
+          record_attributes(record)
+        end
+        
+        ##
+        # [-]
+        ##
+        def find
+          @query.check(:rails_id)
+          #
+          debug 'Searching for %s with %s' % [@rails, @query.inspect]
+          debug 'Query: %s' % find_options.inspect
+          #
+          @rails.find(:all, find_options).map do |record|
+            record_attributes(record)
+          end
+        end
+
+        
+        private
+        
+        ##
+        # [-]
+        ##
+        def record_attributes(record)
+          record_id = [:id, :rails_id].map do |name|
+            [name, record_value(record, name)]
+          end
+          record_props = record_properties(record)
+          record_assoc = record_associations(record)
+          Hash[record_id + record_props + record_assoc]
+        end
+        
+        ##
+        # [-]
+        ##
+        def save_options
+          Hash[@query.to_a.map do |condition|
+            name = @replace[condition.name]
+            [name, validate(condition.value)]
+          end.reject do |name, value|
+            name.nil? or value.nil?
+          end]
+        end
+        
+        ##
+        # Substitutes names of those attributes specified in `options[:substitute]`
+        # and raises a runtime error for attributes that could not be found in the
+        # database. Returns an object which can then be used with ActiveRecord::Base.find
+        ##
+        def find_options #nodoc
+          { :conditions => SQL.new(@query, @replace).to_a,
+            :order => @query.order,
+            :limit => @query.limit,
+            :offset => @query.offset,
+            :include => @query.include
+          }.delete_if { |name, value| value.nil? }
+        end
+        
+        ##
+        # [-]
+        ##
+        def setup_replacements #nodoc
+          @replace = default_replacements
+          @query.flatten.map do |condition|
+            # Original RDF name
+            rdf_name = condition.name
+            # Expected name in the DB
+            expected_name = @replace[rdf_name] || rdf_name
+            # Silently ignore attributes that are not in the DB
+            rails_name = activerecord_attribute?(expected_name)
+            @replace[rdf_name] = rails_name unless rails_name.nil?
+          end
+        end
+        
+        ##
+        # [-]
+        ##
+        def default_replacements
+          @options[:substitute].merge({ :rails_id => :id })
+        end
+        
+        ##
+        # [-]
+        ##
+        def record_properties(record) #nodoc
+          @query.cls.properties.keys.map do |name|
+            value = record_value(record, name)
+            [name, value]
+          end
+        end
+
+        ##
+        # [-]
+        ##
+        def record_associations(record) #nodoc
+          @query.include.map do |name|
+            value = record_value(record, name)
+            value = value.nil? ? nil : value[@replace[:id]]
+            [name, value]
+          end
+        end
+        
+        ##
+        # [-]
+        ##
+        def record_value(record, rdf_name) #nodoc
+          name = default_replacements[rdf_name] || rdf_name
+          unless record.respond_to?(name)
+            nil
+          else
+            record.send(name)
+          end
+        end
+        
+        ##
+        # [-]
+        ##
+        def activerecord_attribute?(name) #nodoc
+          activerecord_property?(name) || activerecord_association?(name)
+        end
+
+        ##
+        # [-]
+        ##
+        def activerecord_association?(name) #nodoc
+          reflection = @rails.reflections[name.to_sym]
+          if reflection.nil? or not reflection.belongs_to?
+            return nil
+          end
+          reflection.primary_key_name.to_sym
+        end
+
+        ##
+        # [-]
+        ##
+        def activerecord_property?(name) #nodoc
+          @rails.column_names.include?(name.to_s) ? name.to_sym : nil
+        end
+        
+        class SQL
+          
+          def initialize(query, replace)
+            @query, @replace = query, replace
+            @text, @values = [], []
+
+            @query.to_a.map do |condition|
+              if condition.kind_of?(query.class)
+                add_query(condition)
+              else
+                add_condition(condition)
+              end
+            end
+          end
+          
+          def add_query(query)
+            child = SQL.new(query, @replace)
+            unless child.text.empty?
+              @text.push("(%s)" % child.text)
+              @values.push(*child.values)
+            end
+          end
+          
+          def add_condition(condition)
+            name = @replace[condition.name]
+            if name.nil?
+              return nil
+            end
+            if condition.value.kind_of?(Array)
+              @text << "%s IN (?)" % name
+            else
+              @text << "%s %s ?" % [name, condition.eq]
+            end
+            @values << validate(condition.value)
+          end
+          
+          def validate(value) #nodoc
+            if value.kind_of? Array
+              return value.map do |item|
+                validate(item)
+              end
+            end
+            if value.kind_of? RDFMapper::Model
+              value[:rails_id]
+            else
+              value
+            end
+          end
+          
+          def text
+            @text.join(' %s ' % @query.modifier)
+          end
+          
+          def values
+            @values
+          end
+          
+          def to_a
+            [text] + values
+          end
+          
+        end # SQL
+      end # Query
+    end # Rails
+  end # Adapters
+end # RDFMapper

data/lib/lib/adapters/rest.rb

@@ -0,0 +1,45 @@
+module RDFMapper
+  module Adapters
+    ##
+    # Not yet implemented
+    ##
+    class REST < Base
+      
+      ##
+      # @todo. Not implemented
+      ##
+      def load(query)
+        raise NotImplementedError, 'REST adapter is not yet implemented'
+      end
+
+      ##
+      # @todo. Not implemented
+      ##
+      def save(instance)
+        raise NotImplementedError, 'REST adapter is not yet implemented'
+      end
+
+      ##
+      # @todo. Not implemented
+      ##
+      def reload(instance)
+        raise NotImplementedError, 'REST adapter is not yet implemented'
+      end
+
+      ##
+      # @todo. Not implemented
+      ##
+      def update(instance)
+        raise NotImplementedError, 'REST adapter is not yet implemented'
+      end
+
+      ##
+      # @todo. Not implemented
+      ##
+      def create(instance)
+        raise NotImplementedError, 'REST adapter is not yet implemented'
+      end
+      
+    end # REST
+  end # Adapters
+end # RDFMapper