activefacts 0.7.0 → 0.7.1

data/lib/activefacts/persistence.rb

@@ -1,3 +1,8 @@
+#
+#       ActiveFacts Relational mapping and persistence.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
 require 'activefacts/persistence/reference'
 require 'activefacts/persistence/tables'
 require 'activefacts/persistence/columns'

data/lib/activefacts/persistence/columns.rb

@@ -1,4 +1,9 @@
 #
+#       ActiveFacts Relational mapping and persistence.
+#       Columns in a relational table; each is derived from a sequence of References.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
 # Each Reference from a Concept creates one or more Columns.
 # A reference to a simple valuetype creates a single column, as
 # does a reference to a table entity identified by a single value.
@@ -10,15 +15,18 @@
 # table, a reference to that entity creates multiple columns,
 # a multi-part foreign key.
 #
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
-#
 
 module ActiveFacts
-  module Metamodel
+  module Persistence    #:nodoc:
 
     class Column
-      attr_reader :references
+      include Metamodel
+
+      def initialize(reference = nil) #:nodoc:
+        references << reference if reference
+      end
 
+      # A Column is created from a path through an array of References to a ValueType
       def references
         @references ||= []
       end
@@ -33,6 +41,7 @@ module ActiveFacts
         end
       end
 
+      # How many of the initial references are involved in full absorption of an EntityType into this column's table
       def absorption_level
         l = 0
         @references.detect do |ref|
@@ -42,15 +51,13 @@ module ActiveFacts
         l
       end
 
-      def initialize(reference = nil)
-        references << reference if reference
-      end
-
-      def prepend reference
+      def prepend reference           #:nodoc:
         references.insert 0, reference
         self
       end
 
+      # A Column name is a sequence of names (derived from the to_roles of the References)
+      # joined by a joiner string (pass nil to get the original array of names)
       def name(joiner = "")
         last_name = ""
         names = @references.
@@ -61,7 +68,7 @@ module ActiveFacts
               ref.to and
               ref.to.is_a?(EntityType) and
               (role_refs = ref.to.preferred_identifier.role_sequence.all_role_ref).size == 1 and
-              role_refs[0].role == ref.from_role
+              role_refs.only.role == ref.from_role
           end.
           inject([]) do |a, ref|
             names = ref.to_names
@@ -85,7 +92,7 @@ module ActiveFacts
         if names.size > 1 and
             (et = @references.last.from).is_a?(EntityType) and
             (role_refs = et.preferred_identifier.role_sequence.all_role_ref).size == 1 and
-            role_refs[0].role == @references.last.to_role and
+            role_refs.only.role == @references.last.to_role and
             names.last[0...et.name.size].downcase == et.name.downcase
           names[-1] = names.last[et.name.size..-1]
           names.pop if names.last == ''
@@ -95,14 +102,17 @@ module ActiveFacts
         joiner ? name_array * joiner : name_array
       end
 
+      # Is this column mandatory or nullable?
       def is_mandatory
         !@references.detect{|ref| !ref.is_mandatory}
       end
 
+      # Is this column an auto-assigned value type?
       def is_auto_assigned
         (to = references[-1].to) && to.is_auto_assigned
       end
 
+      # What's the underlying SQL data type of this column?
       def type
         params = {}
         restrictions = []
@@ -126,6 +136,7 @@ module ActiveFacts
         return [vt.name, params, restrictions]
       end
 
+      # The comment is the readings from the References expressed as a join
       def comment
         @references.map do |ref|
           (ref.is_mandatory ? "" : "maybe ") +
@@ -134,13 +145,13 @@ module ActiveFacts
         end * " and "
       end
 
-      def to_s
+      def to_s  #:nodoc:
         "#{@references[0].from.name} column #{name('.')}"
       end
     end
 
     class Reference
-      def columns(excluded_supertypes)
+      def columns(excluded_supertypes)  #:nodoc:
         kind = ""
         cols = 
           if is_unary
@@ -167,16 +178,24 @@ module ActiveFacts
         end
       end
     end
+  end
 
+  module Metamodel    #:nodoc:
+    # The Concept class is defined in the metamodel; full documentation is not generated.
+    # This section shows the features relevant to relational Persistence.
     class Concept
-      attr_accessor :columns
+      # The array of columns for this Concept's table
+      def columns; @columns; end
 
-      def populate_columns
+      def populate_columns  #:nodoc:
         @columns = all_columns({})
       end
     end
 
