jinx 2.1.3 → 2.1.4

data/lib/jinx/metadata/attribute_enumerator.rb

@@ -1,8 +1,10 @@
+require 'jinx/helpers/collection'
+
 module Jinx
   # A filter on the standard attribute symbol => metadata hash that yields
   # each attribute which satisfies the attribute metadata condition.
   class AttributeEnumerator
-    include Enumerable
+    include Enumerable, Collection
 
     # @param [{Symbol => Property}] hash the attribute symbol => metadata hash
     # @yield [prop] optional condition which determines whether the attribute is
@@ -46,18 +48,10 @@ module Jinx
       @prop_enum ||= enum_for(:each_property)
     end
     
-    # @yield [attribute] the block to apply to the attribute
-    # @yieldparam [Symbol] attribute the attribute to detect
-    # @return [Property] the first attribute metadata whose attribute satisfies the block
-    def detect_property
-      each_pair { |pa, prop| return prop if yield(pa) }
-      nil
-    end
-    
     # @yield [prop] the block to apply to the attribute metadata
     # @yieldparam [Property] prop the attribute metadata
     # @return [Symbol] the first attribute whose metadata satisfies the block
-    def detect_with_property
+    def detect_attribute_with_property
       each_pair { |pa, prop| return pa if yield(prop) }
       nil
     end
@@ -67,7 +61,7 @@ module Jinx
     # @return [AttributeEnumerator] a new eumerator which applies the filter block given to this
     #   method with the Property enumerated by this enumerator
     def compose
-      AttributeEnumerator.new(@hash) { |prop| @filter.call(prop) and yield(prop) }
+      AttributeEnumerator.new(@hash) { |prop| yield(prop) if @filter.call(prop) }
     end
   end
 end

data/lib/jinx/metadata/dependency.rb

@@ -3,35 +3,44 @@ require 'jinx/helpers/validation'
 module Jinx
   # Metadata mix-in to capture Resource dependency.
   module Dependency
-    # @return [<Class>] the owner classes
-    attr_reader :owners
-    
     # @return [<Symbol>] the owner reference attributes
     attr_reader :owner_attributes
 
-    # Adds the given attribute as a dependent.
+    # Adds the given property as a dependent.
     #
-    # If the attribute inverse is not a collection, then the attribute writer
+    # If the property inverse is not a collection, then the property writer
     # is modified to delegate to the dependent owner writer. This enforces
     # referential integrity by ensuring that the following post-condition holds:
     # *  _owner_._attribute_._inverse_ == _owner_
     # where:
-    # * _owner_ is an instance this attribute's declaring class
+    # * _owner_ is an instance this property's declaring class
     # * _inverse_ is the owner inverse attribute defined in the dependent class
     #
-    # @param [Symbol] attribute the dependent to add
+    # @param [Property] property the dependent to add
     # @param [<Symbol>] flags the attribute qualifier flags
-    def add_dependent_attribute(attribute, *flags)
-      prop = property(attribute)
-      logger.debug { "Marking #{qp}.#{attribute} as a dependent attribute of type #{prop.type.qp}..." }
+    def add_dependent_property(property, *flags)
+      logger.debug { "Marking #{qp}.#{property} as a dependent attribute of type #{property.type.qp}..." }
       flags << :dependent unless flags.include?(:dependent)
-      prop.qualify(*flags)
-      inverse = prop.inverse
-      inv_type = prop.type
-      # example: Parent.add_dependent_attribute(:children) with inverse :parent calls the following:
+      property.qualify(*flags)
+      inv = property.inverse
+      inv_type = property.type
+      # example: Parent.add_dependent_property(child_prop) with inverse :parent calls the following:
       #   Child.add_owner(Parent, :children, :parent)
