dbd 0.0.1

data/lib/dbd/provenance_fact.rb

@@ -0,0 +1,76 @@
+module Dbd
+
+  ##
+  # ProvenanceFact
+  #
+  # ProvenanceFact is derived from Fact and behaves very similar.
+  #
+  # The ProvenanceFacts with same subject form a ProvenanceResource and
+  # this is used as the target for the provenance_subject of a Fact.
+  #
+  # The provenance_subject of a ProvenanceFact itself is empty, so the
+  # usage of provenance_subject is not recursive on this level (this
+  # allows efficient single pass loading in an underlying database).
+  #
+  # In the serialisation of the fact stream, the presence or absence of a
+  # provenance_subject marks the difference between a (base) Fact and a
+  # ProvenanceFact.
+  #
+  # The predicates in a ProvenanceFact would typically come from a defined
+  # "provenance ontology". An experimental example of a provenance ontology
+  # is built-up on https://data.vandenabeele.com/ontologies/provenance.
+  class ProvenanceFact < Fact
+
+    ##
+    # Builds a new ProvenanceFact.
+    #
+    # @param [Hash{Symbol => Object}] options
+    # @option options [Fact::Subject] :subject (new_subject) Optional: the subject for the ProvenanceFact
+    # @option options [String] :predicate Required: the subject for the ProvenanceFact
+    # @option options [String] :object Required: the object for the ProvenanceFact
+    def initialize(options)
+      validate_provenance_subject(options)
+      super
+    end
+
+    ##
+    # Executes the required update in used_provenance_subjects.
+    #
+    # For a ProvenanceFact, there is no provenance_subject, so
+    # pointless to mark it in used_provenance_subjects hash.
+    def update_used_provenance_subjects(h)
+      # Do nothing (override the behaviour from super).
+    end
+
+    ##
+    # Validates the presence or absence of provenance_subject.
+    #
+    # Here, in the derived ProvenanceFact, it must not be present.
+    # @param [#nil?] provenance_subject
+    # Return [Boolean]
+    def provenance_subject_valid?(provenance_subject)
+      provenance_subject.nil?
+    end
+
+    ##
+    # Builds duplicate with the subject set.
+    #
+    # @param [Subject] subject_arg
+    # @return [ProvenanceFact] the duplicate fact
+    def dup_with_subject(subject_arg)
+      self.class.new(
+       subject: subject_arg, # from arg
+       predicate: predicate,
+       object: object)
+    end
+
+  private
+
+    ##
+    # Validate that provenance_subject is not set here.
+    def validate_provenance_subject(options)
+      raise ProvenanceError if options[:provenance_subject]
+    end
+
+  end
+end

data/lib/dbd/provenance_resource.rb

@@ -0,0 +1,54 @@
+module Dbd
+  ##
+  # A ProvenanceResource is derived from a Resource, specifically
+  # for a Provenance (does not have and does need a provenance_subject)
+  class ProvenanceResource < Resource
+
+    ##
+    # Build a new ProvenanceResource.
+    #
+    # The subject can be either given as an argument or a new (random)
+    # subject is automatically set (see Resource for details).
+    #
+    # A provenance_subject may not be given here.
+    # @option options [Fact::Subject] :subject (new_subject) Optional: the subject for the resource
+    def initialize(options = {})
+      super
+    end
+
+    ##
+    # Add a ProvenanceFact.
+    #
+    # * if it has no subject, the subject is set in a duplicate provenance_fact
+    # * if is has the same subject as the resource, added unchanged.
+    # * if it has a different subject, a SubjectError is raised.
+    def <<(provenance_fact)
+      # TODO: check the type of the provenance_fact (ProvenanceFact)
+      super
+    end
+
+  private
+
+    ##
+    # Should not be called in ProvenanceResource subclass.
+    def provenance_subject
+      raise RuntimeError, "provenance_subject should not be called in ProvenanceResource."
+    end
+
+    ##
+    # Validate that provenance_subject is not set here.
+    def validate_provenance_subject
+      raise ProvenanceError if @provenance_subject
+    end
+
+    ##
+    # Check provenance_subject, which should be nil here
+    # @param [ProvenanceFact] provenance_fact
+    # @return [ProvenanceFact] with validated nil on provenance_subject
+    def check_or_set_provenance(provenance_fact)
+      raise ProvenanceError if provenance_fact.provenance_subject
+      provenance_fact
+    end
+
+  end
+end

data/lib/dbd/rdf.rb

