caruby-core 1.4.2 → 1.4.3

data/lib/caruby/domain/resource_attributes.rb

@@ -6,13 +6,21 @@ module CaRuby
   # ResourceMetadata mix-in for attribute accessors.
   module ResourceAttributes
 
-    attr_reader :attributes, :defaults
+    attr_reader :attributes
+    
+    # @return [Hashable] the default attribute => value associations
+    attr_reader :defaults
 
-    # Returns the subject class's required attributes, determined as follows:
-    # * An attribute marked with the :mandatory flag is mandatory.
-    # * An attribute marked with the :optional or :autogenerated flag is not mandatory.
-    # * Otherwise, A secondary key or owner attribute is mandatory.
-    attr_reader :mandatory_attributes
+    # Returns whether this class has an attribute with the given symbol.
+    #
+    # @param [Symbol] symbol the potential attribute
+    # @return [Boolean] whether there is a corresponding attribute
+    def attribute_defined?(symbol)
+      unless Symbol === symbol then
+        raise ArgumentError.new("Attribute argument #{symbol.qp} of type #{symbol.class.qp} is not a symbol")
+      end
+      @attr_md_hash.has_key?(symbol)
+    end
 
     # Adds the given attribute to this Class.
     # If attribute refers to a domain type, then the type argument is the referenced domain type.
@@ -46,7 +54,7 @@ module CaRuby
     def attribute_metadata(attribute)
       # simple and predominant case is that attribute is a standard attribute.
       # otherwise, resolve attribute to the standard symbol.
-      attr_md = attribute_metadata_hash[attribute] || attribute_metadata_hash[standard_attribute(attribute)]
+      attr_md = @attr_md_hash[attribute] || @attr_md_hash[standard_attribute(attribute)]
       # if not found, then delegate to handler which will either make the new attribute or raise a NameError
       attr_md || (attribute_missing(attribute) && @local_attr_md_hash[attribute])
     end
@@ -55,13 +63,7 @@ module CaRuby
     #
     # Raises NameError if the attribute is not found
     def standard_attribute(name_or_alias)
-      alias_standard_attribute_hash[name_or_alias.to_sym] or raise NameError.new("#{qp} attribute not found: #{name_or_alias}")
-    end
-
-    # Returns an Enumerable on this Metadata's attributes which iterates on each attribute whose
-    # corresponding AttributeMetadata satisfies the given filter block.
-    def attribute_filter(&filter) # :yields: attribute_metadata
-     Filter.new(attribute_metadata_hash, &filter)
+      @alias_std_attr_map[name_or_alias.to_sym] or raise NameError.new("#{self} attribute not found: #{name_or_alias}")
     end
 
     ## the built-in Metadata attribute filters ##
@@ -92,9 +94,14 @@ module CaRuby
     # @see Mergeable#mergeable_attributes
     alias :mergeable_attributes :nondomain_java_attributes
 
+    # @param [Boolean, nil] inc_super flag indicating whether to include dependents defined in the superclass
     # @return [<Symbol>] the dependent attributes
-    def dependent_attributes
-      @dep_attrs ||= attribute_filter { |attr_md| attr_md.dependent? }
+    def dependent_attributes(inc_super=true)
+      if inc_super then
+        @dep_attrs ||= attribute_filter { |attr_md| attr_md.dependent? }
+      else
+        @local_dep_attrs ||= dependent_attributes.compose { |attr_md| attr_md.declarer == self }
+      end
     end
 
     # @return [<Symbol>] the dependent attributes
@@ -102,12 +109,6 @@ module CaRuby
       @ag_dep_attrs ||= dependent_attributes.compose { |attr_md| attr_md.autogenerated? }
     end
 
-    # @return [<Symbol>] the dependent attributes which are created but not fetched
-    # @see AttributeMetadata#unfetched_created?
-    def unfetched_created_attributes
-      @uc_attrs ||= attribute_filter { |attr_md| attr_md.unfetched_created? }
-    end
-
     # @return [<Symbol>] the autogenerated logical dependent attributes
     # @see #logical_dependent_attributes
     # @see AttributeMetadata#autogenerated?
@@ -115,9 +116,9 @@ module CaRuby
       @ag_log_dep_attrs ||= dependent_attributes.compose { |attr_md| attr_md.autogenerated? and attr_md.logical? }
     end
     
