jinx 2.1.1

data/lib/jinx/metadata/id_alias.rb

@@ -0,0 +1,23 @@
+module Jinx
+  # Mix-in for Java classes which have an +id+ attribute.
+  # Since +id+ is a reserved Ruby method, this mix-in defines an +identifier+ attribute
+  # which fronts the +id+ attribute. This mix-in should be included by any JRuby wrapper
+  # class for a Java class or interface which implements an +id+ property.
+  module IdAlias
+    # Returns the identifier.
+    # This method delegates to the Java +id+ attribute 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+ attribute writer method.
+    #
+    # @param [Integer] value the value to set
+    def identifier=(value)
+      setId(value)
+    end
+  end
+end

data/lib/jinx/metadata/introspector.rb

@@ -0,0 +1,179 @@
+require 'jinx/helpers/module'
+require 'jinx/import/java'
+require 'jinx/metadata/propertied'
+require 'jinx/metadata/java_property'
+
+module Jinx
+  # Meta-data mix-in to infer attribute meta-data from Java properties.
+  module Introspector
+    include Propertied
+    
+    # @return [Boolean] whether this class has been introspected
+    def introspected?
+      !!@introspected
+    end
+    
+    # Adds an optional {attribute=>value} constructor parameter to this class.
+    def add_attribute_value_initializer
+      class << self
+        def new(opts=nil)
+          obj = super()
+          obj.merge_attributes(opts) if opts
+          obj
+        end
+      end
+      logger.debug { "#{self} is extended with an optional {attribute=>value} constructor parameter." }
+    end
+
+    # Defines the Java attribute access 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 attribute 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
+      # Set up the attribute data structures; delegates to Propertied.
+      init_property_classifiers
+      logger.debug { "Introspecting #{qp} metadata..." }
+      # check for method conflicts
+      conflicts = instance_methods(false) & Resource.instance_methods(false)
+      unless conflicts.empty? then
+        logger.warn("#{self} methods conflict with #{Resource} methods: #{conflicts.qp}")
+      end
+      # If this is a Java class rather than interface, then define the Java property
+      # attributes.
+      if Class === self then
+        # the Java attributes defined by this class with both a read and a write method
+        pds = property_descriptors(false)
+        # Define the standard Java attribute methods.
+        pds.each { |pd| define_java_property(pd) }
+      end
+      # Mark this class as introspected.
+      @introspected = true
+      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 attribute reader or
+    # writer.
+    #
+    # @param [Java::PropertyDescriptor] the introspected property descriptor
+    def define_java_property(pd)
+      if transient?(pd) then
+        logger.debug { "Ignoring #{name.demodulize} transient attribute #{pd.name}." }
+        return
+      end
+      # the standard underscore lower-case attributes
+      ja = add_java_property(pd).attribute
+      # delegate the standard attribute accessors to the attribute accessors
+      alias_property_accessors(ja, pd.name)
+      # add special wrappers
+      wrap_java_property(ja, 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 = ja.to_s[/^(is_)?(\w+)/, 2] << '?'
+        delegate_to_attribute(aliaz, ja)
+      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_property(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 attribute 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 attribute 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 _attribute_ and _attribute=_, resp.,
+    # where _attribute_ is the Java attribute name for the attribute.
+    def alias_property_accessors(aliaz, attribute)
+      # strip the Java reader and writer is/get/set prefix and make a symbol
+      prdr, pwtr = property(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.
+    #
+    # @param (see #define_java_property)
+    # @return [Property] the new property
+    def add_java_property(pd)
+      # make the attribute metadata
+      prop = create_java_property(pd)
+      add_property(prop)
+      # the property name is an alias for the standard attribute
+      pa = prop.attribute
+      # the Java property name as an attribute symbol
+      ja = pd.name.to_sym
+      delegate_to_attribute(ja, pa) unless pa == ja
+      prop
+    end
+    
+    # @param (see #add_java_property)
+    # @return (see #add_java_property)
+    def create_java_property(pd)
+      JavaProperty.new(pd, self)
+    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 Jinx.fail(MetadataError, "Cannot delegate #{self} #{aliaz} to itself.") end
+      rdr, wtr = property(attribute).accessors
+      define_method(aliaz) { send(rdr) }
+      define_method("#{aliaz}=".to_sym) { |value| send(wtr, value) }
+      register_property_alias(aliaz, attribute)
+    end
+  end
+end

data/lib/jinx/metadata/inverse.rb

@@ -0,0 +1,170 @@
+module Jinx
+  # Meta-data mix-in to infer and set inverse attributes.
+  module Inverse
+    # Returns the inverse of the given attribute. If the attribute has an #{Property#inverse_property},
+    # then that attribute's inverse is returned. Otherwise, if the attribute is an #{Property#owner?},
+    # then the target class dependent attribute which matches this type is returned, if it exists.
+    #
+    # @param [Property] prop the subject attribute
+    # @param [Class, nil] klass the target class
+    # @return [Property, nil] the inverse attribute, if any
+    def inverse_property(prop, klass=nil)
+      inv_prop = prop.inverse_property
+      return inv_prop if inv_prop
+      if prop.dependent? and klass then
+        klass.owner_property_hash.each { |otype, op|
+        return op if self <= otype }
+      end
+    end
+    
+    protected
+    
+    # Infers the inverse of the given property declared by this class.
+    # A domain attribute is recognized as an inverse according to the
+    # {Inverse#detect_inverse_attribute} criterion.
+    #
+    # @param [Attribute] property the property to check
+    def infer_property_inverse(property)
+      inv = property.type.detect_inverse_attribute(self)
+      if inv then set_attribute_inverse(property.attribute, inv) end
+    end
+    
+    # Sets the given bi-directional association attribute's inverse.
+    #
+    # @param [Symbol] attribute the subject attribute
+    # @param [Symbol] the attribute inverse
+    # @raise [TypeError] if the inverse type is incompatible with this Resource
+    def set_attribute_inverse(attribute, inverse)
+      prop = property(attribute)
+      # the standard attribute
+      pa = prop.attribute
+      # return if inverse is already set
+      return if prop.inverse == inverse
+      # the default inverse
+      inverse ||= prop.type.detect_inverse_attribute(self)
+      # If the attribute is not declared by this class, then make a new attribute
+      # metadata specialized for this class.
+      unless prop.declarer == self then
+        prop = restrict_attribute_inverse(prop, inverse)
+      end
+      logger.debug { "Setting #{qp}.#{pa} inverse to #{inverse}..." }
+      # the inverse attribute meta-data
+      inv_prop = prop.type.property(inverse)
+      # If the attribute is the many side of a 1:M relation, then delegate to the one side.
+      if prop.collection? and not inv_prop.collection? then
+        return prop.type.set_attribute_inverse(inverse, pa)
+      end
+      # This class must be the same as or a subclass of the inverse attribute type.
+      unless self <= inv_prop.type then
+        Jinx.fail(TypeError, "Cannot set #{qp}.#{pa} inverse to #{prop.type.qp}.#{pa} with incompatible type #{inv_prop.type.qp}")
+      end
+      # Set the inverse in the attribute metadata.
+      prop.inverse = inverse
+      # If attribute is the one side of a 1:M or non-reflexive 1:1 relation, then add the inverse updater.
+      unless prop.collection? then
+        # Inject adding to the inverse collection into the attribute writer method. 
+        add_inverse_updater(pa, inverse)
+        unless prop.type == inv_prop.type or inv_prop.collection? then
+          prop.type.delegate_writer_to_inverse(inverse, pa)
+        end
+      end
+      logger.debug { "Set #{qp}.#{pa} inverse to #{inverse}." }
+    end
+    
+    # Detects an unambiguous attribute which refers to the given referencing class.
+    # If there is exactly one attribute with the given return type, then that attribute is chosen.
+    # Otherwise, the attribute whose name matches the underscored referencing class name is chosen,
+    # if any.
+    #
+    # @param [Class] klass the referencing class
+    # @return [Symbol, nil] the inverse attribute for the given referencing class and inverse,
+    #   or nil if no owner attribute was detected
+    def detect_inverse_attribute(klass)
+      # The candidate attributes return the referencing type and don't already have an inverse.
+      candidates = domain_attributes.compose { |prop| klass <= prop.type and prop.inverse.nil? }
+      pa = detect_inverse_attribute_from_candidates(klass, candidates)
+      if pa then
+        logger.debug { "#{qp} #{klass.qp} inverse attribute is #{pa}." }
+      else
+        logger.debug { "#{qp} #{klass.qp} inverse attribute was not detected." }
+      end
+      pa
+    end
+    
+    # Redefines the attribute writer method to delegate to its inverse writer.
+    # This is done to enforce inverse integrity.
+    #
+    # For a +Person+ attribute +account+ with inverse +holder+, this is equivalent to the following:
+    #   class Person
+    #     alias :set_account :account=
+    #     def account=(acct)
+    #       acct.holder = self if acct
+    #       set_account(acct)
+    #     end
+    #   end
+    def delegate_writer_to_inverse(attribute, inverse)
+      prop = property(attribute)
+      # nothing to do if no inverse
+      inv_prop = prop.inverse_property || return
+      logger.debug { "Delegating #{qp}.#{attribute} update to the inverse #{prop.type.qp}.#{inv_prop}..." }
+      # redefine the write to set the dependent inverse
+      redefine_method(prop.writer) do |old_writer|
+        # delegate to the Jinx::Resource set_inverse method
+        lambda { |dep| set_inverse(dep, old_writer, inv_prop.writer) }
+      end
+    end
+
+    private
+    
+    # Copies the given attribute metadata from its declarer to this class. The new attribute metadata
+    # has the same attribute access methods, but the declarer is this class and the inverse is the
+    # given inverse attribute.
+    #
+    # @param [Property] prop the attribute to copy
+    # @param [Symbol] the attribute inverse
+    # @return [Property] the copied attribute metadata
+    def restrict_attribute_inverse(prop, inverse)
+      logger.debug { "Restricting #{prop.declarer.qp}.#{prop} to #{qp} with inverse #{inverse}..." }
+      rst_prop = prop.restrict(self, :inverse => inverse)
+      logger.debug { "Restricted #{prop.declarer.qp}.#{prop} to #{qp} with inverse #{inverse}." }
+      rst_prop
+    end
+    
+    # @param klass (see #detect_inverse_attribute)
+    # @param [<Symbol>] candidates the attributes constrained to the target type
+    # @return (see #detect_inverse_attribute)
+    def detect_inverse_attribute_from_candidates(klass, candidates)
+      return if candidates.empty?
+      # there can be at most one owner attribute per owner.
+      return candidates.first.to_sym if candidates.size == 1
+      # by convention, if more than one attribute references the owner type,
+      # then the attribute named after the owner type is the owner attribute
+      tgt = klass.name[/\w+$/].underscore.to_sym
+      tgt if candidates.detect { |pa| pa == tgt }
+    end
+    
+    # Modifies the given attribute writer method to update the given inverse.
+    #
+    # @param (see #set_attribute_inverse)
+    def add_inverse_updater(attribute, inverse)
+      prop = property(attribute)
+      # the reader and writer methods
+      rdr, wtr = prop.accessors
+      # the inverse atttribute metadata
+      inv_prop = prop.inverse_property
+      # the inverse attribute reader and writer
+      inv_rdr, inv_wtr = inv_accessors = inv_prop.accessors
+      # Redefine the writer method to update the inverse by delegating to the inverse
+      redefine_method(wtr) do |old_wtr|
+        # the attribute reader and (superseded) writer
+        accessors = [rdr, old_wtr]
+        if inv_prop.collection? then
+          lambda { |other| add_to_inverse_collection(other, accessors, inv_rdr) }
+        else
+          lambda { |other| set_inversible_noncollection_attribute(other, accessors, inv_wtr) }
+        end
+      end
+      logger.debug { "Injected inverse #{inverse} updater into #{qp}.#{attribute} writer method #{wtr}." }
+    end
+  end
+end

data/lib/jinx/metadata/java_property.rb

@@ -0,0 +1,169 @@
+require 'jinx/helpers/inflector'
+require 'jinx/metadata/property'
+
+module Jinx
+  # The attribute metadata for an introspected Java property. 
+  class JavaProperty < Property
+
+    # This property's Java property descriptor.
+    attr_reader :property_descriptor
+
+    # This property's Java property [reader, writer] accessors, e.g. +[:getActivityStatus, :setActivityStatus]+.
+    attr_reader :property_accessors
+
+    # Creates a Ruby Property symbol corresponding to the given Ruby Java class wrapper klazz
+    # and Java property_descriptor.
+    #
+    # The property name is the lower-case, underscore property descriptor name with the alterations
+    # described in {JavaProperty.to_attribute_symbol} and {Class#unocclude_reserved_method}.
+    #
+    # The property 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 {Metadata#domain_module}.
+    # * Otherwise, this method returns Java::Javalang::Object.
+    #
+    # The optional restricted_type argument restricts the property 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)
+      Jinx.fail(ArgumentError, "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
+          Jinx.fail(ArgumentError, "Reader method not found for #{declarer} property #{pd.name}")
+        end
+      end
+      unless pd.write_method then
+        Jinx.fail(ArgumentError, "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
+        Jinx.fail(ArgumentError, "Writer method not found for #{declarer} property #{pd.name}")
+      end
+      @property_accessors = [reader, writer]
+      qualify(:collection) if collection_java_class?
+      @type = infer_type
+    end
+    
+    # @return [Symbol] the JRuby wrapper method for the Java property reader
+    def property_reader
+      property_accessors.first
+    end
+    
+    # @return [Symbol] the JRuby wrapper method for the Java property writer
+    def property_writer
+      property_accessors.last
+    end
+
+    # Returns a lower-case, underscore symbol for the given property_name.
+    # A name ending in 'Collection' is changed to a pluralization.
+    #
+    # @example
+    #   JavaProperty.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
+        JavaProperty.to_attribute_symbol(propname)
+      end
+    end
+
+    # @return [Boolean] whether this property's Java type is +Iterable+
+    def collection_java_class?
+      # the Java property type
+      ptype = @property_descriptor.property_type
+      # Test whether the corresponding JRuby wrapper class or module is an Iterable.
+      Class.to_ruby(ptype) < Java::JavaLang::Iterable
+    end
+
+    # @return [Class] the type for the specified klass property descriptor pd as described in {#initialize}
+    def infer_type
+      collection? ? infer_collection_type : infer_non_collection_type
+    end
+
+    # Returns the domain type for this property'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}.
+    #
+    # @return [Class] this property's Ruby type
+    def infer_collection_type
+       generic_parameter_type or infer_collection_type_from_name or Java::JavaLang::Object
+    end
+
+    # @return [Class] this property's Ruby type
+    def infer_non_collection_type
+      jtype = @property_descriptor.property_type
+      Class.to_ruby(jtype)
+    end
+
+    # @return [Class, nil] the domain type of this property's property descriptor Collection generic
+    #   type argument, or nil if none
+    def generic_parameter_type
+      method = @property_descriptor.readMethod || return
+      gtype = method.genericReturnType
+      return unless Java::JavaLangReflect::ParameterizedType === gtype
+      atypes = gtype.actualTypeArguments
+      return unless atypes.size == 1
+      atype = atypes[0]
+      klass = java_to_ruby_class(atype)
+      logger.debug { "Inferred #{declarer.qp} #{self} domain type #{klass.qp} from generic parameter #{atype.name}." } if klass
+      klass
+    end
+
+    # @param [Class, String] jtype the Java class or class name
+    # @return [Class] the corresponding Ruby type 
+    def java_to_ruby_class(jtype)
+      name = String === jtype ? jtype : jtype.name
+      Class.to_ruby(name)
+    end
+
+    # Returns the domain type for this property's collection Java property descriptor name.
+    # By convention, Jinx domain collection propertys 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.
+    #
+    # @return [Class] the collection item type
+    def infer_collection_type_from_name
+      # the property name
+      pname = @property_descriptor.name
+      # The potential class name is the capitalized property name without a 'Collection' suffix.
+      cname = pname.capitalize_first.sub(/Collection$/, '')
+      jname = [@declarer.parent_module, cname].join('::')
+      klass = eval jname rescue nil
+      if klass then logger.debug { "Inferred #{declarer.qp} #{self} collection domain type #{klass.qp} from the property name." } end
+      klass
+    end
+  end
+end