changesets 0.1

data/README.md

@@ -0,0 +1,32 @@
+CHANGESET.RB
+------------
+
+A plugin for RDF.rb that provides support for creating Changesets that describe changes to an RDF 
+graph[1]. 
+
+Changesets can be serialized as RDF and then applied to a triple store. Changesets are currently supported 
+by Talis Platform stores and Kasabi[0] datasets.
+
+AUTHOR
+------
+
+Leigh Dodds (ld@kasabi.com)
+
+INSTALLATION
+------------
+
+Changesets.rb is packaged as a Ruby Gem and can be installed as follows:
+
+	sudo gem install changesets
+	
+The source for the project is maintained in github at:
+
+http://github.com/ldodds/changesets.rb
+
+USAGE
+-----
+
+The test suite provides some simple examples of how to construct changesets.
+
+[0]: [http://kasabi.com]
+[1]: [http://vocab.org/changeset/schema.html]

data/Rakefile

@@ -0,0 +1,60 @@
+require 'rake'
+
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/testtask'
+require 'rake/clean'
+
+NAME = "changesets"
+VER = "0.1"
+
+RDOC_OPTS = ['--quiet', '--title', 'RDF Changesets API']
+
+PKG_FILES = %w( README.md Rakefile ) + 
+  Dir.glob("{tests,lib}/**/*")
+
+CLEAN.include ['*.gem', 'pkg']  
+SPEC =
+  Gem::Specification.new do |s|
+    s.name = NAME
+    s.version = VER
+    s.platform = Gem::Platform::RUBY
+    s.required_ruby_version = ">= 1.8.7"    
+    s.has_rdoc = true
+    s.rdoc_options = RDOC_OPTS
+    s.summary = "RDF Changesets API"
+    s.description = s.summary
+    s.author = "Leigh Dodds"
+    s.email = 'ld@kasabi.com'
+    s.homepage = 'http://github.com/ldodds/changesets.rb'
+    s.files = PKG_FILES
+    s.require_path = "lib" 
+    s.test_file = "tests/ts_changeset.rb"
+    s.add_dependency("rdf")
+    s.add_dependency("mocha", ">= 0.9.5")
+  end
+      
+Rake::GemPackageTask.new(SPEC) do |pkg|
+    pkg.need_tar = true
+end
+
+Rake::RDocTask.new do |rdoc|
+    rdoc.rdoc_dir = 'doc/rdoc'
+    rdoc.options += RDOC_OPTS
+    rdoc.rdoc_files.include("CHANGES", "lib/**/*.rb")    
+end
+
+Rake::TestTask.new do |test|
+  test.test_files = FileList['tests/tc_*.rb']
+end
+
+desc "Install from a locally built copy of the gem"
+task :install do
+  sh %{rake package}
+  sh %{sudo gem install pkg/#{NAME}-#{VER}}
+end
+
+desc "Uninstall the gem"
+task :uninstall => [:clean] do
+  sh %{sudo gem uninstall #{NAME}}
+end

data/lib/changesets.rb

@@ -0,0 +1,4 @@
+require 'rubygems'
+require 'rdf'
+
+require 'changesets/rdf_changeset.rb'

data/lib/changesets/rdf_changeset.rb

@@ -0,0 +1,139 @@
+module RDF
+  module Talis
+    class Changeset < RDF::Vocabulary('http://purl.org/vocab/changeset/schema#')
+      property :removal
+      property :addition
+      property :creatorName
+      property :createdDate
+      property :subjectOfChange
+      property :changeReason
+      property :ChangeSet
+      property :precedingChangeSet
+    end
+  end
+end
+
+module RDF
+    
+  class Changeset
+
+    #Media type for Changesets
+    CONTENT_TYPE_TURTLE = "application/vnd.talis.changeset+turtle"
+    CONTENT_TYPE_XML = "application/vnd.talis.changeset+xml"
+    #Default reason for applying the update to a graph
+    DEFAULT_REASON = "Generated in changeset.rb"
+    #Default name/label for the change agent
+    DEFAULT_CREATOR = "changeset.rb"
+    
+    attr_reader :statements, :subject_of_change
+    
+    def initialize(subject_of_change, change_reason=DEFAULT_REASON, creator_name=DEFAULT_CREATOR)
+      @resource = RDF::Node.new
+      @subject_of_change = subject_of_change
+      @statements = []
+      @statements.concat [RDF::Statement.new(@resource, RDF.type, RDF::Talis::Changeset.ChangeSet),
+       RDF::Statement.new(@resource, RDF::Talis::Changeset.changeReason, change_reason),
+       RDF::Statement.new(@resource, RDF::Talis::Changeset.creatorName, creator_name),
+       RDF::Statement.new(@resource, RDF::Talis::Changeset.createdDate, Time.now),
+       RDF::Statement.new(@resource, RDF::Talis::Changeset.subjectOfChange, subject_of_change)]
+       if block_given?
+         yield self
+       end
+    end
+    
+    #Remove these statements from the graph
+    def remove_statements(stmts)
+      stmts = [stmts] if stmts.is_a?(RDF::Statement)
+      stmts.each do |stmt|
+        raise ArgumentError unless stmt.subject == @subject_of_change        
+        @statements.concat changeset_statement(stmt, :removal)
+      end
+    end
+    
+    #Add these statements to the graph
+    def add_statements(stmts)
+      stmts = [stmts] if stmts.is_a?(RDF::Statement)
+      stmts.each do |stmt|
+        next unless stmt
+        raise ArgumentError unless stmt.subject == @subject_of_change        
+        @statements.concat changeset_statement(stmt, :addition)
+      end
+    end
+        
+    def changeset_statement(stmt, action)
+      s = RDF::Node.new
+      [RDF::Statement.new(@resource, RDF::Talis::Changeset.send(action), s),
+        RDF::Statement.new(s, RDF.type, RDF.to_rdf+"Statement"),
+        RDF::Statement.new(s, RDF.subject, stmt.subject),
+        RDF::Statement.new(s, RDF.predicate, stmt.predicate),
+        RDF::Statement.new(s, RDF.object, stmt.object)]
+    end    
+    
+    #Convert into an RDF::Graph object
+    def to_graph
+      graph = RDF::Graph.new()
+      @statements.each do |s|
+        graph << s
+      end
+      graph
+    end
+            
+    #Update a predicate from one value to another
+    #Will only remove the specified old value, other values for predicate will remain unchanged
+    def Changeset.update_property(subject, predicate, old_value, new_value, change_reason=DEFAULT_REASON, creator_name=DEFAULT_CREATOR)
+      cs = Changeset.new(subject, change_reason, creator_name) do |cs|
+        cs.remove_statements( RDF::Statement.new( subject, predicate, old_value ) )
+        cs.add_statements( RDF::Statement.new( subject, predicate, new_value ) )        
+      end
+      cs
+    end
+        
+    #Remove a specific single property for a subject
+    def Changeset.remove_property(subject, predicate, value, change_reason=DEFAULT_REASON, creator_name=DEFAULT_CREATOR)
+      return Changeset.remove_statement( RDF::Statement.new( subject, predicate, value ) )
+    end
+
+    #Remove a statement
+    def Changeset.remove_statement( statement, change_reason=DEFAULT_REASON, creator_name=DEFAULT_CREATOR)
+      cs = Changeset.new(statement.subject, change_reason, creator_name) do |cs|
+        cs.remove_statements( statement )
+      end
+      cs
+    end
+    
+    #Remove all statements with a specific predicate for a specific resource
+    def Changeset.remove_properties(subject, predicate, graph, change_reason=DEFAULT_REASON, creator_name=DEFAULT_CREATOR)
+      cs = Changeset.new(subject, change_reason, creator_name) do |cs|
+        graph.query( [subject, predicate, nil] ).each do |statement|
+          cs.remove_statements( statement )
+        end              
+      end                  
+      cs
+    end
+    
+    #Remove all statements where the indicated resource is the subject
+    def Changeset.remove_subject(subject, graph, change_reason=DEFAULT_REASON, creator_name=DEFAULT_CREATOR)
+      cs = Changeset.new(subject, change_reason, creator_name) do |cs|
+        graph.query( [subject, nil, nil] ).each do |statement|
+          cs.remove_statements( statement )
+        end              
+      end                  
+      cs      
+    end
+    
+    #Apply an update by removing all statements for the indicated subject from the old graph, replacing it 
+    #with statements in the new graph    
+    def Changeset.update(subject, new, old, change_reason=DEFAULT_REASON, creator_name=DEFAULT_CREATOR)
+      cs = Changeset.new(subject, change_reason, creator_name) do |cs|
+        old.query( [subject, nil, nil] ).each do |statement|
+          cs.remove_statements( statement )
+        end        
+        new.query( [subject, nil, nil] ).each do |statement|
+          cs.add_statements( statement )
+        end
+      end      
+      cs
+    end
+    
+  end
+end

data/tests/tc_rdf_changeset.rb

@@ -0,0 +1,158 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+require 'changesets'
+require 'test/unit'
+require 'mocha'
+
+class ChangesetTest < Test::Unit::TestCase
+  
+  def test_init
+    cs = RDF::Changeset.new( RDF::URI.new("http://www.example.org") )
+    assert_equal( RDF::URI.new("http://www.example.org"), cs.subject_of_change )
+    assert_equal( false, cs.statements.empty? )
+    
+    graph = cs.to_graph()
+    assert_not_nil( graph )
+    assert_equal( cs.statements.length, cs.to_graph.size )
+  end
+  
+  def test_add_single_statement
+    uri = RDF::URI.new("http://www.example.org")
+    cs = RDF::Changeset.new( uri  )
+    stmts = RDF::Statement.new( uri , RDF.type, RDF::RDFS.Class )       
+    cs.add_statements( stmts )    
+    test_for( RDF::Talis::Changeset.addition, cs, stmts )
+  end
+
+  def test_remove_single_statement
+    uri = RDF::URI.new("http://www.example.org")
+    cs = RDF::Changeset.new( uri  )
+    stmts = RDF::Statement.new( uri , RDF.type, RDF::RDFS.Class )
+    cs.remove_statements( stmts )       
+    test_for( RDF::Talis::Changeset.removal, cs, stmts )
+  end
+    
+  def test_add_statements
+    uri = RDF::URI.new("http://www.example.org")
+    cs = RDF::Changeset.new( uri  )    
+    stmts = [ RDF::Statement.new( uri , RDF.type, RDF::RDFS.Class ) ]
+    cs.add_statements( stmts )             
+    test_for( RDF::Talis::Changeset.addition, cs, stmts )    
+  end  
+  
+  def test_remove_statements
+    uri = RDF::URI.new("http://www.example.org")
+    cs = RDF::Changeset.new( uri  )
+    stmts = [ RDF::Statement.new( uri , RDF.type, RDF::RDFS.Class ) ]   
+    cs.remove_statements( stmts )    
+    test_for( RDF::Talis::Changeset.removal, cs, stmts )    
+  end  
+    
+  def test_precondition
+    uri = RDF::URI.new("http://www.example.org")
+    other = RDF::URI.new("http://www.example.com")
+    cs = RDF::Changeset.new( uri  )
+    
+    assert_raise ArgumentError do
+      cs.add_statements( RDF::Statement.new( other , RDF.type, RDF::RDFS.Class ) )
+    end
+    assert_raise ArgumentError do
+      cs.remove_statements( RDF::Statement.new( other , RDF.type, RDF::RDFS.Class ) )
+    end
+        
+  end
+  
+  def test_update_property()
+    uri = RDF::URI.new("http://www.example.org")
+    cs = RDF::Changeset.update_property(uri, RDF::RDFS.label, RDF::Literal.new("Old"), RDF::Literal.new("New") )
+    removal = RDF::Statement.new( uri, RDF::RDFS.label, RDF::Literal.new("Old"))
+    addition = RDF::Statement.new( uri, RDF::RDFS.label, RDF::Literal.new("New"))
+    test_for( RDF::Talis::Changeset.removal, cs, removal )
+    test_for( RDF::Talis::Changeset.addition, cs, addition )
+  end
+
+  def test_remove_property()
+    uri = RDF::URI.new("http://www.example.org")
+    cs = RDF::Changeset.remove_property(uri, RDF::RDFS.label, RDF::Literal.new("Gone") )
+    removal = RDF::Statement.new( uri, RDF::RDFS.label, RDF::Literal.new("Gone"))
+    test_for( RDF::Talis::Changeset.removal, cs, removal )
+  end
+
+  def test_remove_statement()
+    uri = RDF::URI.new("http://www.example.org")
+    removal = RDF::Statement.new( uri, RDF::RDFS.label, RDF::Literal.new("Gone") )
+    cs = RDF::Changeset.remove_statement( removal )    
+    test_for( RDF::Talis::Changeset.removal, cs, removal )
+  end
+  
+  def test_remove_properties()
+    uri = RDF::URI.new("http://www.example.org")
+    graph = RDF::Graph.new()
+    label = RDF::Statement.new( uri, RDF::RDFS.label, RDF::Literal.new("Label") )
+    title = RDF::Statement.new( uri, RDF::RDFS.label, RDF::Literal.new("Title") )
+    graph << label
+    graph << title
+    cs = RDF::Changeset.remove_properties(uri, RDF::RDFS.label, graph )
+    #puts cs.statements
+    test_for( RDF::Talis::Changeset.removal, cs, label )    
+    test_for( RDF::Talis::Changeset.removal, cs, title )
+  end
+
+  def test_remove_subject()
+    uri = RDF::URI.new("http://www.example.org")
+    graph = RDF::Graph.new()
+    label = RDF::Statement.new( uri, RDF::RDFS.label, "Label")
+    title = RDF::Statement.new( uri, RDF::DC.title, "Title")
+    graph << label
+    graph << title
+    cs = RDF::Changeset.remove_subject(uri, graph )
+    test_for( RDF::Talis::Changeset.removal, cs, [ label, title ] )    
+  end
+              
+  def test_update()
+    uri = RDF::URI.new("http://www.example.org")
+    graph = RDF::Graph.new()
+    label = RDF::Statement.new( uri, RDF::RDFS.label, "Label")
+    title = RDF::Statement.new( uri, RDF::DC.title, "Title")
+    graph << label
+    graph << title
+    cs = RDF::Changeset.update(uri, RDF::Graph.new(), graph )
+    test_for( RDF::Talis::Changeset.removal, cs, [ label, title ] )        
+      
+    cs = RDF::Changeset.update(uri, graph, RDF::Graph.new() )
+    test_for( RDF::Talis::Changeset.addition, cs, [ label, title ] )              
+  end
+
+#  def test_apply_to()
+#    uri = RDF::URI.new("http://www.example.org")
+#    graph = RDF::Graph.new()
+#    label = RDF::Statement.new( uri, RDF::RDFS.label, RDF::Literal.new("Label") )
+#    title = RDF::Statement.new( uri, RDF::DC.title, RDF::Literal.new("Title") )
+#    graph << label
+#    graph << title
+#    cs = RDF::Changeset.remove_properties(uri, RDF::RDFS.label, graph )
+#    
+#    cs.apply_to(graph)    
+#    
+#    label = graph.first_object( [uri, RDF::RDFS.label, nil ] )
+#    assert_nil(label)
+#  end
+
+      
+  def test_for( predicate, cs, statements )
+    statements = [statements] if statements.is_a?(RDF::Statement)
+    
+    statements.each do |s|
+      query = RDF::Query.new do
+        pattern [ :x, predicate, :stmt ]
+        pattern [ :stmt, RDF.subject, s.subject]
+        pattern [ :stmt, RDF.predicate, s.predicate]
+        pattern [ :stmt, RDF.object, s.object]
+      end
+      query.execute(cs.to_graph)
+      if query.failed?
+        raise "Unable to find #{predicate} for #{s.subject} #{s.predicate}, #{s.object}"
+      end
+    end
+  end
+  
+end

data/tests/ts_changeset.rb

@@ -0,0 +1,2 @@
+$:.unshift File.dirname(__FILE__)
+require 'test/unit'

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification 
+name: changesets
+version: !ruby/object:Gem::Version 
+  hash: 9
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  version: "0.1"
+platform: ruby
+authors: 
+- Leigh Dodds
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-10-12 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rdf
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 49
+        segments: 
+        - 0
+        - 9
+        - 5
+        version: 0.9.5
+  type: :runtime
+  version_requirements: *id002
+description: RDF Changesets API
+email: ld@kasabi.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.md
+- Rakefile
+- tests/ts_changeset.rb
+- tests/tc_rdf_changeset.rb
+- lib/changesets.rb
+- lib/changesets/rdf_changeset.rb
+homepage: http://github.com/ldodds/changesets.rb
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --quiet
+- --title
+- RDF Changesets API
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 57
+      segments: 
+      - 1
+      - 8
+      - 7
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.9
+signing_key: 
+specification_version: 3
+summary: RDF Changesets API
+test_files: 
+- tests/ts_changeset.rb