caruby-core 1.4.1

data/lib/caruby/domain/java_attribute_metadata.rb

@@ -0,0 +1,160 @@
+require 'caruby/util/inflector'
+require 'caruby/domain/attribute_metadata'
+
+module CaRuby
+  # The attribute metadata for an introspected Java property. 
+  class JavaAttributeMetadata < AttributeMetadata
+
+    # This attribute's Java property descriptor.
+    attr_reader :property_descriptor
+
+    # This attribute's Java property [reader, writer] accessors, e.g. +[:getActivityStatus, :setActivityStatus]+.
+    attr_reader :property_accessors
+
+    # Creates a Ruby Attribute symbol corresponding to the given Ruby Java class wrapper klazz
+    # and Java property_descriptor.
+    #
+    # The attribute name is the lower-case, underscore property descriptor name with the alterations
+    # described in {JavaAttributeMetadata.to_attribute_symbol} and {Class#unocclude_reserved_method}.
+    #
+    # The attribute type is inferred as follows:
+    # * If the property descriptor return type is a primitive Java type, then that type is returned.
+    # * If the return type is a parameterized collection, then the parameter type is returned.
+    # * If the return type is an unparameterized collection, then this method infers the type from
+    #   the property name, e.g. +StudyProtocolCollection+type is inferred as +StudyProtocol+
+    #   by stripping the +Collection+ suffix, capitalizing the prefix and looking for a class of
+    #   that name in the {ResourceMetadata#domain_module}.
+    # * If the declarer class metadata configuration includes a +domain_attributes+ property, then
+    #   the type specified in that property is returned.
+    # * Otherwise, this method returns Java::Javalang::Object.
+    #
+    # The optional restricted_type argument restricts the attribute to a subclass of the declared
+    # property type.
+    def initialize(pd, declarer, restricted_type=nil)
+      symbol = create_standard_attribute_symbol(pd, declarer)
+      super(symbol, declarer, restricted_type)
+      @property_descriptor = pd
+      # 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
+          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
+        raise ArgumentError.new("Writer method not found for #{declarer} property #{pd.name}")
+      end
+      @property_accessors = [reader, writer]
+      qualify(:collection) if collection_java_class?
+    end
+    
+    def type
+      @type ||= infer_type
+    end
+
+    # Returns a lower-case, underscore symbol for the given property_name.
+    # A name ending in 'Collection' is changed to a pluralization.
+    #
+    # @example
+    #   JavaAttributeMetadata.to_attribute_symbol('specimenEventCollection') #=> :specimen_events
+    def self.to_attribute_symbol(property_name)
+      name = if property_name =~ /(.+)Collection$/ then
+        property_name[0...-'Collection'.length].pluralize.underscore
+      else
+        property_name.underscore
+      end
+      name.to_sym
+    end
+
+    private
+
+    # @param pd the Java property descriptor
+    # @param [Class] klass the declarer
+    # @return [String] the lower-case, underscore symbol for the given property descriptor
+    def create_standard_attribute_symbol(pd, klass)
+      propname = pd.name
+      name = propname.underscore
+      renamed = klass.unocclude_reserved_method(pd)
+      if renamed then
+        logger.debug { "Renamed #{klass.qp} reserved Ruby method #{name} to #{renamed}." }
+        renamed
+      else
+        JavaAttributeMetadata.to_attribute_symbol(propname)
+      end
+    end
+
+    # Returns whether java_class is an +Iterable+.
+    def collection_java_class?
+      @property_descriptor.property_type.interfaces.any? { |xfc| xfc.java_object == Java::JavaLang::Iterable.java_class }
+    end
+
+    # Returns 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
+
+    # 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}.
+    def infer_collection_type
+       generic_parameter_type or infer_collection_type_from_name or Java::JavaLang::Object
+    end
+
+    def infer_non_collection_type
+      prop_type = @property_descriptor.property_type
+      if prop_type.primitive then
+        Class.to_ruby(prop_type)
+      else
+        @declarer.domain_module.domain_type_with_name(prop_type.name) or Class.to_ruby(prop_type)
+      end
+    end
+
+    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.
+    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
+      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)
+    end
+
+    # Returns the domain type for this attribute's collection Java property descriptor name.
+    # By convention, caBIG domain collection properties often begin with a domain type
+    # name and end in 'Collection'. This method strips the Collection suffix and checks
+    # whether the prefix is a domain class.
+    #
+    # For example, the type of the property named +distributionProtocolCollection+
+    # 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.
+    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)
+    end
+  end
+end

