caruby-core 1.4.9 → 1.5.1

data/lib/caruby/domain/dependency.rb

@@ -0,0 +1,240 @@
+require 'caruby/util/validation'
+
+module CaRuby
+  module Domain
+    # Metadata mix-in to capture Resource dependency.
+    module Dependency
+  
+      attr_reader :owners, :owner_attributes
+  
+      # Returns the most specific attribute which references the dependent type, or nil if none.
+      # If the given class can be returned by more than dependent attribute, then the attribute
+      # is chosen whose return type most closely matches the given class.
+      #
+      # @param [Class] klass the dependent type
+      # @return [Symbol, nil] the dependent reference attribute, or nil if none
+      def dependent_attribute(klass)
+        dependent_attributes.inject(nil) do |best, attr|
+          type = domain_type(attr)
+          # If the attribute can return the klass then the return type is a candidate.
+          # In that case, the klass replaces the best candidate if it is more specific than
+          # the best candidate so far.
+          klass <= type ? (best && best < type ? best : type) : best
+        end
+      end
+  
+      # Adds the given attribute as a dependent.
+      #
+      # Supported flags include the following:
+      # * :logical - the dependency relation is not cascaded by the application
+      # * :autogenerated - a dependent can be created by the application as a side-effect of creating the owner
+      # * :disjoint - the dependent owner has more than one owner attribute, but only one owner instance
+      #
+      # If the attribute inverse is not a collection, then the attribute 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
+      # * _inverse_ is the owner inverse attribute defined in the dependent class
+      #
+      # @param [Symbol] attribute the dependent to add
+      # @param [<Symbol>] flags the attribute qualifier flags
+      def add_dependent_attribute(attribute, *flags)
+        attr_md = attribute_metadata(attribute)
+        flags << :dependent unless flags.include?(:dependent)
+        attr_md.qualify(*flags)
+        inverse = attr_md.inverse
+        inv_type = attr_md.type
+        # example: Parent.add_dependent_attribute(:children) with inverse :parent calls the following:
+        #   Child.add_owner(Parent, :children, :parent)
+        inv_type.add_owner(self, attribute, inverse)
+      end
+      
+      # Makes a new owner attribute. The attribute name is the lower-case demodulized
+      # owner class name. The owner class must reference this class via the given
+      # inverse dependent attribute.
+      #
+      # @param klass (see #detect_owner_attribute)
+      # @param [Symbol] the owner -> dependent inverse attribute 
+      # @return [Symbol] this class's new owner attribute
+      # @raise [ArgumentError] if the inverse is nil
+      def create_owner_attribute(klass, inverse)
+        if inverse.nil? then
+          raise ArgumentError.new("Cannot create a #{qp} owner attribute to #{klass} without a dependent attribute to this class.")
+        end
+        attr = klass.name.demodulize.underscore.to_sym
+        attr_accessor(attr)
+        attr_md = add_attribute(attr, klass)
+        attr_md.inverse = inverse
+        logger.debug { "Created #{qp} owner attribute #{attr} with inverse #{klass.qp}.#{inverse}." }
+        attr
+      end
+      
+      # @return [Boolean] whether this class depends on an owner
+      def dependent?
+        not owners.empty?
+      end
+      
+      # @return [Boolean] whether this class has an owner which cascades save operations to this dependent
+      def cascaded_dependent?
+        owner_attribute_metadata_enumerator.any? { |attr_md| attr_md.inverse_metadata.cascaded? }
+      end
+  
+      # @return [Boolean] whether this class depends the given other class
+      def depends_on?(other)
+        owners.detect { |owner| owner === other }
+      end
+  
+      # @param [Class] klass the dependent type
+      # @return [Symbol, nil] the attribute which references the dependent type, or nil if none
+      def dependent_attribute(klass)
+        type = dependent_attributes.detect_with_metadata { |attr_md| attr_md.type == klass }
+        return type if type
+        dependent_attribute(klass.superclass) if klass.superclass < Resource
+      end
+  
+      # @return [<Symbol>] this class's owner attributes
+      def owner_attributes
+        @oattrs ||= owner_attribute_metadata_enumerator.transform { |attr_md| attr_md.to_sym }
+      end
+  
+      # @return [<Class>] this class's dependent types
+      def dependents
+        dependent_attributes.wrap { |attr| attr.type }
+      end
+  
+      # @return [<Class>] this class's owner types
+      def owners
+        @owners ||= Enumerable::Enumerator.new(owner_attribute_metadata_hash, :each_key)
+      end
+  
+      # @return [Attribute, nil] the sole owner attribute metadata of this class, or nil if there
+      #   is not exactly one owner
+      def owner_attribute_metadata
+        attr_mds = owner_attribute_metadata_enumerator
+        attr_mds.first if attr_mds.size == 1
+      end
+  
+      # @return [Symbol, nil] the sole owner attribute of this class, or nil if there
+      #   is not exactly one owner
+      def owner_attribute
+        attr_md = owner_attribute_metadata || return
+        attr_md.to_sym
+      end
+      
+      # @return [Class, nil] the sole owner type of this class, or nil if there
+      #   is not exactly one owner
+      def owner_type
+        attr_md = owner_attribute_metadata || return
+        attr_md.type
+      end
+  
+      protected
+  
+      # Adds the given owner class to this dependent class.
+      # This method must be called before any dependent attribute is accessed.
+      # If the attribute is given, then the attribute inverse is set.
+      # Otherwise, if there is not already an owner attribute, then a new owner attribute is created.
+      # The name of the new attribute is the lower-case demodulized owner class name.
+      #
+      # @param [Class] the owner class
+      # @param [Symbol] inverse the owner -> dependent attribute
+      # @param [Symbol, nil] attribute the dependent -> owner attribute, if known
+      # @raise [ValidationError] if the inverse is nil
+      def add_owner(klass, inverse, attribute=nil)
+        if inverse.nil? then raise ValidationError.new("Owner #{klass.qp} missing dependent attribute for dependent #{qp}") end
+        logger.debug { "Adding #{qp} owner #{klass.qp}#{' attribute ' + attribute.to_s if attribute}#{' inverse ' + inverse.to_s if inverse}..." }
+        if @owner_attr_hash then
+          raise MetadataError.new("Can't add #{qp} owner #{klass.qp} after dependencies have been accessed")
+        end
+        
+        # detect the owner attribute, if necessary
+        attribute ||= detect_owner_attribute(klass, inverse)
+        attr_md = attribute_metadata(attribute) if attribute
+        # 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_attribute_metadata_hash[klass] = attr_md
+        # If the dependency is unidirectional, then our job is done.
+        return if attribute.nil?
+  
+        # set the inverse if necessary
+        unless attr_md.inverse then
+          set_attribute_inverse(attribute, inverse)
+        end
+        # set the owner flag if necessary
+        unless attr_md.owner? then attr_md.qualify(:owner) end
+        # Redefine the writer method to warn when changing the owner
+        rdr, wtr = attr_md.accessors
+        logger.debug { "Injecting owner change warning into #{qp}.#{attribute} writer method #{wtr}..." }
+        redefine_method(wtr) do |old_wtr|
+          lambda do |ref|
+            prev = send(rdr)
+            if prev and prev != ref then
+              if ref.nil? then
+                logger.warn("Unsetting the #{self} owner #{attribute} #{prev}.")
+              elsif ref.identifier != prev.identifier then
+                logger.warn("Resetting the #{self} owner #{attribute} from #{prev} to #{ref}.")
+              end
+            end
+            send(old_wtr, ref)
+          end
+        end
+      end
+      
+      # Adds the given attribute as an owner. This method is called when a new attribute is added that
+      # references an existing owner.
+      #
+      # @param [Symbol] attribute the owner attribute
+      def add_owner_attribute(attribute)
+        attr_md = attribute_metadata(attribute)
+        otype = attr_md.type
+        hash = local_owner_attribute_metadata_hash
+        if hash.include?(otype) then
+          oattr = hash[otype]
+          unless oattr.nil? then
+            raise MetadataError.new("Cannot set #{qp} owner attribute to #{attribute} since it is already set to #{oattr}")
+          end
+          hash[otype] = attr_md
+        else
+          add_owner(otype, attr_md.inverse, attribute)
+        end
+      end
+  
+      # @return [{Class => Attribute}] this class's owner type => attribute hash
+      def owner_attribute_metadata_hash
+        @oa_hash ||= create_owner_attribute_metadata_hash
+      end
+      
+      private
+      
+      def local_owner_attribute_metadata_hash
+        @local_oa_hash ||= {}
+      end
+  
+      # @return [{Class => Attribute}] a new owner type => attribute hash
+      def create_owner_attribute_metadata_hash
+        local = local_owner_attribute_metadata_hash
+        superclass < Resource ? local.union(superclass.owner_attribute_metadata_hash) : local
+      end
+      
+      # @return [<Attribute>] the owner attributes
+      def owner_attribute_metadata_enumerator
+        # Enumerate each owner Attribute, filtering out nil values.
+        @oa_enum ||= Enumerable::Enumerator.new(owner_attribute_metadata_hash, :each_value).filter
+      end
+      
+      # Returns the attribute which references the owner. The owner attribute is the inverse
+      # of the given owner class inverse attribute, if it exists. Otherwise, the owner
+      # attribute is inferred by #{Inverse#detect_inverse_attribute}.
+  
+      # @param klass (see #add_owner)
+      # @param [Symbol] inverse the owner -> dependent attribute
+      # @return [Symbol, nil] this class's owner attribute
+      def detect_owner_attribute(klass, inverse)
+        klass.attribute_metadata(inverse).inverse or detect_inverse_attribute(klass)
+      end
+    end
+  end
+end

