caruby-core 1.4.7 → 1.4.9

data/lib/caruby/domain/attribute_metadata.rb

@@ -11,18 +11,18 @@ module CaRuby
   # * reader method symbol
   # * writer method symbol
   class AttributeMetadata
-    # The supported attribute qualifier flags.
+    # The supported attribute qualifier flags. See the complementary methods for an explanation of
+    # the flag option, e.g. {#autogenerated?} for the +:autogenerated+ flag.
     SUPPORTED_FLAGS = [
-      :autogenerated, :collection, :dependent, :derived, :logical, :disjoint, :owner, :cascaded,
-      :no_cascade_update_to_create, :saved, :unsaved, :optional, :fetched, :unfetched,
-      :create_only, :update_only, :unidirectional, :volatile].to_set
+      :autogenerated, :autogenerated_on_update, :collection, :dependent, :derived, :logical, :disjoint,
+      :owner, :cascaded, :no_cascade_update_to_create, :saved, :unsaved, :optional, :fetched, :unfetched,
+      :include_in_save_template, :saved_fetch, :create_only, :update_only, :unidirectional, :volatile].to_set
 
     # @return [(Symbol, Symbol)] the standard attribute reader and writer methods
     attr_reader :accessors
 
     # @return [Class] the declaring class
     attr_accessor :declarer
-    protected :declarer=
     
     # @return [Class] the return type
     attr_reader :type
@@ -88,7 +88,7 @@ module CaRuby
       @type = klass
       if @inv_md then
         self.inverse = @inv_md.to_sym
-        logger.debug { "Reset #{@declarer.qp}.#{self} inverse from #{@inv_md.type}.#{@inv_md} to #{klass}#{inv_md}." }
+        logger.debug { "Reset #{@declarer.qp}.#{self} inverse from #{@inv_md.type}.#{@inv_md} to #{klass}#{@inv_md}." }
       end
     end
 
@@ -150,9 +150,8 @@ module CaRuby
         # if this attribute is disjoint, then so is the inverse.
         @inv_md.qualify(:disjoint) if disjoint?
       end
-      
       # propagate to restrictions
-      if @restrictions then @restrictions.each { |attr_md| attr_md.restrict_inverse_type } end
+      if @restrictions then @restrictions.each { |attr_md| attr_md.restrict_inverse_type(@inv_md) } end
     end
 
     # @return [AttributeMetadata, nil] the metadata for the {#inverse} attribute, if any
@@ -233,11 +232,21 @@ module CaRuby
     end
 
     # Returns whether the subject attribute is a dependent whose value is automatically generated
-    # with place-holder domain objects when the parent is created.
+    # with place-holder domain objects when the parent is created. An attribute is auto-generated
+    # if the +:autogenerate+ or the +:autogenerated_on_update+ flag is set.
     #
     # @return [Boolean] whether the attribute is auto-generated
     def autogenerated?
-      @flags.include?(:autogenerated)
+      @flags.include?(:autogenerated) or @flags.include?(:autogenerated_on_update)
+    end
+    
+    # Returns whether the the subject attribute is #{autogenerated?} for create. An attribute is
+    # auto-generated for create if the +:autogenerate+ flag is set and the
+    # +:autogenerated_on_update+ flag is not set.
+    #
+    # @return [Boolean] whether the attribute is auto-generated on create
+    def autogenerated_on_create?
+      @flags.include?(:autogenerated) and not @flags.include?(:autogenerated_on_update)
     end
     
     # Returns whether this attribute must be fetched when a declarer instance is saved.
@@ -248,7 +257,7 @@ module CaRuby
     # @return [Boolean] whether the subject attribute must be refetched in order to reflect
     #   the database content
     def saved_fetch?
-       autogenerated? or (cascaded? and @flags.include?(:unfetched))
+       @flags.include?(:saved_fetch) or autogenerated? or (cascaded? and @flags.include?(:unfetched))
     end
 
     # Returns whether the subject attribute is a dependent whose owner does not automatically
@@ -300,23 +309,25 @@ module CaRuby
       logical? or (dependent? and not creatable?)
     end
 