-    class ValueType
+    # The ValueType class is defined in the metamodel; full documentation is not generated.
+    # This section shows the features relevant to relational Persistence.
+    class ValueType < Concept
+      # The identifier_columns for a ValueType can only ever be the self-value role that was injected
       def identifier_columns
         debug :columns, "Identifier Columns for #{name}" do
           raise "Illegal call to identifier_columns for absorbed ValueType #{name}" unless is_table
@@ -184,23 +203,27 @@ module ActiveFacts
         end
       end
 
-      def reference_columns(excluded_supertypes)
+      # When creating a foreign key to this ValueType, what columns must we include?
+      # This must be a fresh copy, because the columns will have References prepended
+      def reference_columns(excluded_supertypes)  #:nodoc:
         debug :columns, "Reference Columns for #{name}" do
           if is_table
-            [Column.new(self_value_reference)]
+            [ActiveFacts::Persistence::Column.new(self_value_reference)]
           else
-            [Column.new]
+            [ActiveFacts::Persistence::Column.new]
           end
         end
       end
 
-      def all_columns(excluded_supertypes)
+      # When absorbing this ValueType, what columns must be absorbed?
+      # This must be a fresh copy, because the columns will have References prepended.
+      def all_columns(excluded_supertypes)    #:nodoc:
         columns = []
         debug :columns, "All Columns for #{name}" do
           if is_table
             self_value_reference
           else
-            columns << Column.new
+            columns << ActiveFacts::Persistence::Column.new
           end
           references_from.each do |ref|
             debug :columns, "Columns absorbed via #{ref}" do
@@ -211,19 +234,23 @@ module ActiveFacts
         columns
       end
 
-      def self_value_reference
+      # If someone asks for this, it's because it's needed, so create it.
+      def self_value_reference  #:nodoc:
         # Make a reference for the self-value column
-        @self_value_reference ||= Reference.new(self, nil).tabulate
+        @self_value_reference ||= ActiveFacts::Persistence::Reference.new(self, nil).tabulate
       end
     end
 
-    class EntityType
+    # The EntityType class is defined in the metamodel; full documentation is not generated.
+    # This section shows the features relevant to relational Persistence.
+    class EntityType < Concept
+      # The identifier_columns for an EntityType are the columns that result from the identifying roles
       def identifier_columns
         debug :columns, "Identifier Columns for #{name}" do
           if absorbed_via and
             # If this is a subtype that has its own identification, use that.
-            (all_type_inheritance_by_subtype.size == 0 ||
-              all_type_inheritance_by_subtype.detect{|ti| ti.provides_identification })
+            (all_type_inheritance_as_subtype.size == 0 ||
+              all_type_inheritance_as_subtype.detect{|ti| ti.provides_identification })
             return absorbed_via.from.identifier_columns
           end
 
@@ -235,13 +262,15 @@ module ActiveFacts
         end
       end
 
-      def reference_columns(excluded_supertypes)
+      # When creating a foreign key to this EntityType, what columns must we include (the identifier columns)?
+      # This must be a fresh copy, because the columns will have References prepended
+      def reference_columns(excluded_supertypes)    #:nodoc:
         debug :columns, "Reference Columns for #{name}" do
 
           if absorbed_via and
             # If this is a subtype that has its own identification, use that.
-            (all_type_inheritance_by_subtype.size == 0 ||
-              all_type_inheritance_by_subtype.detect{|ti| ti.provides_identification })
+            (all_type_inheritance_as_subtype.size == 0 ||
+              all_type_inheritance_as_subtype.detect{|ti| ti.provides_identification })
             return absorbed_via.from.reference_columns(excluded_supertypes)
           end
 
@@ -257,7 +286,9 @@ module ActiveFacts
         end
       end
 
-      def all_columns(excluded_supertypes)
+      # When absorbing this EntityType, what columns must be absorbed?
+      # This must be a fresh copy, because the columns will have References prepended.
+      def all_columns(excluded_supertypes)    #:nodoc:
         debug :columns, "All Columns for #{name}" do
           columns = []
           sups = supertypes
@@ -287,15 +318,18 @@ module ActiveFacts
       end
     end
 
+    # The Vocabulary class is defined in the metamodel; full documentation is not generated.
+    # This section shows the features relevant to relational Persistence.
     class Vocabulary
-      # Do things like adding ID fields and ValueType self-value columns
+      # Make schema transformations like adding ValueType self-value columns (and later, Rails-friendly ID fields).
+      # Override this method to change the transformations
       def finish_schema
         all_feature.each do |feature|
           feature.self_value_reference if feature.is_a?(ValueType) && feature.is_table
         end
       end
 
-      def populate_all_columns
+      def populate_all_columns  #:nodoc:
         # REVISIT: Is now a good time to apply schema transforms or should this be more explicit?
         finish_schema
 

