flexirecord 0.0.3 → 0.0.4

data/CHANGELOG

@@ -0,0 +1,15 @@
+
+CHANGELOG for FlexiRecord:
+
+2007-02-10:
+- Changed the order of arguments passed to FlexiRecord::Reference#combine to match the documentation and renamed the method to FlexiRecord::Reference#connect.
+- Minor bugfix in FlexiRecord::Relationship#new
+- Added FlexiRecord::BaseRecord.add_connected_references as a more simple way to add many-to-many relations.
+
+2007-02-11:
+- Renamed the word 'column' to 'attr' or 'attribute' at several places in the code and documentation.
+- Freezed record arrays, which are fetched through attributes for many-to-one or many-to-many relations.
+- Added a lock method, to lock tables in a nicier way.
+
+Release of version 0.0.4.
+

data/lib/flexirecord-demo.rb

@@ -70,9 +70,9 @@ module FlexiRecordDemo
   class MediumEntry < FlexiRecord::BaseRecord
     include FlexiRecord::ListRecord
     self.table_name = 'medium_entry'
-    add_many_to_one_reference(Medium, 'medium_', :medium, :entries).combine(
-      add_many_to_one_reference(Movie, 'movie_', :movie, :movie_entries),
-      :media, :movies
+    add_connected_references(
+      Medium, 'medium_', :medium, :entries, :movies,
+      Movie, 'movie_', :movie, :movie_entries, :media
     )
     Medium.add_read_option :entries, :default, 'ORDER BY "position"'
     Medium.add_read_option :movies,  :default, 'ORDER BY "rel"."position"'
@@ -83,9 +83,9 @@ module FlexiRecordDemo
   # CREATE TABLE "rating" ("person_id" int8 not null references "person" ("id") on delete cascade on update cascade, "movie_id" int8 not null references "movie" ("id") on delete cascade on update cascade, "rating" numeric, "comment" text, PRIMARY KEY ("person_id", "movie_id") );
   class Rating < FlexiRecord::Relationship
     self.table_name = 'rating'
-    add_many_to_one_reference(Person, 'person_', :person, :ratings).combine(
-      add_many_to_one_reference(Movie, ['movie_id', 'id'], :movie, :ratings),
-      :rated_by, :rated_movies
+    add_connected_references(
+      Person, 'person_', :person, :ratings, :rated_movies,
+      Movie, ['movie_id', 'id'], :movie, :ratings, :rated_by
     )
   end
 

data/lib/flexirecord.rb

@@ -104,23 +104,81 @@ module FlexiRecord
       self.to_i <=> other.to_i
     end
 
-    ReadUncommitted = new(0, :read_uncommitted, "READ UNCOMMITTED", "ReadUncommitted")
-    ReadCommitted   = new(1, :read_committed,   "READ COMMITTED",   "ReadCommitted")
-    RepeatableRead  = new(2, :repeatable_read,  "REPEATABLE READ",  "RepeatableRead")
-    Serializable    = new(3, :serializable,     "SERIALIZABLE",     "Serializable")
+    ReadUncommitted = new(0, :read_uncommitted, 'READ UNCOMMITTED', 'ReadUncommitted')
+    ReadCommitted   = new(1, :read_committed,   'READ COMMITTED',   'ReadCommitted')
+    RepeatableRead  = new(2, :repeatable_read,  'REPEATABLE READ',  'RepeatableRead')
+    Serializable    = new(3, :serializable,     'SERIALIZABLE',     'Serializable')
 
   end  # end of class IsolationLevel
 
 
-  # Objects of this class are used to describe a reference between two tables. You can create and register them by calling BaseRecord::add_many_to_one_reference or RaseRecord::add_one_to_one_reference.
+  # Table lock modes are represented by (constant) LockMode objects:
+  # - LockMode::AccessShare
+  #   (Acquired by any read operation.)
+  # - LockMode::RowShare
+  #   (Acquired for any row-locking operation.)
+  # - LockMode::RowExclusive
+  #   (Acquired when data in a table is modified.)
+  # - LockMode::ShareUpdateExclusive
+  # - LockMode::Share
+  #   (Prohibits data changes in the table.)
+  # - LockMode::ShareRowExclusive
+  #   (Prohibits data changes and other Share or ShareRowExclusive locks. Used instead of LockMode::Share to prohibit dead locks.)
+  # - LockMode::Exclusive
+  #   (Prohibits anything else than reading from the table.)
+  # - LockMode::AccessExclusive
+  #   (Prohibits any other access to the table.)
+
+  class LockMode
+
+    private_class_method :new
+    @@symbols = {}
+
+    # Returns a LockMode object, matching the given symbol.
+    def self.by_symbol(symbol)
+      @@symbols[symbol.to_sym]
+    end
+
+    # Used for generating the constants representing the possible table lock modes.
+    def initialize(symbol, sql, name)
+      @symbol  = symbol.to_sym
+      @sql     = sql.to_s.dup.freeze
+      @name    = name.to_s.dup.freeze
+      @@symbols[@symbol] = self
+      nil
+    end
+
+    # Returns the SQL string representation of the lock mode.
+    def to_s
+      @sql
+    end
+
+    # Returns the name of the constant referring to the lock mode.
+    def inspect
+      "#{self.class.name}::#{@name}"
+    end
+
+    AccessShare          = new(:access_share,           'ACCESS SHARE MODE',           'AccessShare')
+    RowShare             = new(:row_share,              'ROW SHARE MODE',              'RowShare')
+    RowExclusive         = new(:row_exclusive,          'ROW EXCLUSIVE MODE',          'RowExclusive')
+    ShareUpdateExclusive = new(:share_update_exclusive, 'SHARE UPDATE EXCLUSIVE MODE', 'ShareUpdateExclusive')
+    Share                = new(:share,                  'SHARE MODE',                  'Share')
+    ShareRowExclusive    = new(:share_row_exclusive,    'SHARE ROW EXCLUSIVE MODE',    'ShareRowExclusive')
+    Exclusive            = new(:exclusive,              'EXCLUSIVE MODE',              'Exclusive')
+    AccessExclusive      = new(:access_exclusive,       'ACCESS EXCLUSIVE MODE',       'AccessExclusive')
+
+  end  # end of class LockMode
+
+
+  # Objects of this class are used to describe a reference between two tables. You can create and register them by calling FlexiRecord::BaseRecord.add_many_to_one_reference or FlexiRecord::RaseRecord.add_one_to_one_reference. For using many-to-many relationships you have to extend the class FlexiRecord::Relationship and create two connected ManyToOneReference's for that class by calling FlexiRecord::BaseRecord.add_connected_references.
 
   class Reference
 
     private_class_method :new
 
-    # Returns a new reference object, describing a relation where objects of the 'source_class' refer to objects of the 'destination_class'. The 'column_info' field describes the columns used for that reference. If the 'column_info' field is a string, the primary key is used in the destination class, and the primary key prefixed by the string given in 'column_info' is used as the foreign key in the source class. If 'column_info' is an array, it contains the columns in the source class, followed by the columsn in the destination class. The field 'src_to_dst_column' contains the name of the column in the source class, which is referring to one object of the destination class. The field 'dst_to_src_column' contains the name of the column in the destination class, which is referring to one or many objects of the source class. After the reference has been created reader, loader and setter functions are added to the 'source_class' and 'destination_class', to provide access to referenced and referring objects.
+    # Returns a new reference object, describing a relation where objects of the 'source_class' refer to objects of the 'destination_class'. The 'column_info' field describes the columns used for that reference. If the 'column_info' field is a string, the primary key is used in the destination class, and the primary key prefixed by the string given in 'column_info' is used as the foreign key in the source class. If 'column_info' is an array, it contains the columns in the source class, followed by the columns in the destination class. The field 'src_to_dst_attr' contains the name of the attribute in the source class, which is referring to one object of the destination class. The field 'dst_to_src_attr' contains the name of the attribute in the destination class, which is referring to one or many objects of the source class. After the reference has been created, reader, loader and setter functions are added to the 'source_class' and 'destination_class', to provide access to referenced and referring objects.
     # This method is private, use one of the child classes OneToOneReference or ManyToOneReference, which get the same arguments, to generate references of a given type.
-    def initialize(source_class, destination_class, column_info, src_to_dst_column, dst_to_src_column)
+    def initialize(source_class, destination_class, column_info, src_to_dst_attr, dst_to_src_attr)
       unless source_class.kind_of? Class and destination_class.kind_of? Class
         raise TypeError, "Class expected"
       end
@@ -146,10 +204,10 @@ module FlexiRecord
       end
       @source_columns.freeze
       @destination_columns.freeze
-      @src_to_dst_column = src_to_dst_column.to_s.dup.freeze
-      @dst_to_src_column = dst_to_src_column.to_s.dup.freeze
+      @src_to_dst_attr = src_to_dst_attr.to_s.dup.freeze
+      @dst_to_src_attr = dst_to_src_attr.to_s.dup.freeze
       # Work at the source class:
-      @source_class.set_loader(@src_to_dst_column) do |source_records, arguments|
+      @source_class.set_loader(@src_to_dst_attr) do |source_records, arguments|
         unless arguments.empty?
           raise ArgumentError, "No extra arguments may be specified for outgoing reference columns."
         end
@@ -164,15 +222,15 @@ module FlexiRecord
         destination_records.each do |destination_record|
           destination_record_hash[@destination_columns.collect { |column| destination_record[column] }] = destination_record
           if self.one_to_one?
-            destination_record[@dst_to_src_column] = nil
+            destination_record[@dst_to_src_attr] = nil
           end
         end
         source_records.each do |source_record|
           destination_record = 
             destination_record_hash[@source_columns.collect { |column| source_record[column] }]
-          source_record[@src_to_dst_column, *arguments] = destination_record
+          source_record[@src_to_dst_attr, *arguments] = destination_record
           if destination_record and self.one_to_one?
-            destination_record[@dst_to_src_column] = source_record
+            destination_record[@dst_to_src_attr] = source_record
           end
         end
         next destination_records
@@ -181,28 +239,28 @@ module FlexiRecord
         source_column = @source_columns[column_index]
         destination_column = @destination_columns[column_index]
         @source_class.set_reader(source_column) do |source_record, arguments|
-          destination_record = source_record[@src_to_dst_column]
+          destination_record = source_record[@src_to_dst_attr]
           next destination_record ? destination_record[destination_column] : source_record[source_column]
         end
         @source_class.set_setter(source_column) do |source_record, value|
-          source_record.delete_from_cache(@src_to_dst_column)
+          source_record.delete_from_cache(@src_to_dst_attr)
           source_record[source_column] = value
         end
       end
       if self.one_to_one?
-        @source_class.set_setter(@src_to_dst_column) do |source_record, value|
-          old_destination_record = source_record[@src_to_dst_column]
+        @source_class.set_setter(@src_to_dst_attr) do |source_record, value|
+          old_destination_record = source_record[@src_to_dst_attr]
           if old_destination_record
-            old_destination_record[@dst_to_src_column] = nil
+            old_destination_record[@dst_to_src_attr] = nil
           end
-          source_record[@src_to_dst_column] = value
+          source_record[@src_to_dst_attr] = value
           if value
-            value[@dst_to_src_column] = source_record
+            value[@dst_to_src_attr] = source_record
           end
         end
       end
       # Work at the destination class:
-      @destination_class.set_loader(@dst_to_src_column) do |destination_records, arguments|
+      @destination_class.set_loader(@dst_to_src_attr) do |destination_records, arguments|
         unless arguments.empty?
           unless arguments[0].respond_to? :to_str
             raise "First argument of reader method is not a SQL snippet string."
@@ -219,7 +277,7 @@ module FlexiRecord
         destination_record_hash = {}
         destination_records.each do |destination_record|
           destination_record_hash[@destination_columns.collect { |column| destination_record[column] }] = destination_record
-          destination_record[@dst_to_src_column, *arguments] =
+          destination_record[@dst_to_src_attr, *arguments] =
             if self.many_to_one?
               FlexiRecord::RecordArray.new(@source_class)
             else
@@ -228,49 +286,54 @@ module FlexiRecord
         end
         source_records.each do |source_record|
           destination_record = destination_record_hash[@source_columns.collect { |column| source_record[column] }]
-          source_record[@src_to_dst_column] = destination_record
+          source_record[@src_to_dst_attr] = destination_record
           if destination_record
             if self.many_to_one?
-              destination_record[@dst_to_src_column, *arguments] << source_record
+              destination_record[@dst_to_src_attr, *arguments] << source_record
             else
-              destination_record[@dst_to_src_column, *arguments] = source_record
+              destination_record[@dst_to_src_attr, *arguments] = source_record
             end
           end
         end
+        if self.many_to_one?
+          destination_records.each do |destination_record|
+            destination_record[@dst_to_src_attr, *arguments].freeze
+          end
+        end
         next source_records
       end
       if self.one_to_one?
-        @destination_class.set_setter(@dst_to_src_column) do |destination_record, value|
-          old_source_record = destination_record[@dst_to_src_column]
+        @destination_class.set_setter(@dst_to_src_attr) do |destination_record, value|
+          old_source_record = destination_record[@dst_to_src_attr]
           if old_source_record
-            old_source_record[@src_to_dst_column] = nil
+            old_source_record[@src_to_dst_attr] = nil
           end
-          destination_record[@dst_to_src_column] = value
+          destination_record[@dst_to_src_attr] = value
           if value
-            value[@src_to_dst_column] = destination_record
+            value[@src_to_dst_attr] = destination_record
           end
         end
       end
       return self
     end
 
-    # Combines two ManyToOneReference's to a many-to-many relation. 'other_reference' is another Reference object (as returned by Reference#new, BaseRecord#add_many_to_one_reference or BaseRecord#add_one_to_one_reference), 'own_column' is the virtual column to be installed in the destination_class of this object and 'other_column' is the virtual column to be installed in the destination_class of the 'other_reference' object.
-    def combine(other_reference, own_column, other_column)
+    # Connects two ManyToOneReference's to form a many-to-many relation. 'other_reference' is another Reference object (as returned by FlexiRecord::Reference.new, 'own_attr' is the attribute to be installed in the destination_class of this Reference object for accessing objects of the destination_class of the 'other_reference' object, and 'other_attr' is the attribute to be installed in the destination_class of the 'other_reference' object for accessing objects of the destination_class of this Reference object.
+    def connect(other_reference, own_attr, other_attr)
       unless other_reference.kind_of? FlexiRecord::Reference
         raise TypeError, "Object of class FlexiRecord::Reference expected."
       end
       reference1 = self
       reference2 = other_reference
-      column1 = own_column.to_s
-      column2 = other_column.to_s
+      attr1 = own_attr.to_s
+      attr2 = other_attr.to_s
       unless self.source_class == other_reference.source_class
         "Combining references having different source classes is not possible."
       end
       relationship_class = self.source_class
       [
-        [reference1, reference2, column1, column2],
-        [reference2, reference1, column2, column1]
-      ].each do |source_reference, destination_reference, source_column, destination_column|
+        [reference1, reference2, attr1, attr2],
+        [reference2, reference1, attr2, attr1]
+      ].each do |source_reference, destination_reference, source_attr, destination_attr|
         source_class = source_reference.destination_class
         destination_class = destination_reference.destination_class
         tmp1 = []
@@ -280,7 +343,7 @@ module FlexiRecord
             destination_reference.destination_columns[column_index]
           ]
         end