@@ -0,0 +1,9 @@
+# from the rdf gem (developed by rdf-ruby account on github)
+require 'rdf'
+
+module Dbd
+  ##
+  # To allow some tests of the *rdf* gem.
+  module RdfBase
+  end
+end

data/lib/dbd/repo.rb

@@ -0,0 +1,8 @@
+require 'dbd/repo/neo4j_repo.rb'
+
+module Dbd
+  ##
+  # To allow some tests of Neo4j
+  module Repo
+  end
+end

data/lib/dbd/repo/neo4j_repo.rb

@@ -0,0 +1,4 @@
+# from neopgraphy gem
+require 'neography'
+
+require 'dbd/repo/neo4j_repo/base.rb'

data/lib/dbd/repo/neo4j_repo/base.rb

@@ -0,0 +1,55 @@
+module Dbd
+  module Repo
+    module Neo4jRepo
+      ##
+      # To allow some tests on the Neo4j Neography gem.
+      class Base
+
+        def initialize
+          @neo = Neography::Rest.new
+        end
+
+        def create_node(hash)
+          @neo.create_node(hash)
+        end
+
+        def batch(*args)
+          @neo.batch(*args)
+        end
+
+        def create_relationship(p, s, o)
+          @neo.create_relationship(p, s, o)
+        end
+
+        def list_node_indexes
+          @neo.list_node_indexes
+        end
+
+        def create_node_index(name, type, provider)
+          @neo.create_node_index(name, type, provider)
+        end
+
+        def add_node_to_index(index, key, value, node)
+          @neo.add_node_to_index(index, key, value, node)
+        end
+
+        def get_node_index(index, key, value)
+          @neo.get_node_index(index, key, value)
+        end
+
+        def execute_query(query_string)
+          @neo.execute_query(query_string)
+        end
+
+        def get_root
+          @neo.get_root
+        end
+
+        def load_node(uri)
+          Neography::Node.load(uri)
+        end
+
+      end
+    end
+  end
+end

data/lib/dbd/resource.rb

@@ -0,0 +1,117 @@
+require 'dbd/helpers/ordered_set_collection'
+
+module Dbd
+  ##
+  # A Resource is a collection of facts that have the same subject.
+  #
+  # In the real-world this is a mainly an "instance" about which all
+  # facts are giving information (e.g. a conference, a person, a
+  # bicycle, ...). More generally this can also be used to describe
+  # classes and other concepts in the software system.
+  #
+  # A new (random) subject is generated for a resource. In Dbd,
+  # a subject is a random uuid (like a oid), not a meaningful URI
+  # as it is in RDF.
+  #
+  # A provenance_subject is a required field in the options hash.
+  # Practically, first a ProvenanceResource will be created and the
+  # subject of that will be used as provenance_subject for the
+  # Resources that are associated with it.
+  #
+  # During build-up of a Fact, the subject and the provenance_subject
+  # can be nil. These will then be set in a local duplicate when the
+  # Fact is added (with '<<') to a resource.
+  class Resource
+
+    include Helpers::OrderedSetCollection
+
+    attr_reader :subject
+
+    ##
+    # @return [Fact::Subject] a new (random) Resource subject
+    def self.new_subject
+      Fact.new_subject
+    end
+
+    ##
+    # Build a new resource.
+    #
+    # By default, a new (random) subject is generated for a resource.
+    # Optionally, an explicit subject can be given in the options parameter
+    # (this is best created with the new_subject class method for forward
+    # compatibility).
+    #
+    # The provenance_subject argument is required. This will typically be
+    # taken from an earlier created ProvenanceResource.
+    # @param [Hash{Symbol => Object}] options
+    # @option options [Fact::Subject] :provenance_subject (required) the subject of the provenance resource for this resource
+    # @option options [Fact::Subject] :subject (new_subject) Optional: the subject for the resource
+    def initialize(options)
+      @subject = options[:subject] || self.class.new_subject
+      @provenance_subject = options[:provenance_subject]
+      validate_provenance_subject
+      super()
+    end
+
+    ##
+    # Add a fact.
+    #
+    # * if it has no subject, the subject is set in a duplicate fact
+    # * if is has the same subject as the resource, added unchanged.
+    # * if it has a different subject, a SubjectError is raised.
+    # * if it has no provenance_subject, the provenance_subject is set in a duplicate fact
+    # * if is has the same provenance_subject as the resource, added unchanged.
+    # * if it has a different provenance_subject, a ProvenanceError is raised.
+    def <<(fact)
+      # TODO: check the type of the fact (Fact)
+      super(check_or_set_subject_and_provenance(fact))
+    end
+
+    ##
+    # Getter for provenance_subject.
+    #
+    # Will be overridden in the ProvenanceResource subclass.
+    def provenance_subject
+      @provenance_subject
+    end
+
+  private
+
+    def check_or_set_subject_and_provenance(element)
+      with_subject = check_or_set_subject(element)
+      check_or_set_provenance(with_subject)
+    end
+
+    def check_or_set_subject(element)
+      if element.subject
+        if element.subject == @subject
+          return element
+        else
+          raise SubjectError,
+            "self.subject is #{subject} and element.subject is #{element.subject}"
+        end
+      else
+        element.dup_with_subject(@subject)
+      end
+    end
+
+    # this will be overriden in the ProvenanceResource sub_class
+    def check_or_set_provenance(element)
+      if element.provenance_subject
+        if element.provenance_subject == @provenance_subject
+          return element
+        else
+          raise ProvenanceError,
+            "self.provenance_subject is #{provenance_subject} and element.provenance_subject is #{element.provenance_subject}"
+        end
+      else
+        element.dup_with_provenance_subject(@provenance_subject)
+      end
+    end
+
+    def validate_provenance_subject
+      raise ProvenanceError if @provenance_subject.nil?
+    end
+
+  end
+end