data/lib/caruby/domain/importer.rb

@@ -0,0 +1,183 @@
+require 'caruby/domain/metadata'
+require 'caruby/resource'
+
+module CaRuby
+  module Domain
+    # Importer extends a {Module} with Java class import support.
+    #
+    # A Java class is imported into JRuby on demand by referencing the class name.
+    # Import on demand is induced by a reference to the class, e.g., given the
+    # following domain resource module definition:
+    #   module ClinicalTrials
+    #     module Resource
+    #      ...
+    #     end
+    #
+    #     CaRuby::Domain.extend_module(self, Resource, 'org.nci.ctms')
+    # then the first reference by name to +ClinicalTrials::Subject+
+    # imports the Java class +org.nci.ctms.Subject+ into the JRuby class wrapper
+    # +ClinicalTrials::Subject+. The +ClinicalTrials::Resource+ module is included
+    # in +ClinicalTrials::Subject+ and the Java property meta-data is introspected
+    # into {Attributes}.
+    module Importer
+      # Extends the given module with Java class meta-data import support.
+      #
+      # @param [Module] mod the module to extend
+      # @param [{Symbol => Object}] opts the extension options
+      # @option opts (see #configure)
+      def self.extend_module(mod, opts)
+        mod.extend(self).configure_importer(opts)
+      end
+  
+      # Imports a Java class constant on demand. If the class does not already
+      # include this module's mixin, then the mixin is included in the class.
+      #
+      # @param [Symbol] symbol the missing constant
+      # @return [Class] the imported class
+      # @raise [NameError] if the symbol is not an importable Java class
+      def const_missing(symbol)
+        logger.debug { "Detecting whether #{symbol} is a #{@pkg} Java class..." }
+        # Append the symbol to the package to make the Java class name.
+        begin
+          klass = eval "Java::#{@pkg}.#{symbol}"
+          resource_import klass
+        rescue NameError
+          logger.debug { "#{symbol} is not recognized as a #{@pkg} Java class - #{$!}\n#{caller.qp}." }
+          super
+        end
+        logger.info(klass.pp_s)
+        klass
+      end
+      
+      # Imports the given Java class and introspects the {Metadata}.
+      # The Java class is assumed to be defined in this module's package.
+      # This module's mixin is added to the class.
+      #
+      # @param [String] class_or_name the source directory
+      # @raise [NameError] if the symbol does not correspond to a Java class
+      #   in this module's package
+      def resource_import(klass)
+        # Add the superclass metadata, if necessary.
+        sc = klass.superclass
+        unless sc < @mixin or klass.parent_module != sc.parent_module then
+          const_get(sc.name.demodulize)
+        end
+        java_import(klass)
+        ensure_metadata_introspected(klass)
+        klass
+      end
+      
+      # @param [Class, String] class_or_name the class to import into this module
+      # @return [Class] the imported class
+      def java_import(class_or_name)
+        # JRuby 1.4.x does not support a class argument
+        begin
+          Class === class_or_name ? super(class_or_name.java_class.name) : super
+        rescue Exception
+          raise JavaImportError.new("#{class_or_name} is not a Java class - #{$!}")
+        end
+      end
+
+      # Configures this importer with the given options. This method is intended for use by the
+      # {#extend_module} method.
+      #
+      # @param [{Symbol => Object}] opts the extension options
+      # @option opts [String] :package the required Java package name
+      # @option opts [Module, Proc] :metadata the optional {Metadata} extension module or proc (default {Metadata})
+      # @option opts [Module] :mixin the optional mix-in module (default {Resource})
+      # @option opts [String] :directory the optional directory of source class definitions to load
+      def configure_importer(opts)
+        @pkg = opts[:package]
+        if @pkg.nil? then raise ArgumentError.new("Required domain package option not found") end
+        @metadata = opts[:metadata] || Metadata
+        @mixin = opts[:mixin] || Resource
+        @introspected = Set.new
+        dir = opts[:directory]
+        load_dir(dir) if dir
+      end
+      
+      private
+      
+      # Enables the given class {Metadata} if necessary.
+      #
+      # @param [Class] klass the class to enable
+      def ensure_metadata_introspected(klass)
+        add_metadata(klass) unless @introspected.include?(klass)
+      end
+      
+      # Enables the given class meta-data.
+      #
+      # @param [Class] klass the class to enable
+      def add_metadata(klass)
+        # Mark the class as introspected. Do this first to preclude a recursive loop back
+        # into this method when the references are introspected in add_metadata.
+        @introspected << klass
+        # the package module
+        mod = klass.parent_module
+        # Add the superclass metadata, if necessary.
+        sc = klass.superclass
+        unless @introspected.include?(sc) or sc.parent_module != mod then
+          resource_import(sc)
+        end
+        # Include the mixin.
+        unless klass < @mixin then
+          mixin = @mixin
+          klass.class_eval { include mixin }
+        end
+        # Add the class metadata.
+        case @metadata
+          when Module then klass.extend(@metadata)
+          when Proc then @metadata.call(klass)
+          else raise MetadataError.new("#{self} metadata is neither a class nor a proc: #{@metadata.qp}")
+        end
+        klass.domain_module = self
+        # Add referenced domain class metadata as necessary.
+        klass.each_attribute_metadata do |attr_md|
+          ref = attr_md.type
+          if ref.nil? then raise MetadataError.new("#{self} #{attr_md} domain type is unknown.") end
+          unless @introspected.include?(ref) or ref.parent_module != mod then
+            logger.debug { "Adding #{qp} #{attr_md} reference #{ref.qp} metadata..." }
+            resource_import(ref)
+          end
+        end
+      end
+      
+      # Loads the Ruby source files in the given directory.
+      #
+      # @param [String] dir the source directory
+      def load_dir(dir)
+        # Auto-load the files on demand.
+        syms = autoload_dir(dir)
+        # Load each file on demand.
+        syms.each do |sym|
+          klass = const_get(sym)
+          logger.info(klass.pp_s)
+        end
+      end
+  
+      # Auto-loads the Ruby source files in the given directory.
+      #
+      # @param [String] dir the source directory
+      # @return [<Symbol>] the class constants that will be loaded
+      def autoload_dir(dir)
+        # the domain class definitions
+        srcs = Dir.glob(File.join(dir, "*.rb"))
+        # autoload the domain classes to ensure that definitions are picked up on demand in class hierarchy order
+        srcs.map do |file|
+          base_name = File.basename(file, ".rb")
+          sym = base_name.camelize.to_sym
+          # JRuby autoload of classes defined in a submodule of a Java wrapper class is not supported.
+          # However, this only occurs with the caTissue Specimen Pathology annotation class definitions,
+          # not the caTissue Participant or SCG annotations. TODO - confirm, isolate and report.
+          # Work-around is to require the files instead.
+          if name[/^Java::/] then
+            require file
+          else
+            autoload(sym, file)
+          end
+          sym
+        end    
+      end
+    end
+  end
+end