-        source_class.set_loader destination_column do |source_records, arguments|
+        source_class.set_loader source_attr do |source_records, arguments|
           sql_arguments = arguments.dup
           sql_snippet = sql_arguments.shift
           unless sql_snippet.nil?
@@ -307,7 +370,7 @@ module FlexiRecord
                 destination_record['_flexirecord_rel_' << column]
               }
             ] ||= FlexiRecord::RecordArray.new(destination_class)) << destination_record
-            relationship_hash = { destination_reference.src_to_dst_column => destination_record }
+            relationship_hash = { destination_reference.src_to_dst_attr => destination_record }
             relationship_class.columns.each do |column|
               relationship_hash[column] =
               destination_record.delete_from_cache("_flexirecord_rel_#{column}")
@@ -315,13 +378,18 @@ module FlexiRecord
             destination_record[FlexiRecord::RelationshipColumn] = relationship_class.new(relationship_hash)
           end
           source_records.each do |source_record|
-            source_record[destination_column, *arguments] = (destination_record_hash[source_reference.destination_columns.collect { |column| source_record[column] } ]) || FlexiRecord::RecordArray.new(destination_class)
+            source_record[source_attr, *arguments] = ((destination_record_hash[source_reference.destination_columns.collect { |column| source_record[column] } ]) || FlexiRecord::RecordArray.new(destination_class)).freeze
           end
           next destination_records
         end
       end
     end
 