-      inv_type.add_owner(self, attribute, inverse)
-      logger.debug { "Marked #{qp}.#{attribute} as a dependent attribute with inverse #{inv_type.qp}#{inverse}." }
+      inv_type.add_owner(self, property.attribute, inv)
+      if inv then
+        logger.debug "Marked #{qp}.#{property} as a dependent attribute with inverse #{inv_type.qp}.#{inv}."
+      else  
+        logger.debug "Marked #{qp}.#{property} as a uni-directional dependent attribute."
+      end
+    end
+
+    # Adds the given attribute as a dependent.
+    #
+    # @see #add_dependent_property
+    # @param [Symbol] attribute the dependent to add
+    # @param (see #add_dependent_property)
+    def add_dependent_attribute(attribute, *flags)
+      add_dependent_property(property(attribute), *flags)
     end
     
     # @return [Boolean] whether this class depends on an owner
@@ -66,19 +75,40 @@ module Jinx
     end
     
     # @return [Boolean] whether this {Resource} class is dependent and reference its owners
-    def bidirectional_dependent?
-      dependent? and not owner_attributes.empty?
+    def bidirectional_java_dependent?
+      dependent? and owner_properties.any? { |prop| prop.java_property? }
     end
 
     # @return [<Class>] this class's dependent types
-    def dependents
-      dependent_attributes.wrap { |da| da.type }
+    def dependent_types
+      dependent_properties.wrap { |dp| dp.type }
+    end
+    
+    # @return [<Property>, nil] the path of this class to the given class through dependent
+    #   properties, or nil if there is no such path exists
+    def dependency_path_to(klass)
+      return if klass.owner_types.empty? 
+      op = klass.owner_properties.detect { |prop| self <= prop.type }
+      dp = op.inverse if op
+      dp ||= if klass.owner_properties.size < klass.owner_types.size then
+        dependent_properties.detect { |prop| klass <= prop.type }
+      end
+      return [dp] if dp
+      dependent_properties.detect_value do |dp|
+        next if self <= dp.type
+        path = dp.type.dependency_path_to(klass)
+        path.unshift(dp) if path
+      end
     end
+    
+    alias :dependents :dependent_types
 
     # @return [<Class>] this class's owner types
-    def owners
+    def owner_types
       @owners ||= Enumerable::Enumerator.new(owner_property_hash, :each_key)
     end
+    
+    alias :owners :owner_types
 
     # @return [Property, nil] the sole owner attribute metadata of this class, or nil if there
     #   is not exactly one owner
@@ -122,29 +152,34 @@ module Jinx
         raise MetadataError.new("Can't add #{qp} owner #{klass.qp} after dependencies have been accessed")
       end
       
-      # detect the owner attribute, if necessary
+      # Detect the owner attribute, if necessary.
       attribute ||= detect_owner_attribute(klass, inverse)
-      prop = property(attribute) if attribute
+      hash = local_owner_property_hash
+      # Guard against a conflicting owner reference attribute.
+      if hash[klass] then
+        raise MetadataError.new("Cannot set #{qp} owner attribute to #{attribute or 'nil'} since it is already set to #{hash[klass]}")
+      end
       # Add the owner class => attribute entry.
       # The attribute is nil if the dependency is unidirectional, i.e. there is an owner class which
       # references this class via a dependency attribute but there is no inverse owner attribute.
-      local_owner_property_hash[klass] = prop
+      prop = property(attribute) if attribute
+      hash[klass] = prop
       # If the dependency is unidirectional, then our job is done.
       if attribute.nil? then
-        logger.debug { "#{qp} owner #{klass.qp} has unidirectional inverse #{inverse}." }
+        logger.debug { "#{qp} owner #{klass.qp} has unidirectional dependent attribute #{inverse}." }
         return
       end
 
-      # Bi-directional: add the owner property
+      # Bi-directional: add the owner property.
       local_owner_properties << prop
-      # set the inverse if necessary
+      # Set the inverse if necessary.
       unless prop.inverse then
         set_attribute_inverse(attribute, inverse)
       end
-      # set the owner flag if necessary
-      unless prop.owner? then prop.qualify(:owner) end
+      # Set the owner flag if necessary.
+      prop.qualify(:owner) unless prop.owner?
 
-      # Redefine the writer method to warn when changing the owner.
+      # Redefine the writer method to issue a warning if the owner is changed.
       rdr, wtr = prop.accessors
       redefine_method(wtr) do |old_wtr|
         lambda do |ref|

