activerecord 2.0.5 → 2.1.0

data/lib/active_record/observer.rb

@@ -19,7 +19,7 @@ module ActiveRecord
       #   # Same as above, just using explicit class references
       #   ActiveRecord::Base.observers = Cacher, GarbageCollector
       #
-      # Note: Setting this does not instantiate the observers yet.  #instantiate_observers is
+      # Note: Setting this does not instantiate the observers yet. +instantiate_observers+ is
       # called during startup, and before each development request.  
       def observers=(*observers)
         @observers = observers.flatten
@@ -30,7 +30,7 @@ module ActiveRecord
         @observers ||= []
       end
 
-      # Instantiate the global ActiveRecord observers
+      # Instantiate the global Active Record observers.
       def instantiate_observers
         return if @observers.blank?
         @observers.each do |observer|
@@ -125,6 +125,20 @@ module ActiveRecord
   #
   # Observers will not be invoked unless you define these in your application configuration.
   #
+  # == Loading
+  #
+  # Observers register themselves in the model class they observe, since it is the class that
+  # notifies them of events when they occur. As a side-effect, when an observer is loaded its
+  # corresponding model class is loaded.
+  # 
+  # Up to (and including) Rails 2.0.2 observers were instantiated between plugins and
+  # application initializers. Now observers are loaded after application initializers, 
+  # so observed models can make use of extensions.
+  # 
+  # If by any chance you are using observed models in the initialization you can still
+  # load their observers by calling <tt>ModelObserver.instance</tt> before. Observers are
+  # singletons and that call instantiates and registers them.
+  #
   class Observer
     include Singleton
 
@@ -137,10 +151,10 @@ module ActiveRecord
       end
 
       # The class observed by default is inferred from the observer's class name:
-      #   assert_equal [Person], PersonObserver.observed_class
+      #   assert_equal Person, PersonObserver.observed_class
       def observed_class
-        if observed_class_name = name.scan(/(.*)Observer/)[0]
-          observed_class_name[0].constantize
+        if observed_class_name = name[/(.*)Observer/, 1]
+          observed_class_name.constantize
         else
           nil
         end

data/lib/active_record/reflection.rb

@@ -45,7 +45,7 @@ module ActiveRecord
       end
 
       # Returns an array of AssociationReflection objects for all the associations in the class. If you only want to reflect on a
-      # certain association type, pass in the symbol (:has_many, :has_one, :belongs_to) for that as the first parameter. 
+      # certain association type, pass in the symbol (<tt>:has_many</tt>, <tt>:has_one</tt>, <tt>:belongs_to</tt>) for that as the first parameter.
       # Example:
       #
       #   Account.reflect_on_all_associations             # returns an array of all associations
@@ -76,34 +76,38 @@ module ActiveRecord
         @macro, @name, @options, @active_record = macro, name, options, active_record
       end
 
-      # Returns the name of the macro, so it would return :balance for "composed_of :balance, :class_name => 'Money'" or
-      # :clients for "has_many :clients".
+      # Returns the name of the macro.  For example, <tt>composed_of :balance, :class_name => 'Money'</tt> will return
+      # <tt>:balance</tt> or for <tt>has_many :clients</tt> it will return <tt>:clients</tt>.
       def name
         @name
       end
 
-      # Returns the type of the macro, so it would return :composed_of for
-      # "composed_of :balance, :class_name => 'Money'" or :has_many for "has_many :clients".
+      # Returns the macro type. For example, <tt>composed_of :balance, :class_name => 'Money'</tt> will return <tt>:composed_of</tt>
+      # or for <tt>has_many :clients</tt> will return <tt>:has_many</tt>.
       def macro
         @macro
       end
 
-      # Returns the hash of options used for the macro, so it would return { :class_name => "Money" } for
-      # "composed_of :balance, :class_name => 'Money'" or {} for "has_many :clients".
+      # Returns the hash of options used for the macro.  For example, it would return <tt>{ :class_name => "Money" }</tt> for
+      # <tt>composed_of :balance, :class_name => 'Money'</tt> or +{}+ for <tt>has_many :clients</tt>.
       def options
         @options
       end
 
-      # Returns the class for the macro, so "composed_of :balance, :class_name => 'Money'" returns the Money class and
-      # "has_many :clients" returns the Client class.
+      # Returns the class for the macro.  For example, <tt>composed_of :balance, :class_name => 'Money'</tt> returns the Money
+      # class and <tt>has_many :clients</tt> returns the Client class.
       def klass
         @klass ||= class_name.constantize
       end
 