+    # Deprecated. Use FlexiRecord::Reference#connect instead.
+    def combine(*arguments)
+      self.connect(*arguments)
+    end
+
     # Class, whose objects are referring to others.
     attr_reader :source_class
 
@@ -334,11 +402,11 @@ module FlexiRecord
     # Columns in the referred class, providing a unique or primary key.
     attr_reader :destination_columns
 
-    # Name (String) of the column in the source class, which is referring to one object of the destination class.
-    attr_reader :src_to_dst_column
+    # Name (String) of the attribute in the source class, which is referring to one object of the destination class.
+    attr_reader :src_to_dst_attr
 
-    # Name (String) of the column in the destination class, which is referring to one or many objects of the source class.
-    attr_reader :dst_to_src_column
+    # Name (String) of the attribute in the destination class, which is referring to one or many objects of the source class.
+    attr_reader :dst_to_src_attr
 
     # Returns true, if the object describes a one-to-one relation.
     def one_to_one?
@@ -383,7 +451,7 @@ module FlexiRecord
   end  # end of class ManyToOneReference
 
 
-  # An abstract record, super-class of all record classes. By now there is only one sub-class 'BaseRecord', which represents a record being directly stored in one database table. Other sub-classes might be added in near future, to be able to use inheritance of data models to be stored in the database using multiple tables in the backend for one model.
+  # An abstract record, super-class of all record classes. By now there is only one sub-class 'BaseRecord', which represents a record being directly stored in one database table. Other sub-classes might be added in future, to be able to use inheritance of data models.
 
   class AbstractRecord
 
