agraph 0.1.0.beta1

data/README.rdoc

@@ -0,0 +1,137 @@
+
+= Ruby client for the AllegroGraph RDF graph database
+
+The agraph gem provides a client for the RESTful interface of AllegroGraph RDF graph database version 4.x. This
+document should give you overview, how the client can be used. To get familiar with the database server, this
+documentation[http://franz.com/agraph/support/documentation/current/agraph-introduction.html] is strongly recommended.
+
+The features that are exposed by this client are...
+* simple repository management
+* add / remove statements (aka triples) to / from the store
+* searching for statements by subject, predicate or object (or any combination of them)
+* searching for statements by geo-spatial queries
+* transactions
+* performing SparQL and Prolog queries
+* mapping of data type
+
+== Repository management
+
+A repository can be created by simply typing the following.
+
+  require 'allegro_graph'
+
+  server = AllegroGraph::Server.new :username => "user", :password => "pass"
+  repository = AllegroGraph::Repository.new server, "test_repository"
+  repository.create_if_missing!
+
+The code will try to connect to a AllegroGraph server running at <tt>localhost:10035</tt> with the credentials
+<tt>user</tt> and <tt>pass</tt>, and creates a repository named <tt>test_repository</tt> if it's not already existing.
+
+== Adding and Removing triples
+
+Once a repository is created, statements can be added.
+
+  repository.statements.create "<a_subject>", "<a_predicate>", "<an_object>", "<context>"
+
+The last argument is optional and defines a context for the given triple. This context can be used to define named
+graphs inside the repository.
+
+To delete statements, matching options can be passed to the delete method.
+
+  repository.statements.delete :predicate => "<a_predicate>"
+
+This will delete all statements with the predicate <tt><a_predicate></tt>.
+
+== Searching for statements
+
+The <tt>find</tt> method provides an easy way to find specified statements.
+
+  repository.statements.find :subject => "<a_subject>"
+
+The result will be an array that holds arrays of all matching statements.
+
+  [
+    [ "<a_subject>", "<a_predicate>", "<a_object>" ],
+    [ "<a_subject>", "<another_predicate>", "<another_object>" ]
+  ]
+
+== Searching for statements by geo-spatial queries
+
+=== Adding coordinates to the database
+
+Before coordinates can be added, a fitting type has to be requested from the database. Coordinates can have the
+cartesian (x and y) or spherical (latitude and longitude) type. When creating the type, also a range has to be defined.
+
+  cartesian_type = repository.geo.cartesian_type 1, 0, 0, 100, 100
+
+The first argument specifies the strip width and the last four the top-left and bottom-right corner of the rectangle
+that represent the boundaries for any coordinate.
+
+Afterwards, the return type can be used add geometric nodes (subjects or objects) to the database.
+
+  repository.statements.create "<a_subject>", "<a_predicate>", "\"+20+20\"^^#{cartesian_type}"
+
+=== Finding statements by geo-spatial queries
+
+To find statements by thier assigned coordinates, the following methods are provided.
+
+  repository.geo.inside_box
+  repository.geo.inside_circle
+  repository.geo.inside_haversine
+  repository.geo.inside_polygon
+
+The previously create statement will be returned by
+
+  repository.geo.inside_box cartesian_type, "<a_predicate>", 10, 10, 30, 30
+
+== Transactions
+
+agraph also allows you to perform transaction. All operations performed within a transaction will committed at once. If
+an error occurs during the transaction, all operations will be rolled back.
+
+  repository.transaction do
+    statements.create "<a_subject>", "<a_predicate>", "<an_object>"
+    statements.create "<a_subject>", "<a_predicate>", "<another_object>"
+    # ... if an error is raised here, no operation will be committed
+  end
+  # ... if no error has occured, all operations will be committed
+
+== SparQL and Prolog queries
+
+The perform a SparQL or Prolog query, simply set the language that the query is written in and pass the query string to
+the following method.
+
+  repository.query.language = :sparql
+  repository.query.perform "SELECT ?s WHERE { ?s ?p ?o . }"
+
+At the moment only <tt>:sparql</tt> and <tt>:prolog</tt> queries are supported.
+
+The result will look like this.
+
+  { "names" => [ "s" ], "values" => [ [ "<a_subject>" ], [ "<another_subject>" ] ] }
+
+== Mapping of data types
+
+To add and remove mapping between types and it's encodings, the following methods can be used.
+
+  repository.mapping.create "<time>", "<http://www.w3.org/2001/XMLSchema#dateTime>"
+  repository.mapping.delete "<time>"
+
+With such a type defined, it's possible to perform range queries like
+
+  repository.statements.create "<event_one>", "<occurs>", "\"2010-03-29T11:40:00\"^^<time>"
+  repository.statements.create "<event_two>", "<occurs>", "\"2010-03-29T17:40:00\"^^<time>"
+
+  repository.statements.find :predicate => "<occurs>", :object => [ "\"2010-03-29T11:00:00\"^^<time>", "\"2010-03-29T12:00:00\"^^<time>" ]
+
+Only the second event would be returned.
+
+== More Examples
+
+More examples can be found in the integration specs (spec/integration)
+
+== Contribution
+
+Any contribution - especially bug reports - is welcome.
+
+Fork or send mail to b.phifty@gmail.com

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rubygems'
+gem 'rspec'
+require 'spec'
+require "rake/rdoctask"
+require 'rake/gempackagetask'
+require 'spec/rake/spectask'
+
+task :default => :spec
+
+specification = Gem::Specification.new do |specification|
+  specification.name              = "agraph"
+  specification.version           = "0.1.0.beta1"
+  specification.date              = "2010-03-29"
+  specification.email             = "b.phifty@gmail.com"
+  specification.homepage          = "http://github.com/phifty/agraph"
+  specification.summary           = "Client for the AllegroGraph 4.x graph database."
+  specification.description       = "The gem provides a client for the AllegroGraph 4.x RDF graph database. Features like searching geo-spatial data, type mapping and transactions are supported."
+  specification.has_rdoc          = true
+  specification.authors           = [ "Philipp Bruell" ]
+  specification.files             = [ "README.rdoc", "Rakefile" ] + Dir["{lib,spec}/**/*"]
+  specification.extra_rdoc_files  = [ "README.rdoc" ]
+  specification.require_path      = "lib"
+end
+
+Rake::GemPackageTask.new(specification) do |package|
+  package.gem_spec = specification
+end
+
+desc "Generate the rdoc"
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_files.add [ "README.rdoc", "lib/**/*.rb" ]
+  rdoc.main   = "README.rdoc"
+  rdoc.title  = "Client for the AllegroGraph 4.x graph database."
+end
+
+desc "Run all specs in spec directory"
+Spec::Rake::SpecTask.new do |task|
+  task.spec_files = FileList["spec/lib/**/*_spec.rb"]
+end
+
+namespace :spec do
+
+  desc "Run all integration specs in spec/integration directory"
+  Spec::Rake::SpecTask.new(:integration) do |task|
+    task.spec_files = FileList["spec/integration/**/*_spec.rb"]
+  end
+
+end

data/lib/allegro_graph.rb

@@ -0,0 +1,5 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "allegro_graph", "server"))
+require File.expand_path(File.join(File.dirname(__FILE__), "allegro_graph", "catalog"))
+require File.expand_path(File.join(File.dirname(__FILE__), "allegro_graph", "repository"))
+require File.expand_path(File.join(File.dirname(__FILE__), "allegro_graph", "session"))
+require File.expand_path(File.join(File.dirname(__FILE__), "allegro_graph", "federation"))