data/lib/caruby/domain/merge.rb

@@ -0,0 +1,91 @@
+module CaRuby
+  # A Mergeable supports merging attribute values.
+  module Mergeable
+    # Merges the values of the other attributes into this object and returns self.
+    # The other argument can be either a Hash or an object whose class responds to the
+    # +mergeable_attributes+ method.
+    # The optional attributes argument can be either a single attribute symbol or a
+    # collection of attribute symbols.
+    #
+    # A hash argument consists of attribute name => value associations.
+    # For example, given a Mergeable +person+ object with attributes +ssn+ and +children+, the call:
+    #   person.merge_attributes(:ssn => '555-55-5555', :children => children)
+    # is equivalent to:
+    #   person.ssn ||= '555-55-5555'
+    #   person.children ||= []
+    #   person.children.merge(children, :deep)
+    # An unrecognized attribute is ignored.
+    #
+    # If other is not a Hash, then the other object's attributes values are merged into
+    # this object. The default attributes is the intersection of this object's
+    # mergeable attributes and the other object's mergeable attributes as determined by
+    # {ResourceAttributes#mergeable_attributes}.
+    #
+    # #merge_attribute is called on each attribute with the merger block given to this
+    # method.
+    #
+    # @param [Mergeable, {Symbol => Object}] other the source domain object or value hash to merge from
+    # @param [<Symbol>, nil] attributes the attributes to merge (default {ResourceAttributes#nondomain_attributes})
+    # @return [Mergeable] self
+    # @raise [ArgumentError] if none of the following are true:
+    #   * other is a Hash
+    #   * attributes is non-nil
+    #   * the other class responds to +mergeable_attributes+
+    def merge_attributes(other, attributes=nil, &merger) # :yields: attribute, oldval, newval
+      return self if other.nil? or other.equal?(self)
+      attributes = [attributes] if Symbol === attributes
+      attributes ||= self.class.mergeable_attributes
+
+      # if the source object is not a hash, then convert it to an attribute => value hash
+      vh = Hashable === other ? other : other.value_hash(attributes)
+      # merge the value hash
+      suspend_lazy_loader do
+        vh.each { |attr, value| merge_attribute(attr, value, &merger) }
+      end
+      self
+    end
+
+    alias :merge :merge_attributes
+
+    alias :merge! :merge
+
+    # Merges value into attribute as follows:
+    # * if the value is nil, empty or equal to the current attribute value, then no merge
+    #   is performed
+    # * otherwise, if the merger block is given to this method, then that block is called
+    #   to perform the merge
+    # * otherwise, if the current value responds to the merge! method, then that method
+    #   is called recursively on the current value
+    # * otherwise, if the current value is nil, then the attribute is set to value
+    # * otherwise, no merge is performed
+    #
+    # Returns the merged value.
+    def merge_attribute(attribute, value, &merger) # :yields: attribute, oldval, newval
+      # the previous value
+      oldval = send(attribute)
+
+      # if nothing to merge, then return the unchanged previous value.
+      # otherwise, if a merge block is given, then call it.
+      # otherwise, if nothing to merge into then set the attribute to the new value.
+      # otherwise, if the previous value is mergeable, then merge the new value into it.
+      if value.nil_or_empty? or mergeable__equal?(oldval, value) then
+        oldval
+      elsif block_given? then
+        yield(attribute, oldval, value)
+      elsif oldval.nil? then
+        send("#{attribute}=", value)
+      elsif oldval.respond_to?(:merge!) then
+        oldval.merge!(value)
+      else
+        oldval
+      end
+    end
+
+    private
+
+    # Fixes a rare Java TreeSet aberration: comparison uses the TreeSet comparator rather than an element-wise comparator.
+    def mergeable__equal?(v1, v2)
+      Java::JavaUtil::TreeSet === v1 && Java::JavaUtil::TreeSet === v2 ? v1.to_set == v2.to_set : v1 == v2
+    end
+  end
+end

data/lib/caruby/domain/properties.rb

