caruby-core 1.4.2 → 1.4.3

data/lib/caruby/domain/resource_introspection.rb

@@ -4,7 +4,7 @@ require 'caruby/domain/java_attribute_metadata'
 module CaRuby
   # ResourceMetadata mix-in to infer attribute meta-data from Java properties.
   module ResourceIntrospection
-
+    
     private
 
     # Defines the Java property attribute and standard attribute methods, e.g.
@@ -106,6 +106,13 @@ module CaRuby
       alias_method(writer, pwtr)
     end
 
+    # Makes a standard attribute for the given property descriptor.
+    # Adds a camelized Java-like alias to the standard attribute.
+    #
+    # caTissue alert - DE annotation collection attributes are often misnamed,
+    # e.g. +histologic_grade+ for a +HistologicGrade+ collection attribute.
+    # This is fixed by adding a pluralized alias, e.g. +histologic_grades+.
+    #
     # @return a new attribute symbol created for the given PropertyDescriptor pd
     def create_java_attribute(pd)
       # make the attribute metadata
@@ -115,6 +122,19 @@ module CaRuby
       std_attr = attr_md.to_sym
       prop_attr = pd.name.to_sym
       delegate_to_attribute(prop_attr, std_attr) unless prop_attr == std_attr
+      
+      # alias a misnamed collection attribute, if necessary
+      if attr_md.collection? then
+        name = std_attr.to_s
+        if name.singularize == name then
+          aliaz = name.pluralize.to_sym
+          if aliaz != name then
+            logger.debug { "Adding annotation #{qp} alias #{aliaz} to the misnamed collection attribute #{std_attr}..." }
+            delegate_to_attribute(aliaz, std_attr)
+          end
+        end
+      end
+
       std_attr
     end
 
@@ -136,32 +156,5 @@ module CaRuby
       offset_attr_accessor(hash, offset)
       hash.each { |attr, original| add_attribute(attr, attribute_metadata(original).type) }
     end
-
-    # Modifies the given attribute writer method if necessary to update the given inverse_attr value.
-    # This method is called on dependent and attributes qualified as inversible.
-    #
-    # @see ResourceDependency#add_owner
-    # @see ResourceAttributes#set_attribute_inverse
-    def add_inverse_updater(attribute, inverse)
-      attr_md = attribute_metadata(attribute)
-      # the reader and writer methods
-      reader, writer = attr_md.accessors
-      logger.debug { "Injecting inverse #{inverse} updater into #{qp}.#{attribute} writer method #{writer}..." }
-      # the inverse atttribute metadata
-      inv_attr_md = attr_md.inverse_attribute_metadata
-      # the inverse attribute reader and writer
-      inv_rdr, inv_wtr = inv_accessors = inv_attr_md.accessors
-      # redefine the writer method to update the inverse
-      # by delegating to the Resource instance set_inversible_attribute
-      redefine_method(writer) do |old_wtr|
-        # the attribute reader and (superseded) writer
-        accessors = [reader, old_wtr]
-        if inv_attr_md.collection? then
-          lambda { |owner| add_to_inverse_collection(owner, accessors, inv_rdr) }
-        else
-          lambda { |owner| set_inversible_noncollection_attribute(owner, accessors, inv_wtr) }
-        end
-      end
-    end
   end
 end

data/lib/caruby/domain/resource_inverse.rb