data/lib/allegro_graph/catalog.rb

@@ -0,0 +1,39 @@
+require File.join(File.dirname(__FILE__), "repository")
+
+module AllegroGraph
+
+  class Catalog
+
+    attr_reader   :server
+    attr_accessor :name
+
+    def initialize(server, name, options = { })
+      @server = server
+      @name = name
+      @root = options[:root] || false
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && self.server == other.server && self.root? == other.root? && self.name == other.name
+    end
+
+    def path
+      self.root? ? "" : "/catalogs/#{@name}"
+    end
+
+    def root?
+      !!@root
+    end
+
+    def exists?
+      @server.catalogs.include? self
+    end
+
+    def repositories
+      repositories = @server.request :get, self.path + "/repositories", :expected_status_code => 200
+      repositories.map { |repository| Repository.new self, repository["id"] }
+    end
+
+  end
+
+end

data/lib/allegro_graph/federation.rb

@@ -0,0 +1,72 @@
+require File.join(File.dirname(__FILE__), "transport")
+require File.join(File.dirname(__FILE__), "proxy", "statements")
+require File.join(File.dirname(__FILE__), "proxy", "query")
+require File.join(File.dirname(__FILE__), "proxy", "geo")
+require File.join(File.dirname(__FILE__), "proxy", "mapping")
+
+module AllegroGraph
+
+  class Federation
+
+    attr_reader   :server
+    attr_accessor :name
+    attr_accessor :repository_names
+    attr_accessor :repository_urls
+
+    attr_reader :statements
+    attr_reader :query
+    attr_reader :geo
+    attr_reader :mapping
+
+    def initialize(server, name, options = { })
+      @server, @name = server, name
+
+      @repository_names = options[:repository_names]
+      @repository_urls  = options[:repository_urls]
+
+      @statements = Proxy::Statements.new self
+      @query      = Proxy::Query.new self
+      @geo        = Proxy::Geo.new self
+      @mapping    = Proxy::Mapping.new self
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && @server == other.server && @name == other.name
+    end
+
+    def path
+      "/federated/#{@name}"
+    end
+
+    def request(http_method, path, options = { })
+      @server.request http_method, path, options
+    end
+
+    def exists?
+      @server.federations.include? self
+    end
+
+    def create!
+      parameters = { }
+      parameters.merge! :repo => @repository_names if @repository_names
+      parameters.merge! :url  => @repository_urls  if @repository_urls
+      @server.request :put, self.path, :parameters => parameters, :expected_status_code => 204
+      true
+    end
+
+    def create_if_missing!
+      create! unless exists?
+    end
+
+    def delete!
+      @server.request :delete, self.path, :expected_status_code => 204
+      true
+    end
+
+    def delete_if_exists!
+      delete! if exists?
+    end
+
+  end
+
+end