+      # Returns the class name for the macro.  For example, <tt>composed_of :balance, :class_name => 'Money'</tt> returns <tt>'Money'</tt>
+      # and <tt>has_many :clients</tt> returns <tt>'Client'</tt>.
       def class_name
         @class_name ||= options[:class_name] || derive_class_name
       end
 
+      # Returns +true+ if +self+ and +other_aggregation+ have the same +name+ attribute, +active_record+ attribute,
+      # and +other_aggregation+ has an options hash assigned to it.
       def ==(other_aggregation)
         name == other_aggregation.name && other_aggregation.options && active_record == other_aggregation.active_record
       end
@@ -129,6 +133,10 @@ module ActiveRecord
         @table_name ||= klass.table_name
       end
 
+      def quoted_table_name
+        @quoted_table_name ||= klass.quoted_table_name
+      end
+
       def primary_key_name
         @primary_key_name ||= options[:foreign_key] || derive_primary_key_name
       end
@@ -145,22 +153,34 @@ module ActiveRecord
         end
       end
 
+      # Returns the AssociationReflection object specified in the <tt>:through</tt> option
+      # of a HasManyThrough or HasOneThrough association. Example:
+      #
+      #   class Post < ActiveRecord::Base
+      #     has_many :taggings
+      #     has_many :tags, :through => :taggings
+      #   end
+      #
+      #   tags_reflection = Post.reflect_on_association(:tags)
+      #   taggings_reflection = tags_reflection.through_reflection
+      #
       def through_reflection
         @through_reflection ||= options[:through] ? active_record.reflect_on_association(options[:through]) : false
       end
 
-      # Gets an array of possible :through source reflection names
+      # Gets an array of possible <tt>:through</tt> source reflection names:
       #
-      #   [singularized, pluralized]
+      #   [:singularized, :pluralized]
       #
       def source_reflection_names
         @source_reflection_names ||= (options[:source] ? [options[:source]] : [name.to_s.singularize, name]).collect { |n| n.to_sym }
       end
 
-      # Gets the source of the through reflection.  It checks both a singularized and pluralized form for :belongs_to or :has_many.
-      # (The :tags association on Tagging below)
+      # Gets the source of the through reflection.  It checks both a singularized and pluralized form for <tt>:belongs_to</tt> or <tt>:has_many</tt>.
+      # (The <tt>:tags</tt> association on Tagging below.)
       # 
-      #   class Post
+      #   class Post < ActiveRecord::Base
+      #     has_many :taggings
       #     has_many :tags, :through => :taggings
       #   end
       #

data/lib/active_record/schema.rb

@@ -30,28 +30,21 @@ module ActiveRecord
 
     # Eval the given block. All methods available to the current connection
     # adapter are available within the block, so you can easily use the
-    # database definition DSL to build up your schema (#create_table,
-    # #add_index, etc.).
+    # database definition DSL to build up your schema (+create_table+,
+    # +add_index+, etc.).
     #
     # The +info+ hash is optional, and if given is used to define metadata
-    # about the current schema (like the schema's version):
+    # about the current schema (currently, only the schema's version):
     #
-    #   ActiveRecord::Schema.define(:version => 15) do
+    #   ActiveRecord::Schema.define(:version => 20380119000001) do
     #     ...
     #   end
     def self.define(info={}, &block)
       instance_eval(&block)
 
-      unless info.empty?
-        initialize_schema_information
-        cols = columns('schema_info')
-
-        info = info.map do |k,v|
-          v = Base.connection.quote(v, cols.detect { |c| c.name == k.to_s })
-          "#{k} = #{v}"
-        end
-
-        Base.connection.update "UPDATE #{Migrator.schema_info_table_name} SET #{info.join(", ")}"
+      unless info[:version].blank?
+        initialize_schema_migrations_table
+        assume_migrated_upto_version info[:version]
       end
     end
   end

data/lib/active_record/schema_dumper.rb

@@ -30,15 +30,15 @@ module ActiveRecord
       def initialize(connection)
         @connection = connection
         @types = @connection.native_database_types
-        @info = @connection.select_one("SELECT * FROM schema_info") rescue nil
+        @version = Migrator::current_version rescue nil
       end
 
       def header(stream)