-    # @return [<Symbol>] the autogenerated {AttributeMetadata#saved_mergeable?} dependent attributes
-    def mergeable_saved_autogenerated_attributes
-      @mgbl_sv_unftchd_ag_attrs ||= autogenerated_dependent_attributes.compose { |attr_md| attr_md.saved_mergeable? }
+    # @return [<Symbol>] the {AttributeMetadata#saved_fetch?} attributes
+    def saved_fetch_attributes
+      @svd_ftch_attrs ||= domain_attributes.compose { |attr_md| attr_md.saved_fetch? }
     end
     
     # @return [<Symbol>] the logical dependent attributes
@@ -182,6 +183,10 @@ module CaRuby
       @cp_sv_attrs ||= dependent_attributes.compose { |attr_md| attr_md.autogenerated? or not attr_md.logical? }
     end
 
+    # Returns the subject class's required attributes, determined as follows:
+    # * An attribute marked with the :mandatory flag is mandatory.
+    # * An attribute marked with the :optional or :autogenerated flag is not mandatory.
+    # * Otherwise, A secondary key or owner attribute is mandatory.
     def mandatory_attributes
       @mndtry_attrs ||= collect_mandatory_attributes
     end
@@ -257,18 +262,15 @@ module CaRuby
     end
 
     #@return [<Symbol>] the #domain_attributes which are not #fetched_domain_attributes
-    def unfetched_domain_attributes
+    def unfetched_attributes
       @unftchd_attrs ||= domain_attributes.compose { |attr_md| not attr_md.fetched? }
     end
+    
+    alias :toxic_attributes :unfetched_attributes
 
-    # @return [<Symbol>] the Java property non-abstract {#unfetched_domain_attributes}
+    # @return [<Symbol>] the Java property non-abstract {#unfetched_attributes}
     def loadable_attributes
-      @unftchd_attrs ||= unfetched_domain_attributes.compose { |attr_md| attr_md.java_property? and not attr_md.type.abstract? }
-    end
-
-    # @return [<Symbol>] the {#loadable_attributes} which are not {AttributeMetadata#autogenerated?}
-    def non_autogenerated_loadable_attributes
-      @unftchd_attrs ||= unfetched_domain_attributes.compose { |attr_md| not attr_md.type.autogenerated? }
+      @ldbl_attrs ||= unfetched_attributes.compose { |attr_md| attr_md.java_property? and not attr_md.type.abstract? }
     end
 
     # @param [Symbol] attribute the attribute to check
@@ -290,18 +292,14 @@ module CaRuby
     end
 
     protected
-
+    
     # @return [{Symbol => AttributeMetadata}] the attribute => metadata hash
     def attribute_metadata_hash
-      # initialize the meta-data if necessary
-      superclass.introspect_subclass(self) if @attr_md_hash.nil?
       @attr_md_hash
     end
 
     # @return [{Symbol => Symbol}] the attribute alias => standard hash
     def alias_standard_attribute_hash
-      # initialize the meta-data if necessary
-      superclass.introspect_subclass(self) if @alias_std_attr_map.nil?
       @alias_std_attr_map
     end
 
@@ -324,18 +322,52 @@ module CaRuby
         @filter = filter
       end
 
-      # @yield [attribute] enumerates each filtered attribute
+      # @yield [attribute, attr_md] the block to apply to the filtered attribute metadata and attribute
+      # @yieldparam [Symbol] attribute the attribute
+      # @yieldparam [AttributeMetadata] attr_md the attribute metadata
+      def each_pair
+        @hash.each { |attr, attr_md| yield(attr, attr_md) if @filter.call(attr_md) }
+      end
+      
+      # @yield [attribute] block to apply to each filtered attribute
       # @yieldparam [Symbol] the attribute which satisfies the filter condition
-      def each(&block)
-        @hash.each { |k, v| yield(k) if @filter.call(v) }
+      def each_attribute(&block)
+        each_pair { |attr, attr_md| yield(attr) }
+      end
+      
+      alias :each :each_attribute
+
+      # @yield [attr_md] the block to apply to the filtered attribute metadata
+      # @yieldparam [AttributeMetadata] attr_md the attribute metadata
+      def each_metadata
+        each_pair { |attr, attr_md| yield(attr_md) }
+      end
+      
+      # @yield [attr_md] the block to apply to the attribute metadata
+      # @yieldparam [AttributeMetadata] attr_md the attribute metadata
+      # @return [Symbol] the first attribute whose metadata satisfies the block
+      def detect_with_metadata
+        each_pair { |attr, attr_md| return attr if yield(attr_md) }
+        nil
       end
 
+      # @yield [attr_md] the attribute selection filter
+      # @yieldparam [AttributeMetadata] attr_md the candidate attribute metadata
       # @return [Filter] a new Filter which applies the filter block given to this