@@ -408,18 +476,18 @@ module FlexiRecord
       @flexirecord_class
     end
 
-    # Preloads a virtualized column of an Array of records at once (without doing one SQL query for each record). Can return another RecordArray, which can be used for the next level of preloading.
-    def preload(column, *arguments)
-      column = column.to_s
-      @flexirecord_class.prepare_read_parameters(column, arguments)
-      cache_key = [column] + arguments
+    # Preloads the attribute named 'attr' in each record of the RecordArray, without doing one SQL query for each record. Can return another RecordArray, which can be used for the next level of preloading.
+    def preload(attr, *arguments)
+      attr = attr.to_s
+      @flexirecord_class.prepare_read_parameters(attr, arguments)
+      cache_key = [attr] + arguments
       if @flexirecord_preloaded.has_key?(cache_key)
         return @flexirecord_preloaded[cache_key]
       end
-      column = column.to_s
-      loader = self.record_class.loader(column)
+      attr = attr.to_s
+      loader = self.record_class.loader(attr)
       unless loader
-        raise ArgumentError, "Could not preload column '#{column}', due to missing loading procedure."
+        raise ArgumentError, "Could not preload attribute '#{attr}', due to missing loading procedure."
       end
       return @flexirecord_preloaded[cache_key] = loader.call(self, arguments)
     end