@@ -0,0 +1,134 @@
+require 'caruby/import/java'
+require 'caruby/domain/java_attribute_metadata'
+
+module CaRuby
+  # ResourceMetadata mix-in to infer and set inverse attributes.
+  module ResourceInverse
+    
+    protected
+    
+    # Sets the given bi-directional association attribute's inverse.
+    #
+    # @param [Symbol] attribute the subject attribute
+    # @param [Symbol] the attribute inverse
+    # @raise [TypeError] 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 default inverse
+      inverse ||= attr_md.type.detect_inverse_attribute(self)
+      # 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 TypeError.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 or non-reflexive 1:1 relation, then add the inverse updater.
+      unless attr_md.collection? then
+        add_inverse_updater(attribute, inverse)
+        unless attr_md.type == inv_md.type or inv_md.collection? then
+          attr_md.type.delegate_writer_to_inverse(inverse, attribute)
+        end
+      end
+    end
+    
+    # Detects an unambiguous attribute which refers to the given referencing class.
+    # If there is exactly one attribute with the given return type, then that attribute is chosen.
+    # Otherwise, the attribute whose name matches the underscored referencing class name is chosen,
+    # if any.
+    #
+    # @param [Class] klass the referencing class
+    # @return [Symbol, nil] the inverse attribute for the given referencing class and inverse,
+    #   or nil if no owner attribute was detected
+    def detect_inverse_attribute(klass)
+      # the candidate attributes which return the referencing type
+      candidates = domain_attributes.compose { |attr_md| klass <= attr_md.type }.to_a
+      attr = detect_inverse_attribute_from_candidates(klass, candidates)
+      if attr then
+        logger.debug { "#{qp} #{klass.qp} inverse attribute is #{attr}." }
+      else
+        logger.debug { "#{qp} #{klass.qp} inverse attribute was not detected." }
+      end
+      attr
+    end
+    
+    # Redefines the attribute writer method to delegate to its inverse writer.
+    # This is done to enforce inverse integrity.
+    #
+    # For a +Person+ attribute +account+ with inverse +holder+, this is equivalent to the following:
+    #   class Person
+    #     alias :set_account :account=
+    #     def account=(acct)
+    #       acct.holder = self if acct
+    #       set_account(acct)
+    #     end
+    #   end
+    def delegate_writer_to_inverse(attribute, inverse)
+      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.qp}.#{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_inverse method
+        lambda { |dep| set_inverse(dep, old_writer, inv_attr_md.writer) }
+      end
+    end
+
+    private
+
+    # @param klass (see #detect_inverse_attribute)
+    # @param [<Symbol>] candidates the attributes constrained to the target type
+    # @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.
+      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
+      tgt if candidates.detect { |attr| attr == tgt }
+    end
+    
+    # Modifies the given attribute writer method if necessary to update the given inverse_attr value.
+    # This method is called on dependent and attributes qualified as inversible.
+    #
+    # @see #set_attribute_inverse
+    def add_inverse_updater(attribute, inverse)
+      attr_md = attribute_metadata(attribute)
+      # the reader and writer methods
+      rdr, wtr = attr_md.accessors
+      logger.debug { "Injecting inverse #{inverse} updater into #{qp}.#{attribute} writer method #{wtr}..." }
+      # the inverse atttribute metadata
+      inv_attr_md = attr_md.inverse_attribute_metadata
+      # the inverse attribute reader and writer
+      inv_rdr, inv_wtr = inv_accessors = inv_attr_md.accessors
+
+      # 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]
+        if inv_attr_md.collection? then
+          lambda { |other| add_to_inverse_collection(other, accessors, inv_rdr) }
+        else
+          lambda { |other| set_inversible_noncollection_attribute(other, accessors, inv_wtr) }
+        end
+      end
+    end
+  end
+end

data/lib/caruby/domain/resource_metadata.rb

@@ -1,9 +1,10 @@
 require 'caruby/util/collection'
 require 'caruby/import/java'
 require 'caruby/domain/java_attribute_metadata'
-require 'caruby/domain/resource_attributes'
 require 'caruby/domain/resource_introspection'
+require 'caruby/domain/resource_inverse'
 require 'caruby/domain/resource_dependency'
+require 'caruby/domain/resource_attributes'
 
 module CaRuby
   # Exception raised if a meta-data setting is missing or invalid.
@@ -11,7 +12,7 @@ module CaRuby
   
   # Adds introspected metadata to a Class.
   module ResourceMetadata
-    include ResourceIntrospection, ResourceDependency, ResourceAttributes
+    include ResourceIntrospection, ResourceInverse, ResourceDependency, ResourceAttributes
 
     attr_reader :domain_module
 
@@ -21,7 +22,6 @@ module CaRuby
     # by the {#domain_module} method.
     def add_metadata(mod)
       @domain_module = mod