-        define_params = @info ? ":version => #{@info['version']}" : ""
+        define_params = @version ? ":version => #{@version}" : ""
 
         stream.puts <<HEADER
 # This file is auto-generated from the current state of the database. Instead of editing this file, 
-# please use the migrations feature of ActiveRecord to incrementally modify your database, and
+# please use the migrations feature of Active Record to incrementally modify your database, and
 # then regenerate this schema definition.
 #
 # Note that this schema.rb definition is the authoritative source for your database schema. If you need
@@ -59,7 +59,7 @@ HEADER
 
       def tables(stream)
         @connection.tables.sort.each do |tbl|
-          next if ["schema_info", ignore_tables].flatten.any? do |ignored|
+          next if ['schema_migrations', ignore_tables].flatten.any? do |ignored|
             case ignored
             when String; tbl == ignored
             when Regexp; tbl =~ ignored

data/lib/active_record/serialization.rb

@@ -8,11 +8,11 @@ module ActiveRecord #:nodoc:
       end
 
       # To replicate the behavior in ActiveRecord#attributes,
-      # :except takes precedence over :only.  If :only is not set
+      # <tt>:except</tt> takes precedence over <tt>:only</tt>.  If <tt>:only</tt> is not set
       # for a N level model but is set for the N+1 level models,
-      # then because :except is set to a default value, the second
-      # level model can have both :except and :only set.  So if
-      # :only is set, always delete :except.
+      # then because <tt>:except</tt> is set to a default value, the second
+      # level model can have both <tt>:except</tt> and <tt>:only</tt> set.  So if
+      # <tt>:only</tt> is set, always delete <tt>:except</tt>.
       def serializable_attribute_names
         attribute_names = @record.attribute_names
 
@@ -38,7 +38,7 @@ module ActiveRecord #:nodoc:
         serializable_attribute_names + serializable_method_names
       end
 
-      # Add associations specified via the :includes option.
+      # Add associations specified via the <tt>:includes</tt> option.
       # Expects a block that takes as arguments:
       #   +association+ - name of the association
       #   +records+     - the association record(s) to be serialized

data/lib/active_record/serializers/json_serializer.rb

@@ -1,5 +1,10 @@
 module ActiveRecord #:nodoc:
   module Serialization
+    def self.included(base)
+      base.cattr_accessor :include_root_in_json, :instance_writer => false
+      base.extend ClassMethods
+    end
+
     # Returns a JSON string representing the model. Some configuration is
     # available through +options+.
     #
@@ -8,37 +13,32 @@ module ActiveRecord #:nodoc:
     #
     #   konata = User.find(1)
     #   konata.to_json
+    #   # => {"id": 1, "name": "Konata Izumi", "age": 16,
+    #         "created_at": "2006/08/01", "awesome": true}
     #
-    #   {"id": 1, "name": "Konata Izumi", "age": 16,
-    #    "created_at": "2006/08/01", "awesome": true}
-    #
-    # The :only and :except options can be used to limit the attributes
-    # included, and work similar to the #attributes method. For example:
+    # The <tt>:only</tt> and <tt>:except</tt> options can be used to limit the attributes
+    # included, and work similar to the +attributes+ method. For example:
     #
     #   konata.to_json(:only => [ :id, :name ])
-    #
-    #   {"id": 1, "name": "Konata Izumi"}
+    #   # => {"id": 1, "name": "Konata Izumi"}
     #
     #   konata.to_json(:except => [ :id, :created_at, :age ])
+    #   # => {"name": "Konata Izumi", "awesome": true}
     #
-    #   {"name": "Konata Izumi", "awesome": true}
-    #
-    # To include any methods on the model, use :methods.
+    # To include any methods on the model, use <tt>:methods</tt>.
     #
     #   konata.to_json(:methods => :permalink)
+    #   # => {"id": 1, "name": "Konata Izumi", "age": 16,
+    #         "created_at": "2006/08/01", "awesome": true,
+    #         "permalink": "1-konata-izumi"}
     #
-    #   {"id": 1, "name": "Konata Izumi", "age": 16,
-    #    "created_at": "2006/08/01", "awesome": true,
-    #    "permalink": "1-konata-izumi"}
-    #
-    # To include associations, use :include.
+    # To include associations, use <tt>:include</tt>.
     #
     #   konata.to_json(:include => :posts)