-      #   method with the AttributeMetadata enumerated by this filter.
+      #   method with the AttributeMetadata enumerated by this filter
       def compose
         Filter.new(@hash) { |attr_md| @filter.call(attr_md) and yield(attr_md) }
       end
     end
+    
+    # Returns an Enumerable on this Resource class's attributes which iterates on each attribute whose
+    # corresponding AttributeMetadata satisfies the given filter block.
+    #
+    # @yield [attr_md] the attribute selector
+    # @yieldparam [AttributeMetadata] attr_md the candidate attribute
+    def attribute_filter(&filter)
+     Filter.new(@attr_md_hash, &filter)
+    end
 
     # Initializes the attribute meta-data structures.
     def init_attributes
@@ -349,6 +381,9 @@ module CaRuby
       @defaults = append_parent_enum(@local_defaults) { |par| par.defaults }
     end
 
+    # Creates the given aliases to attributes.
+    #
+    # @param [{Symbol => Symbol}] hash the alias => attribute hash
     def add_attribute_aliases(hash)
       hash.each { |aliaz, attr| delegate_to_attribute(aliaz, attr) }
     end
@@ -373,49 +408,20 @@ module CaRuby
     # Raises ArgumentError if klass is incompatible with the current attribute type.
     def set_attribute_type(attribute, klass)
       attr_md = attribute_metadata(attribute)
+      # If this class is the declarer, then simply set the attribute type.
+      # Otherwise, if the attribute type is unspecified or is a superclass of the given class,
+      # then make a new attribute metadata for this class.
       if attr_md.declarer == self then
         attr_md.type = klass
       elsif attr_md.type.nil? or klass < attr_md.type then
-        new_attr_md = attr_md.restrict(self, klass)
+        logger.debug { "Restricting #{attr_md.declarer.qp}.#{attribute}(#{attr_md.type.qp}) to #{qp} with return type #{klass.qp}..." }
+        new_attr_md = attr_md.restrict_type(self, klass)
         add_attribute_metadata(new_attr_md)
       elsif klass != attr_md.type then
         raise ArgumentError.new("Cannot reset #{qp}.#{attribute} type #{attr_md.type} to incompatible #{klass.qp}")
       end
     end
 
-    # Sets the given attribute inverse to the inverse symbol.
-    #
-    # Raises ArgumentError if the inverse type is incompatible with this Resource.
-    def set_attribute_inverse(attribute, inverse)
-      attr_md = attribute_metadata(attribute)
-      # return if inverse is already set
-      return if attr_md.inverse == inverse
-      # the inverse attribute meta-data
-      inv_md = attr_md.type.attribute_metadata(inverse)
-      # if the attribute is the many side of a 1:M relation, then delegate to the one side.
-      if attr_md.collection? and not inv_md.collection? then
-        return attr_md.type.set_attribute_inverse(inverse, attribute)
-      end
-      # this class must be the same as or a subclass of the inverse attribute type
-      unless self <= inv_md.type then
-        raise ArgumentError.new("Cannot set #{qp}.#{attribute} inverse to #{attr_md.type.qp}.#{attribute} with incompatible type #{inv_md.type.qp}")
-      end
-
-      # if the attribute is defined by this class, then set the inverse in the attribute metadata.
-      # otherwise, make a new attribute metadata specialized for this class.
-      unless attr_md.declarer == self then
-        attr_md = attr_md.dup
-        attr_md.declarer = self
-        add_attribute_metadata(attribute, inverse)
-      end
-      attr_md.inverse = inverse
-
-      # if attribute is the one side of a 1:M relation, then add the inverse updater.
-      unless attr_md.collection? then
-        add_inverse_updater(attribute, inverse)
-      end
-    end
-
     def add_attribute_defaults(hash)
       hash.each { |attr, value| @local_defaults[standard_attribute(attr)] = value }
     end
@@ -426,7 +432,14 @@ module CaRuby
 
     # Marks the given attribute with flags supported by {AttributeMetadata#qualify}.
     def qualify_attribute(attribute, *flags)
-      attribute_metadata(attribute).qualify(*flags)
+      attr_md = attribute_metadata(attribute)
+      if attr_md.declarer == self then
+        attr_md.qualify(*flags)
+      else
+        logger.debug { "Restricting #{attr_md.declarer.qp}.#{attribute} to #{qp} with additional flags #{flags.to_series}" }
+        new_attr_md = attr_md.restrict_flags(self, *flags)
+        add_attribute_metadata(new_attr_md)
+      end
     end
 
     # Removes the given attribute from this Resource.