-      init_attributes # in ResourceAttributes
       introspect # in ResourceIntrospection
     end
 
@@ -31,8 +31,43 @@ module CaRuby
       attr_md.type if attr_md.domain?
     end
 
+    # Returns an empty value for the given attribute.
+    # * If this class is not abstract, then the empty value is the initialized value.
+    # * Otherwise, if the attribute is a Java primitive number then zero.
+    # * Otherwise, if the attribute is a Java primitive boolean then +false+.
+    # * Otherwise, the empty value is nil.
+    #
+    # @param [Symbol] attribute the target attribute
+    # @return [Numeric, Boolean, Enumerable, nil] the empty attribute value
+    def empty_value(attribute)
+      if abstract? then
+        attr_md = attribute_metadata(attribute)
+        # the Java property type
+        jtype = attr_md.property_descriptor.property_type if JavaAttributeMetadata === attr_md
+        # A primitive is either a boolean or a number (String is not primitive).
+        if jtype and jtype.primitive? then
+          type.name == 'boolean' ? false : 0
+        end
+      else
+        # Since this class is not abstract, create a prototype instance on demand and make
+        # a copy of the initialized collection value from that instance.
+        @prototype ||= new
+        value = @prototype.send(attribute) || return
+        value.class.new
+      end
+    end
+    
    # Prints this classifier's content to the log.
     def pretty_print(q)
+      
+      
+      # KLUDGE - if not inited then bail
+      if @attr_md_hash.nil? then
+        q.text(qp)
+        return
+      end
+      
+      
       # the Java property descriptors
       property_descriptors = java_attributes.wrap { |attr| attribute_metadata(attr).property_descriptor }
       # build a map of relevant display label => attributes
@@ -71,16 +106,6 @@ module CaRuby
     end
 
     protected
-    
-    # Adds the given subclass to this class's {ResourceMetadata#domain_module}.
-    def introspect_subclass(klass)
-      # introspect this class if necessary
-      unless @domain_module then
-        raise TypeError.new("Can't introspect #{qp}") unless superclass and superclass.include?(Resource)
-        superclass.introspect_subclass(self) 
-      end
-      @domain_module.add_class(klass)
-    end
 
     def self.extend_class(klass, mod)
       klass.extend(self)
@@ -105,12 +130,9 @@ module CaRuby
 
     def format_print_value(value)
       case value
-      when String then
-        value
-      when Class then
-        value.qp
-      else
-        value.pp_s(:single_line)
+        when String then value
+        when Class then value.qp
+        else value.pp_s(:single_line)
       end
     end
   end

data/lib/caruby/domain/resource_module.rb

@@ -47,21 +47,23 @@ module CaRuby
   module ResourceModule
     # Adds the given klass to this ResourceModule. The class is extended with ResourceMetadata methods.
     def add_class(klass)
-      @resource_module__loaded ||= Set.new
+      @rsc_classes ||= Set.new
       # add superclass if necessary
-      unless @resource_module__loaded.include?(klass.superclass) or klass.superclass == Java::JavaLang::Object then
+      unless @rsc_classes.include?(klass.superclass) or klass.superclass == Java::JavaLang::Object then
         # the domain module includes the superclass on demand
         const_get(klass.superclass.name[/\w+$/].to_sym)
       end
       ResourceMetadata.extend_class(klass, self)
-      @resource_module__loaded << klass
+      @rsc_classes << klass
     end
     
-    # Reinclude the mixin in all loaded classes.
-    def mixin_changed
-      @resource_module__loaded.each { |klass| klass.instance_eval { include CaRuby::Resource } }
+    # @return [Module] the resource mix-in module (default {Resouce})
+    def mixin
+      @mixin || Resource
     end
 
+    # @return [{Symbol => Object}] the caBIG application access properties
+    # @see #load_access_properties
     def access_properties
       @resource_module__props ||= load_access_properties
     end
@@ -70,9 +72,9 @@ module CaRuby
     # The default file path is a period followed by the lower-case application name in the home directory,
     # e.g. +~/.clincaltrials+.
     #