@@ -464,7 +532,7 @@ module FlexiRecord
         )
       end
 
-      # Returns the database schema name, even if no schema is set (in this case "public" is returned.
+      # Returns the database schema name, even if no schema is set (in this case "public" is returned).
       def schema_name!
         schema_name or "public".freeze
       end
@@ -562,6 +630,17 @@ module FlexiRecord
         result
       end
 
+      # Locks the table used to store objects of this class. Calling this command only makes sense, if a transaction is in progress.
+      def lock(mode)
+        if not mode.kind_of? FlexiRecord::LockMode and mode.respond_to? :to_sym
+          mode = FlexiRecord::LockMode.by_symbol(mode)
+        end
+        if mode.nil?
+          raise "Table lock mode expected"
+        end
+        db_execute("LOCK #{table} IN #{mode}")
+      end
+
       # Autodetects the columns (and primary key columns) of the underlaying table, to be later retrieved by the 'columns' and the 'primary_columns' methods.
       def autodetect_columns
         columns = []
@@ -682,22 +761,22 @@ module FlexiRecord
       # Adds a "shortcut" for a parameter to reader and loader functions.
       #
       # Example: List.add_read_option :items, :by_name, 'ORDER BY "name"'
-      def add_read_option(column, symbol, value)
+      def add_read_option(attr, symbol, value)
         unless symbol.kind_of? Symbol
           raise "Symbol expected as second argument to 'add_read_option'."
         end
-        (@read_options ||= {})[[column.to_s, symbol]] = value
+        (@read_options ||= {})[[attr.to_s, symbol]] = value
       end
 
       # Returns the value of a "shortcut" for a parameter to reader and loader functions.
-      def read_option_value(column, symbol)
-        value = (@read_options || {})[[column.to_s, symbol]] || ((superclass <= FlexiRecord::BaseRecord) ? superclass.read_option_value(column, symbol) : nil)
+      def read_option_value(attr, symbol)
+        value = (@read_options || {})[[attr.to_s, symbol]] || ((superclass <= FlexiRecord::BaseRecord) ? superclass.read_option_value(attr, symbol) : nil)
       end
 
       # Modifies a parameter array by replacing "shortcut" symbols being defined by add_read_option. Returns the parameter array.
