rdf-blazegraph 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8e2e77f00c85d5d33fa1138638238040525b0311
+  data.tar.gz: d3cc73a2b6bd389a3206999ff1a8105d8764f065
+SHA512:
+  metadata.gz: 34f1525cf7ded366446347c4b6721649943f6674d2e0f8bd03b494386cd8876c7671e891a664db3b6a3e282aebbf88eb851bc20a9d4a953aeee817fce236f014
+  data.tar.gz: 612f391cff097c9631f03f08b14d4350690a3c7db1bc10703043e3d72f8975d888eb4d5c60bca8df26e7362d15bde483846c19d908be48906e072d51f6a8f102

data/AUTHORS

@@ -0,0 +1,2 @@
+* Tom Johnson <tom@dp.la>
+

data/README.md

@@ -0,0 +1,33 @@
+RDF::Blazegraph
+================
+
+## Running the Tests
+
+```bash
+$ bundle install
+$ bundle exec rspec
+```
+
+## Contributing
+
+This repository uses [Git Flow](https://github.com/nvie/gitflow) to mange development and release activity. All submissions _must_ be on a feature branch based on the _develop_ branch to ease staging and integration.
+
+* Do your best to adhere to the existing coding conventions and idioms.
+* Don't use hard tabs, and don't leave trailing whitespace on any line.
+  Before committing, run `git diff --check` to make sure of this.
+* Do document every method you add using YARD annotations. Read the
+  [tutorial][YARD-GS] or look at the existing code for examples.
+* Don't touch the `.gemspec` or `VERSION` files. If you need to change them,
+  do so on your private branch only.
+* Do feel free to add yourself to the `CREDITS` file and the
+  corresponding list in the the `README`. Alphabetical order applies.
+* Don't touch the `AUTHORS` file. If your contributions are significant
+  enough, be assured we will eventually add you in there.
+* Do note that in order for us to merge any non-trivial changes (as a rule
+  of thumb, additions larger than about 15 lines of code), we need an
+  explicit [public domain dedication][PDD] on record from you.
+
+## License
+
+This is free and unencumbered public domain software. For more information,
+see <http://unlicense.org/> or the accompanying {file:UNLICENSE} file.

data/UNLICENSE

@@ -0,0 +1,24 @@
+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, please refer to <http://unlicense.org/>

data/VERSION

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

data/lib/rdf/blazegraph.rb

@@ -0,0 +1,19 @@
+require 'rdf'
+require 'sparql/client'
+require 'rexml/document'
+require 'net/http/persistent'
+
+module RDF
+  ##
+  # This module bundles tools for working with Blazegraph using RDF.rb.
+  #
+  # @see http://ruby-rdf.github.io
+  # @see http://wiki.blazegraph.com
+  module Blazegraph
+    VOCAB_BD = RDF::Vocabulary.new('http://www.bigdata.com/rdf#')
+    NULL_GRAPH_URI = Blazegraph::VOCAB_BD.nullGraph
+    
+    autoload :Repository, 'rdf/blazegraph/repository'
+    autoload :RestClient, 'rdf/blazegraph/rest_client'
+  end
+end

data/lib/rdf/blazegraph/repository.rb

@@ -0,0 +1,147 @@
+module RDF::Blazegraph
+  ##
+  # An RDF::Repository implementaton for Blazegraph (formerly BigData).
+  #
+  # @see RDF::Repository
+  class Repository < SPARQL::Client::Repository
+    ##
+    # @return [RDF::Blazegraph::RestClient]
+    def rest_client
+      @rest_client = RestClient.new(@client.url)
+    end
+
+    ##
+    # @see RDF::Enumerable#count
+    def count
+      rest_client.fast_range_count
+    end
+
+    ##
+    # @see RDF::Repository#each
+    def each(&block)
+      rest_client.get_statements.each_statement(&block)
+    end
+
+    ##
+    # @see RDF::Repository#empty?
+    def empty?
+      !rest_client.has_statement?
+    end
+
+    ##
+    # @see RDF::Repository#has_predicate?
+    def has_context?(context)
+      rest_client.has_statement?(context: context)
+    end
+
+    ##
+    # @see RDF::Repository#has_predicate?
+    def has_predicate?(predicate)
+      rest_client.has_statement?(predicate: predicate)
+    end
+
+    ##
+    # @see RDF::Repository#has_object?
+    def has_object?(object)
+      return super if object.node?
+      rest_client.has_statement?(object: object)
+    end
+
+    ##
+    # @see RDF::Repository#has_triple?
+    def has_triple?(triple)
+      return super unless triple.find(&:node?).nil?
+      rest_client.has_statement?(subject:   triple[0],
+                                 predicate: triple[1],
+                                 object:    triple[2])
+    end
+
+    ##
+    # Calls the Blazegraph API unless a blank node is present, in which case we 
+    # fall back on SPARQL ASK.
+    # @see RDF::Repostiory#has_statement?
+    def has_statement?(statement)
+      has_quad?(statement)
+    end
+
+    ##
+    # @see RDF::Repository#has_subject?
+    def has_subject?(subject)
+      return super if subject.node?
+      rest_client.has_statement?(subject: subject)
+    end
+
+    ##
+    # @see RDF::Repository#has_subject?
+    def has_quad?(statement)
+      statement = RDF::Statement.from(statement)
+      rest_client.has_statement?(subject:   statement.subject,
+                                 predicate: statement.predicate,
+                                 object:    statement.object,
+                                 context:   statement.context)
+    end
+
+    ##
+    # @see SPARQL::Client::Repository#supports?
+    def supports?(feature)
+      return true if feature.to_sym == :context
+      super
+    end
+
+    protected
+
+    ##
+    # Deletes the given RDF statements from the underlying storage.
+    #
+    # Overridden here to use SPARQL/UPDATE
+    #
+    # @param  [RDF::Enumerable] statements
+    # @return [void]
+    def delete_statements(statements)
+      @rest_client.delete(statements)
+    end
+
+    ##
+    # Queries `self` for RDF statements matching the given `pattern`.
+    #
+    # @see SPARQL::Client::Repository#query_pattern
+    def query_pattern(pattern, &block)
+      pattern = pattern.dup
+      pattern.subject   ||= RDF::Query::Variable.new
+      pattern.predicate ||= RDF::Query::Variable.new
+      pattern.object    ||= RDF::Query::Variable.new
+      pattern.initialize!
+
+      # Blazegraph objects to bnodes shared across the CONSTRUCT & WHERE scopes
+      # so we dup the pattern with fresh bnodes
+      where_pattern = pattern.dup
+      where_pattern.subject = RDF::Node.new if where_pattern.subject.node?
+      where_pattern.predicate = RDF::Node.new if where_pattern.predicate.node?
+      where_pattern.object = RDF::Node.new if where_pattern.object.node?
+      where_pattern.initialize!
+
+      query = client.construct(pattern).where(where_pattern)
+      
+      unless where_pattern.context.nil?
+        where_pattern.context ||= NULL_GRAPH_URI
+        query.graph(where_pattern.context)
+        query.filter("#{where_pattern.context} != #{NULL_GRAPH_URI.to_base}") if
+          where_pattern.context.variable?
+      end
+
+      if block_given?
+        query.each_statement(&block)
+      else
+        query.solutions.to_a.extend(RDF::Enumerable, RDF::Queryable)
+      end
+    end
+
+    def insert_statements(statements)
+      rest_client.insert(statements)
+    end
+
+    def insert_statement(statement)
+      rest_client.insert([statement])
+    end
+  end
+end

data/lib/rdf/blazegraph/rest_client.rb

@@ -0,0 +1,219 @@
+module RDF::Blazegraph
+  ##
+  # A wrapper for the NanoSparqlServer REST API. This implements portions of 
+  # the API that are not parts of SPARQL; such as optimized queries like 
+  # FastRangeCount.
+  #
+  # @see https://wiki.blazegraph.com/wiki/index.php/REST_API NanoSparqlServer 
+  #   REST documentation
+  class RestClient
+    attr_reader :url
+
+    ##
+    # @param [#to_s] uri  a uri identifying the Blazegraph API endpoint; e.g.
+    #   `http://localhost:9999/bigdata/sparql`
+    def initialize(url)
+      @http = Net::HTTP::Persistent.new(self.class)
+      @url = URI(url.to_s)
+      @sparql_client = SPARQL::Client.new(@url)
+    end
+
+    ##
+    # Send a request to the server
+    #
+    # @param [String] query
+    #
+    # @return [Net::HTTP::Response] the server's response
+    # @raise [RequestError] if the request returns a non-success response code
+    def execute(query)
+      response = @http.request(url + ::URI::encode(query))
+
+      return response if response.is_a? Net::HTTPSuccess
+      raise RequestError.new("#{response.code}: #{response.body}\n" \
+                             "Processing query #{query}") 
+    end
+
+    ##
+    # Returns a count of the number of triples in the datastore.
+    #
+    # We use the `exact` option, to ensure that counts are exact regardless
+    # of sharding and other configuration conditions.
+    #
+    # Errors are thrown if a bnode is given for any of the terms or if a 
+    # literal is given in the subject or predicate place.
+    #
+    # @param [Boolean] exact  whether to insist on an exact range count, or 
+    #   allow approximations e.g. across multiple shards; default: `true`
+    #
+    # @return [Integer] the count of triples matching the query
+    #
+    # @raise [RequestError] if the request is invalid or the server throws an 
+    #   error
+    def fast_range_count(subject: nil, predicate: nil, object: nil, 
+                         context: nil, exact: true)
+      st_query = access_path_query(subject, predicate, object, context)
+      resp = execute("?ESTCARD#{st_query}&exact=#{exact}")
+      read_xml_response(resp, :rangeCount).to_i
+    end
+
+    ##
+    # Returns statements matching the given pattern.
+    # 
+    # Errors are thrown if a bnode is given for any of the terms or if a 
+    # literal is given in the subject or predicate place.
+    # 
+    # @param [Boolean] include_inferred  includes inferred triples if `true', 
+    #   default: `false`
+    # 
+    # @return [RDF::Enumerable] statements parsed from the server response
+    #
+    # @raise [RequestError] if the request is invalid or the server throws an 
+    #   error
+    def get_statements(subject: nil, predicate: nil, object: nil, 
+                       context: nil, include_inferred: false)
+      st_query = access_path_query(subject, predicate, object, context)
+      query = "?GETSTMTS#{st_query}&include_inferred=#{include_inferred}"
+      read_rdf_response(execute(query))
+    end
+
+    ##
+    # Checks for existence of a statement matching the pattern.
+    #
+    # Errors are thrown if a bnode is given for any of the terms or if a 
+    # literal is given in the subject or predicate place.
+    #
+    # @param [Boolean] include_inferred  includes inferred triples if `true', 
+    #   default: `false`
+    # 
+    # @return [Boolean] true if statement matching the pattern exists
+    #
+    # @raise [RequestError] if the request is invalid or the server throws an 
+    #   error
+    def has_statement?(subject: nil, predicate: nil, object: nil, 
+                       context: nil, include_inferred: false)
+      if [subject, predicate, object].compact.find(&:node?)
+        sparql_ask_statement([subject, predicate, object], context)
+      else
+        st_query = access_path_query(subject, predicate, object, context)
+        query = "?HASSTMT#{st_query}&include_inferred=#{include_inferred}"
+
+        read_boolean_response(execute(query))
+      end
+    end
+
+    ##
+    # @param [RDF::Enumerable] statements
+    #
+    # @todo handle blank nodes
+    def insert(statements)
+      send_post_request(url, statements)
+      return self
+    end
+
+    ##
+    # @param [RDF::Enumerable] statements
+    #
+    # @todo handle blank nodes
+    def delete(statements)
+      return self if statements.empty?
+
+      statements.map! do |s| 
+        statement = RDF::Statement.from(s)
+        statement.context ||= NULL_GRAPH_URI 
+        statement
+      end
+
+      constant = statements.all? do |statement|
+        !statement.respond_to?(:each_statement) && statement.constant? && 
+          !statement.has_blank_nodes?
+      end
+
+      if constant
+        send_post_request(url + '?delete', statements)
+      else
+        # delete with blank nodes
+      end
+
+      return self
+    end
+
+    private
+
+    def sparql_ask_statement(triple, context)
+      triple.map! do |term|
+        unless term.nil?
+          term.node? ? RDF::Query::Variable.new(term.id) : term
+        end
+      end
+
+      query = @sparql_client.ask.where(triple)
+      query.graph(context) if context
+      triple.each do |term| 
+        query.filter("isBlank(#{term})") if !term.nil? && term.variable?
+      end
+
+      query.true?
+    end
+    
+    def send_post_request(request_url, statements)
+      io = StringIO.new
+      writer = RDF::Writer.for(:nquads)
+      
+      io.rewind
+
+      request = Net::HTTP::Post.new(request_url)
+      request['Content-Type'] = 
+        RDF::Writer.for(:nquads).format.content_type.last # use text/x-nquads
+      request.body = writer.dump(statements)
+      
+      @http.request(url, request)
+    end
+    
+    ## 
+    # @param [Net::HTTPResponse] response
+    # @return [RDF::Enumerable]
+    def read_rdf_response(response)
+      RDF::Reader.for(content_type: response.content_type).new(response.body)
+    end
+
+    ## 
+    # @param [Net::HTTPResponse] response
+    # @return [RDF::Enumerable]
+    def read_boolean_response(response)
+      read_xml_response(response, :result) == 'true' ? true : false
+    end
+
+    ## 
+    # @param [Net::HTTPResponse] response
+    # @param [Net::HTTPResponse] attr
+    # @return [RDF::Enumerable]
+    def read_xml_response(response, attr)
+      REXML::Document.new(response.body).root.attribute(attr).value
+    end
+
+    ##
+    # @param [RDF::URI, RDF::Literal] subject
+    # @param [RDF::URI, RDF::Literal] predicate
+    # @param [RDF::URI, RDF::Literal] object
+    # @param [RDF::URI, RDF::Literal] context
+    #
+    # @return [String] a query string for "Access Path Operations"
+    #
+    # @todo: fail fast when given a literal predicate or a bnode? Currently we
+    #   try the request on Blazegraph and handle the Net::HTTP response.
+    #
+    # @see https://wiki.blazegraph.com/wiki/index.php/REST_API#Access_Path_Operations
+    def access_path_query(subject, predicate, object, context)
+      str = {s: subject, p: predicate, o: object, c: context}.map do |k, v|
+        v ? "#{k}=#{v.to_base}" : nil
+      end.compact.join('&')
+      str.empty? ? str : "&#{str}" 
+    end
+
+    public
+
+    ##
+    # An error class to capture non-succesful RestClient responses
+    class RequestError < RuntimeError; end
+  end
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: rdf-blazegraph
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Tom Johnson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-08-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rdf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: sparql-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rdf-spec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.13
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.13
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: A Blazegraph Repository adapter for RDF.rb
+email: public-rdf-ruby@w3.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AUTHORS
+- README.md
+- UNLICENSE
+- VERSION
+- lib/rdf/blazegraph.rb
+- lib/rdf/blazegraph/repository.rb
+- lib/rdf/blazegraph/rest_client.rb
+homepage: http://ruby-rdf.github.com/
+licenses:
+- Public Domain
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+- app
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.1
+signing_key: 
+specification_version: 4
+summary: A Blazegraph Repository adapter for RDF.rb
+test_files: []
+has_rdoc: false