caruby-core 1.4.1

data/lib/caruby/domain/resource_dependency.rb

@@ -0,0 +1,205 @@
+module CaRuby
+  # ResourceMetadata mix-in to capture Resource dependency.
+  module ResourceDependency
+
+    attr_reader :owners, :owner_attributes
+
+    # Returns the attribute which references the dependent type, or nil if none.
+    def dependent_attribute(type)
+      dependent_attributes.detect { |attr| type <= domain_type(attr) }
+    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] inverse the owner attribute defined in the dependent
+    # @param [<Symbol>] the attribute qualifier flags
+    def add_dependent_attribute(attribute, *flags)
+      attr_md = attribute_metadata(attribute)
+      unless attr_md.inverse_attribute_metadata.collection? then
+        delegate_writer_to_dependent(attribute)
+      end
+      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
+      # Child.add_owner(Parent, :parent, :children)
+      inv_type.add_owner(self, inverse, attribute)
+    end
+
+    # Returns whether this metadata's subject class depends on an owner.
+    def dependent?
+      not owners.empty?
+    end
+
+    # Returns whether this metadata's subject class depends the given other class.
+    def depends_on?(other)
+      owners.detect { |owner| owner === other }
+    end
+
+    # Returns the attribute which references the dependent type, or nil if none.
+    def dependent_attribute(dep_type)
+      type = dependent_attributes.detect { |attr| domain_type(attr) == dep_type }
+      return type if type
+      dependent_attribute(dep_type.superclass) if dep_type.superclass < Resource
+    end
+
+    # Returns the sole owner attribute of this class, or nil if there is not exactly one owner.
+    def owner_attribute
+      if @local_owner_attr_hash then
+        @local_owner_attr_hash.each_value { |attr| return attr } if @local_owner_attr_hash.size == 1
+      elsif superclass < Resource
+        superclass.owner_attribute
+      end
+    end
+
+    # Returns this Resource class's owner types.
+    def owner_attributes
+      if @local_owner_attr_hash then
+        @local_owner_attrs ||= Enumerable::Enumerator.new(@local_owner_attr_hash, :each_value).filter
+      elsif superclass < Resource
+        superclass.owner_attributes
+      else
+        Array::EMPTY_ARRAY
+      end
+    end
+
+    # Returns this Resource class's dependent types.
+    def dependents
+      dependent_attributes.wrap { |attr| attr.type }
+    end
+
+    # Returns this Resource class's owner types.
+    def owners
+      if @local_owner_attr_hash then
+        @local_owners ||= Enumerable::Enumerator.new(@local_owner_attr_hash, :each_key)
+      elsif superclass < Resource
+        superclass.owners
+      else
+        Array::EMPTY_ARRAY
+      end
+    end
+
+    protected
+
+    # If attribute is nil, then the owner attribute is inferred as follows:
+    # * If there is exactly one reference attribute from this dependent to the owner klass, then that
+    #   attribute is the owner attribute.
+    # * Otherwise, if this dependent class has a default attribute name given by the demodulized,
+    #   underscored owner class name and that attribute references the owner klass, then that attribute
+    #   is the owner attribute.
+    # * Otherwise, there is no owner attribute.
+    def add_owner(klass, attribute=nil, inverse=nil)
+      logger.debug { "Adding #{qp} owner #{klass.qp}..." }
+      if @owner_attr_hash then
+        raise MetadataError.new("Can't add #{qp} owner #{klass.qp} after dependencies have been accessed.")
+      end
+      @local_owner_attr_hash ||= {}
+      @local_owner_attr_hash[klass] = attribute ||= detect_owner_attribute(klass, inverse)
+
+      # augment the owner writer method
+      if attribute then
+        raise ValidationError.new("Owner #{klass.qp} missing dependent attribute for dependent #{qp}") if inverse.nil?
+        set_attribute_inverse(attribute, inverse)
+        attribute_metadata(attribute).qualify(:owner)
+      else
+        logger.debug { "No #{qp} owner attribute detected for #{klass.qp}." }
+      end
+    end
+
+    # Returns this Resource class's owner type => attribute hash.
+    def owner_attribute_hash
+      @local_owner_attr_hash or (superclass.owner_attribute_hash if superclass < Resource) or Hash::EMPTY_HASH
+    end
+
+    private
+
+    def domain_class?(klass)
+      Class === klass and klass.include?(CaRuby::Resource)
+    end
+
+    # Redefines the attribute writer method to delegate to its inverse writer.
+    #
+    # For an attribute +dep+ with setter +setDep+ and inverse +owner+ with setter +setOwner+,
+    # this is equivalent to the following:
+    #   class Owner
+    #     def dep=(d)
+    #       d.setOwner(self) if d
+    #       setDep(self)
+    #     end
+    #   end
+    def delegate_writer_to_dependent(attribute)
+      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}.#{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_exclusive_dependent method
+        lambda { |dep| set_exclusive_dependent(dep, old_writer, inv_attr_md.writer) }
+      end
+    end
+
+    # Returns the owner attribute for the given owner klass and inverse, or nil if no
+    # owner attribute was detected.
+    def detect_owner_attribute(klass, inverse=nil)
+      # example: Parent.add_dependent_attribute(:children) without inverse calls
+      # Child.add_owner(Parent, nil, :children) which calls
+      # Child.detect_owner_attribute(klass, :children)
+
+      # the candidate attributes which return the owner type
+      candidates = domain_attributes.map do |attr|
+        attr_md = attribute_metadata(attr)
+        # possible hit if there is a match on the type
+        attr_md if klass.equal?(attr_md.type) or klass <= attr_md.type
+      end
+      candidates.compact!
+      return if candidates.empty?
+
+      # there can be at most one owner attribute per owner.
+      return candidates.first.to_sym if candidates.size == 1
+
+      # we have a hit if there is a match on the inverse. in the above example,
+      # attribute :parent with inverse :children => :parent is the owner attribute
+      candidates.each { |attr_md| return attr_md.to_sym if attr_md.inverse == inverse }
+
+      # by convention, if more than one attribute references the owner type,
+      # then the attribute named after the owner type is the owner attribute
+      hit = klass.name[/\w+$/].downcase.to_sym
+      hit if candidates.detect { |attr_md| attr_md.to_sym == hit }
+    end
+
+    # Infers annotation dependent attributes based on whether a domain attribute satisfies the
+    # following criteria:
+    # 1. the referenced type has an attribute which refers back to this classifier's subject class
+    # 2. the referenced type is not an owner of this classifier's subject class
+    # Annotation dependencies are not specified in a configuration and follow the above convention.
+    def infer_annotation_dependent_attributes
+      dep_attrs = []
+      domain_attributes.each do |attr|
+        next if owner_attribute?(attr)
+        ref_md = domain_type(attr).metadata
+        owner_attr = ref_md.detect_owner_attribute(subject_class)
+        if owner_attr then
+          ref_md.add_owner(subject_class, owner_attr)
+          dep_attrs << attr
+        end
+      end
+      dep_attrs
+    end
+  end
+end