-      def prepare_read_parameters(column, parameters)
+      def prepare_read_parameters(attr, parameters)
         option = parameters.first
-        value = read_option_value(column, option.nil? ? :default : option)
+        value = read_option_value(attr, option.nil? ? :default : option)
         if value
           parameters[0] = value
         elsif option == :default
@@ -706,43 +785,43 @@ module FlexiRecord
         return parameters
       end
 
-      # Sets a given block to be the "reader function" for a particlular virtualized column. A reader function is invoked, when you try to read a value of the given 'column' of a record. Two arguments are passed to the block. The first is the record, whose data is to be read, the second is an Array of arguments passed to the method used for reading the value. The block has to evaluate to the value which should be read.
-      def set_reader(column, &reader)
-        (@readers ||= {})[column.to_s] = reader
+      # Sets a given block to be the "reader function" for a particlular attribute. A reader function is invoked, when you try to read a value of the given attribute of a record. Two arguments are passed to the block. The first is the record, whose data is to be read, the second is an Array of arguments passed to the method used for reading the value. The block has to evaluate to the value which should be read.
+      def set_reader(attr, &reader)
+        (@readers ||= {})[attr.to_s] = reader
       end
 
-      # Returns the reader function (a Proc object) for a certain virtualized column.
-      def reader(column)
-        (@readers || {})[column.to_s] or ((superclass <= FlexiRecord::BaseRecord) ? superclass.reader(column) : nil)
+      # Returns the reader function (a Proc object) for a certain attribute.
+      def reader(attr)
+        (@readers || {})[attr.to_s] or ((superclass <= FlexiRecord::BaseRecord) ? superclass.reader(attr) : nil)
       end
 
-      # Returns an array containing all virtualized columns having a reader Proc stored in the class.
-      def reader_columns
+      # Returns an array containing all attributes having a reader Proc stored in the class.
+      def reader_attrs
         (@readers || {}).keys + (
           (superclass <= FlexiRecord::BaseRecord) ?
-          superclass.reader_columns :
+          superclass.reader_attrs :
           []
         )
       end
 
-      # Sets a given block to be the "loader function" for a particular virtualized column. Loader functions are invoked, when you try to read an uncached value of the given 'column' of a record, or when you preload data for a whole Array of records. Two arguments are passed to the block. The first is an Array of records, whose data is to be loaded, the second is an Array of arguments passed to the method used for accessing the value. The block has to evaluate to an Array of records, which can be used for more than one level deep preloads.
-      def set_loader(column, &loader)
-        (@loaders ||= {})[column.to_s] = loader
+      # Sets a given block to be the "loader function" for a particular attribute. Loader functions are invoked, when you try to read an uncached value of the given attribute of a record, or when you preload data for a whole Array of records. Two arguments are passed to the block. The first is an Array of records, whose data is to be loaded, the second is an Array of arguments passed to the method used for accessing the value. The block has to evaluate to an Array of records, which can be used for more than one level deep preloads.
+      def set_loader(attr, &loader)
+        (@loaders ||= {})[attr.to_s] = loader
       end
 
-      # Returns the loader function (a Proc object) for a certain virtualized column.
-      def loader(column)
-        (@loaders || {})[column.to_s] or ((superclass <= FlexiRecord::BaseRecord) ? superclass.loader(column) : nil)
+      # Returns the loader function (a Proc object) for a certain attribute.
+      def loader(attr)
+        (@loaders || {})[attr.to_s] or ((superclass <= FlexiRecord::BaseRecord) ? superclass.loader(attr) : nil)
       end
 
-      # Sets a given block to be the "setter function" for a particular virtualized column. The setter function is invoked, when you set the value of the given 'column' of a record. Two arguments are passed to the block. The first is the record, whose data is to be changed, the second is the new value to be written into the 'column' field.
-      def set_setter(column, &setter)
-        (@setters ||= {})[column.to_s] = setter
+      # Sets a given block to be the "setter function" for a particular attribute. The setter function is invoked, when you set the value of the given attribute of a record. Two arguments are passed to the block. The first is the record, whose data is to be changed, the second is the new value to be written into the field.
+      def set_setter(attr, &setter)
+        (@setters ||= {})[attr.to_s] = setter
       end
 