-    #
-    #   {"id": 1, "name": "Konata Izumi", "age": 16,
-    #    "created_at": "2006/08/01", "awesome": true,
-    #    "posts": [{"id": 1, "author_id": 1, "title": "Welcome to the weblog"},
-    #              {"id": 2, author_id: 1, "title": "So I was thinking"}]}
+    #   # => {"id": 1, "name": "Konata Izumi", "age": 16,
+    #         "created_at": "2006/08/01", "awesome": true,
+    #         "posts": [{"id": 1, "author_id": 1, "title": "Welcome to the weblog"},
+    #                   {"id": 2, author_id: 1, "title": "So I was thinking"}]}
     #
     # 2nd level and higher order associations work as well:
     #
@@ -46,15 +46,18 @@ module ActiveRecord #:nodoc:
     #                                  :include => { :comments => {
     #                                                :only => :body } },
     #                                  :only => :title } })
-    #
-    #   {"id": 1, "name": "Konata Izumi", "age": 16,
-    #    "created_at": "2006/08/01", "awesome": true,
-    #    "posts": [{"comments": [{"body": "1st post!"}, {"body": "Second!"}],
-    #               "title": "Welcome to the weblog"},
-    #              {"comments": [{"body": "Don't think too hard"}],
-    #               "title": "So I was thinking"}]}
+    #   # => {"id": 1, "name": "Konata Izumi", "age": 16,
+    #         "created_at": "2006/08/01", "awesome": true,
+    #         "posts": [{"comments": [{"body": "1st post!"}, {"body": "Second!"}],
+    #                    "title": "Welcome to the weblog"},
+    #                   {"comments": [{"body": "Don't think too hard"}],
+    #                    "title": "So I was thinking"}]}
     def to_json(options = {})
-      JsonSerializer.new(self, options).to_s
+      if include_root_in_json
+        "{#{self.class.json_class_name}: #{JsonSerializer.new(self, options).to_s}}"
+      else
+        JsonSerializer.new(self, options).to_s
+      end
     end
 
     def from_json(json)
@@ -67,5 +70,11 @@ module ActiveRecord #:nodoc:
         serializable_record.to_json
       end
     end
+
+    module ClassMethods
+      def json_class_name
+        @json_class_name ||= name.demodulize.underscore.inspect
+      end
+    end
   end
 end

data/lib/active_record/serializers/xml_serializer.rb

@@ -1,11 +1,11 @@
 module ActiveRecord #:nodoc:
   module Serialization
-    # Builds an XML document to represent the model.   Some configuration is
-    # available through +options+, however more complicated cases should
-    # override ActiveRecord's to_xml.
+    # Builds an XML document to represent the model. Some configuration is
+    # available through +options+. However more complicated cases should
+    # override ActiveRecord::Base#to_xml.
     #
     # By default the generated XML document will include the processing
-    # instruction and all object's attributes.  For example:
+    # instruction and all the object's attributes. For example:
     #
     #   <?xml version="1.0" encoding="UTF-8"?>
     #   <topic>
@@ -22,12 +22,12 @@ module ActiveRecord #:nodoc:
     #     <last-read type="date">2004-04-15</last-read>
     #   </topic>
     #
-    # This behavior can be controlled with :only, :except,
-    # :skip_instruct, :skip_types and :dasherize.  The :only and
-    # :except options are the same as for the #attributes method.
-    # The default is to dasherize all column names, to disable this,
-    # set :dasherize to false.  To not have the column type included
-    # in the XML output, set :skip_types to true.
+    # This behavior can be controlled with <tt>:only</tt>, <tt>:except</tt>,
+    # <tt>:skip_instruct</tt>, <tt>:skip_types</tt> and <tt>:dasherize</tt>.
+    # The <tt>:only</tt> and <tt>:except</tt> options are the same as for the
+    # +attributes+ method. The default is to dasherize all column names, but you
+    # can disable this setting <tt>:dasherize</tt> to +false+. To not have the
+    # column type included in the XML output set <tt>:skip_types</tt> to +true+.
     #
     # For instance:
     #
@@ -43,7 +43,7 @@ module ActiveRecord #:nodoc:
     #     <last-read type="date">2004-04-15</last-read>
     #   </topic>
     #
-    # To include first level associations use :include
+    # To include first level associations use <tt>:include</tt>:
     #
     #   firm.to_xml :include => [ :account, :clients ]
     #
