mongoid 2.0.0.beta.20 → 2.0.0.rc.1

data/lib/mongoid/relations/embedded/one.rb

@@ -0,0 +1,169 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+    module Embedded #:nodoc:
+
+      # This class defines the behaviour needed for embedded one to one
+      # relations.
+      class One < Relations::One
+
+        # Binds the base object to the inverse of the relation. This is so we
+        # are referenced to the actual objects themselves and dont hit the
+        # database twice when setting the relations up.
+        #
+        # This is called after first creating the relation, or if a new object
+        # is set on the relation.
+        #
+        # @example Bind the relation.
+        #   person.name.bind(:continue => false)
+        #
+        # @param [ Hash ] options The options to bind with.
+        #
+        # @option options [ true, false ] :building Are we in build mode?
+        # @option options [ true, false ] :continue Continue binding the
+        #   inverse?
+        #
+        # @since 2.0.0.rc.1
+        def bind(options = {})
+          binding.bind(options)
+          target.save if base.persisted? && !options[:building]
+        end
+
+        # Instantiate a new embeds_one relation.
+        #
+        # @example Create the new proxy.
+        #   One.new(person, name, metadata)
+        #
+        # @param [ Document ] base The document this relation hangs off of.
+        # @param [ Document ] target The child document in the relation.
+        # @param [ Metadata ] metadata The relation's metadata
+        def initialize(base, target, metadata)
+          init(base, target, metadata) do
+            target.parentize(base)
+          end
+        end
+
+        # Unbinds the base object to the inverse of the relation. This occurs
+        # when setting a side of the relation to nil.
+        #
+        # Will delete the object if necessary.
+        #
+        # @example Unbind the relation.
+        #   person.name.unbind(name, :continue => true)
+        #
+        # @param [ Document ] old_target The previous target of the relation.
+        # @param [ Hash ] options The options to bind with.
+        #
+        # @option options [ true, false ] :building Are we in build mode?
+        # @option options [ true, false ] :continue Continue binding the
+        #   inverse?
+        #
+        # @since 2.0.0.rc.1
+        def unbind(old_target, options = {})
+          binding(old_target).unbind(options)
+          old_target.delete if base.persisted? && !old_target.destroyed?
+        end
+
+        private
+
+        # Instantiate the binding associated with this relation.
+        #
+        # @example Get the binding.
+        #   relation.binding([ address ])
+        #
+        # @param [ Document ] new_target The new document to bind with.
+        #
+        # @return [ Binding ] The relation's binding.
+        #
+        # @since 2.0.0.rc.1
+        def binding(new_target = nil)
+          Bindings::Embedded::One.new(base, new_target || target, metadata)
+        end
+
+        class << self
+
+          # Return the builder that is responsible for generating the documents
+          # that will be used by this relation.
+          #
+          # @example Get the builder.
+          #   Embedded::One.builder(meta, object, person)
+          #
+          # @param [ Metadata ] meta The metadata of the relation.
+          # @param [ Document, Hash ] object A document or attributes to build with.
+          #
+          # @return [ Builder ] A newly instantiated builder object.
+          #
+          # @since 2.0.0.rc.1
+          def builder(meta, object)
+            Builders::Embedded::One.new(meta, object)
+          end
+
+          # Returns true if the relation is an embedded one. In this case
+          # always true.
+          #
+          # @example Is this relation embedded?
+          #   Embedded::One.embedded?
+          #
+          # @return [ true ] true.
+          #
+          # @since 2.0.0.rc.1
+          def embedded?
+            true
+          end
+
+          # Returns the macro for this relation. Used mostly as a helper in
+          # reflection.
+          #
+          # @example Get the macro.
+          #   Mongoid::Relations::Embedded::One.macro
+          #
+          # @return [ Symbol ] :embeds_one.
+          #
+          # @since 2.0.0.rc.1
+          def macro
+            :embeds_one
+          end
+
+          # Return the nested builder that is responsible for generating
+          # the documents that will be used by this relation.
+          #
+          # @example Get the builder.
+          #   NestedAttributes::One.builder(attributes, options)
+          #
+          # @param [ Metadata ] metadata The relation metadata.
+          # @param [ Hash ] attributes The attributes to build with.
+          # @param [ Hash ] options The options for the builder.
+          #
+          # @option options [ true, false ] :allow_destroy Can documents be
+          #   deleted?
+          # @option options [ Integer ] :limit Max number of documents to
+          #   create at once.
+          # @option options [ Proc, Symbol ] :reject_if If documents match this
+          #   option then they are ignored.
+          # @option options [ true, false ] :update_only Only existing documents
+          #   can be modified.
+          #
+          # @return [ Builder ] A newly instantiated nested builder object.
+          #
+          # @since 2.0.0.rc.1
+          def nested_builder(metadata, attributes, options)
+            Builders::NestedAttributes::One.new(metadata, attributes, options)
+          end
+
+          # Tells the caller if this relation is one that stores the foreign
+          # key on its own objects.
+          #
+          # @example Does this relation store a foreign key?
+          #   Embedded::One.stores_foreign_key?
+          #
+          # @return [ false ] false.
+          #
+          # @since 2.0.0.rc.1
+          def stores_foreign_key?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/relations/macros.rb

