dbd 0.0.1

data/lib/dbd/errors.rb

@@ -0,0 +1,11 @@
+module Dbd
+
+  class OutOfOrderError < StandardError ; end
+  class FactError < StandardError ; end
+
+  class ProvenanceError < StandardError ; end
+  class SubjectError < StandardError ; end
+  class PredicateError < StandardError ; end
+  class ObjectError < StandardError ; end
+
+end

data/lib/dbd/fact.rb

@@ -0,0 +1,182 @@
+require 'dbd/fact/collection'
+require 'dbd/fact/subject'
+require 'dbd/fact/id'
+
+module Dbd
+
+  ##
+  # Basic Fact of knowledge.
+  #
+  # The database is built as an ordered sequence of facts, the "fact stream".
+  #
+  # This is somewhat similar to a "triple" in the RDF (Resource Description
+  # Framework) concept, but with different and extended functionality.
+  #
+  # Each basic fact has:
+  # * a unique and invariant *id* (a uuid)
+  #
+  #   To allow referencing back to it (e.g. to invalidate it later in the fact stream).
+  #
+  # * a *time_stamp*  (time with nanosecond granularity)
+  #
+  #   To allow verifying that the order in the fact stream is correct.
+  #
+  #   A time_stamp does not need to represent the exact time of the
+  #   creation of the fact, but it has to increase in strictly monotic
+  #   order in the fact stream.
+  #
+  # * a *provenance_subject* (a uuid)
+  #
+  #   The subject of the ProvenanceResource (a set of ProvenanceFacts with
+  #   the same subject) about this fact. Each Fact, points *back* to a
+  #   ProvenanceResource (the ProvenanceResource must have been fully
+  #   defined, earlier in the fact stream).
+  #
+  # * a *subject* (a uuid)
+  #
+  #   "About which Resource is this fact?".
+  #
+  #   Similar to the subject of an  RDF triple, except that this subject is not
+  #   a URI, but an abstract uuid (that is world-wide unique and invariant).
+  #
+  #   Links to "real-world" URI's and URL's can be added later as separate facts
+  #   (this also allows linking multiple "real-world" URI's to a single Resource).
+  #
+  # * a *predicate* (a string)
+  #
+  #   "Which property of the resource are we describing?".
+  #
+  #   Currently this is a string, but I suggest modeling this similar to predicate
+  #   in RDF. Probably more detailed modeling using RDF predicate will follow.
+  #
+  # * an *object* (a string)
+  #
+  #   "What is the value of the property of the resource we are describing?".
+  #
+  #   Currently this is a string, but I suggest modeling this similar to object
+  #   in RDF. Probably more detailed modeling using RDF object will follow.
+  class Fact
+
+    ##
+    # @return [Array] The 6 attributes of a Fact.
+    def self.attributes
+      [:id,
+       :time_stamp,
+       :provenance_subject,
+       :subject,
+       :predicate,
+       :object]
+    end
+
+    attributes.each do |attribute|
+      attr_reader attribute
+    end
+
+    def time_stamp=(time_stamp)
+      raise RuntimeError if @time_stamp
+      @time_stamp = time_stamp
+    end
+
+    ##
+    # @return [Subject] A new random subject.
+    def self.new_subject
+      Subject.new
+    end
+
+    ##
+    # @return [ID] A new random id.
+    def self.new_id
+      ID.new
+    end
+
+    ##
+    # Builds a new Fact.
+    #
+    # @param [Hash{Symbol => Object}] options
+    # @option options [#to_s] :predicate Required : the predicate for this Fact
+    # @option options [#to_s] :object Required :  the object for this Fact (required)
+    # @option options [Subject] :provenance_subject (nil) Optional: the subject of the provenance(resource|fact)
+    # @option options [Subject] :subject (nil) Optional: the subject for this Fact
+    def initialize(options)
+      @id = self.class.new_id
+      @provenance_subject = options[:provenance_subject]
+      @subject = options[:subject]
+      @predicate = options[:predicate]
+      @object = options[:object]
+      raise PredicateError, "predicate cannot be nil" if predicate.nil?
+      raise ObjectError, "object cannot be nil" if object.nil?
+    end
+
+    ##
+    # @return [Array] The 6 values of a Fact.
+    def values
+      self.class.attributes.map{ |attribute| self.send(attribute) }
+    end
+
+    ##
+    # Executes the required update in used_provenance_subjects.
+    #
+    # For a Fact, pointing to a ProvenanceResource in it's provenance_subject,
+    # marks this provenance_subject in the "used_provenance_subjects" hash that
+    # is passed in as an argument (DCI). This will avoid further changes to the
+    # ProvenanceResource with this provenance_subject.
+    #
+    # This is overridden in the ProvenanceFact, since only relevant for a Fact.
+    def update_used_provenance_subjects(h)
+      # using a provenance_subject sets the key
+      h[provenance_subject] = true
+    end
+
+    ##
+    # Checks if a fact is valid for storing in the graph.
+    #
+    # @return [#true?] not nil if valid
+    def valid?
+      # id not validated, is set automatically
+      # predicate not validated, is validated in initialize
+      # object not validated, is validated in initialize
+      provenance_subject_valid?(provenance_subject) &&
+      subject
+    end
+
+    ##
+    # Validates the presence or absence of provenance_subject.
+    #
+    # Here, in (base) Fact, provenance_subject must be present
+    # In the derived ProvenanceFact it must not be present.
+    # This is how the difference is encoded between Fact and
+    # ProvenanceFact in the fact stream.
+    # @param [#nil?] provenance_subject
+    # Return [Boolean]
+    def provenance_subject_valid?(provenance_subject)
+      provenance_subject
+    end
+
+    ##
+    # Builds duplicate with the subject set.
+    #
+    # @param [Subject] subject_arg
+    # @return [Fact] the duplicate fact
+    def dup_with_subject(subject_arg)
+      self.class.new(
+       provenance_subject: provenance_subject,
+       subject: subject_arg, # from arg
+       predicate: predicate,
+       object: object)
+    end
+
+    ##
+    # Builds duplicate with the provenance_subject set.
+    #
+    # @param [Subject] provenance_subject_arg
+    # @return [Fact] the duplicate fact
+    def dup_with_provenance_subject(provenance_subject_arg)
+      self.class.new(
+       provenance_subject: provenance_subject_arg, # from arg
+       subject: subject,
+       predicate: predicate,
+       object: object)
+    end
+
+  end
+end

