stonegao-mongoid 2.0.0.rc.6

data/lib/mongoid/relations/proxy.rb

@@ -0,0 +1,128 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+
+    # This class is the superclass for all relation proxy objects, and contains
+    # common behaviour for all of them.
+    class Proxy
+
+      # We undefine most methods to get them sent through to the target.
+      instance_methods.each do |method|
+        undef_method(method) unless
+          method =~ /(^__|^send$|^object_id$|^extend$|^tap$)/
+      end
+
+      attr_accessor :base, :loaded, :metadata, :target
+
+      # Backwards compatibiloty with Mongoid beta releases.
+      delegate :klass, :to => :metadata
+
+      # Convenience for setting the target and the metadata properties since
+      # all proxies will need to do this.
+      #
+      # @example Initialize the proxy.
+      #   proxy.init(person, name, metadata)
+      #
+      # @param [ Document ] base The base document on the proxy.
+      # @param [ Document, Array<Document> ] target The target of the proxy.
+      # @param [ Metadata ] metadata The relation's metadata.
+      #
+      # @since 2.0.0.rc.1
+      def init(base, target, metadata, &block)
+        @base, @building, @target, @metadata = base, false, target, metadata
+        yield block if block_given?
+        extend Module.new(&metadata.extension) if metadata.extension?
+      end
+
+      protected
+
+      # Yields to the block to allow the building flag to get set and unset for
+      # the supplied code.
+      #
+      # @example Set the building status.
+      #   person.building { @target << Post.new }
+      #
+      # @since 2.0.0.rc.1
+      def building(&block)
+        @building = true
+        yield block if block_given?
+        @building = false
+      end
+
+      # Convenience method for determining if we are building an association.
+      # We never want to save in this case.
+      #
+      # @example Are we currently building?
+      #   person.posts.building?
+      #
+      # @return [ true, false ] True if currently building, false if not.
+      #
+      # @since 2.0.0.rc.1
+      def building?
+        !!@building
+      end
+
+      # Return a new document for the type of class we want to instantiate.
+      # If the type is provided use that, otherwise the klass from the
+      # metadata.
+      #
+      # @example Get an instantiated document.
+      #   proxy.instantiated(Person)
+      #
+      # @param [ Class ] type The type of class to instantiate.
+      #
+      # @return [ Document ] The freshly created document.
+      #
+      # @since 2.0.0.rc.1
+      def instantiated(type = nil)
+        type ? type.instantiate : metadata.klass.instantiate
+      end
+
+      # Determines if the target been loaded into memory or not.
+      #
+      # @example Is the proxy loaded?
+      #   proxy.loaded?
+      #
+      # @return [ true, false ] True if loaded, false if not.
+      #
+      # @since 2.0.0.rc.1
+      def loaded?
+        !!@loaded
+      end
+
+      # Takes the supplied documents and sets the metadata on them. Used when
+      # creating new documents and adding them to the relation.
+      #
+      # @example Set the metadata.
+      #   proxy.characterize(addresses)
+      #
+      # @param [ Array<Document> ] documents The documents to set metadata on.
+      #
+      # @since 2.0.0.rc.4
+      def characterize(documents)
+        documents.each { |doc| characterize_one(doc) }
+      end
+
+      # Takes the supplied document and sets the metadata on it.
+      #
+      # @example Set the metadata.
+      #   proxt.characterize_one(name)
+      #
+      # @param [ Document ] document The document to set on.
+      #
+      # @since 2.0.0.rc.4
+      def characterize_one(document)
+        document.metadata = metadata unless document.metadata
+      end
+
+      # Default behavior of method missing should be to delegate all calls
+      # to the target of the proxy. This can be overridden in special cases.
+      #
+      # @param [ String, Symbol ] name The name of the method.
+      # @param [ Array ] *args The arguments passed to the method.
+      def method_missing(name, *args, &block)
+        target.send(name, *args, &block)
+      end
+    end
+  end
+end

data/lib/mongoid/relations/referenced/in.rb

