tripod 0.2.3 → 0.3.0

data/.autotest

@@ -0,0 +1 @@
+require "autotest/bundler"

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -4,5 +4,6 @@ source 'https://rubygems.org'
 gemspec
 
 group :test do
-  gem "rspec", "~> 2.11"
+  gem "rspec", "~> 2.12"
+  gem "webmock"
 end

data/README.md

@@ -55,21 +55,10 @@ Note: Tripod doesn't supply a database. You need to install one. I recommend [Fu
         p.important_dates = [Date.new(2011,1,1)]
         p.save!
 
-        # Note: queries supplied to the where method should return the uris of the resource,
-        # and what graph they're in.
-        people = Person.where("
-          SELECT ?person ?graph
-          WHERE {
-            GRAPH ?graph {
-              ?person ?p ?o .
-              ?person a <http://person> .
-            }
-          }",
-        :uri_variable => 'person' ) # optionally, set a different name for the uri parameter (default: uri)
-        # => returns an array of Person objects, containing all data we know about them.
+        people = Person.all.resources #=> returns all people as an array
+
+        ric = Person.find('http://ric') #=> returns a single Person object.
 
-        ric = Person.find('http://ric')
-        # => returns a single Person object.
 
 ## Some Other interesting features
 
@@ -89,20 +78,42 @@ Note: Tripod doesn't supply a database. You need to install one. I recommend [Fu
 ## Defining a graph at instantiation-time
 
         class Resource
-          field :label RDF::RDFS.label
+          include Tripod::Resource
+          field :label, RDF::RDFS.label
 
           # notice also that you don't need to supply an rdf type or graph here!
         end
 
         r = Resource.new('http://foo', 'http://mygraph')
+        r.label = "example"
+        r.save
 
-        # if you don't supply a graph at any point, you will get an error when you try to persist the resource.
+        # Note: if you don't supply a graph at any point (i.e. class or instance level), you will get an error when you try to persist the resource.
 
 ## Reading and writing arbitrary predicates
 
         r.write_predicate(RDF.type, 'http://myresource/type')
         r.read_predicate(RDF.type) # => RDF::URI.new("http://myresource/type")
 
