caruby-core 1.5.5 → 2.1.1

data/lib/caruby/domain/dependency.rb

@@ -1,225 +0,0 @@
-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
-      
-      # @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 [Boolean] whether this {Resource} class is dependent and reference its owners
-      def bidirectional_dependent?
-        dependent? and not owner_attributes.empty?
-      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/id_alias.rb

@@ -1,22 +0,0 @@
-module CaRuby
-  # Mix-in for Java classes which have an +id+ property.
-  # Since +id+ is a reserved Ruby method, this mix-in defines an +identifier+ attribute
-  # which fronts the +id+ property.
-  module IdAlias
-    # Returns the identifier.
-    # This method delegates to the Java +id+ property reader method.
-    #
-    # @return [Integer] the identifier value
-    def identifier
-      getId
-    end
-
-    # Sets the identifier to the given value.
-    # This method delegates to the Java +id+ property writer method.
-    #
-    # @param [Integer] value the value to set
-    def identifier=(value)
-      setId(value)
-    end
-  end
-end

data/lib/caruby/domain/importer.rb

@@ -1,183 +0,0 @@
-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 = java_import "#{@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 [Class] klass 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

@@ -1,176 +0,0 @@
-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