data/lib/activefacts/persistence/foreignkey.rb

@@ -1,15 +1,38 @@
+#
+#       ActiveFacts Relational mapping and persistence.
+#       A ForeignKey exists for every Reference from a Concept to another Concept that's a table.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
 module ActiveFacts
-  module Metamodel
-
+  module Persistence
     class ForeignKey
-      attr_reader :from, :to, :reference, :from_columns, :to_columns
-      def initialize(from, to, fk_ref, from_columns, to_columns)
+      # What table (Concept) is the FK from?
+      def from; @from; end
+
+      # What table (Concept) is the FK to?
+      def to; @to; end
+
+      # What reference created the FK?
+      def reference; @reference; end
+
+      # What columns in the *from* table form the FK
+      def from_columns; @from_columns; end
+
+      # What columns in the *to* table form the identifier
+      def to_columns; @to_columns; end
+
+      def initialize(from, to, fk_ref, from_columns, to_columns) #:nodoc:
         @from, @to, @fk_ref, @from_columns, @to_columns =
           from, to, fk_ref, from_columns, to_columns
       end
     end
+  end
 
+  module Metamodel    #:nodoc:
     class Concept
+      # When an EntityType is fully absorbed, its foreign keys are too.
+      # Return an Array of Reference paths for such absorbed FKs
       def all_absorbed_foreign_key_reference_path
         references_from.inject([]) do |array, ref|
           if ref.is_simple_reference
@@ -23,6 +46,7 @@ module ActiveFacts
         end
       end
 
+      # Return an array of all the foreign keys from this table
       def foreign_keys
         fk_ref_paths = all_absorbed_foreign_key_reference_path
 
@@ -78,7 +102,7 @@ module ActiveFacts
             end
             debug :fk, "to_columns in #{to.name}: #{to_columns.map { |column| column ? column.name : "OOPS!" }*", "}"
 
-            ForeignKey.new(self, to, fk_ref_path[-1], from_columns, to_columns)
+            ActiveFacts::Persistence::ForeignKey.new(self, to, fk_ref_path[-1], from_columns, to_columns)
           end
         end
       end

data/lib/activefacts/persistence/index.rb

@@ -1,31 +1,49 @@
 #
-# An Index on a Concept is used to represent a unique constraint across roles absorbed
-# into that concept's table.
+#       ActiveFacts Relational mapping and persistence.
+#       An Index on a Concept is used to represent a unique constraint across roles absorbed
+#       into that concept's table.
 #
-# Reference objects update each concept's list of the references *to* and *from* that concept.
-#
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 
 module ActiveFacts
-  module Metamodel
+  module Persistence
     class Index
-      attr_reader :uniqueness_constraint, :on, :over, :columns, :is_primary, :is_unique
+      # The UniquenessConstraint that created this index
+      def uniqueness_constraint; @uniqueness_constraint; end
+
+      # The table that the index is on
+      def on; @on; end
+
+      # If a non-mandatory reference was absorbed, only the non-nil instances are unique.
+      # Return the Concept that was absorbed, which might differ from this Index's table.
+      def over; @over; end
+
+      # Return the array of columns in this index
+      def columns; @columns; end
+
+      # Is this index the primary key for this table?
+      def is_primary; @is_primary; end
+
+      # Is this index unique?
+      def is_unique; @is_unique; end
 
       # An Index arises from a uniqueness constraint and applies to a table,
       # but because the UC may actually be over an object absorbed into the table,
       # we must record that object also.
       # We record the columns it's over, whether it's primary (for 'over'),
       # and whether it's unique (always, at present)
-      def initialize(uc, on, over, columns, is_primary, is_unique = true)
+      def initialize(uc, on, over, columns, is_primary, is_unique = true)   #:nodoc:
         @uniqueness_constraint, @on, @over, @columns, @is_primary, @is_unique =
           uc, on, over, columns, is_primary, is_unique
       end
 
+      # The name that was assigned (perhaps implicitly by NORMA)
       def real_name
         @uniqueness_constraint.name && @uniqueness_constraint.name != '' ? @uniqueness_constraint.name : nil
       end
 
+      # This name is either the name explicitly assigned (if any) or is constructed to form a unique index name.
       def name
         uc = @uniqueness_constraint
         r = real_name
@@ -35,35 +53,41 @@ module ActiveFacts
           (uc.is_preferred_identifier ? "" : "By"+column_names*"")
       end
 