data/lib/caruby/domain/resource_introspection.rb

@@ -0,0 +1,159 @@
+require 'caruby/import/java'
+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.
+    # +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
+      init_attributes # in ResourceAttributes
+      logger.debug { "Introspecting #{qp} metadata..." }
+      # filter properties for those with both a read and 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
+
+    # 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.propertyType == Java::JavaLang::String.java_class then
+        wrap_java_string_attribute(attribute, pd)
+      elsif pd.propertyType == 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
+
+    # @return a new attribute symbol created for the given PropertyDescriptor pd
+    def create_java_attribute(pd)
+      # make the attribute metadata
+      attr_md = JavaAttributeMetadata.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
+      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)
+      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
+
+    # 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_metadata.rb

@@ -0,0 +1,117 @@
+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_dependency'
+
+module CaRuby
+  # Exception raised if a meta-data setting is missing or invalid.
+  class MetadataError < RuntimeError; end
+  
+  # Adds introspected metadata to a Class.
+  module ResourceMetadata
+    include ResourceIntrospection, ResourceDependency, ResourceAttributes
+
+    attr_reader :domain_module
+
+    # Associates meta-data with a Resource class. When a Resource class is added to a ResourceModule,
+    # the ResourceModule extends the Resource class with ResourceMetadata and calls this
+    # {#add_metadata} method with itself as the mod argument. The ResourceModule is accessed
+    # by the {#domain_module} method.
+    def add_metadata(mod)
+      @domain_module = mod
+      init_attributes # in ResourceAttributes
+      introspect # in ResourceIntrospection
+    end
+
+    # @return the domain type for attribute, or nil if attribute is not a domain attribute
+    def domain_type(attribute)
+      attr_md = attribute_metadata(attribute)
+      attr_md.type if attr_md.domain?
+    end
+
+   # Prints this classifier's content to the log.
+    def pretty_print(q)
+      # the Java property descriptors
+      property_descriptors = java_attributes.wrap { |attr| attribute_metadata(attr).property_descriptor }
+      # build a map of relevant display label => attributes
+      prop_printer = property_descriptors.wrap { |pd| PROP_DESC_PRINTER.wrap(pd) }
+      prop_syms = property_descriptors.map { |pd| pd.name.to_sym }.to_set
+      aliases = @alias_std_attr_map.keys - attributes.to_a - prop_syms
+      alias_attr_hash = aliases.to_compact_hash { |aliaz| @alias_std_attr_map[aliaz] }
+      dependents_printer = dependent_attributes.wrap { |attr| DEPENDENT_ATTR_PRINTER.wrap(attribute_metadata(attr)) }
+      owner_printer = owners.wrap { |type| TYPE_PRINTER.wrap(type) }
+      inverses = @attributes.to_compact_hash do |attr|
+         attr_md = attribute_metadata(attr)
+         "#{attr_md.type.qp}.#{attr_md.inverse}" if attr_md.inverse
+      end
+      domain_attr_printer = domain_attributes.to_compact_hash { |attr| domain_type(attr).qp }
+      map = {
+        "Java properties" => prop_printer,
+        "standard attributes" => attributes,
+        "aliases to standard attributes" => alias_attr_hash,
+        "secondary key" => secondary_key_attributes,
+        "mandatory attributes" => mandatory_attributes,
+        "domain attributes" => domain_attr_printer,
+        "creatable domain attributes" => creatable_domain_attributes,
+        "updatable domain attributes" => updatable_domain_attributes,
+        "fetched domain attributes" => fetched_domain_attributes,
+        "cascaded domain attributes" => cascaded_attributes,
+        "owners" => owner_printer,
+        "owner attributes" => owner_attributes,
+        "inverse attributes" => inverses,
+        "dependent attributes" => dependents_printer,
+        "default values" => defaults
+      }.delete_if { |key, value| value.nil_or_empty? }
+      # one indented line per entry, all but the last line ending in a comma
+      content = map.map { |label, value| "  #{label}=>#{format_print_value(value)}" }.join(",\n")
+      # print the content to the log
+      q.text("#{qp} structure:\n#{content}")
+    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)
+      klass.add_metadata(mod)
+    end
+
+    private
+
+    # A proc to print the unqualified class name.
+    TYPE_PRINTER = PrintWrapper.new { |type| type.qp }
+
+    DEPENDENT_ATTR_PRINTER = PrintWrapper.new do |attr_md|
+      flags = []
+      flags << :logical if attr_md.logical?
+      flags << :autogenerated if attr_md.autogenerated?
+      flags << :disjoint if attr_md.disjoint?
+      flags.empty? ? "#{attr_md}" : "#{attr_md}(#{flags.join(',')})"
+    end
+
+    # A proc to print the property descriptor name.
+    PROP_DESC_PRINTER = PrintWrapper.new { |pd| pd.name }
+
+    def format_print_value(value)
+      case value
+      when String then
+        value
+      when Class then
+        value.qp
+      else
+        value.pp_s(:single_line)
+      end
+    end
+  end
+end