Class: Dbd::Fact

Inherits:
Object
  • Object
show all
Defined in:
lib/dbd/fact.rb,
lib/dbd/fact/id.rb,
lib/dbd/fact/subject.rb,
lib/dbd/fact/collection.rb

Overview

Basic Fact of knowledge.

The database is built as an ordered sequence of facts, a "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 a fact stream).

  • a time_stamp (time with nanosecond granularity)

    To allow verifying that the order in a 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 a 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 a 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.

Direct Known Subclasses

ProvenanceFact

Defined Under Namespace

Modules: Collection Classes: ID, Subject

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ Fact

Builds a new Fact.

Parameters:

  • options (Hash{Symbol => Object})

Options Hash (options):

  • :predicate (#to_s) —

    Required : the predicate for this Fact

  • :object (#to_s) —

    Required : the object for this Fact (required)

  • :provenance_subject (Subject) — default: nil —

    Optional: the subject of the provenance(resource|fact)

  • :subject (Subject) — default: nil —

    Optional: the subject for this Fact

Raises:



126
127
128
129
130
131
132
133
134
 
# File 'lib/dbd/fact.rb', line 126

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

Class Method Details

.attributes ⇒ Array

Returns The 6 attributes of a Fact.

Returns:

  • (Array) —

    The 6 attributes of a Fact.



62
63
64
65
66
67
68
69
 
# File 'lib/dbd/fact.rb', line 62

def self.attributes
  [:id,
   :time_stamp,
   :provenance_subject,
   :subject,
   :predicate,
   :object]
end

.new_id ⇒ ID

Returns A new random id.

Returns:

  • (ID) —

    A new random id.



114
115
116
 
# File 'lib/dbd/fact.rb', line 114

def self.new_id
  ID.new
end

.new_subject ⇒ Subject

Returns A new random subject.

Returns:

  • (Subject) —

    A new random subject.



108
109
110
 
# File 'lib/dbd/fact.rb', line 108

def self.new_subject
  Subject.new
end

Instance Method Details

#errors ⇒ Array

Checks if a fact has errors for storing in the graph.

Returns:

  • (Array) —

    an Array of error messages



160
161
162
163
164
165
166
167
168
169
 
# File 'lib/dbd/fact.rb', line 160

def errors
  # * id not validated, is set automatically upon creation
  # * time_stamp not validated, is set automatically later
  # * predicate not validated, is validated in initialize
  # * object not validated, is validated in initialize
  [].tap do |a|
    a << provenance_subject_error(provenance_subject)
    a << "Subject is missing" unless subject
  end.compact
end

#provenance_subject=(provenance_subject) ⇒ Object

A set_once setter for provenance_subject.

This implements a "form" of immutable behavior. The value can be set once (possibly after creation the object), but can never be changed after that.



102
103
104
 
# File 'lib/dbd/fact.rb', line 102

def provenance_subject=(provenance_subject)
  set_once(:provenance_subject, provenance_subject)
end

#provenance_subject_error(provenance_subject) ⇒ Object

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. Return [nil, String] nil or an error message

Parameters:

  • provenance_subject (#nil?) 


180
181
182
 
# File 'lib/dbd/fact.rb', line 180

def provenance_subject_error(provenance_subject)
  "Provenance subject is missing" unless provenance_subject
end

#subject=(subject) ⇒ Object

A set_once setter for subject.

This implements a "form" of immutable behavior. The value can be set once (possibly after creation the object), but can never be changed after that.



92
93
94
 
# File 'lib/dbd/fact.rb', line 92

def subject=(subject)
  set_once(:subject, subject)
end

#time_stamp=(time_stamp) ⇒ Object

A set_once setter for time_stamp.

This implements a "form" of immutable behavior. The value can be set once (possibly after creation the object), but can never be changed after that.

Raises:

  • (ArgumentError) 


81
82
83
84
 
# File 'lib/dbd/fact.rb', line 81

def time_stamp=(time_stamp)
  raise ArgumentError unless time_stamp.is_a?(TimeStamp)
  set_once(:time_stamp, time_stamp)
end

#update_used_provenance_subjects(h) ⇒ Object

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.



151
152
153
154
 
# File 'lib/dbd/fact.rb', line 151

def update_used_provenance_subjects(h)
  # using a provenance_subject sets the key
  h[provenance_subject] = true
end

#values ⇒ Array

Returns The 6 values of a Fact.

Returns:

  • (Array) —

    The 6 values of a Fact.



138
139
140
 
# File 'lib/dbd/fact.rb', line 138

def values
  self.class.attributes.map{ |attribute| self.send(attribute) }
end