@@ -0,0 +1,302 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+
+    # This module contains the core macros for defining relations between
+    # documents. They can be either embedded or referenced (relational).
+    module Macros
+      extend ActiveSupport::Concern
+
+      included do
+        cattr_accessor :embedded
+        class_inheritable_accessor :relations
+        self.embedded = false
+        self.relations = {}
+
+        # For backwards compatibility, alias the class method for associations
+        # and embedding as well. Fix in related gems.
+        #
+        # @todo Affected libraries: Machinist
+        class << self
+          alias :associations :relations
+          alias :embedded? :embedded
+        end
+
+        # Convenience methods for the instance to know about attributes that
+        # are located at the class level.
+        delegate :associations, :relations, :to => "self.class"
+      end
+
+      module ClassMethods #:nodoc:
+
+        # Adds the relation back to the parent document. This macro is
+        # necessary to set the references from the child back to the parent
+        # document. If a child does not define this relation calling
+        # persistence methods on the child object will cause a save to fail.
+        #
+        # @example Define the relation.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     embeds_many :addresses
+        #   end
+        #
+        #   class Address
+        #     include Mongoid::Document
+        #     embedded_in :person
+        #   end
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def embedded_in(name, options = {}, &block)
+          metadatafy(name, Embedded::In, options, &block).tap do |meta|
+            self.embedded = true
+            relate(name, meta)
+          end
+        end
+
+        # Adds the relation from a parent document to its children. The name
+        # of the relation needs to be a pluralized form of the child class
+        # name.
+        #
+        # @example Define the relation.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     embeds_many :addresses
+        #   end
+        #
+        #   class Address
+        #     include Mongoid::Document
+        #     embedded_in :person
+        #   end
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def embeds_many(name, options = {}, &block)
+          metadatafy(name, Embedded::Many, options, &block).tap do |meta|
+            relate(name, meta)
+            validate_relation(meta)
+          end
+        end
+
+        # Adds the relation from a parent document to its child. The name
+        # of the relation needs to be a singular form of the child class
+        # name.
+        #
+        # @example Define the relation.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     embeds_one :name
+        #   end
+        #
+        #   class Name
+        #     include Mongoid::Document
+        #     embedded_in :person
+        #   end
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def embeds_one(name, options = {}, &block)
+          metadatafy(name, Embedded::One, options, &block).tap do |meta|
+            relate(name, meta)
+            builder(name).creator(name)
+            validate_relation(meta)
+          end
+        end
+
+        # Adds a relational association from the child Document to a Document in
+        # another database or collection.
+        #
+        # @example Define the relation.
+        #
+        #   class Game
+        #     include Mongoid::Document
+        #     referenced_in :person
+        #   end
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     references_one :game
+        #   end
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def referenced_in(name, options = {}, &block)
+          metadatafy(name, Referenced::In, options, &block).tap do |meta|
+            relate(name, meta)
+            reference(meta)
+          end
+        end
+        alias :belongs_to_related :referenced_in
+
+        # Adds a relational association from a parent Document to many
+        # Documents in another database or collection.
+        #
+        # @example Define the relation.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     references_many :posts
+        #   end
+        #
+        #   class Game
+        #     include Mongoid::Document
+        #     referenced_in :person
+        #   end
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def references_many(name, options = {}, &block)
+          check_options(options)
+          metadatafy(name, Referenced::Many, options, &block).tap do |meta|
+            relate(name, meta)
+            reference(meta)
+            autosave(meta)
+            validate_relation(meta)
+          end
+        end
+        alias :has_many_related :references_many
+
+        # Adds a relational many-to-many association between many of this
+        # Document and many of another Document.
+        #
+        # @example Define the relation.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     references_and_referenced_in_many :preferences
+        #   end
+        #
+        #   class Preference
+        #     include Mongoid::Document
+        #     references_and_referenced_in_many :people
+        #   end
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        #
+        # @since 2.0.0.rc.1
+        def references_and_referenced_in_many(name, options = {}, &block)
+          metadatafy(name, Referenced::ManyToMany, options, &block).tap do |meta|
+            relate(name, meta)
+            reference(meta)
+          end
+        end
+
+        # Adds a relational association from the child Document to a Document in
+        # another database or collection.
+        #
+        # @example Define the relation.
+        #
+        #   class Game
+        #     include Mongoid::Document
+        #     referenced_in :person
+        #   end
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     references_one :game
+        #   end
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def references_one(name, options = {}, &block)
+          metadatafy(name, Referenced::One, options, &block).tap do |meta|
+            relate(name, meta)
+            reference(meta)
+            builder(name).creator(name).autosave(meta)
+            validate_relation(meta)
+          end
+        end
+        alias :has_one_related :references_one
+
+        private
+
+        # Temporary check while people switch over to the new macro. Will be
+        # deleted in 2.0.0.
+        #
+        # @example Check the options.
+        #   Person.check_options({})
+        #
+        # @param [ Hash ] options The options given to the relational many.
+        #
+        # @raise [ RuntimeError ] If :stored_as => :array is found.
+        #
+        # @since 2.0.0.rc.1
+        def check_options(options = {})
+          if options[:stored_as] == :array
+            raise RuntimeError.new(
+              "Macro: references_many :name, :stored_as => :array " <<
+              "Is no longer valid. Please use: references_and_referenced_in_many :name"
+            )
+          end
+        end
+
+        # Create the metadata for the relation.
+        #
+        # @example Create the metadata.
+        #   Person.metadatafy(:posts, Referenced::Many, {})
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Object ] relation The type of relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        #
+        # @return [ Metadata ] The metadata for the relation.
+        def metadatafy(name, relation, options, &block)
+          Metadata.new(
+            options.merge(
+              :relation => relation,
+              :extend => block,
+              :inverse_class_name => self.name,
+              :name => name
+            )
+          )
+        end
+
+        # Defines a field to be used as a foreign key in the relation and
+        # indexes it if defined.
+        #
+        # @example Set up the relational fields and indexes.
+        #   Person.reference(metadata)
+        #
+        # @param [ Metadata ] metadata The metadata for the relation.
+        def reference(metadata)
+          polymorph(metadata).cascade(metadata)
+          if metadata.relation.stores_foreign_key?
+            key = metadata.foreign_key
+            field(
+              key,
+              :identity => true,
+              :metadata => metadata,
+              :default => metadata.foreign_key_default
+            )
+            index(key, :background => true) if metadata.indexed?
+          end
+        end
+
+        # Creates a relation for the given name, metadata and relation. It adds
+        # the metadata to the relations hash and has the accessors set up.
+        #
+        # @example Set up the relation and accessors.
+        #   Person.relate(:addresses, Metadata)
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Metadata ] metadata The metadata for the relation.
+        def relate(name, metadata)
+          relations[name.to_s] = metadata
+          getter(name, metadata).setter(name, metadata)
+        end
+      end
+    end
+  end
+end