-    # The property file format is a series of property definitions in the form _property_ +=+ _value_.
+    # The property file format is a series of property definitions in the form _property_: _value_.
     # The supported properties include the following:
-    # * +path+ - the application client Java jar file directories
+    # * +path+ - the application client Java directories
     # * +user+ - the application service login
     # * +password+ - the application service password
     # * +database+ - the application database name
@@ -82,8 +84,13 @@ module CaRuby
     # * +database_type+ - the application database type, + mysql+ or +oracle+ (default +mysql+)
     # * +database_driver+ - the application database connection driver (default is the database type default)
     # * +database_port+ - the application database connection port
-    # # The +path+ value is one or more directories separated by a semi-colon(;) or colon (:)
-    # # The jar files in the +path+ directory are added to the caRuby execution Java classpath.
+    #
+    # The +path+ value is one or more directories separated by a semi-colon(;) or colon (:)
+    # Each path directory and all jar files within the directory are added to the caRuby execution
+    # Java classpath.
+    #
+    # @param [String, nil] file the property file, or nil for the default location
+    # @return [{Symbol => Object}] the loaded caBIG application access properties
     def load_access_properties(file=nil)
       # If a file was specified, then it must exist.
       if file and not File.exists?(file) then
@@ -146,7 +153,7 @@ module CaRuby
         sym = base_name.camelize.to_sym
         sym_file_hash[sym] = file
         autoload(sym, file)
-     end
+      end
 
       # load the domain class definitions
       sym_file_hash.each do |sym, file|
@@ -163,10 +170,29 @@ module CaRuby
     end
 
     # Extends the mod module with Java class support. See the class documentation for details.
+    #
+    # @param [Symbol] symbol the missing constant
     def const_missing(symbol)
       autoload?(symbol) ? super : import_domain_class(symbol)
     end
 
+    # Returns the domain class for class_name, or nil if none in this module.
+    def domain_type_with_name(class_name)
+      pkg, base = split_class_name(class_name)
+      return unless pkg.nil? or pkg == @java_package
+      begin
+        type = const_get(base)
+      rescue JavaIncludeError
+        # no such domain type; not an error.
+        # other exceptions indicate that there was a domain type but could not be loaded; these exceptions propagate up the call stack
+        logger.debug("#{base} is not a #{qp} Java class.")
+        return
+      end
+      type if type < Resource
+    end
+
+    private
+
     # Imports the domain Java class with specified class name_or_sym.
     # This method enables the domain class extensions for storing and retrieving domain objects.
     # The class is added to this module.
@@ -218,10 +244,10 @@ module CaRuby
       # the Resource import stack
       @import_stack ||= []
       @import_stack.push klass
-      # include the Resource mixin into the imported class
-      mixin = @mixin
-      klass.instance_eval { include mixin }
-      logger.info("Imported #{qp} class #{klass.qp}")
+      # include the Resource mixin in the imported class
+      inc = "include #{mixin}"
+      klass.instance_eval(inc)
+      
       # if we are back to top of the stack, then print the imported Resources
       if klass == @import_stack.first then
         # a referenced class could be imported on demand in the course of printing a referencing class;
@@ -235,23 +261,6 @@ module CaRuby
       klass
     end
 
-    # Returns the domain class for class_name, or nil if none in this module.
-    def domain_type_with_name(class_name)
-      pkg, base = split_class_name(class_name)
-      return unless pkg.nil? or pkg == @java_package
-      begin
-        type = const_get(base)
-      rescue JavaIncludeError
-        # no such domain type; not an error.
-        # other exceptions indicate that there was a domain type but could not be loaded; these exceptions propagate up the call stack
-        logger.debug("#{base} is not a #{qp} Java class.")
-        return
-      end
-      type if type < Resource
-    end
-
-    private
-
     # The property/value matcher, e.g.:
     #   host: jacardi
     #   host = jacardi
@@ -273,7 +282,7 @@ module CaRuby
       end
     end
     
-    # Returns the [package prefix, base class symbol] pair.
+    # @return [(String, Symbol)] the [package prefix, base class symbol] pair
     def split_class_name(class_name)
       # the package prefix, including the period
       package = Java.java_package_name(class_name)