@@ -439,9 +452,9 @@ module CaRuby
         @local_mndty_attrs.delete(std_attr)
         @local_std_attr_hash.delete_if { |aliaz, attr| attr == std_attr }
       else
-        @attr_md_hash = attribute_metadata_hash.filter_on_key { |attr| attr != attribute }
+        @attr_md_hash = @attr_md_hash.filter_on_key { |attr| attr != attribute }
         @attributes = Enumerable::Enumerator.new(@attr_md_hash, :each_key)
-        @alias_std_attr_map = alias_standard_attribute_hash.filter_on_key { |attr| attr != attribute }
+        @alias_std_attr_map = @alias_std_attr_map.filter_on_key { |attr| attr != attribute }
       end
     end
 
@@ -466,7 +479,7 @@ module CaRuby
     end
 
     def each_attribute_metadata(&block)
-      attribute_metadata_hash.each_value(&block)
+      @attr_md_hash.each_value(&block)
     end
 
     # Collects the {AttributeMetadata#fetched_dependent?} and {AttributeMetadata#fetched_independent?}

data/lib/caruby/domain/resource_dependency.rb

@@ -25,20 +25,16 @@ module CaRuby
     # * _inverse_ is the owner inverse attribute defined in the dependent class
     #
     # @param [Symbol] attribute the dependent to add
-    # @param [Symbol] inverse the owner attribute defined in the dependent
     # @param [<Symbol>] the attribute qualifier flags
     def add_dependent_attribute(attribute, *flags)
       attr_md = attribute_metadata(attribute)
-      unless attr_md.inverse_attribute_metadata.collection? then
-        delegate_writer_to_dependent(attribute)
-      end
       flags << :dependent unless flags.include?(:dependent)
       attr_md.qualify(*flags)
       inverse = attr_md.inverse
       inv_type = attr_md.type
       # example: Parent.add_dependent_attribute(:children) with inverse :parent calls
-      # Child.add_owner(Parent, :parent, :children)
-      inv_type.add_owner(self, inverse, attribute)
+      # Child.add_owner(Parent, :children, :parent)
+      inv_type.add_owner(self, attribute, inverse)
     end
 
     # Returns whether this metadata's subject class depends on an owner.
@@ -51,18 +47,22 @@ module CaRuby
       owners.detect { |owner| owner === other }
     end
 
-    # Returns the attribute which references the dependent type, or nil if none.
+    # @return [Symbol, nil] the attribute which references the dependent type,
+    #   or nil if none
     def dependent_attribute(dep_type)
       type = dependent_attributes.detect { |attr| domain_type(attr) == dep_type }
       return type if type
       dependent_attribute(dep_type.superclass) if dep_type.superclass < Resource
     end
 
-    # Returns the sole owner attribute of this class, or nil if there is not exactly one owner.
+    # @return [Symbol, nil] the sole owner attribute of this class, or nil if there
+    #   is not exactly one owner
     def owner_attribute
       if @local_owner_attr_hash then
+        # the sole attribute in the owner class => attribute hash
         @local_owner_attr_hash.each_value { |attr| return attr } if @local_owner_attr_hash.size == 1
       elsif superclass < Resource
+        # delegate to superclass
         superclass.owner_attribute
       end
     end
@@ -96,24 +96,25 @@ module CaRuby
 
     protected
 
-    # If attribute is nil, then the owner attribute is inferred as follows:
-    # * If there is exactly one reference attribute from this dependent to the owner klass, then that
-    #   attribute is the owner attribute.
-    # * Otherwise, if this dependent class has a default attribute name given by the demodulized,
-    #   underscored owner class name and that attribute references the owner klass, then that attribute
-    #   is the owner attribute.
-    # * Otherwise, there is no owner attribute.
-    def add_owner(klass, attribute=nil, inverse=nil)
-      logger.debug { "Adding #{qp} owner #{klass.qp}..." }
+    # Adds the given owner class to this dependent class.
+    # This method must be called before any dependent attribute is accessed.
+    #
+    # @param [Class] the owner class
+    # @param [Symbol, nil] inverse the owner -> dependent attribute
+    # @param [Symbol, nil] attribute the dependent -> owner attribute, if known
+    # @raise [ValidationError] if there is no owner -> dependent inverse attribute
+    # @raise [MetadataError] if this method is called after a dependent attribute has been accessed
+    def add_owner(klass, inverse, attribute=nil)
+      logger.debug { "Adding #{qp} owner #{klass.qp}#{' attribute ' + attribute.to_s if attribute}#{' inverse ' + inverse.to_s if inverse}..." }
       if @owner_attr_hash then
         raise MetadataError.new("Can't add #{qp} owner #{klass.qp} after dependencies have been accessed")
       end
       @local_owner_attr_hash ||= {}