-    # @return whether this attribute is saved in a update operation
-    #
     # A Java attribute is updatable if all of the following conditions hold:
     # * the attribute is {#saved?}
     # * the attribute :create_only flag is not set
+    #
+    # @return [Boolean] whether this attribute is saved in a update operation
     def updatable?
       saved? and not @flags.include?(:create_only)
     end
 
-    # @return whether this attribute is navigated to build a template used in a create or update operation
-    # A cascaded attribute determines where to prune a database create or update object graph.
-    #
-    # An attribute is cascaded if it is a physical dependent or the :cascaded flag is set.
+    # @return [Boolean] whether the attribute is a physical dependent or the +:cascaded+ flag is set
     def cascaded?
       (dependent? and not logical?) or @flags.include?(:cascaded)
     end
     
+    # @return whether this attribute is {#cascaded?} or marked with the +:include_in_save_template+ flag
+    def include_in_save_template?
+      cascaded? or @flags.include?(:include_in_save_template)
+    end
+    
     # Returns whether this attribute is #{#cascaded} and cascades a parent update to a child
     # create. This corresponds to the Hibernate +save-update+ cascade style but not the Hibernate
     # +all+ cascade style.
@@ -327,6 +338,8 @@ module CaRuby
     #   Exception: gov.nih.nci.system.applicationservice.ApplicationException:
     #   The given object has a null identifier:
     # followed by the attribute type name.
+    #
+    # @return [Boolean] whether the attribute cascades to crate when the owner is updated
     def cascade_update_to_create?
       cascaded? and not @flags.include?(:no_cascade_update_to_create)
     end
@@ -412,12 +425,6 @@ module CaRuby
       @flags.include?(:disjoint)
     end
     
-    # @param [Symbol] attribute the attribute to check
-    # @return [Boolean] whether the attribute is part of a 1:1 non-dependency association
-    def one_to_one_bidirectional_independent?
-      independent? and not owner? and not collection? and @inv_md and not @inv_md.collection?
-    end
-    
     # @return [Boolean] whether this attribute is a dependent which does not have a Java inverse owner attribute
     def unidirectional_java_dependent?
       # TODO - can this be relaxed to java_unidirectional? i.e. eliminate dependent filter
@@ -453,8 +460,11 @@ module CaRuby
     
     # If there is a current inverse which can be restricted to an attribute in the scope of
     # this metadata's restricted type, then reset the inverse to that attribute.
-    def restrict_inverse_type
-      return unless @inv_md
+    #
+    # @param [AttributeMetadata, nil] inv_md the inverse attribute to restrict
+    def restrict_inverse_type(inv_md=nil)
+      # set the inverse, if necessary
+      @inv_md ||= inv_md || return
       # the current inverse
       attr = inverse
       # the restricted type's metadata for the current inverse

data/lib/caruby/domain/java_attribute_metadata.rb

@@ -55,6 +55,16 @@ module CaRuby
       qualify(:collection) if collection_java_class?
     end
     
+    # @return [Symbol] the JRuby wrapper method for the Java property reader
+    def property_reader
+      property_accessors.first
+    end
+    
+    # @return [Symbol] the JRuby wrapper method for the Java property writer
+    def property_writer
+      property_accessors.last
+    end
+    
     def type
       @type ||= infer_type
     end
@@ -90,12 +100,15 @@ module CaRuby
       end
     end
 
-    # Returns whether java_class is an +Iterable+.
+    # @return [Boolean] whether this property's Java type is +Iterable+
     def collection_java_class?