data/lib/jinx/metadata/id_alias.rb

@@ -11,6 +11,7 @@ module Jinx
     def identifier
       getId
     end
+    
 
     # Sets the identifier to the given value.
     # This method delegates to the Java +id+ attribute writer method.

data/lib/jinx/metadata/introspector.rb

@@ -8,18 +8,32 @@ module Jinx
   # Meta-data mix-in to infer attribute meta-data from Java properties.
   module Introspector
     include Propertied
-    
-    # @return [Boolean] whether this class has been introspected
-    def introspected?
-      !!@introspected
+      
+    # Introspects the given class, if necessary. Some member of the class hierarchy
+    # must first be introspected.
+    #
+    # @param [Class] klass the class to introspect if necessary 
+    # @raise [NoSuchMethodError] if the class or an ancestor of the class is not
+    #   introspected 
+    def self.ensure_introspected(klass)
+      return if klass < Resource and klass.introspected?
+      sc = klass.superclass
+      ensure_introspected(sc) unless sc == Java::java.lang.Object
+      logger.debug { "Introspecting the fetched object class #{klass}..." }
+      # Resolving the class name in the context of the domain module
+      # introspects the class.
+      sc.domain_module.const_get(klass.name.demodulize)
     end
     
-    # Adds an optional {attribute=>value} constructor parameter to this class.
+    # Augments the introspected class +new+ method as follows:
+    # * Adds an optional {attribute=>value} constructor parameter.
+    # * Calls the {Resource#post_initialize} method after initialization.
     def add_attribute_value_initializer
       class << self
-        def new(params=nil)
+        def new(opts=nil)
           obj = super()
-          obj.merge_attributes(params) if params
+          obj.post_initialize
+          obj.merge_attributes(opts) if opts
           obj
         end
       end
@@ -52,8 +66,6 @@ module Jinx
         # Define the standard Java attribute methods.
         pds.each { |pd| define_java_property(pd) }
       end
-      # Mark this class as introspected.
-      @introspected = true
       logger.debug { "Introspection of #{qp} metadata complete." }
       self
     end

data/lib/jinx/metadata/inverse.rb

@@ -23,10 +23,13 @@ module Jinx
     # A domain attribute is recognized as an inverse according to the
     # {Inverse#detect_inverse_attribute} criterion.
     #
-    # @param [Attribute] property the property to check
+    # @param [Property] property the property to check
+    # @return [Symbol, nil] the inverse attribute, or nil if none was
+    #   detected
     def infer_property_inverse(property)
       inv = property.type.detect_inverse_attribute(self)
-      if inv then set_attribute_inverse(property.attribute, inv) end
+      set_attribute_inverse(property.attribute, inv) if inv
+      inv
     end
     
     # Sets the given bi-directional association attribute's inverse.
@@ -63,7 +66,7 @@ module Jinx
       # If attribute is the one side of a 1:M or non-reflexive 1:1 relation, then add the inverse updater.
       unless prop.collection? then
         # Inject adding to the inverse collection into the attribute writer method. 
-        add_inverse_updater(pa, inverse)
+        add_inverse_updater(pa)
         unless prop.type == inv_prop.type or inv_prop.collection? then
           prop.type.delegate_writer_to_inverse(inverse, pa)
         end
@@ -151,26 +154,26 @@ module Jinx
     # @return (see #detect_inverse_attribute)
     def detect_inverse_attribute_from_candidates(klass, candidates)
       return if candidates.empty?
-      # there can be at most one owner attribute per owner.
+      # There can be at most one owner attribute per owner.
       return candidates.first.to_sym if candidates.size == 1
-      # by convention, if more than one attribute references the owner type,
-      # then the attribute named after the owner type is the owner attribute
-      tgt = klass.name[/\w+$/].underscore.to_sym
+      # By convention, if more than one attribute references the owner type,
+      # then the attribute named after the owner type is the owner attribute.
+      tgt = klass.name.demodulize.underscore.to_sym
       tgt if candidates.detect { |pa| pa == tgt }
     end
     
     # Modifies the given attribute writer method to update the given inverse.
     #
     # @param (see #set_attribute_inverse)