data/lib/caruby/domain/introspection.rb

@@ -0,0 +1,176 @@
+require 'caruby/util/module'
+require 'caruby/import/java'
+require 'caruby/domain/java_attribute'
+
+module CaRuby
+  module Domain
+    # Meta-data mix-in to infer attribute meta-data from Java properties.
+    module Introspection
+      
+      protected
+      
+      # @return [Boolean] whether this {Resource} class meta-data has been introspected
+      def introspected?
+        # initialization sets the attribute => metadata hash
+        not @attr_md_hash.nil?
+      end
+  
+      # Defines the Java property attribute and standard attribute methods, e.g.
+      # +study_protocol+ and +studyProtocol+. A boolean attribute is provisioned
+      # with an additional reader alias, e.g.  +available?+  for +is_available+.
+      #
+      # Each Java property attribute delegates to the Java property getter and setter.
+      # Each standard attribute delegates to the Java property attribute.
+      # Redefining these methods results in a call to the redefined method.
+      # This contrasts with a Ruby alias, where the alias remains bound to the
+      # original method body.
+      def introspect
+        # the module corresponding to the Java package of this class
+        mod = parent_module
+        # Set up the attribute data structures; delegates to Attributes.
+        init_attributes
+        logger.debug { "Introspecting #{qp} metadata..." }
+        # The Java properties defined by this class with both a read and a write method.
+        pds = java_properties(false)
+        # Define the standard Java attribute methods.
+        pds.each { |pd| define_java_attribute(pd) }
+        logger.debug { "Introspection of #{qp} metadata complete." }
+        self
+      end
+      
+      private
+  
+      # Defines the Java property attribute and standard attribute methods, e.g.
+      # +study_protocol+ and +studyProtocol+. A boolean attribute is provisioned
+      # with an additional reader alias, e.g.  +available?+  for +is_available+.
+      #
+      # A standard attribute which differs from the property attribute delegates
+      # to the property attribute, e.g. +study_protocol+ delegates to +studyProtocol+
+      # rather than aliasing +setStudyProtocol+. Redefining these methods results
+      # in a call to the redefined method.  This contrasts with a Ruby alias,
+      # where each attribute alias is bound to the respective property reader or
+      # writer.
+      def define_java_attribute(pd)
+        if transient?(pd) then
+          logger.debug { "Ignoring #{name.demodulize} transient property #{pd.name}." }
+          return
+        end
+        # the standard underscore lower-case attributes
+        attr = create_java_attribute(pd)
+        # delegate the standard attribute accessors to the property accessors
+        alias_attribute_property(attr, pd.name)
+        # add special wrappers
+        wrap_java_attribute(attr, pd)
+        # create Ruby alias for boolean, e.g. alias :empty? for :empty
+        if pd.property_type.name[/\w+$/].downcase == 'boolean' then
+          # strip leading is_, if any, before appending question mark
+          aliaz = attr.to_s[/^(is_)?(\w+)/, 2] << '?'
+          delegate_to_attribute(aliaz, attr)
+        end
+      end
+  
+      # Adds a filter to the attribute access method for the property descriptor pd if it is a String or Date.
+      def wrap_java_attribute(attribute, pd)
+        if pd.property_type == Java::JavaLang::String.java_class then
+          wrap_java_string_attribute(attribute, pd)
+        elsif pd.property_type == Java::JavaUtil::Date.java_class then
+          wrap_java_date_attribute(attribute, pd)
+        end
+      end
+  
+      # Adds a to_s filter to this Class's String property access methods.
+      def wrap_java_string_attribute(attribute, pd)
+        # filter the attribute writer
+        awtr = "#{attribute}=".to_sym
+        pwtr = pd.write_method.name.to_sym
+        define_method(awtr) do |value|
+          stdval = value.to_s unless value.nil_or_empty?
+          send(pwtr, stdval)
+        end
+        logger.debug { "Filtered #{qp} #{awtr} method with non-String -> String converter." }
+      end
+  
+      # Adds a date parser filter to this Class's Date property access methods.
+      def wrap_java_date_attribute(attribute, pd)
+        # filter the attribute reader
+        prdr = pd.read_method.name.to_sym
+        define_method(attribute) do
+          value = send(prdr)
+          Java::JavaUtil::Date === value ? value.to_ruby_date : value
+        end
+        
+        # filter the attribute writer
+        awtr = "#{attribute}=".to_sym
+        pwtr = pd.write_method.name.to_sym
+        define_method(awtr) do |value|
+          value = Java::JavaUtil::Date.from_ruby_date(value) if ::Date === value
+          send(pwtr, value)
+        end
+  
+        logger.debug { "Filtered #{qp} #{attribute} and #{awtr} methods with Java Date <-> Ruby Date converter." }
+      end
+  
+      # Aliases the methods _aliaz_ and _aliaz=_ to _property_ and _property=_, resp.,
+      # where _property_ is the Java property name for the attribute.
+      def alias_attribute_property(aliaz, attribute)
+        # strip the Java reader and writer is/get/set prefix and make a symbol
+        prdr, pwtr = attribute_metadata(attribute).property_accessors
+        alias_method(aliaz, prdr)
+        writer = "#{aliaz}=".to_sym
+        alias_method(writer, pwtr)
+      end
+  
+      # Makes a standard attribute for the given property descriptor.
+      # Adds a camelized Java-like alias to the standard attribute.
+      #
+      # @quirk caTissue 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
+        attr_md = JavaAttribute.new(pd, self)
+        add_attribute_metadata(attr_md)
+        # the property name is an alias for the standard attribute
+        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
+  
+      # Defines methods _aliaz_ and _aliaz=_ which calls the standard _attribute_ and
+      # _attribute=_ accessor methods, resp.
+      # Calling rather than aliasing the attribute accessor allows the aliaz accessor to
+      # reflect a change to the attribute accessor.
+      def delegate_to_attribute(aliaz, attribute)
+        if aliaz == attribute then raise MetadataError.new("Cannot delegate #{self} #{aliaz} to itself.") end
+        rdr, wtr = attribute_metadata(attribute).accessors
+        define_method(aliaz) { send(rdr) }
+        define_method("#{aliaz}=".to_sym) { |value| send(wtr, value) }
+        add_alias(aliaz, attribute)
+      end
+  
+      # Makes a new synthetic attribute for each _method_ => _original_ hash entry.
+      #
+      # @param (see Class#offset_attr_accessor)
+      def offset_attribute(hash, offset=nil)
+        offset_attr_accessor(hash, offset)
+        hash.each { |attr, original| add_attribute(attr, attribute_metadata(original).type) }
+      end
+    end
+  end
+end