data/lib/dbd/version.rb

@@ -0,0 +1,3 @@
+module Dbd
+  VERSION = "0.0.1"
+end

data/spec/factories/fact.rb

@@ -0,0 +1,76 @@
+module Factories
+  module Fact
+
+    def self.factory_for
+      ::Dbd::Fact
+    end
+
+    def self.new_subject
+      factory_for.new_subject
+    end
+
+    def self.fact_1(provenance_subject = nil)
+      factory_for.new(
+        provenance_subject: provenance_subject,
+        predicate: "http://example.org/test/name",
+        object: "Gandhi")
+    end
+
+    def self.fact_2_with_subject(provenance_subject = nil)
+      factory_for.new(
+        provenance_subject: provenance_subject,
+        subject: new_subject,
+        predicate: "http://example.org/test/name",
+        object: "Mandela")
+    end
+
+    def self.fact_3_with_subject(provenance_subject = nil)
+      factory_for.new(
+        provenance_subject: provenance_subject,
+        subject: new_subject,
+        predicate: "http://example.org/test/name",
+        object: "King")
+    end
+
+    def self.data_fact(provenance_subject = nil, subject = nil)
+      factory_for.new(
+        provenance_subject: provenance_subject,
+        subject: subject,
+        predicate: "http://example.org/test/name",
+        object: "Aung San Suu Kyi")
+    end
+
+    def self.data_fact_EU(provenance_subject = nil, subject = nil)
+      factory_for.new(
+        provenance_subject: provenance_subject,
+        subject: subject,
+        predicate: "http://example.org/test/name",
+        object: "European Union")
+    end
+
+    module Collection
+
+      def self.factory_for_instance
+        o = Object.new
+        o.extend(::Dbd::Fact::Collection)
+        o.send(:initialize)
+        o
+      end
+
+      def self.fact_2_3(provenance_subject)
+        factory_for_instance.tap do |fact_collection|
+          fact_collection << Fact.fact_2_with_subject(provenance_subject)
+          fact_collection << Fact.fact_3_with_subject(provenance_subject)
+        end
+      end
+
+      def self.provenance_facts(subject)
+        factory_for_instance.tap do |provenance_facts|
+          provenance_facts << ProvenanceFact.context(subject)
+          provenance_facts << ProvenanceFact.created_by(subject)
+          provenance_facts << ProvenanceFact.original_source(subject)
+        end
+      end
+    end
+  end
+end

data/spec/factories/provenance_fact.rb

@@ -0,0 +1,34 @@
+module Factories
+  module ProvenanceFact
+
+    def self.factory_for
+      ::Dbd::ProvenanceFact
+    end
+
+    def self.new_subject
+      factory_for.new_subject
+    end
+
+    def self.context(subject = nil)
+      factory_for.new(
+        subject: subject,
+        predicate: "https://data.vandenabeele.com/ontologies/provenance#context",
+        object: "public")
+    end
+
+    def self.created_by(subject = nil)
+      factory_for.new(
+        subject: subject,
+        predicate: "https://data.vandenabeele.com/ontologies/provenance#created_by",
+        object:"peter_v")
+    end
+
+    def self.original_source(subject = nil)
+      factory_for.new(
+        subject: subject,
+        predicate: "https://data.vandenabeele.com/ontologies/provenance#original_source",
+        object: "this has a comma , a newline \n and a double quote \"")
+    end
+
+  end
+end