-    def add_inverse_updater(attribute, inverse)
+    def add_inverse_updater(attribute)
       prop = property(attribute)
       # the reader and writer methods
       rdr, wtr = prop.accessors
-      # the inverse atttribute metadata
+      # the inverse attribute metadata
       inv_prop = prop.inverse_property
       # the inverse attribute reader and writer
       inv_rdr, inv_wtr = inv_accessors = inv_prop.accessors
-      # Redefine the writer method to update the inverse by delegating to the inverse
+      # Redefine the writer method to update the inverse by delegating to the inverse.
       redefine_method(wtr) do |old_wtr|
         # the attribute reader and (superseded) writer
         accessors = [rdr, old_wtr]
@@ -180,7 +183,7 @@ module Jinx
           lambda { |other| set_inversible_noncollection_attribute(other, accessors, inv_wtr) }
         end
       end
-      logger.debug { "Injected inverse #{inverse} updater into #{qp}.#{attribute} writer method #{wtr}." }
+      logger.debug { "Injected inverse #{inv_prop} updater into #{qp}.#{attribute} writer method #{wtr}." }
     end
   end
 end

data/lib/jinx/metadata/java_property.rb

@@ -5,6 +5,9 @@ module Jinx
   # The attribute metadata for an introspected Java property. 
   class JavaProperty < Property
 
+    # This property's Java property descriptor type JRuby class wrapper.
+    attr_reader :java_wrapper_class
+
     # This property's Java property descriptor.
     attr_reader :property_descriptor
 
@@ -35,21 +38,22 @@ module Jinx
       # deficient Java introspector does not recognize 'is' prefix for a Boolean property
       rm = declarer.property_read_method(pd)
       raise ArgumentError.new("Property does not have a read method: #{declarer.qp}.#{pd.name}") unless rm
-      reader = rm.name.to_sym
-      unless declarer.method_defined?(reader) then
-        reader = "is#{reader.to_s.capitalize_first}".to_sym
-        unless declarer.method_defined?(reader) then
+      rdr = rm.name.to_sym
+      unless declarer.method_defined?(rdr) then
+        rdr = "is#{rdr.to_s.capitalize_first}".to_sym
+        unless declarer.method_defined?(rdr) then
           raise ArgumentError.new("Reader method not found for #{declarer} property #{pd.name}")
         end
       end
       unless pd.write_method then
         raise ArgumentError.new("Property does not have a write method: #{declarer.qp}.#{pd.name}")
       end
-      writer = pd.write_method.name.to_sym
-      unless declarer.method_defined?(writer) then
+      wtr = pd.write_method.name.to_sym
+      unless declarer.method_defined?(wtr) then
         raise ArgumentError.new("Writer method not found for #{declarer} property #{pd.name}")
       end
-      @java_accessors = [reader, writer]
+      @java_accessors = [rdr, wtr]
+      @java_wrapper_class = Class.to_ruby(pd.property_type)
       qualify(:collection) if collection_java_class?
       @type = infer_type
     end
@@ -97,15 +101,13 @@ module Jinx
 
     # @return [Boolean] whether this property's Java type is +Iterable+
     def collection_java_class?
-      # the Java property type
-      ptype = @property_descriptor.property_type
-      # Test whether the corresponding JRuby wrapper class or module is an Iterable.
-      Class.to_ruby(ptype) < Java::JavaLang::Iterable
+      # Test whether the JRuby wrapper class or module is an Iterable.
+      @java_wrapper_class < Java::JavaLang::Iterable
     end
 
     # @return [Class] the type for the specified klass property descriptor pd as described in {#initialize}
     def infer_type
-      collection? ? infer_collection_type : infer_non_collection_type
+      collection? ? infer_collection_type : @java_wrapper_class
     end
 
     # Returns the domain type for this property's Java Collection property descriptor.
@@ -117,12 +119,6 @@ module Jinx
        generic_parameter_type or infer_collection_type_from_name or Java::JavaLang::Object
     end
 