data/lib/dbd/fact/collection.rb

@@ -0,0 +1,60 @@
+require 'dbd/helpers/ordered_set_collection'
+
+module Dbd
+  class Fact
+    module Collection
+
+      include Helpers::OrderedSetCollection
+
+      def initialize
+        super
+        @hash_by_subject = Hash.new { |h, k| h[k] = [] }
+        @used_provenance_subjects = {}
+      end
+
+      def newest_time_stamp
+        newest_entry = @internal_collection.last
+        newest_entry && newest_entry.time_stamp
+      end
+
+      def oldest_time_stamp
+        oldest_entry = @internal_collection.first
+        oldest_entry && oldest_entry.time_stamp
+      end
+
+      ##
+      # This is the central method of Fact::Collection module
+      #
+      # @param [Fact] fact the fact that is added to the collection
+      #
+      # @return [self] for chaining
+      #
+      # Validates that added fact is valid.
+      #
+      # Validates that added fact is newer.
+      #
+      # Validates that subject was never used as provenance_subject [A].
+      #
+      # Adds the fact and return the index in the collection.
+      #
+      # Store this index in the hash_by_subject.
+      #
+      # Mark the fact in the list of used provenance_subjects (for [A]).
+      def <<(fact)
+        # TODO Add a more descriptive Exception message
+        raise FactError unless fact.valid?
+        raise OutOfOrderError if (self.newest_time_stamp && fact.time_stamp <= self.newest_time_stamp)
+        raise OutOfOrderError if (@used_provenance_subjects[fact.subject])
+        index = Helpers::OrderedSetCollection.add_and_return_index(fact, @internal_collection)
+        @hash_by_subject[fact.subject] << index
+        fact.update_used_provenance_subjects(@used_provenance_subjects)
+        self
+      end
+
+      def by_subject(fact_subject)
+        @hash_by_subject[fact_subject].map{ |index| @internal_collection[index]}
+      end
+
+    end
+  end
+end

data/lib/dbd/fact/id.rb

@@ -0,0 +1,19 @@
+module Dbd
+  class Fact
+    class ID
+
+      def initialize
+        @uuid = Helpers::UUID.new
+      end
+
+      def to_s
+        @uuid.to_s
+      end
+
+      def self.regexp
+        Helpers::UUID.regexp
+      end
+
+    end
+  end
+end

data/lib/dbd/fact/subject.rb

@@ -0,0 +1,21 @@
+require 'dbd/helpers/uuid'
+
+module Dbd
+  class Fact
+    class Subject
+
+      def initialize
+        @uuid = Helpers::UUID.new
+      end
+
+      def to_s
+        @uuid.to_s
+      end
+
+      def self.regexp
+        Helpers::UUID.regexp
+      end
+
+    end
+  end
+end