-      def abbreviated_column_names
-        columns.map{|column| column.name.sub(/^#{over.name}/,'')}
-      end
-
+      # An array of the names of the columns this index covers
       def column_names
         columns.map{|column| column.name}
       end
 
+      # An array of the names of the columns this index covers, with some lexical truncations.
+      def abbreviated_column_names
+        columns.map{|column| column.name.sub(/^#{over.name}/,'')}
+      end
+
+      # The name of a view that can be created to enforce uniqueness over non-null key values
       def view_name
         "#{over.name}#{on == over ? "" : "In"+on.name}"
       end
 
-      def to_s
+      def to_s  #:nodoc:
         name = @uniqueness_constraint.name
         colnames = @columns.map(&:name)*", "
         preferred = @uniqueness_constraint.is_preferred_identifier ? " (preferred)" : ""
         "Index #{name} on #{@on.name} over #{@over.name}(#{colnames})#{preferred}"
       end
     end
+  end
 
+  module Metamodel    #:nodoc:
     class Concept
-      attr_reader :indices
+      # An array of each Index for this table
+      def indices; @indices; end
 
-      def clear_indices
+      def clear_indices     #:nodoc:
         # Clear any previous indices
         @indices = nil
       end
 
-      def populate_indices
+      def populate_indices     #:nodoc:
         # The absorption path of a column indicates how it came to be in this table.
         # It might be a direct many:one valuetype relationship, or it might be in such
         # a relationship to an entity that was absorbed into this table (and so on).
@@ -96,14 +120,20 @@ module ActiveFacts
                       !pc.max_frequency or      # No maximum freq; cannot be a uniqueness constraint
                       pc.max_frequency != 1 or  # maximum is not 1
                       pc.role_sequence.all_role_ref.size == 1 &&        # UniquenessConstraint is over one role
-                        (pc.role_sequence.all_role_ref[0].role.fact_type.is_a?(TypeInheritance) ||      # Inheritance
-                        pc.role_sequence.all_role_ref[0].role.fact_type.all_role.size == 1)             # Unary
+                        ((fact_type = pc.role_sequence.all_role_ref.only.role.fact_type).is_a?(TypeInheritance) ||      # Inheritance
+                        fact_type.all_role.size == 1)             # Unary
                         # The preceeeding two restrictions exclude the internal UCs created within NORMA.
                     end
                   next unless pcs.size > 0
                   # The columns for this ref_path support the UCs in "pcs".
                   pcs.each do |pc|
-                    (columns_by_unique_constraint[pc] ||= []).concat(all_column_by_ref_path[ref_path])
+                    ref_columns = all_column_by_ref_path[ref_path]
+                    ordinal = role_ref.ordinal  # Position in priority order
+                    ref_columns.each_with_index do |column, index|
+                      #puts "Adding index column #{column.name} in rank[#{ordinal},#{index}]"
+                      # REVISIT: the "index" here might be a duplicate in some cases: change sort_by below to just sort and run the SeparateSubtypes CQL model for example.
+                      (columns_by_unique_constraint[pc] ||= []) << [ordinal, index, column]
+                    end
                   end
                   hash[role_ref] = all_column_by_ref_path[ref_path]
                 end
@@ -112,17 +142,19 @@ module ActiveFacts
             end
 
         debug :index, "All Indices in #{name}:" do
-          @indices = columns_by_unique_constraint.map do |uc, columns|
+          @indices = columns_by_unique_constraint.map do |uc, columns_with_ordinal|
+            #puts "Index on #{name} over (#{columns_with_ordinal.sort.map{|ca| [ca[0], ca[1], ca[2].name].inspect}})"
+            columns = columns_with_ordinal.sort_by{|ca| [ca[0,2], ca[2].name]}.map{|ca| ca[2]}
             absorption_level = columns.map(&:absorption_level).min
             over = columns[0].references[absorption_level].from
 
             # Absorption through a one-to-one forms a UC that we don't need to enforce using an index:
-            next if over != self and
+            next nil if over != self and
               over.absorbed_via == columns[0].references[absorption_level-1] and
               (rrs = uc.role_sequence.all_role_ref).size == 1 and
-              over.absorbed_via.fact_type.all_role.include?(rrs[0].role)
+              over.absorbed_via.fact_type.all_role.include?(rrs.only.role)
 
-            index = Index.new(
+            index = ActiveFacts::Persistence::Index.new(
               uc,
               self,
               over,
@@ -131,14 +163,14 @@ module ActiveFacts
             )
             debug :index, index
             index
-          end
+          end.compact
         end
       end
 
     end
 
     class Vocabulary
-      def populate_all_indices
+      def populate_all_indices  #:nodoc:
         debug :index, "Populating all concept indices" do
           all_feature.each do |feature|
             next unless feature.is_a? Concept