-    # @return [Class] this property's Ruby type
-    def infer_non_collection_type
-      jtype = @property_descriptor.property_type
-      Class.to_ruby(jtype)
-    end
-
     # @return [Class, nil] the domain type of this property's property descriptor Collection generic
     #   type argument, or nil if none
     def generic_parameter_type
@@ -132,18 +128,11 @@ module Jinx
       atypes = gtype.actualTypeArguments
       return unless atypes.size == 1
       atype = atypes[0]
-      klass = java_to_ruby_class(atype)
+      klass = Class.to_ruby(atype)
       logger.debug { "Inferred #{declarer.qp} #{self} domain type #{klass.qp} from generic parameter #{atype.name}." } if klass
       klass
     end
 
-    # @param [Class, String] jtype the Java class or class name
-    # @return [Class] the corresponding Ruby type 
-    def java_to_ruby_class(jtype)
-      name = String === jtype ? jtype : jtype.name
-      Class.to_ruby(name)
-    end
-
     # Returns the domain type for this property's collection Java property descriptor name.
     # By convention, Jinx domain collection propertys often begin with a domain type
     # name and end in 'Collection'. This method strips the Collection suffix and checks

data/lib/jinx/metadata/propertied.rb

@@ -10,7 +10,7 @@ module Jinx
     # @return [<Symbol>] this class's attributes
     attr_reader :attributes
     
-    # @return [Hashable] the default attribute => value associations
+    # @return [Hasher] the default attribute => value associations
     attr_reader :defaults
 
     # Returns whether this class has an attribute with the given symbol.
@@ -77,6 +77,11 @@ module Jinx
       @prop_hash.each_value(&block)
     end
 
+    # @return [<Property>] this domain class's properties
+    def properties
+      @props ||= enum_for(:each_property)
+    end
+
     # @param [Symbol] attribute the property attribute symbol or alias
     # @return [Property] the corresponding property
     # @raise [NameError] if the attribute is not recognized
@@ -133,6 +138,11 @@ module Jinx
     def domain_attributes
       @dom_flt ||= attribute_filter { |prop| prop.domain? }
     end
+    
+    # @return [<Property>] the domain properties
+    def domain_properties
+      domain_attributes.properties
+    end
 
     # @return [<Symbol>] the non-domain Java attributes
     def nondomain_attributes
@@ -164,6 +174,12 @@ module Jinx
       end
     end
     
+    # @param (see #dependent_attributes)
+    # @return [<Property>] the dependent properties
+    def dependent_properties(inc_super=true)
+      dependent_attributes(inc_super).properties
+    end
+    
     # @return [<Symbol>] the unidirectional dependent attributes
     # @see Property#unidirectional?
     def unidirectional_dependent_attributes
@@ -250,7 +266,48 @@ module Jinx
       @local_defaults = {}
       @defaults = append_ancestor_enum(@local_defaults) { |par| par.defaults }
     end
-              
+    
+    # Creates a new convenience property in this source class which composes
+    # the given property and the other property. The new property symbol is
+    # the same as the other property symbol. The new property reader and
+    # writer methods delegate to the respective composed property reader and
+    # writer methods.
+    #
+    # @param [Property] property the reference from the source to the intermediary
+    # @param [Property] other the reference from the intermediary to the target
+    # @yield [target] obtain the intermediary object from the target
+    # @yieldparam [Resource] target the target object
+    # @return [Property] the new property
+    # @raise [ArgumentError] if the other property does not have an inverse
+    def compose_property(property, other)
+      if other.inverse.nil? then
+        raise ArgumentError.new("Can't compose #{qp}.#{property} with inverseless #{other.declarer.qp}.#{other}")
+      end
+      # the source -> intermediary access methods
+      sir, siw = property.accessors
+      # the intermediary -> target access methods
+      itr, itw = other.accessors
+      # the target -> intermediary reader method
+      tir = other.inverse
+      # The reader composes the source -> intermediary -> target readers.
+      define_method(itr) do
+        ref = send(sir)
+        ref.send(itr) if ref
+      end
+      # The writer sets the source intermediary to the target intermediary.
+      define_method(itw) do |tgt|
+        if tgt then
+          ref = block_given? ? yield(tgt) : tgt.send(tir)
+          raise ArgumentError.new("#{tgt} does not reference a #{other.inverse}") if ref.nil?
+        end
+        send(siw, ref)
+      end
+      prop = add_attribute(itr, other.type)
+      logger.debug { "Created #{qp}.#{prop} which composes #{qp}.#{property} and #{other.declarer.qp}.#{other}." }
+      prop.qualify(:collection) if other.collection?
+      prop
+    end
+             
     # @param (see #add_attribute)
     # @return (see #add_attribute) 
     def create_nonjava_property(attribute, type, *flags)