data/lib/allegro_graph/proxy/geo.rb

@@ -0,0 +1,117 @@
+
+module AllegroGraph
+
+  module Proxy
+
+    class Geo
+
+      attr_reader :resource
+
+      def initialize(resource)
+        @resource = resource
+      end
+
+      def path
+        "#{@resource.path}/geo"
+      end
+
+      def cartesian_type(strip_width, x_min, y_min, x_max, y_max)
+        parameters = {
+          :stripWidth => strip_width.to_s,
+          :xmin       => x_min.to_s,
+          :ymin       => y_min.to_s,
+          :xmax       => x_max.to_s,
+          :ymax       => y_max.to_s
+        }
+        type = @resource.request :post, self.path + "/types/cartesian", :parameters => parameters, :expected_status_code => 200
+        type.sub! /^.*</, "<"
+        type.sub! />.*$/, ">"
+        type
+      end
+
+      def spherical_type(strip_width, unit, latitude_min, longitude_min, latitude_max, longitude_max)
+        parameters = {
+          :stripWidth => strip_width.to_s,
+          :unit       => unit.to_s,
+          :latmin     => latitude_min.to_s,
+          :longmin    => longitude_min.to_s,
+          :latmax     => latitude_max.to_s,
+          :longmax    => longitude_max.to_s
+        }
+        type = @resource.request :post, self.path + "/types/spherical", :parameters => parameters, :expected_status_code => 200
+        type.sub! /^.*</, "<"
+        type.sub! />.*$/, ">"
+        type
+      end
+
+      def create_polygon(name, type, points)
+        raise ArgumentError, "at least three points has to defined" unless points.is_a?(Array) && points.size >= 3
+        parameters = {
+          :resource => "\"#{name}\"",
+          :point    => points.map{ |point| "\"%+g%+g\"^^%s" % [ point[0], point[1], type ] }
+        }
+        @resource.request :put, self.path + "/polygon", :parameters => parameters, :expected_status_code => 204
+        true
+      end
+
+      def inside_box(type, predicate, x_min, y_min, x_max, y_max)
+        parameters = {
+          :type       => type,
+          :predicate  => predicate,
+          :xmin       => x_min.to_s,
+          :ymin       => y_min.to_s,
+          :xmax       => x_max.to_s,
+          :ymax       => y_max.to_s
+        }
+        @resource.request :get, self.path + "/box", :parameters => parameters, :expected_status_code => 200
+      end
+
+      def inside_circle(type, predicate, x, y, radius)
+        parameters = {
+          :type       => type,
+          :predicate  => predicate,
+          :x          => x.to_s,
+          :y          => y.to_s,
+          :radius     => radius.to_s
+        }
+        @resource.request :get, self.path + "/circle", :parameters => parameters, :expected_status_code => 200
+      end
+
+      def inside_haversine(type, predicate, latitude, longitude, radius, unit = :km)
+        parameters = {
+          :type       => type,
+          :predicate  => predicate,
+          :lat        => float_to_iso_6709(latitude, 2),
+          :long       => float_to_iso_6709(longitude, 3),
+          :radius     => radius.to_s,
+          :unit       => unit.to_s
+        }
+        @resource.request :get, self.path + "/haversine", :parameters => parameters, :expected_status_code => 200
+      end
+
+      def inside_polygon(type, predicate, name)
+        parameters = {
+          :type       => type,
+          :predicate  => predicate,
+          :polygon    => "\"#{name}\""
+        }
+        @resource.request :get, self.path + "/polygon", :parameters => parameters, :expected_status_code => 200
+      end
+
+      private
+
+      def float_to_iso_6709(value, digits)
+        sign = "+"
+        if value < 0
+          sign = "-"
+          value = -value
+        end
+        floor = value.to_i
+        sign + (("%%0%dd" % digits) % floor) + (".%07d" % ((value - floor) * 10000000))
+      end
+
+    end
+
+  end
+
+end

data/lib/allegro_graph/proxy/mapping.rb

@@ -0,0 +1,34 @@
+
+module AllegroGraph
+
+  module Proxy
+
+    class Mapping
+
+      attr_reader :resource
+
+      def initialize(resource)
+        @resource = resource
+      end
+
+      def path
+        "#{@resource.path}/mapping"
+      end
+
+      def create(type, encoding)
+        parameters = { :type => type, :encoding => encoding }
+        @resource.request :put, self.path + "/type", :parameters => parameters, :expected_status_code => 204
+        true
+      end
+
+      def delete(type)
+        parameters = { :type => type }
+        @resource.request :delete, self.path + "/type", :parameters => parameters, :expected_status_code => 204
+        true
+      end
+
+    end
+
+  end
+
+end