rdf-virtuoso 0.0.11

data/README.md

@@ -0,0 +1,73 @@
+# rdf-virtuoso: Ruby Virtuoso adapter for RDF.rb
+The intent of this class is to act as an abstraction for clients wishing to connect and manipulate linked data stored in a Virtuoso Quad store.
+
+## How?
+RDF::Virtuoso::Repository builds on RDF.rb and is the main connection class built on top of APISmith to establish the read and write methods to a Virtuoso store SPARQL endpoint.
+RDF::Virtuoso::Query extends RDF::Query and adds SPARQL 1.1. update methods (insert, delete, aggregates, etc.).
+
+For examples on use, see ./spec/client_spec.rb and ./spec/query_spec.rb 
+
+### A simple example
+
+This example assumes you have a local installation of Virtoso running at standard port 8890
+
+#### Setup Repository connection connection with auth
+
+    uri = "http://localhost:8890"
+    REPO = RDF::Virtuoso::Repository.new(uri, :username => 'admin', :password => 'secret', :auth_method => 'digest')
+
+:auth_method can be 'digest' or 'basic'. a repository connection without auth requires only uri
+
+#### INSERT WHERE query example
+
+    QUERY = RDF::Virtuoso::Query
+    graph = RDF::URI.new("http://test.com")
+    subject = RDF::URI.new("http://subject")
+
+    query = QUERY.insert([subject, :p, "object"]).graph(graph).where([subject, :p, :o])
+    result = REPO.insert(query)
+
+#### A count query example
+
+    QUERY = RDF::Virtuoso::Query
+    graph = RDF::URI.new("http://test.com")
+    type =  RDF::BIBO.Document
+
+    count = REPO.select.where(:s, type, :o).count(:s).graph(graph)
+    
+## Rails specifics
+Working on a prototype Rails application for negotiating and manipulating linked data in an RDF store, I discovered the lack of a reasonably current library to bridge the gap between the fairly well-established, modular RDF.rb library and a Rails 3 application. I wanted to be able to manipulate RDF data in a convenient, ActiveRecord/ActiveModel way. It turned out to be fairly non-trivial to mimic true AR/AM behavior and this is more or less the groundwork and result of my experimentation. I now have a much better idea of how to proceed, I just need the time to really go deep into this.
+An example prototype that exercises this library can be found here: https://github.com/digibib/booky
+
+It must be stressed that this is still early days, with lots of refactoring and abstraction to be done, along with very specific functionality targeted at the prototype I've been working on. So anyone wanting a more generalized approach would be well served by waiting until I'm further along.
+
+Essentially, a model in a Rails 3 app subclasses ActiveRDF::Model, which in itself includes the following modules: 
+ActiveAttr::Model - https://github.com/cgriego/active_attr
+ActiveModel::Dirty - http://api.rubyonrails.org/classes/ActiveModel/Dirty.html
+ActiveRDF::Persistence - responsible for handling persistence, in this gem
+
+In a nutshell:
+
+ActiveRDF::Model provides common functionality for models along with some mixed-in 3rd-party modules
+
+ActiveRDF::Persistence provides some of the functionality a Rails model may expect, along with some placeholder methods that are waiting for AR/Arel type implementations. All communication is done via the query language SPARQL, (version 1.1 as of this writing).
+
+RDF::Virtuoso::Client provides a rudimentary connection class for interacting with a Virtuoso server. It is inspired by API Smith (https://github.com/filtersquad/api_smith) which has some nice features, such as a convenient way to specify a Parser class for a given mimetype. See RDF::Virtuoso::Parser for example, and the method RDF::Virtuoso::Client#api_get.
+
+## Challenges
+In no particular order:
+
+* In RDF data, the equivalent of a primary key in a relational database is called the subject (part of each of a set of triples), which is represented by a URI which looks like an absolute URL. When Rails does its magic with routes and friends, it assumes by default that it's dealing with an Integer, which is fine for a relational database id column which is auto-generated by the RDBM, unique and very often an int. Under the covers, to_i is called on id. This does not work for URLs, obviously. Also, you can't just send unencoded URLs over the wire as part of a path in a route. Anyway, this whole issue needed to be solved quickly, so for now RDF subjects that are part of a path are encoded and then decoded before insertion.
+* On the topic of unique ids, relational databases can be told to autogenerate unique primary keys on insert for you. Here, we have to use a library (UUID) to generate unique ids before insert. 
+* On the whole, when dealing with RDF subjects, care has to be taken how they are constructed. They can end with either a forward-slash or a hash, followed by some unique identifier. Seems like the hash-notation is preferred if the data is ever to be be exported as turtle files (suffix ttl) and the unique identifier potentially starts with an integer. Whether that is a bug in the writer implementation is unclear, but better safe than sorry.
+* An update in an RDF store is a so-called modify and consists of one or more delete statements followed by one or more insert statements. Meaning that when a triple has changed, the original has to be deleted before the modified triple is inserted. There is a potential for leaving the data in an inconsistent state if, for instance, the delete directive isn't constructed correctly and the insert is. Or vice versa. With ActiveRecord, database writes are automatically wrapped in transactions that will roll back the data on failure. This too needed to be implemented explicitly, as seen in ActiveRDF::Persistence#update_attributes, using the SimpleTransaction libray.
+
+## Notes
+The following classes are not yet in use or will probably disapper:
+
+* ActiveRDF::AssociationReflection
+* ActiveRDF::Exceptions
+* ActiveRDF::Reflections
+
+
+ 

data/lib/active_rdf.rb

@@ -0,0 +1,14 @@
+require 'active_support'
+require 'active_model'
+require 'active_attr'
+require 'active_rdf/exceptions'
+require 'active_rdf/errors'
+require 'active_rdf/version'
+
+module ActiveRDF
+  extend ActiveSupport::Autoload
+
+  autoload :Model
+  autoload :Persistence
+  autoload :Reflection
+end

data/lib/active_rdf/association_reflection.rb

@@ -0,0 +1,26 @@
+class AssociationReflection
+  attr_reader :macro
+  attr_reader :name
+  attr_reader :options
+
+  def initialize(macro, name, options = {})
+    @macro = macro
+    @name = name
+    @options = options
+  end
+
+  def class_name
+    @class_name ||= (options[:type] || derive_class_name).to_s
+  end
+
+  def klass
+    @klass ||= class_name.constantize
+  end
+
+  private
+
+  def derive_class_name
+    name.to_s.camelize
+  end
+end
+

data/lib/active_rdf/errors.rb

@@ -0,0 +1,9 @@
+module ActiveRDF
+
+  # Base class for all ActiveRDF errors
+  class ActiveRDFError < StandardError
+  end
+
+  class ResourceNotFoundError < ActiveRDFError
+  end
+end  

data/lib/active_rdf/exceptions.rb

@@ -0,0 +1,83 @@
+module ActiveRDF
+
+  class ConnectionError < StandardError # :nodoc:
+    attr_reader :response
+
+    def initialize(response, message = nil)
+      @response = response
+      @message  = message
+    end
+
+    def to_s
+      message = "Failed."
+      message << "  Response code = #{response.code}." if response.respond_to?(:code)
+      message << "  Response message = #{response.message}." if response.respond_to?(:message)
+      message
+    end
+  end
+
+  # Raised when a Timeout::Error occurs.
+  class TimeoutError < ConnectionError
+    def initialize(message)
+      @message = message
+    end
+    def to_s; @message ;end
+  end
+
+  # Raised when a OpenSSL::SSL::SSLError occurs.
+  class SSLError < ConnectionError
+    def initialize(message)
+      @message = message
+    end
+    def to_s; @message ;end
+  end
+
+  # 3xx Redirection
+  class Redirection < ConnectionError # :nodoc:
+    def to_s
+      response['Location'] ? "#{super} => #{response['Location']}" : super
+    end
+  end
+
+  class MissingPrefixParam < ArgumentError # :nodoc:
+  end
+
+  # 4xx Client Error
+  class ClientError < ConnectionError # :nodoc:
+  end
+
+  # 400 Bad Request
+  class BadRequest < ClientError # :nodoc:
+  end
+
+  # 401 Unauthorized
+  class UnauthorizedAccess < ClientError # :nodoc:
+  end
+
+  # 403 Forbidden
+  class ForbiddenAccess < ClientError # :nodoc:
+  end
+
+  # 404 Not Found
+  class ResourceNotFound < ClientError # :nodoc:
+  end
+
+  # 409 Conflict
+  class ResourceConflict < ClientError # :nodoc:
+  end
+
+  # 410 Gone
+  class ResourceGone < ClientError # :nodoc:
+  end
+
+  # 5xx Server Error
+  class ServerError < ConnectionError # :nodoc:
+  end
+
+  # 405 Method Not Allowed
+  class MethodNotAllowed < ClientError # :nodoc:
+    def allowed_methods
+      @response['Allow'].split(',').map { |verb| verb.strip.downcase.to_sym }
+    end
+  end
+end

data/lib/active_rdf/model.rb

@@ -0,0 +1,69 @@
+require 'uuid'
+require 'transaction/simple'
+require 'rdf'
+require 'active_rdf/reflections'
+
+module ActiveRDF
+
+  class Model
+    include ActiveAttr::Model
+    include ActiveModel::Dirty
+    include ActiveRDF::Persistence
+
+    # All children should have these attributes
+    attribute :id,          type: String
+    attribute :subject,     type: String  
+
+
+    class << self
+      attr_accessor :reflections
+
+      def graph
+        url = RDF::URI.new("http://data.deichman.no")
+        if defined?(Rails)
+          url = url.join Rails.env unless (Rails.env.production? || Rails.env.staging?)
+        end
+        url / self.name.downcase.pluralize
+      end
+
+      def encode(string)
+        [string].pack('m0')
+      end
+
+      def decode(string)
+        string.unpack('m')[0]
+      end
+
+      def from_param(param)
+        decode param
+      end
+
+      private
+
+      def inherited(child)
+        child.instance_variable_set :@reflections, @reflections.dup
+        super
+      end
+    end  # Class methods
+
+    def type
+      self.class.type
+    end
+
+    # When using an object's subject, which comes in the format http://example.org/object#123 as 
+    # a query param, we must encode it first
+    def to_param
+      self.class.encode self.subject
+    end
+
+    def graph
+      self.class.graph
+    end
+
+    extend Reflections
+
+    @reflections = HashWithIndifferentAccess.new
+
+  end
+
+end

data/lib/active_rdf/persistence.rb

@@ -0,0 +1,185 @@
+module ActiveRDF
+  module Persistence
+    extend ActiveSupport::Concern
+
+    included do
+
+      # Override ActiveAttr::Attributes.attribute=(name, value)
+      def attribute=(name, value)
+        @attributes ||= {}
+        # We'll assume that nil and "" are equivalent
+        unless (@attributes[name].blank? && value.blank?) || (@attributes[name] == value)
+          send("#{name}_will_change!")
+        end
+        @attributes[name] = value
+      end
+    end
+
+    module ClassMethods
+
+      def connection
+        # TODO: make this behave like AM/AR Connection
+        CLIENT
+      end
+
+      def create(attrs = nil) 
+        object = new(attrs)
+        object.save
+        object
+      end
+
+      def create!(attrs = nil)
+        object = new(attrs)
+        object.save!
+        object
+      end
+
+      def before_create(method)
+        # Placeholder until implemented in ActiveRDF::Callbacks
+      end
+
+      def before_save(method)
+        # Placeholder until implemented in ActiveRDF::Callbacks
+      end
+
+      # @see: http://rdf.rubyforge.org/RDF/Query/Solutions.html
+      def order(variable)
+      end
+
+      def where(conditions)
+      end
+
+      def scope(variable, conditions)
+      end
+
+      def scoped
+      end
+
+      def count
+        query = "SELECT COUNT(DISTINCT ?s) WHERE { GRAPH <#{self.graph}> { ?s a <#{self.type}> }}"
+        result = CLIENT.select(query)
+        result.first['callret-0'].to_i
+      end
+
+      def find(object_or_id, conditions = {})
+
+        subject = case object_or_id
+                  when String then decode(object_or_id)
+                  when self then object_or_id.subject
+                  else raise ActiveModel::MissingAttributeError.new(object_or_id.inspect)
+                  end
+
+        find_by_subject(subject, conditions = {})
+      end      
+
+      def first
+        all(limit: 1).first
+      end
+
+      def execute(sql)
+        results = []
+        solutions = CLIENT.select(sql)
+        solutions.each do |solution|
+          record = new
+          solution.each_binding do |name, value|
+            record[name] = value.to_s
+          end
+          if record.subject.present?
+            record.id = id_for(record.subject)
+            record.changed_attributes.clear
+          end
+          results << record
+        end
+        results
+      end
+
+      # TODO: set baseurl via config
+      def subject_for(id)
+        RDF::URI('http://data.deichman.no') / self.name.downcase / "#" / id
+      end
+
+      def id_for(subject)
+        subject.to_s.split("#").last
+      end
+
+      def destroy_all
+        query = "DELETE FROM <#{self.graph}> { ?s ?p ?o } WHERE { GRAPH <#{self.graph}> { ?s a <#{self.type}> . ?s ?p ?o } }"
+        connection.delete(query)
+      end
+
+    end
+
+    # Instance methods
+    
+    def connection
+      self.class.connection
+    end
+
+    def save
+      return false unless self.valid?
+      create_or_update
+    end
+
+    def save!
+      unless self.valid?
+        raise ActiveRecord::RecordInvalid.new(self)
+      end
+      create_or_update
+    end
+
+    def destroy
+      subject = subject_for(self.id)
+      query = 
+<<-q 
+DELETE FROM <#{graph}> { <#{subject}> ?p ?o } 
+WHERE { <#{subject}> ?p ?o }
+q
+      result = connection.delete(query)
+    end
+
+
+    def update_attributes(attributes)
+      self.extend(::Transaction::Simple)
+      status = false
+      begin
+        self.start_transaction
+        self.assign_attributes(attributes)
+        status = save
+        self.commit_transaction
+      rescue Exception
+        self.rewind_transaction
+        self.abort_transaction
+      end
+      status
+    end
+
+    def reload
+      self.attributes = self.class.find(self).attributes
+      self
+    end
+
+    def new_record?
+      self.id.nil?
+    end
+
+    def persisted?
+      !new_record?
+    end
+
+    def subject_for(id)
+      self.class.subject_for(id)
+    end
+
+    private
+
+    def create_or_update
+      result = new_record? ? create : update
+      result != false
+    end
+
+    def guid
+      UUID.generate(:compact)
+    end
+
+  end
+end