@@ -279,14 +336,6 @@ module Jinx
       end
     end
     
-    # Detects the first attribute with the given type.
-    #
-    # @param [Class] klass the target attribute type
-    # @return [Symbol, nil] the attribute with the given type
-    def detect_attribute_with_type(klass)
-      property_hash.detect_key_with_value { |prop| prop.type == klass }
-    end
-    
     # Creates the given attribute alias. If the attribute metadata is registered with this class, then
     # this method overrides +Class.alias_attribute+ to create a new alias reader (writer) method
     # which delegates to the attribute reader (writer, resp.). This aliasing mechanism differs from
@@ -398,18 +447,25 @@ module Jinx
 
     # Marks the given attribute with flags supported by {Property#qualify}.
     #
-    # @param [Symbol] attribute the attribute to qualify
+    # @param [Property] property the property to qualify
     # @param [{Symbol => Object}] the flags to apply to the restricted attribute
-    def qualify_attribute(attribute, *flags)
-      prop = property(attribute)
-      if prop.declarer == self then
-        prop.qualify(*flags)
+    def qualify_property(property, *flags)
+      if property.declarer == self then
+        property.qualify(*flags)
       else
-        logger.debug { "Restricting #{prop.declarer.qp}.#{attribute} to #{qp} with additional flags #{flags.to_series}" }
-        prop.restrict_flags(self, *flags)
+        logger.debug { "Restricting #{property.declarer.qp}.#{property} to #{qp} with additional flags #{flags.to_series}" }
+        property.restrict_flags(self, *flags)
       end
     end
 
+    # Convenience method which delegates to {#qualify_property}.
+    #
+    # @param [Symbol] attribute the attribute to qualify
+    # @param [{Symbol => Object}] (see #qualify_property)
+    def qualify_attribute(attribute, *flags)
+      qualify_property(property(attribute), *flags)
+    end
+
     # Removes the given attribute from this Resource.
     # An attribute declared in a superclass Resource is hidden from this Resource but retained in
     # the declaring Resource.
@@ -431,11 +487,16 @@ module Jinx
         anc_alias_hash = @alias_std_prop_map.components[1]
         @alias_std_prop_map.components[1] = anc_alias_hash.filter_on_key { |pa| pa != attribute }
       end
+      logger.debug { "Removed the #{qp} #{attribute} property." }
     end
 
     # @param [Property] the property to add
     def add_property(property)
       pa = property.attribute
+      # Guard against redundant property
+      if @local_prop_hash.has_key?(pa) then
+        raise ArgumentError.new("#{self} property already exists: #{pa}")
+      end
       @local_prop_hash[pa] = property
       # map the attribute symbol to itself in the alias map
       @local_std_prop_hash[pa] = pa
@@ -451,13 +512,13 @@ module Jinx
     end
 
     # Appends to the given enumerable the result of evaluating the block given to this method
-    # on the superclass, if the superclass is in the same parent module as this class.
+    # on the superclass, if the superclass is also a {Resource} class.
     #
     # @param [Enumerable] enum the base collection
     # @return [Enumerable] the {Enumerable#union} of the base collection with the superclass
     #   collection, if applicable 
     def append_ancestor_enum(enum)
-      return enum unless Class === self and superclass.parent_module == parent_module
+      return enum unless Class === self and superclass < Resource and superclass.introspected?
       anc_enum = yield superclass
       if anc_enum.nil? then
         raise MetadataError.new("#{qp} superclass #{superclass.qp} does not have required metadata")