-      # Returns the setter function (a Proc object) for a certain virtualized column.
-      def setter(column)
-        (@setters || {})[column.to_s] or ((superclass <= FlexiRecord::BaseRecord) ? superclass.setter(column) : nil)
+      # Returns the setter function (a Proc object) for a certain attribute.
+      def setter(attr)
+        (@setters || {})[attr.to_s] or ((superclass <= FlexiRecord::BaseRecord) ? superclass.setter(attr) : nil)
       end
 
       # Adds an OneToOneReference to the class (by simply creating it). The first argument is the destination class, followed by arguments being passed to Reference.new.
@@ -759,6 +838,11 @@ module FlexiRecord
         )
       end
 
+      # Adds two ManyToOneReferences and connects them to form a many-to-many relation between two other record classes. Please look at the FlexiRecordDemo module to see how this works.
+      def add_connected_references(destination_class1, column_info1, src_to_dst_attr1, dst_to_src_attr1, class1_to_class2_attr, destination_class2, column_info2, src_to_dst_attr2, dst_to_src_attr2, class2_to_class1_attr)
+        self.add_many_to_one_reference(destination_class1, column_info1, src_to_dst_attr1, dst_to_src_attr1).combine(self.add_many_to_one_reference(destination_class2, column_info2, src_to_dst_attr2, dst_to_src_attr2), class1_to_class2_attr, class2_to_class1_attr)
+      end
+
     end  # end of singleton meta class of BaseRecord
 
     private  # methods of BaseRecord
@@ -801,7 +885,7 @@ module FlexiRecord
 
     public  # methods of BaseRecord
 
-      # Rewrites several attributes given by the keys and values in the 'data' hash. Returns self.
+      # Rewrites several attributes given by the keys and values in the 'data' hash. Note: A SQL UPDATE command is not executed before 'save' is called, this method just updates the ruby object. Returns self.
       def update(data)
         synchronize do
           data.each { |key, value| self.set(key, value) }
@@ -827,14 +911,14 @@ module FlexiRecord
         end
       end
 
-      # Reads a value (whose key can consist of multiple fields) from the internal cache. The first argument is by convention a name of a column as String(!), but NOT as a Symbol.
+      # Reads a value (whose key can consist of multiple fields) from the internal cache. The first argument is by convention usually a name of a column as String(!), but NOT as a Symbol.
       def [](*key)
         synchronize do
           return @data_hash[key]
         end
       end
 
-      # Writes a value to the internal cache. The first argument is by convention a name of a column as String(!), but NOT as a Symbol.
+      # Writes a value to the internal cache. The first argument is by convention usually a name of a column as String(!), but NOT as a Symbol.
       def []=(*arguments)
         synchronize do
           value = arguments.pop
@@ -857,13 +941,13 @@ module FlexiRecord
         end
       end
 
-      # Reads the field with the specified 'column'. If there is a dynamic reader, this reader is used, otherwise an existent assigned loader function is invoked or the internal cache will give a result. If there is no data for the column with the given name, then nil will be returned.
-      def read(column, *arguments)
-        column = column.to_s
-        self.class.prepare_read_parameters(column, arguments)
-        data_hash_key = [column] + arguments
-        reader = self.class.reader(column)
-        loader = self.class.loader(column)
+      # Reads an attribute. If there is a dynamic reader, this reader is used, otherwise an existent assigned loader function is invoked or the internal cache will give a result. If there is no data for the attribute with the given name, then nil will be returned.
+      def read(attr, *arguments)
+        attr = attr.to_s
+        self.class.prepare_read_parameters(attr, arguments)
+        data_hash_key = [attr] + arguments
+        reader = self.class.reader(attr)
+        loader = self.class.loader(attr)
         synchronize do
           if reader
             return reader.call(self, arguments)
@@ -879,22 +963,22 @@ module FlexiRecord
         end
       end
 
-      # Sets a value of a field of the specified 'column'. If there is a dynamic setter, this setter is used, otherwise the value get's written in the internal cache.
-      def set(column, value)
-        column = column.to_s
-        setter = self.class.setter(column)
+      # Sets an attribute. If there is a dynamic setter, this setter is used, otherwise the value get's written in the internal cache.
+      def set(attr, value)
+        attr = attr.to_s
+        setter = self.class.setter(attr)
         if setter
           setter.call(self, value)
-          return @data_hash[[column]]
+          return @data_hash[[attr]]
         else