@@ -0,0 +1,216 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+    module Referenced #:nodoc:
+
+      # This class handles all behaviour for relations that are either
+      # one-to-many or one-to-one, where the foreign key is store on this side
+      # of the relation and the reference is to document(s) in another
+      # collection.
+      class In < 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.
+        #   game.person.bind
+        #
+        # @param [ Hash ] options The options to bind with.
+        #
+        # @option options [ true, false ] :binding 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)
+        end
+
+        # Instantiate a new referenced_in relation.
+        #
+        # @example Create the new relation.
+        #   Referenced::In.new(game, person, metadata)
+        #
+        # @param [ Document ] base The document this relation hangs off of.
+        # @param [ Document, Array<Document> ] target The target (parent) of the
+        #   relation.
+        # @param [ Metadata ] metadata The relation's metadata.
+        def initialize(base, target, metadata)
+          init(base, target, metadata) do
+            characterize_one(target)
+          end
+        end
+
+        # Substitutes the supplied target documents for the existing document
+        # in the relation.
+        #
+        # @example Substitute the relation.
+        #   name.substitute(new_name)
+        #
+        # @param [ Document, Array<Document> ] new_target The replacement.
+        # @param [ true, false ] building Are we in build mode?
+        #
+        # @return [ In, nil ] The relation or nil.
+        #
+        # @since 2.0.0.rc.1
+        def substitute(new_target, options = {})
+          old_target = target
+          tap do |relation|
+            relation.target = new_target
+            if new_target
+              bind(options)
+            else
+              unbind(old_target, options)
+              nil
+            end
+          end
+        end
+
+        # Unbinds the base object to the inverse of the relation. This occurs
+        # when setting a side of the relation to nil.
+        #
+        # @example Unbind the relation.
+        #   game.person.unbind
+        #
+        # @param [ Document, Array<Document> ] old_target The previous target.
+        # @param [ Hash ] options The options to bind with.
+        #
+        # @option options [ true, false ] :binding 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)
+        end
+
+        private
+
+        # Instantiate the binding associated with this relation.
+        #
+        # @example Get the binding object.
+        #   binding([ address ])
+        #
+        # @param [ Document, Array<Document> ] new_target The replacement.
+        #
+        # @return [ Binding ] The binding object.
+        #
+        # @since 2.0.0.rc.1
+        def binding(new_target = nil)
+          Bindings::Referenced::In.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.
+          #   Referenced::In.builder(meta, object)
+          #
+          # @param [ Metadata ] meta The metadata of the relation.
+          # @param [ Document, Hash ] object A document or attributes to build
+          #   with.
+          #
+          # @return [ Builder ] A new builder object.
+          #
+          # @since 2.0.0.rc.1
+          def builder(meta, object)
+            Builders::Referenced::In.new(meta, object)
+          end
+
+          # Returns true if the relation is an embedded one. In this case
+          # always false.
+          #
+          # @example Is this relation embedded?
+          #   Referenced::In.embedded?
+          #
+          # @return [ false ] Always false.
+          #
+          # @since 2.0.0.rc.1
+          def embedded?
+            false
+          end
+
+          # Get the default value for the foreign key.
+          #
+          # @example Get the default.
+          #   Referenced::In.foreign_key_default
+          #
+          # @return [ nil ] Always nil.
+          #
+          # @since 2.0.0.rc.1
+          def foreign_key_default
+            nil
+          end
+
+          # Returns the suffix of the foreign key field, either "_id" or "_ids".
+          #
+          # @example Get the suffix for the foreign key.
+          #   Referenced::In.foreign_key_suffix
+          #
+          # @return [ String ] "_id"
+          #
+          # @since 2.0.0.rc.1
+          def foreign_key_suffix
+            "_id"
+          end
+
+          # Returns the macro for this relation. Used mostly as a helper in
+          # reflection.
+          #
+          # @example Get the macro.
+          #   Referenced::In.macro
+          #
+          # @return [ Symbol ] :referenced_in
+          def macro
+            :referenced_in
+          end
+
+          # Return the nested builder that is responsible for generating the documents
+          # that will be used by this relation.
+          #
+          # @example Get the nested builder.
+          #   Referenced::In.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 [ NestedBuilder ] 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?
+          #   Referenced::In.stores_foreign_key?
+          #
+          # @return [ true ] Always true.
+          #
+          # @since 2.0.0.rc.1
+          def stores_foreign_key?
+            true
+          end
+        end
+      end
+    end
+  end
+end