+## Finders and criteria
+
+        Person.all #=> returns a Tripod::Criteria which selets all resources of rdf_type http://person
+
+        Resource.all #=> returns all resources in the database (as no rdf_type specified at class level)
+
+        Person.all.resources #=> returns all the actual resources for the criteria, as an array
+
+        Person.first #=> returns the first person
+
+        Person.count  #=> returns the count of all people
+
+        # note that you need to use ?uri as the variable for the subject.
+        Person.where("?uri <http://name> 'Joe'") #=> returns a Tripod::Criteria
+
+## Chainable criteria
+
+        Person.all.where("?uri <http://name> 'Ric'").where("?uri <http://knows> <http://asa>).first
+
 
 
 [Full Documentation](http://rubydoc.info/gems/tripod/frames)

data/lib/tripod/criteria/execution.rb

@@ -0,0 +1,100 @@
+# This module defines behaviour for criteria
+module Tripod
+
+  # this module provides execution methods to a criteria object
+  module CriteriaExecution
+
+    extend ActiveSupport::Concern
+
+    # Execute the query and return an array of all hydrated resources
+    def resources
+      resources_from_sparql(build_select_query)
+    end
+
+    # Execute the query and return the first result as a hydrated resource
+    def first
+      sq = Tripod::SparqlQuery.new(build_select_query)
+      first_sparql = sq.as_first_query_str
+      resources_from_sparql(first_sparql).first
+    end
+
+    # Return how many records the current criteria would return
+    def count
+      sq = Tripod::SparqlQuery.new(build_select_query)
+      count_sparql = sq.as_count_query_str
+      result = Tripod::SparqlClient::Query.select(count_sparql)
+      result[0][".1"]["value"].to_i
+    end
+
+    # PRIVATE:
+
+    included do
+
+      private
+
+      def resources_from_sparql(sparql)
+        uris_and_graphs = select_uris_and_graphs(sparql)
+        create_and_hydrate_resources(uris_and_graphs)
+      end
+
+      def build_select_query
+        select_query = "SELECT ?uri ?graph WHERE { GRAPH ?graph { "
+        select_query += self.where_clauses.join(" . ")
+        # TODO: Deal with extras.
+        select_query += " } }"
+      end
+
+      # create and hydrate the resources identified in uris_and_graphs.
+      # Note: if any of the graphs are not set, those resources can still be constructed, but not persisted back to DB.
+      def create_and_hydrate_resources(uris_and_graphs)
+
+        graph = self.resource_class.describe_uris(uris_and_graphs.keys) #uses the resource_class on the criteria object
+        repo = self.resource_class.add_data_to_repository(graph)
+
+        resources = []
+
+        uris_and_graphs.each_pair do |u,g|
+
+          # instantiate a new resource
+          r = self.resource_class.new(u,g)
+
+          # make a graph of data for this resource's uri
+          data_graph = RDF::Graph.new
+          repo.query( [RDF::URI.new(u), :predicate, :object] ) do |statement|
+            data_graph << statement
+          end
+
+          # use it to hydrate this resource
+          r.hydrate!(:graph => data_graph)
+          r.new_record = false
+          resources << r
+        end
+
+        resources
+      end
+
+
+      # based on the query passed in, build a hash of uris->graphs
+      # @param [ String] sparql. The sparql query
+      # @param [ Hash ] opts. A hash of options.
+      #
+      # @option options [ String ] uri_variable The name of the uri variable in the query, if not 'uri'
+      # @option options [ String ] graph_variable The name of the uri variable in thh query, if not 'graph'
+      def select_uris_and_graphs(sparql, opts={})
+        select_results = Tripod::SparqlClient::Query.select(sparql)
+
+        uris_and_graphs = {}
+
+        select_results.each do |r|
+          uri_variable = opts[:uri_variable] || 'uri'
+          graph_variable = opts[:graph_variable] || 'graph'
+          uris_and_graphs[ r[uri_variable]["value"] ] = r[graph_variable]["value"]
+        end
+
+        uris_and_graphs
+      end
+
+    end
+
+  end
+end

data/lib/tripod/criteria.rb

@@ -0,0 +1,56 @@
+# encoding: utf-8
+require "tripod/criteria/execution"
+
+module Tripod
+
+  # This module defines behaviour for criteria
+  class Criteria
+
+   include Tripod::CriteriaExecution
+
+    # the resource class that this criteria is for.
+    attr_accessor :resource_class
+
+    # array of all the where clauses in this criteria
+    attr_accessor :where_clauses
+
+    # array of all the extra clauses in this criteria
+    attr_accessor :extra_clauses
+
+    def initialize(resource_class)
+      self.resource_class = resource_class
+      self.where_clauses = []
+      self.extra_clauses = []
+
+      if resource_class._RDF_TYPE
+        self.where("?uri a <#{resource_class._RDF_TYPE.to_s}>")
+      else
+        self.where("?uri ?p ?o")
+      end
+    end
+
+    # they're equal if they return the same query
+    def ==(other)
+      build_select_query == other.send(:build_select_query)
+    end
+
+    # Takes a string and adds a where clause to this criteria.
+    # Returns a criteria object.
+    # Note: the subject being returned by the query must be identified by ?uri
+    # e.g. my_criteria.where("?uri a <http://my-type>")
+    #
+    # TODO: make it also take a hash?
+    def where(sparql_snippet)
+      where_clauses << sparql_snippet
+      self
+    end
+
+    # takes a string and adds an extra clause to this criteria.
+    # TODO: make it also take a hash?
+    def extras(sparql_snippet)
+      extra_clauses << sparql_snippet
+      self
+    end
+
+  end
+end

data/lib/tripod/errors/bad_data_request.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+module Tripod::Errors
+
+  # field not present error.
+  class BadDataRequest < StandardError
+
+    attr_accessor :parent_bad_request
+
+    def initialize(message=nil, parent_bad_request_error=nil)
+      super(message)
+      parent_bad_request = parent_bad_request_error
+    end
+  end
+
+end

data/lib/tripod/errors/bad_sparql_request.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+module Tripod::Errors
+
+  # field not present error.
+  class BadSparqlRequest < StandardError
+
+    attr_accessor :parent_bad_request
+
+    def initialize(message=nil, parent_bad_request_error=nil)
+      super(message)
+      parent_bad_request = parent_bad_request_error
+    end
+  end
+
+end

data/lib/tripod/errors/rdf_parse_failed.rb

@@ -0,0 +1,7 @@
+# encoding: utf-8
+module Tripod::Errors
+
+  class RdfParseFailed < StandardError
+  end
+
+end

data/lib/tripod/errors/rdf_type_not_set.rb

@@ -0,0 +1,9 @@
+# encoding: utf-8
+module Tripod::Errors
+
+  # Action attempted on a resource which requires the rdf type to be set.
+  class RdfTypeNotSet < StandardError
+
+  end
+
+end

data/lib/tripod/errors.rb

@@ -3,4 +3,9 @@ require 'tripod/errors/field_not_present'
 require 'tripod/errors/resource_not_found'
 require 'tripod/errors/uri_not_set'
 require 'tripod/errors/graph_uri_not_set'
-require 'tripod/errors/validations'
+require 'tripod/errors/rdf_type_not_set'
+require 'tripod/errors/validations'
+require 'tripod/errors/rdf_parse_failed'
+
+require 'tripod/errors/bad_sparql_request'
+require 'tripod/errors/bad_data_request'

data/lib/tripod/finders.rb

@@ -48,23 +48,26 @@ module Tripod::Finders
       resource
     end
 
-    # Find a collection of +Resource+s by a SPARQL select statement which returns their uris.
-    # Under the hood, this only executes two queries: a select, then a describe.
-    #
-    # @example
-    #   Person.where('SELECT ?uri ?graph WHERE { GRAPH ?graph { ?uri ?p ?o } } LIMIT 3')
-    #
-    # @param [ String ] criteria. A sparql query which returns a list of uris of the objects.
-    # @param [ Hash ] opts. A hash of options.
-    #
-    # @option options [ String ] uri_variable The name of the uri variable in thh query, if not 'uri'
-    # @option options [ String ] graph_variable The name of the uri variable in thh query, if not 'graph'
-    # @option options [ String, RDF:URI, Array] only_hydrate a single predicate or list of predicates to hydrate the returned objects with. If ommited, does a full hydrate
-    #
-    # @return [ Array ] An array of hydrated resources of this class's type.
-    def where(criteria, opts={})
-      uris_and_graphs = select_uris_and_graphs(criteria, opts)
-      create_and_hydrate_resources(uris_and_graphs)
+    # execute a where clause on this resource.
+    # returns a criteria object
+    def where(sparql_snippet)
+      criteria = Tripod::Criteria.new(self)
+      criteria.where(sparql_snippet)
+    end
+
+    # execute a query to return all objects (restricted by this class's rdf_type if specified)
+    # returns a criteria object
+    def all
+      criteria = Tripod::Criteria.new(self)
+      criteria
+    end
+
+    def count
+      self.all.count
+    end
+
+    def first
+      self.all.first
     end
 
     # returns a graph of triples which describe the uris passed in.
@@ -75,7 +78,7 @@ module Tripod::Finders
         uris_sparql_str = uris.map{ |u| "<#{u.to_s}>" }.join(" ")
 
         # Do a big describe statement, and read the results into an in-memory repo
-        triples_string = Tripod::SparqlClient::Query::describe("DESCRIBE #{uris_sparql_str}")
+        triples_string = Tripod::SparqlClient::Query.describe("DESCRIBE #{uris_sparql_str}")
 
         RDF::Reader.for(:ntriples).new(triples_string) do |reader|
           reader.each_statement do |statement|
@@ -88,63 +91,5 @@ module Tripod::Finders
       graph
     end
 
-
-  end
-
-  # FOLLOWING METHODS NOT PART OF THE PUBLIC API:
-  def self.included(base)
-
-    class << base
-
-      private
-
-      # create and hydrate the resources identified in uris_and_graphs.
-      # Note: if any of the  graphs are not set, those resources can still be constructed, but not persisted back to DB.
-      def create_and_hydrate_resources(uris_and_graphs)
-
-        graph = describe_uris(uris_and_graphs.keys)
-        repo = add_data_to_repository(graph)
-
-        resources = []
-
-        uris_and_graphs.each_pair do |u,g|
-
-          # instantiate a new resource
-          r = self.new(u,g)
-
-          # make a graph of data for this resource's uri
-          data_graph = RDF::Graph.new
-          repo.query( [RDF::URI.new(u), :predicate, :object] ) do |statement|
-            data_graph << statement
-          end
-
-          # use it to hydrate this resource
-          r.hydrate!(:graph => data_graph)
-          r.new_record = false
-          resources << r
-        end
-
-        resources
-      end
-
-
-      # based on the query passed in, build a hash of uris->graphs
-      def select_uris_and_graphs(criteria, opts)
-        select_results = Tripod::SparqlClient::Query.select(criteria)
-
-        uris_and_graphs = {}
-
-        select_results.each do |r|
-          uri_variable = opts[:uri_variable] || 'uri'
-          graph_variable = opts[:graph_variable] || 'graph'
-          uris_and_graphs[ r[uri_variable]["value"] ] = r[graph_variable]["value"]
-        end
-
-        uris_and_graphs
-      end
-
-
-    end
-
   end
 end

data/lib/tripod/persistence.rb

@@ -32,7 +32,7 @@ module Tripod::Persistence
       transaction && transaction.class == Tripod::Persistence::Transaction
     end
 
-    def self.get_transcation(trans)
+    def self.get_transaction(trans)
       transaction = nil
 
       if Tripod::Persistence::Transaction.valid_transaction(trans)
@@ -70,7 +70,7 @@ module Tripod::Persistence
 
     raise Tripod::Errors::GraphUriNotSet.new() unless @graph_uri
 
-    transaction = Tripod::Persistence::Transaction.get_transcation(opts[:transaction])
+    transaction = Tripod::Persistence::Transaction.get_transaction(opts[:transaction])
 
     if self.valid?
 
@@ -114,7 +114,7 @@ module Tripod::Persistence
       # if we get in here, save failed.
 
       # abort the transaction
-      transaction = Tripod::Persistence::Transaction.get_transcation(opts[:transaction])
+      transaction = Tripod::Persistence::Transaction.get_transaction(opts[:transaction])
       transaction.abort() if transaction
 
       self.class.fail_validate!(self) # throw an exception
@@ -126,7 +126,7 @@ module Tripod::Persistence
 
   def destroy(opts={})
 
-    transaction = Tripod::Persistence::Transaction.get_transcation(opts[:transaction])
+    transaction = Tripod::Persistence::Transaction.get_transaction(opts[:transaction])
 
     query = "
       # delete from default graph:

data/lib/tripod/resource.rb

@@ -92,9 +92,11 @@ module Tripod::Resource
       other.class == Class ? self <= other : other.is_a?(self)
     end
 
+    # makes a "field" on this model called rdf_type
+    # and sets a class level _RDF_TYPE variable with the rdf_type passed in.
     def rdf_type(new_rdf_type)
       field :rdf_type, RDF.type
-      self._RDF_TYPE = new_rdf_type
+      self._RDF_TYPE = RDF::URI.new(new_rdf_type.to_s)
     end
 
     def graph_uri(new_graph_uri)

data/lib/tripod/sparql_client.rb

@@ -23,13 +23,8 @@ module Tripod::SparqlClient
           :timeout => Tripod.timeout_seconds,
         )
       rescue RestClient::BadRequest => e
-        body = e.http_body
-        if body.start_with?('Error 400: Parse error:')
-          # TODO: this is a SPARQL parsing exception. Do something different.
-          raise e
-        else
-          raise e
-        end
+        # just re-raise as a BadSparqlRequest Exception
+        raise Tripod::Errors::BadSparqlRequest.new(e.http_body, e)
       end
     end
 
@@ -67,6 +62,21 @@ module Tripod::SparqlClient
       return response.body
     end
 
+    # Executes an ASK +query+ against the SPARQL endpoint.
+    # Executes the +query+ and returns text by default
+    #
+    # @example Run a ASK query
+    #   Tripod::SparqlClient::Query.select('ASK <http://foo>')
+    #
+    # @param [ String ] query The query to run
+    # @param [ String ] accept_header The format parameter to send to the database. Valud valid formats are text, xml, json
+    # 
+    # @return [ String ] the raw response from the endpoint
+    def self.ask(query, format='text')
+      response = self.query(query, format)
+      return response.body
+    end
+
     # Executes a CONSTRUCT +query+ against the SPARQL endpoint.
     # Executes the +query+ and returns ntriples by default
     #
@@ -102,15 +112,37 @@ module Tripod::SparqlClient
         )
         true
       rescue RestClient::BadRequest => e