-          return @data_hash[[column]] = value
+          return @data_hash[[attr]] = value
         end
       end
 
       # Returns an array of strings of the columns in the backend database, which have either values in the internal cache, or which have a dynamic reader function.
       def used_columns
         synchronize do
-          return self.class.columns & (self.class.reader_columns + @data_hash.keys.reject { |key| key.length > 1 }.collect { |key| key.first })
+          return self.class.columns & (self.class.reader_attrs + @data_hash.keys.reject { |key| key.length > 1 }.collect { |key| key.first })
         end
       end
 
@@ -928,20 +1012,20 @@ module FlexiRecord
       # Provides easy access to the fields of the record.
       def method_missing(method_symbol, *arguments)
         synchronize do
-          column = method_symbol.to_s
-          if column[-1, 1] == '='
-            column = column[0, column.length-1]
+          attr = method_symbol.to_s
+          if attr[-1, 1] == '='
+            attr = attr[0, attr.length-1]
             mode = :write
             value = arguments.pop
           else
             mode = :read
           end
-          reader                = self.class.reader(column)
-          loader                = self.class.loader(column)
-          table_column_existent = self.class.columns.include?(column)
+          reader                = self.class.reader(attr)
+          loader                = self.class.loader(attr)
+          table_column_existent = self.class.columns.include?(attr)
           if mode == :write
-            data_hash_key         = [column] + arguments
-            setter = self.class.setter(column)
+            data_hash_key        = [attr] + arguments
+            setter = self.class.setter(attr)
             if setter
               setter.call(self, value)
               return nil
@@ -950,8 +1034,8 @@ module FlexiRecord
               return nil
             end
           elsif mode == :read
-            self.class.prepare_read_parameters(column, arguments)
-            data_hash_key = [column] + arguments
+            self.class.prepare_read_parameters(attr, arguments)
+            data_hash_key = [attr] + arguments
             if reader
               return reader.call(self, arguments)
             elsif @data_hash.has_key?(data_hash_key)
@@ -1079,7 +1163,7 @@ module FlexiRecord
 
     def initialize(*arguments)
       super
-      self['void'] = nil
+      self['void'] = nil unless self.has_key?('void')
     end
 
     # Alias for the (field) method 'void'. True, if the Relationship is void, and is to be removed, when calling 'save'.
@@ -1091,7 +1175,7 @@ module FlexiRecord
     def save
       # TODO: improve efficiency, when a "REPLACE" command is available in PostgreSQL
       self.class.transaction(self, :read_committed) do
-        self.class.db_execute "LOCK TABLE #{self.class.table} IN SHARE ROW EXCLUSIVE MODE"
+        self.class.lock(:share_row_exclusive)
         @saved =
           self.class.select_by_value_set(self.class.primary_columns, [self.class.primary_columns.collect { |column| self.read(column) }]).length > 0
         copy_primary_key
@@ -1187,7 +1271,7 @@ module FlexiRecord
       }
       raise ArgumentError, "Too many arguments supplied for SQL command." unless command_arguments.empty?
       if $flexirecord_debug_output
-        $flexirecord_debug_output << "===>  #{command}\n"
+        $flexirecord_debug_output << "#{command}\n"
       end
       begin
         synchronize do
@@ -1399,8 +1483,8 @@ module FlexiRecord
 
     def save
       self.class.transaction(self, :read_committed) do
-        self.class.db_execute "LOCK TABLE #{self.class.table} IN SHARE ROW EXCLUSIVE MODE"
-        if self.position == :first
+        self.class.lock(:share_row_exclusive)
+         if self.position == :first
           db_result = self.class.db_query1(
             'SELECT COALESCE("position" - 1, 0) AS "result" ' <<
             'FROM ' << self.class.table << ' WHERE "position" NOTNULL ORDER BY "position" ASC)')

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: flexirecord
 version: !ruby/object:Gem::Version 
-  version: 0.0.3
-date: 2007-02-08 00:00:00 +00:00
+  version: 0.0.4
+date: 2007-02-11 00:00:00 +00:00
 summary: Object-Oriented Database Access Library
 require_paths: 
 - lib/
@@ -30,6 +30,7 @@ authors:
 - Jan Behrens
 files: 
 - ./LICENSE
+- ./CHANGELOG
 - lib/thread_resource_pool.rb
 - lib/flexirecord.rb
 - lib/flexirecord-demo.rb