@@ -68,7 +68,37 @@ module ActiveRecord #:nodoc:
     #     </account>
     #   </firm>
     #
-    # To include any methods on the object(s) being called use :methods
+    # To include deeper levels of associations pass a hash like this:
+    #
+    #   firm.to_xml :include => {:account => {}, :clients => {:include => :address}}
+    #   <?xml version="1.0" encoding="UTF-8"?>
+    #   <firm>
+    #     <id type="integer">1</id>
+    #     <rating type="integer">1</rating>
+    #     <name>37signals</name>
+    #     <clients type="array">
+    #       <client>
+    #         <rating type="integer">1</rating>
+    #         <name>Summit</name>
+    #         <address>
+    #           ...
+    #         </address>
+    #       </client>
+    #       <client>
+    #         <rating type="integer">1</rating>
+    #         <name>Microsoft</name>
+    #         <address>
+    #           ...
+    #         </address>
+    #       </client>
+    #     </clients>
+    #     <account>
+    #       <id type="integer">1</id>
+    #       <credit-limit type="integer">50</credit-limit>
+    #     </account>
+    #   </firm>
+    #
+    # To include any methods on the model being called use <tt>:methods</tt>:
     #
     #   firm.to_xml :methods => [ :calculated_earnings, :real_earnings ]
     #
@@ -78,9 +108,8 @@ module ActiveRecord #:nodoc:
     #     <real-earnings>5</real-earnings>
     #   </firm>
     #
-    # To call any Proc's on the object(s) use :procs.  The Proc's
-    # are passed a modified version of the options hash that was
-    # given to #to_xml.
+    # To call any additional Procs use <tt>:procs</tt>. The Procs are passed a
+    # modified version of the options hash that was given to +to_xml+:
     #
     #   proc = Proc.new { |options| options[:builder].tag!('abc', 'def') }
     #   firm.to_xml :procs => [ proc ]
@@ -90,7 +119,7 @@ module ActiveRecord #:nodoc:
     #     <abc>def</abc>
     #   </firm>
     #
-    # Alternatively, you can also just yield the builder object as part of the to_xml call:
+    # Alternatively, you can yield the builder object as part of the +to_xml+ call:
     #
     #   firm.to_xml do |xml|
     #     xml.creator do
@@ -107,8 +136,9 @@ module ActiveRecord #:nodoc:
     #     </creator>
     #   </firm>
     #
-    # You can override the to_xml method in your ActiveRecord::Base
-    # subclasses if you need to.  The general form of doing this is
+    # As noted above, you may override +to_xml+ in your ActiveRecord::Base
+    # subclasses to have complete control about what's generated. The general
+    # form of doing this is:
     #
     #   class IHaveMyOwnXML < ActiveRecord::Base
     #     def to_xml(options = {})
@@ -155,13 +185,6 @@ module ActiveRecord #:nodoc:
       !options.has_key?(:dasherize) || options[:dasherize]
     end
 
-
-    # To replicate the behavior in ActiveRecord#attributes,
-    # :except takes precedence over :only.  If :only is not set
-    # for a N level model but is set for the N+1 level models,
-    # then because :except is set to a default value, the second
-    # level model can have both :except and :only set.  So if
-    # :only is set, always delete :except.
     def serializable_attributes
       serializable_attribute_names.collect { |name| Attribute.new(name, @record) }
     end
@@ -250,14 +273,14 @@ module ActiveRecord #:nodoc:
       end
 
       # There is a significant speed improvement if the value
-      # does not need to be escaped, as #tag! escapes all values
-      # to ensure that valid XML is generated.  For known binary
+      # does not need to be escaped, as <tt>tag!</tt> escapes all values
+      # to ensure that valid XML is generated. For known binary
       # values, it is at least an order of magnitude faster to
       # Base64 encode binary values and directly put them in the
       # output XML than to pass the original value or the Base64
-      # encoded value to the #tag! method. It definitely makes
+      # encoded value to the <tt>tag!</tt> method. It definitely makes
       # no sense to Base64 encode the value and then give it to
-      # #tag!, since that just adds additional overhead.
+      # <tt>tag!</tt>, since that just adds additional overhead.
       def needs_encoding?
         ![ :binary, :date, :datetime, :boolean, :float, :integer ].include?(type)
       end