@@ -0,0 +1,95 @@
+require 'caruby/util/properties'
+require 'caruby/util/collection'
+require 'caruby/util/options'
+
+module CaRuby
+  module Domain
+    # CaRuby::Domain::Properties specializes the generic CaRuby::Properties class for domain properties.
+    class Properties < CaRuby::Properties
+
+      # The application login userid environment variable.
+      USER_ENV_VAR_SUFFIX = 'USER'
+
+      # The application login password environment variable.
+      PASSWORD_ENV_VAR_SUFFIX = 'PASSWORD'
+
+      # The application service user property name.
+      USER_PROP = :user
+
+      # The application service password property name.
+      PASSWORD_PROP = :password
+
+      # The application Java jar location.
+      PATH_PROP = :path
+
+      attr_reader :application
+
+      # Creates a new Properties.
+      #
+      # Supported options include the CaRuby::Properties options as well as the following:
+      # * :application - the application name
+      #
+      # The application name is used as a prefix for application-specific upper-case environment variables
+      # and lower-case file names, e.g. +CATISSUE_USER+ for the +caTissue+ application login username
+      # environment variable. The default application name is +caBIG+.
+      #
+      # The user properties file is always loaded if it exists. This file's name is a period followed by the
+      # lower-case application name, located in the home directory, e.g. +~/.catissue.yaml+ for application
+      # +caTissue+.
+      def initialize(file=nil, options=nil)
+        @application = Options.get(:application, options, "caBIG")
+        super(file, options)
+      end
+
+      # Loads the properties in the following low-to-high precedence order:
+      # * the home file +.+_application_+.yaml+, where _application_ is the application name
+      # * the given property file
+      # * the environment varialables
+      def load_properties(file)
+        # canonicalize the file path
+        file = File.expand_path(file)
+        # load the home properties file, if it exists
+        user_file = File.expand_path("~/.#{@application.downcase}.yaml")
+        super(user_file) if user_file != file and File.exists?(user_file)
+        # load the given file
+        super(file)
+        # the environment variables take precedence
+        load_environment_properties
+        # validate the required properties
+        validate_properties
+      end
+
+      private
+
+      def load_environment_properties
+        user = ENV[user_env_var]
+        if user then
+          self[USER_PROP] = user
+          logger.info("#{@application} login user obtained from environment property #{user_env_var} value '#{user}'.")
+        end
+        password = ENV[password_env_var]
+        if password then
+          self[PASSWORD_PROP] = password
+          logger.info("#{@application} login password obtained from environment property #{password_env_var} value.")
+        end
+        path = ENV[path_env_var]
+        if path then
+          self[PATH_PROP] = path
+          logger.info("#{@application} Java library path obtained from environment property #{path_env_var} value '#{path}'.")
+        end
+      end
+
+      def user_env_var
+        "#{@application}_#{USER_PROP}".upcase
+      end
+
+      def password_env_var
+        "#{@application}_#{PASSWORD_PROP}".upcase
+      end
+
+      def path_env_var
+        "#{@application}_#{PATH_PROP}".upcase
+      end
+    end
+  end
+end

data/lib/caruby/domain/reference_visitor.rb