data/lib/dbd/graph.rb

@@ -0,0 +1,47 @@
+require 'csv'
+
+module Dbd
+
+  ##
+  # The Graph stores the Facts and ProvenanceFacts in an in-memory
+  # collection structure.
+  class Graph
+
+    include Fact::Collection
+
+    def <<(fact)
+      enforce_strictly_monotonic_time(fact)
+      super(fact)
+    end
+
+    ##
+    # Export the graph to a CSV string
+    #
+    # @return [String] comma separated string with double quoted cells
+    def to_CSV
+      CSV.generate(force_quotes: true) do |csv|
+        @internal_collection.each do |fact|
+          csv << fact.values
+        end
+      end.encode("utf-8")
+    end
+
+  private
+
+    ##
+    # The system mmust enforce that the time_stamps are strictly monotonic.
+    #
+    # This has been detected because on Java (JRuby) the the Wall time has
+    # a resolution of only 1 ms so sometimes, the exact same value for
+    # Time.now was reported.
+    def enforce_strictly_monotonic_time(fact)
+      new_time = Time.now.utc
+      newest_time_stamp = newest_time_stamp()
+      if newest_time_stamp && new_time <= newest_time_stamp
+        new_time = newest_time_stamp + 0.000_000_002 # Add approx. 2 nanoseconds
+      end
+      fact.time_stamp = new_time
+    end
+
+  end
+end

data/lib/dbd/helpers/ordered_set_collection.rb

@@ -0,0 +1,86 @@
+module Dbd
+  module Helpers
+
+    ##
+    # Transforms the mixing class into an OrderedSet.
+    #
+    # On the mixing class, enumerable functions are possible,
+    # looping over the set in O(n), but it is not intended
+    # that the mixing class allows arbitrary access into
+    # the collection.
+    #
+    # The *add_and_return_index* module method allows to get
+    # an index to an added element, so indexes can be
+    # built to access elements in O(1). The mixing class
+    # should not expose this index to the added element in
+    # it's public API. The goal is to allow other
+    # implementations (e.g. with Hadoop, Neo4j, ...) with
+    # the same API.
+    module OrderedSetCollection
+
+      include Enumerable
+
+      ##
+      # Creates @internal_collection in the mixing class.
+      def initialize
+        @internal_collection = []
+        super
+      end
+
+      ##
+      # Inserts an element at the end of the collection.
+      # Returns self to allow chaining.
+      # @param [Object] element
+      # @return [Object] self
+      def <<(element)
+        @internal_collection << element
+        self
+      end
+
+      ##
+      # For the Enumerable functionality.
+      def each
+        @internal_collection.each do |e|
+          yield e
+        end
+      end
+
+      ##
+      # This is required as an efficient way to find the last
+      # element without stepping through the entire collection.
+      # This implementation is probably not thread safe.
+      # @return [Object] the last element
+      def last
+        @internal_collection.last
+      end
+
+      ##
+      # This is required as an efficient way to find the size
+      # without stepping through the entire collection.
+      # This implementation is probably not thread safe.
+      # @return [Object] the last element
+      def size
+        @internal_collection.size
+      end
+
+      ##
+      # Adds an element at the end of the collection and
+      # returns the array index of that element.
+      #
+      # This is not an instance method to avoid it ending
+      # up in the public API of classes that mixin this module.
+      #
+      # The implementation to find the index of the inserted
+      # element with `rindex` is primitive, but I did not see
+      # a better way in Ruby to do this (using `size` would
+      # certainly be not thread safe, maybe the current
+      # approach is thread safe, but that is not tested).
+      # @return [Integer] index
+      def self.add_and_return_index(element, collection)
+        collection << element
+        collection.rindex(element)
+      end
+
+    end
+  end
+end

data/lib/dbd/helpers/uuid.rb

@@ -0,0 +1,33 @@
+require 'securerandom'
+
+module Dbd
+  module Helpers
+
+    ##
+    # A simple UUID implementation based on SecureRandom.
+    class UUID
+
+      ##
+      # A regexp that can be used in tests.
+      # @return [Regexp]
+      def self.regexp
+        /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/
+      end
+
+      ##
+      # Store a SecureRandom.uuid.
+      # @return [void]
+      def initialize
+        @uuid = SecureRandom.uuid
+      end
+
+      ##
+      # The to_s of the uuid.
+      # @return [String]
+      def to_s
+        @uuid.to_s
+      end
+
+    end
+  end
+end