-      @property_descriptor.property_type.interfaces.any? { |xfc| xfc.java_object == Java::JavaLang::Iterable.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
     end
 
-    # Returns the type for the specified klass property descriptor pd as described in {#initialize}.
+    # @return [Class] the type for the specified klass property descriptor pd as described in {#initialize}
     def infer_type
       collection_java_class? ? infer_collection_type : infer_non_collection_type
     end
@@ -103,40 +116,47 @@ module CaRuby
     # Returns the domain type for this attribute's Java Collection property descriptor.
     # If the property type is parameterized by a single domain class, then that generic type argument is the domain type.
     # Otherwise, the type is inferred from the property name as described in {#infer_collection_type_from_name}.
+    #
+    # @return [Class] this property's Ruby type
     def infer_collection_type
        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
-      prop_type = @property_descriptor.property_type
-      if prop_type.primitive then
-        Class.to_ruby(prop_type)
+      jtype = @property_descriptor.property_type
+      if jtype.primitive then
+        Class.to_ruby(jtype)
       else
-        @declarer.domain_module.domain_type_with_name(prop_type.name) or Class.to_ruby(prop_type)
+        @declarer.domain_module.domain_type_with_name(jtype.name) or Class.to_ruby(jtype)
       end
     end
 
+    # @return [Class, nil] the Ruby type as determined by the configuration, if any
     def configured_type
       name = @declarer.class.configuration.domain_type_name(to_sym) || return
       @declarer.domain_module.domain_type_with_name(name) or java_to_ruby_class(name)
     end
 
-    # Returns the domain type of this attribute's property descriptor Collection generic type argument, or nil if none.
+    # @return [Class, nil] the domain type of this attribute's property descriptor Collection generic
+    #   type argument, or nil if none
     def generic_parameter_type
       method = @property_descriptor.readMethod || return
-      prop_type = method.genericReturnType
-      return unless Java::JavaLangReflect::ParameterizedType === prop_type
-      arg_types = prop_type.actualTypeArguments
-      return unless arg_types.size == 1
-      arg_type = arg_types[0]
-      klass = java_to_ruby_class(arg_type)
-      logger.debug { "Inferred #{declarer.qp} #{self} domain type #{klass.qp} from generic parameter #{arg_type.name}." } if klass
+      gtype = method.genericReturnType
+      return unless Java::JavaLangReflect::ParameterizedType === gtype
+      atypes = gtype.actualTypeArguments
+      return unless atypes.size == 1
+      atype = atypes[0]
+      klass = java_to_ruby_class(atype)
+      logger.debug { "Inferred #{declarer.qp} #{self} domain type #{klass.qp} from generic parameter #{atype.name}." } if klass
       klass
     end
 
-    def java_to_ruby_class(java_type)
-      java_type = java_type.name unless String === java_type
-      @declarer.domain_module.domain_type_with_name(java_type) or Class.to_ruby(java_type)
+    # @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
+      @declarer.domain_module.domain_type_with_name(name) or Class.to_ruby(name)
     end
 
     # Returns the domain type for this attribute's collection Java property descriptor name.
@@ -148,13 +168,16 @@ module CaRuby
     # is inferred as +DistributionProtocol+ by stripping the +Collection+ suffix,
     # capitalizing the prefix and looking for a class of that name in this classifier's
     # domain_module.
+    #
+    # @return [Class] the collection item type
     def infer_collection_type_from_name
       prop_name = @property_descriptor.name
       index = prop_name =~ /Collection$/
       index ||= prop_name.length
       prefix = prop_name[0...1].upcase + prop_name[1...index]
-      logger.debug { "Inferring #{declarer.qp} #{self} domain type from attribute name prefix #{prefix}..." }
-      @declarer.domain_module.domain_type_with_name(prefix)
+      klass = @declarer.domain_module.domain_type_with_name(prefix)
+      if klass then logger.debug { "Inferred #{declarer.qp} #{self} collection domain type #{klass.qp} from the attribute name." } end
+      klass
     end
   end
 end

data/lib/caruby/domain/merge.rb

@@ -1,3 +1,5 @@
+require 'caruby/util/validation'
+
 module CaRuby
   # A Mergeable supports merging {Resource} attribute values.
   module Mergeable
@@ -74,7 +76,7 @@ module CaRuby
     # @return the merged attribute value
     def merge_attribute(attribute, newval, matches=nil)
       # the previous value
-      oldval = send(attribute)
+      oldval = send(attribute)      
       # If nothing to merge or a block can take over, then bail. 
       if newval.nil? or mergeable__equal?(oldval, newval) then
         return oldval
@@ -132,10 +134,12 @@ module CaRuby
           if matches && matches.has_key?(src) then
             # the source match
             tgt = matches[src]
-            if oldval.include?(tgt) then
-              tgt.merge_attributes(src)
-            else
-              adds << tgt
+            if tgt then
+              if oldval.include?(tgt) then
+                tgt.merge_attributes(src)
+              else
+                adds << tgt
+              end
             end
           else
             adds << src

data/lib/caruby/domain/reference_visitor.rb

@@ -2,6 +2,7 @@ require 'enumerator'
 require 'generator'
 require 'caruby/util/options'
 require 'caruby/util/collection'
+require 'caruby/util/validation'
 require 'caruby/util/visitor'
 require 'caruby/util/math'
 
@@ -184,13 +185,13 @@ module CaRuby
     # @yieldparam [Resource] source the visited source domain object
     # @yieldparam [Resource] target the domain object which matches the visited source
     def visit_matched(source)
-      target = match_for_visited(source)
+      tgt = match_for_visited(source)
       # match the matchable references, if any
       if @matchable then
         attrs = @matchable.call(source) - attributes_to_visit(source)
-        attrs.each { |attr| match_reference(source, target, attr) }
+        attrs.each { |attr| match_reference(source, tgt, attr) }
       end
-      block_given? ? yield(source, target) : target
+      block_given? ? yield(source, tgt) : tgt
     end
 
     # @param source (see #match_visited)

data/lib/caruby/domain/resource_attributes.rb

@@ -129,6 +129,8 @@ module CaRuby
       @log_dep_attrs ||= dependent_attributes.compose { |attr_md| attr_md.logical? }
     end
     
+    # @return [<Symbol>] the unidirectional dependent attributes
+    # @see AttributeMetadata#unidirectional?
     def unidirectional_dependent_attributes
       @uni_dep_attrs ||= dependent_attributes.compose { |attr_md| attr_md.unidirectional? }
     end
@@ -165,14 +167,19 @@ module CaRuby
 
     # @return [<Symbol>] the {#cascaded_attributes} which are saved with a proxy
     #   using the dependent saver_proxy method
-    def proxied_cascaded_attributes
-      @px_cscd_attrs ||= cascaded_attributes.compose { |attr_md| attr_md.proxied_save? }
+    def proxied_save_template_attributes
+      @px_cscd_attrs ||= save_template_attributes.compose { |attr_md| attr_md.proxied_save? }
     end
 
     # @return [<Symbol>] the {#cascaded_attributes} which do not have a
     #   #{AttributeMetadata#proxied_save?}
-    def unproxied_cascaded_attributes
-      @unpx_cscd_attrs ||= cascaded_attributes.compose { |attr_md| not attr_md.proxied_save? }
+    def unproxied_save_template_attributes
+      @unpx_sv_tmpl_attrs ||= save_template_attributes.compose { |attr_md| not attr_md.proxied_save? }
+    end
+
+    # @return [<Symbol>] the {#domain_attributes} to {AttributeMetadata#include_in_save_template?}
+    def save_template_attributes
+      @sv_tmpl_attrs ||= domain_attributes.compose { |attr_md| attr_md.include_in_save_template? }
     end
     
     # Returns the physical or auto-generated logical dependent attributes that can
@@ -317,9 +324,9 @@ module CaRuby
       # @param [{Symbol => AttributeMetadata}] hash the attribute symbol => metadata hash
       # @yield [attr_md] condition which determines whether the attribute is selected
       # @yieldparam [AttributeMetadata] the metadata for the standard attribute
-      def initialize(hash, &filter)
-        raise ArgumentError.new("Attribute filter missing hash argument") if hash.nil?
-        raise ArgumentError.new("Attribute filter missing filter block") unless block_given?
+      def initialize(klass, hash, &filter)
+        raise ArgumentError.new("#{klass.qp} attribute filter missing hash argument") if hash.nil?
+        raise ArgumentError.new("#{klass.qp} attribute filter missing filter block") unless block_given?
         @hash = hash
         @filter = filter
       end
@@ -345,6 +352,14 @@ module CaRuby
         each_pair { |attr, attr_md| yield(attr_md) }
       end
       
+      # @yield [attribute] the block to apply to the attribute
+      # @yieldparam [Symbol] attribute the attribute
+      # @return [AttributeMetadata] the first attribute metadata satisfies the block
+      def detect_metadata
+        each_pair { |attr, attr_md| return attr_md if yield(attr) }
+        nil
+      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
@@ -358,7 +373,7 @@ module CaRuby
       # @return [Filter] a new Filter which applies the filter block given to this
       #   method with the AttributeMetadata enumerated by this filter
       def compose
-        Filter.new(@hash) { |attr_md| @filter.call(attr_md) and yield(attr_md) }
+        Filter.new(self, @hash) { |attr_md| @filter.call(attr_md) and yield(attr_md) }
       end
     end
     
@@ -368,7 +383,7 @@ module CaRuby
     # @yield [attr_md] the attribute selector
     # @yieldparam [AttributeMetadata] attr_md the candidate attribute
     def attribute_filter(&filter)
-      Filter.new(@attr_md_hash, &filter)
+      Filter.new(self, @attr_md_hash, &filter)
     end
 
     # Initializes the attribute meta-data structures.
@@ -382,10 +397,23 @@ module CaRuby
       @local_defaults = {}
       @defaults = append_ancestor_enum(@local_defaults) { |par| par.defaults }
     end
+    
+    
+    # Creates the given attribute alias. Not that unlike {Class#alias_attribute}, this method creates a new
+    # alias reader (writer) method which delegates to the attribute reader (writer, resp.) rather than aliasing
+    # the existing reader or writer method. This allows the alias to pick up run-time redefinitions of the
+    # aliased reader and writer.
+    #
+    # @param [Symbol] aliaz the attribute alias
+    # @param [Symbol] attribute the attribute to alias
+    def alias_attribute(aliaz, attribute)
+      add_attribute_aliases(aliaz => attribute)
+    end
 
     # Creates the given aliases to attributes.
     #
     # @param [{Symbol => Symbol}] hash the alias => attribute hash
+    # @see #attribute_alias
     def add_attribute_aliases(hash)
       hash.each { |aliaz, attr| delegate_to_attribute(aliaz, attr) }
     end
@@ -414,10 +442,11 @@ module CaRuby
       # 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
+        logger.debug { "Set #{qp}.#{attribute} type to #{klass.qp}." }
         attr_md.type = klass
       elsif attr_md.type.nil? or klass < attr_md.type then
-        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)
+        logger.debug { "Restricted #{attr_md.declarer.qp}.#{attribute}(#{attr_md.type.qp}) to #{qp} with return type #{klass.qp}." }
         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}")