@@ -0,0 +1,289 @@
+require 'enumerator'
+require 'generator'
+require 'caruby/util/options'
+require 'caruby/util/collection'
+require 'caruby/util/visitor'
+require 'caruby/util/math'
+
+module CaRuby
+  # A ReferenceVisitor traverses reference attributes.
+  class ReferenceVisitor < Visitor
+    private
+
+    # Flag to print a detailed debugging visit message
+    DETAIL_DEBUG = false
+
+    public
+
+    attr_reader :ref_attr_hash
+
+    # Creates a new ReferenceVisitor on domain reference attributes.
+    #
+    # If a selector block is given to this initializer, then the reference attributes to visit
+    # are determined by calling the block. Otherwise, the {ResourceAttributes#saved_domain_attributes}
+    # are visited.
+    #
+    # @param options (see Visitor#initialize)
+    # @yield [ref] selects which attributes to visit next
+    # @yieldparam [Resource] ref the currently visited domain object
+    def initialize(options=nil, &selector)
+      # use the default attributes if no block given
+      @slctr = selector || Proc.new { |obj| obj.class.saved_domain_attributes }
+      # delegate to Visitor with the visit selector block
+      super { |parent| references_to_visit(parent) }
+      # the visited reference => parent attribute hash
+      @ref_attr_hash = {}
+      # TODO - reconcile @excludes here with Visitor exclude.
+      # refactor usage and interaction with prune_cycles.
+      # eliminate if possible.
+      @excludes = []
+    end
+
+    # @return [Symbol, nil] the parent attribute which was visited to get to the current visited domain object
+    def attribute
+      @ref_attr_hash[current]
+    end
+
+    # Excludes obj from the next visit.
+    # Exclusions are cleared after visit is completed.
+    def exclude(obj)
+      @excludes << obj
+    end
+
+    # Performs Visitor::visit and clears exclusions.
+    def visit(obj)
+      if DETAIL_DEBUG then
+        logger.debug { "Visiting #{obj.qp} from navigation path #{lineage.qp}..." }
+      end
+      
+      # TODO - current, attribute and parent are nil when a value is expected.
+      # Uncomment below, build test cases, analyze and fix.
+      #
+      # puts "Visit #{obj.qp} current: #{self.current.qp} parent: #{self.parent.qp} attribute: #{self.attribute}"
+      # puts "  lineage:#{lineage.qp}n  attributes:#{@ref_attr_hash.qp}"
+      # puts "  reference => attribute hash: #{@ref_attr_hash.qp}"
+
+      result = super
+      @excludes.clear
+      result
+    end
+
+    # Adds a default matcher block if necessary and delegates to {Visitor#sync}. The default matcher block
+    # calls {CaRuby::Resource#match_in} to match the candidate domain objects to visit.
+    #
+    # @yield [ref, others] matches ref in others (optional)
+    # @yieldparam [Resource] ref the domain object to match
+    # @yieldparam [<Resource>] the candidates for matching ref
+    def sync
+      block_given? ? super : super { |ref, others| ref.match_in(others) }
+    end
+
+    protected
+
+    def clear
+      super
+      @ref_attr_hash.clear
+    end
+
+    private
+
+    # @return the domain objects to visit next for the given parent
+    def references_to_visit(parent)
+      attributes = @slctr.call(parent)
+      if attributes.nil? then return Array::EMPTY_ARRAY end
+      refs = []
+      attributes.each do | attr|
+        # the reference(s) to visit
+        value = parent.send(attr)
+        # associate each reference to visit with the current visited attribute
+        value.enumerate do |ref|
+          @ref_attr_hash[ref] = attr
+          refs << ref
+        end
+      end
+      if DETAIL_DEBUG then
+        logger.debug { "Visiting #{parent.qp} references: #{refs.qp}" }
+        logger.debug { " lineage: #{lineage.qp}" }
+        logger.debug { " attributes: #{@ref_attr_hash.qp}..." }
+      end
+      refs
+    end
+  end
+
+  # A MergeVisitor merges a domain object's visitable attributes transitive closure into a target.
+  class MergeVisitor < ReferenceVisitor
+
+    attr_reader :matches
+
+    # Creates a new MergeVisitor on domain attributes.
+    # The domain attributes to visit are determined by calling the selector block given to
+    # this initializer as described in {ReferenceVisitor#initialize}.
+    #
+    # @param [Hash] options the visit options
+    # @option options [Proc] :mergeable the mergeable domain attribute selector
+    # @option options [Proc] :matcher the match block
+    # @option options [Proc] :copier the unmatched source copy block
+    # @yield [source, target] the visit domain attribute selector block
+    # @yieldparam [Resource] source the current merge source domain object
+    # @yieldparam [Resource] target the current merge target domain object
+    def initialize(options=nil, &selector)
+      raise ArgumentError.new("Reference visitor missing domain reference selector") unless block_given?
+      options = Options.to_hash(options)
+      @mergeable = options.delete(:mergeable) || selector
+      @matcher = options.delete(:matcher) || Resource.method(:match_all)
+      @copier = options.delete(:copier)
+      # the source => target matches
+      @matches = {}
+      # the class => {id => target} hash
+      @id_mtchs = LazyHash.new { Hash.new }
+      super do |src|
+        tgt = @matches[src]
+        yield(src, tgt) if tgt
+      end
+    end
+
+    # Visits the source and target and returns a recursive copy of obj and each of its visitable references.
+    #
+    # If a block is given to this method, then this method returns the evaluation of the block on the visited
+    # source reference and its matching copy, if any. The default return value is the target which matches
+    # source.
+    #
+    # caCORE alert = caCORE does not enforce reference identity integrity, i.e. a search on object _a_
+    # with database record references _a_ => _b_ => _a_, the search result might be _a_ => _b_ => _a'_,
+    # where _a.identifier_ == _a'.identifier_. This visit method remedies the caCORE defect by matching source
+    # references on a previously matched identifier where possible.
+    #
+    # @param [Resource] target the domain object to merge into 
+    # @param [Resource] source the domain object to merge from
+    # @yield [target, source] the optional block to call on the visited source domain object and its matching target
+    # @yieldparam [Resource] target the domain object which matches the visited source
+    # @yieldparam [Resource] source the visited source domain object
+    def visit(target, source)
+      # clear the match hashes
+      @matches.clear
+      @id_mtchs.clear
+      # seed the matches with the top-level source => target
+      add_match(source, target)
+      # visit the source reference. the visit block merges each source reference into
+      # the matching target reference.
+      super(source) do |src|
+        tgt = match(src) || next
+        merge(tgt, src)
+        block_given? ? yield(tgt, src) : tgt
+      end
+    end
+
+    private
+
+    # Merges the given source object into the target object.
+    #
+    # @param [Resource] target thedomain object to merge into
+    # @param [Resource] source the domain object to merge from
+    def merge(target, source)
+      # the domain attributes to merge; non-domain attributes are always merged
+      attrs = @mergeable.call(source, target)
+      # Match each source reference to a target reference.
+      target.merge_match(source, attrs, &method(:match_all))
+      target
+    end
+
+    # Matches the given sources to targets. The match is performed by this visitor's matcher Proc.
+    #
+    # @param [<Resource>] sources the domain objects to match
+    # @param [<Resource>] targets the match candidates
+    # @return [{Resource => Resource}] the source => target matches
+    def match_all(sources, targets)
+     # the match targets
+      mtchd_tgts = Set.new
+      # capture the matched targets and the the unmatched sources
+      unmtchd_srcs = sources.reject do |src|
+        # the prior match, if any
+        tgt = match(src)
+        mtchd_tgts << tgt if tgt
+      end
+      # the unmatched targets
+      unmtchd_tgts = targets.difference(mtchd_tgts)
+
+      # match the residual targets and sources
+      rsd_mtchs = @matcher.call(unmtchd_srcs, unmtchd_tgts)
+      # add residual matches
+      rsd_mtchs.each { |src, tgt| add_match(src, tgt) }
+      # The source => target match hash.
+      # If there is a copier, then copy each unmatched source.
+      matches = sources.to_compact_hash { |src| match(src) or copy_unmatched(src) }
+      logger.debug { "Merge visitor matched #{matches.qp}." } unless matches.empty?
+      matches
+    end
+
+    # @return the target matching the given source
+    def match(source)
+      @matches[source] or identifier_match(source)
+    end
+    
+    def add_match(source, target)
+      @matches[source] = target
+      @id_mtchs[source.class][source.identifier] = target if source.identifier
+      target
+    end
+
+    # @return the target matching the given source on the identifier, if any
+    def identifier_match(source)
+      tgt = @id_mtchs[source.class][source.identifier] if source.identifier
+      @matches[source] = tgt if tgt
+    end
+
+    # @return [Resource, nil] a copy of the given source if this ReferenceVisitor has a copier, nil otherwise
+    def copy_unmatched(source)
+      return unless @copier
+      copy = @copier.call(source)
+      add_match(source, copy)
+    end
+  end
+
+  # A CopyVisitor copies a domain object's visitable attributes transitive closure.
+  class CopyVisitor < MergeVisitor
+    # Creates a new CopyVisitor with the options described in {MergeVisitor#initialize}.
+    # The default :copier option is {Resource#copy}.
+    def initialize(options=nil) # :yields: source
+      options = Options.to_hash(options)
+      options[:copier] ||= Proc.new { |src| src.copy }
+      super
+    end
+
+    # Visits obj and returns a recursive copy of obj and each of its visitable references.
+    #
+    # If a block is given to this method, then the block is called with the visited
+    # source reference and its matching copy target.
+    def visit(source, &block) # :yields: target, source
+      target = @copier.call(source)
+      super(target, source, &block)
+    end
+  end
+
+  # A ReferencePathVisitorFactory creates a ReferenceVisitor that traverses an attributes path.
+  #
+  # For example, given the attributes:
+  #   treatment: BioMaterial -> Treatment
+  #   measurement: Treatment -> BioMaterial
+  # then a path visitor given by:
+  #   ReferencePathVisitorFactory.create(BioMaterial, [:treatment, :measurement])
+  # visits all biomaterial, treatments and measurements derived directly or indirectly from a starting BioMaterial instance.
+  class ReferencePathVisitorFactory
+    # @return a new ReferenceVisitor that visits the given path attributes starting at an instance of type
+    def self.create(type, attributes, options=nil)
+      # augment the attributes path as a [class, attribute] path
+      path = []
+      attributes.each do |attr|
+        path << [type, attr]
+        type = type.domain_type(attr)
+      end
+
+      # make the visitor
+      visitor = ReferenceVisitor.new(options) do |ref|
+        # collect the path reference attributes whose source match the ref type up to the next position in the path
+        max = visitor.lineage.size.min(path.size)
+        (0...max).map { |i| path[i].last if ref.class == path[i].first }.compact
+      end
+    end
+  end
+end