-      @local_owner_attr_hash[klass] = attribute ||= detect_owner_attribute(klass, inverse)
+      @local_owner_attr_hash[klass] = attribute ||= detect_inverse_attribute(klass)
 
-      # augment the owner writer method
+      # set the inverse
       if attribute then
-        raise ValidationError.new("Owner #{klass.qp} missing dependent attribute for dependent #{qp}") if inverse.nil?
+        if inverse.nil? then raise ValidationError.new("Owner #{klass.qp} missing dependent attribute for dependent #{qp}") end
         set_attribute_inverse(attribute, inverse)
         attribute_metadata(attribute).qualify(:owner)
       else
@@ -121,85 +122,9 @@ module CaRuby
       end
     end
 
-    # Returns this Resource class's owner type => attribute hash.
+    # @return [{Class => Symbol}] this Resource class's owner type => attribute hash
     def owner_attribute_hash
       @local_owner_attr_hash or (superclass.owner_attribute_hash if superclass < Resource) or Hash::EMPTY_HASH
     end
-
-    private
-
-    def domain_class?(klass)
-      Class === klass and klass.include?(CaRuby::Resource)
-    end
-
-    # Redefines the attribute writer method to delegate to its inverse writer.
-    #
-    # For an attribute +dep+ with setter +setDep+ and inverse +owner+ with setter +setOwner+,
-    # this is equivalent to the following:
-    #   class Owner
-    #     def dep=(d)
-    #       d.setOwner(self) if d
-    #       setDep(self)
-    #     end
-    #   end
-    def delegate_writer_to_dependent(attribute)
-      attr_md = attribute_metadata(attribute)
-      # nothing to do if no inverse
-      inv_attr_md = attr_md.inverse_attribute_metadata || return
-      logger.debug { "Delegating #{qp}.#{attribute} update to the inverse #{attr_md.type}.#{inv_attr_md}..." }
-      # redefine the write to set the dependent inverse
-      redefine_method(attr_md.writer) do |old_writer|
-        # delegate to the CaRuby::Resource set_exclusive_dependent method
-        lambda { |dep| set_exclusive_dependent(dep, old_writer, inv_attr_md.writer) }
-      end
-    end
-
-    # Returns the owner attribute for the given owner klass and inverse, or nil if no
-    # owner attribute was detected.
-    def detect_owner_attribute(klass, inverse=nil)
-      # example: Parent.add_dependent_attribute(:children) without inverse calls
-      # Child.add_owner(Parent, nil, :children) which calls
-      # Child.detect_owner_attribute(klass, :children)
-
-      # the candidate attributes which return the owner type
-      candidates = domain_attributes.map do |attr|
-        attr_md = attribute_metadata(attr)
-        # possible hit if there is a match on the type
-        attr_md if klass.equal?(attr_md.type) or klass <= attr_md.type
-      end
-      candidates.compact!
-      return if candidates.empty?
-
-      # there can be at most one owner attribute per owner.
-      return candidates.first.to_sym if candidates.size == 1
-
-      # we have a hit if there is a match on the inverse. in the above example,
-      # attribute :parent with inverse :children => :parent is the owner attribute
-      candidates.each { |attr_md| return attr_md.to_sym if attr_md.inverse == inverse }
-
-      # by convention, if more than one attribute references the owner type,
-      # then the attribute named after the owner type is the owner attribute
-      hit = klass.name[/\w+$/].downcase.to_sym
-      hit if candidates.detect { |attr_md| attr_md.to_sym == hit }
-    end
-
-    # Infers annotation dependent attributes based on whether a domain attribute satisfies the
-    # following criteria:
-    # 1. the referenced type has an attribute which refers back to this classifier's subject class
-    # 2. the referenced type is not an owner of this classifier's subject class
-    # Annotation dependencies are not specified in a configuration and follow the above convention.
-    def infer_annotation_dependent_attributes
-      dep_attrs = []
-      domain_attributes.each do |attr|
-        next if owner_attribute?(attr)
-        ref_md = domain_type(attr).metadata
-        owner_attr = ref_md.detect_owner_attribute(subject_class)
-        if owner_attr then
-          ref_md.add_owner(subject_class, owner_attr)
-          dep_attrs << attr
-        end
-      end
-      dep_attrs
-    end
   end
 end