@@ -481,7 +510,10 @@ module CaRuby
     # @return [Enumerable] the {Enumerable#union} of the base collection with the superclass
     #   collection, if applicable 
     def append_ancestor_enum(enum)
-      superclass < Resource ? enum.union(yield(superclass)) : enum
+      return enum unless superclass < Resource
+      anc_enum = yield superclass
+      if anc_enum.nil? then raise MetadataError.new("#{qp} superclass #{superclass.qp} does not have required metadata") end
+      enum.union(anc_enum)
     end
 
     def each_attribute_metadata(&block)
@@ -508,12 +540,20 @@ module CaRuby
       # add the secondary key
       mandatory.merge(secondary_key_attributes)
       # add the owner attribute, if any
-      mandatory << owner_attribute unless owner_attribute.nil? or not attribute_metadata(owner_attribute).java_property?
+      oattr = mandatory_owner_attribute
+      mandatory << oattr if oattr
       # remove autogenerated or optional attributes
       mandatory.delete_if { |attr| attribute_metadata(attr).autogenerated? or attribute_metadata(attr).optional? }
       @local_mndty_attrs.merge!(mandatory)
       append_ancestor_enum(@local_mndty_attrs) { |par| par.mandatory_attributes }
     end
+    
+    # @return [Symbol, nil] the unique non-self-referential owner attribute, if one exists
+    def mandatory_owner_attribute
+      attr = owner_attribute || return
+      attr_md = attribute_metadata(attr)
+      attr if attr_md.java_property? and attr_md.type != self
+    end
 
     # Raises a NameError. Domain classes can override this method to dynamically create a new reference attribute.
     #