-        body = e.http_body
-        if body.start_with?('Error 400: Parse error:')
-          # TODO: this is a SPARQL parsing exception. Do something different.
-          raise e
-        else
-          raise e
+        # just re-raise as a BadSparqlRequest Exception
+        raise Tripod::Errors::BadSparqlRequest.new(e.http_body, e)
+      end
+    end
+
+  end
+
+  module Data
+    class DataClient
+      def self.submit(graph_uri, data, method)
+        url = "#{Tripod.data_endpoint}?graph=#{graph_uri}"
+        begin
+          RestClient::Request.execute(
+            :method => method,
+            :url => url,
+            :timeout => Tripod.timeout_seconds,
+            :payload => data
+          )
+          true
+        rescue RestClient::BadRequest => e
+          raise Tripod::Errors::BadDataRequest.new(e.http_body, e)
         end
       end
     end
 
+    def self.append(graph_uri, data)
+      DataClient.submit(graph_uri, data, :post)
+    end
+
+    def self.replace(graph_uri, data)
+      DataClient.submit(graph_uri, data, :put)
+    end
   end
 end

data/lib/tripod/sparql_query.rb

@@ -0,0 +1,86 @@
+# encoding: utf-8
+module Tripod
+
+  class SparqlQueryError < StandardError; end
+
+  class SparqlQuery
+
+    attr_reader :query # the original query string
+    attr_reader :query_type # symbol representing the type (:select, :ask etc)
+    attr_reader :body # the body of the query
+    attr_reader :prefixes # any prefixes the query may have
+
+    cattr_accessor :PREFIX_KEYWORDS
+    @@PREFIX_KEYWORDS = %w(BASE PREFIX)
+    cattr_accessor :KEYWORDS
+    @@KEYWORDS = %w(CONSTRUCT ASK DESCRIBE SELECT)
+
+    def initialize(query_string, parent_query=nil)
+      @query = query_string
+      @parent_query = parent_query
+
+      if self.has_prefixes?
+        @prefixes, @body = self.extract_prefixes
+      else
+        @body = self.query
+      end
+
+      @query_type = get_query_type
+    end
+
+    def has_prefixes?
+      self.class.PREFIX_KEYWORDS.each do |k|
+        return true if /^#{k}/i.match(query)
+      end
+      return false
+    end
+
+    def extract_prefixes
+      i = self.class.KEYWORDS.map {|k| self.query.index(/#{k}/i) || self.query.size+1 }.min
+      p = query[0..i-1]
+      b = query[i..-1]
+      return p.strip, b.strip
+    end
+
+    def as_count_query_str
+      # only allow for selects
+      raise SparqlQueryError.new("Can't turn this into a subquery") unless self.query_type == :select
+
+      count_query = "SELECT COUNT(*) { #{self.body} }"
+      count_query = "#{self.prefixes} #{count_query}" if self.prefixes
+
+      # just returns the string representing the count query for this query.
+      count_query
+    end
+
+    def as_first_query_str
+      # only allow for selects
+      raise SparqlQueryError.new("Can't turn this into a subquery") unless self.query_type == :select
+
+      first_query = "SELECT * { #{self.body} } LIMIT 1"
+      first_query = "#{self.prefixes} #{first_query}" if self.prefixes
+
+      # just returns the string representing the 'first' query for this query.
+      first_query
+    end
+
+    private
+
+    def get_query_type
+      if /^CONSTRUCT/i.match(self.body)
+        :construct
+      elsif /^ASK/i.match(self.body)
+        :ask
+      elsif /^DESCRIBE/i.match(self.body)
+        :describe
+      elsif /^SELECT/i.match(self.body)
+        :select
+      else
+        :unknown
+      end
+    end
+
+
+  end
+
+end

data/lib/tripod/version.rb

@@ -1,3 +1,3 @@
 module Tripod
-  VERSION = "0.2.3"
+  VERSION = "0.3.0"
 end

data/lib/tripod.rb

@@ -45,6 +45,9 @@ module Tripod
   mattr_accessor :query_endpoint
   @@query_endpoint = 'http://127.0.0.1:3030/tripod/sparql'
 
+  mattr_accessor :data_endpoint
+  @@data_endpoint = 'http://127.0.0.1:3030/tripod/data'
+
   mattr_accessor :timeout_seconds
   @@timeout_seconds = 30
 
@@ -64,12 +67,14 @@ end
 
 require "tripod/extensions"
 require "tripod/sparql_client"
+require "tripod/sparql_query"
 
 require "tripod/predicates"
 require "tripod/attributes"
 require "tripod/errors"
 require "tripod/repository"
 require "tripod/fields"
+require "tripod/criteria"
 require "tripod/finders"
 require "tripod/persistence"
 require "tripod/eager_loading"