jinx 2.1.1

data/lib/jinx/metadata.rb

@@ -0,0 +1,155 @@
+require 'jinx/helpers/collections'
+require 'jinx/import/java'
+require 'jinx/metadata/java_property'
+require 'jinx/metadata/introspector'
+require 'jinx/metadata/inverse'
+require 'jinx/metadata/dependency'
+
+module Jinx
+  # Exception raised if a meta-data setting is missing or invalid.
+  class MetadataError < RuntimeError; end
+
+  # The metadata introspection mix-in for a Java application domain class or interface.
+  module Metadata
+    include Introspector, Inverse, Dependency
+    
+    # @return [Module] the application domain {Resource} module which introspected this class
+    attr_accessor :domain_module
+    
+    # @param [Symbol] attribute the property attribute
+    # @param [{Symbol => Object}] opts the property options
+    # @option opts [true, Symbol, <Symbol>] :dependent whether this property is a dependent reference
+    #   qualified by the given {Property} flags
+    def property(attribute, *opts)
+      return super(attribute) if opts.empty?
+      Options.to_hash(*opts).each do |k, v|
+        case k
+          when :alias then alias_attribute(v, attribute)
+          when :default then add_attribute_default(attribute, v)
+          when :dependent then add_dependent_attribute(attribute) if v
+          when :inverse then set_attribute_inverse(attribute, v)
+          when :mandatory then add_mandatory_attribute(attribute) if v
+          when :primary_key then add_primary_key_attribute(attribute) if v
+          when :secondary_key then add_secondary_key_attribute(attribute) if v
+          when :alternate_key then add_alternate_key_attribute(attribute) if v
+          when :type then set_attribute_type(attribute, v)
+          else qualify_attribute(attribute, k) if v
+        end
+      end
+    end
+
+    # @return [Class, nil] the domain type for attribute, or nil if attribute is not a domain attribute
+    def domain_type(attribute)
+      prop = property(attribute)
+      prop.type if prop.domain?
+    end
+
+    # Returns an empty value for the given attribute.
+    # * If this class is not abstract, then the empty value is the initialized value.
+    # * Otherwise, if the attribute is a Java primitive number then zero.
+    # * Otherwise, if the attribute is a Java primitive boolean then +false+.
+    # * Otherwise, the empty value is nil.
+    #
+    # @param [Symbol] attribute the target attribute
+    # @return [Numeric, Boolean, Enumerable, nil] the empty attribute value
+    def empty_value(attribute)
+      if abstract? then
+        prop = property(attribute)
+        # the Java attribute type
+        jtype = prop.property_descriptor.attribute_type if JavaProperty === prop
+        # A primitive is either a boolean or a number (String is not primitive).
+        if jtype and jtype.primitive? then
+          type.name == 'boolean' ? false : 0
+        end
+      else
+        # Since this class is not abstract, create a prototype instance on demand and make
+        # a copy of the initialized collection value from that instance.
+        @prototype ||= new
+        value = @prototype.send(attribute) || return
+        value.class.new
+      end
+    end
+  
+   # Prints this classifier's content to the log.
+    def pretty_print(q)
+      map = pretty_print_attribute_hash.delete_if { |k, v| v.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
+
+    private
+  
+    # A proc to print the unqualified class name.
+    # @private
+    TYPE_PRINTER = PrintWrapper.new { |type| type.qp }
+
+    # A proc to print the property descriptor name.
+    # @private
+    PROP_DESC_PRINTER = PrintWrapper.new { |pd| pd.name }
+             
+    # @param [Property] the property to print
+    # @return [<Symbol>] the flags to modify the property
+    def pretty_print_attribute_flags(prop)
+      flags = []
+      flags << :disjoint if prop.disjoint?
+      flags
+    end
+    
+    # @return [{String => <Symbol>}] the attributes to print
+    def pretty_print_attribute_hash
+      # the Java property descriptors
+      pds = java_attributes.wrap { |pa| property(pa).property_descriptor }
+      # the display label => properties printer
+      prop_prn = pds.wrap { |pd| PROP_DESC_PRINTER.wrap(pd) }
+      # the Java attributes
+      prop_syms = pds.map { |pd| pd.name.to_sym }.to_set
+      # the attribute aliases
+      aliases = @alias_std_prop_map.keys - attributes.to_a - prop_syms
+      alias_hash = aliases.to_compact_hash { |aliaz| @alias_std_prop_map[aliaz] }
+      # the dependent attributes printer
+      dep_prn_wrapper = dependent_attributes_print_wrapper
+      dep_prn = dependent_attributes.wrap { |pa| dep_prn_wrapper.wrap(property(pa)) }
+      # the owner classes printer
+      own_prn = owners.wrap { |type| TYPE_PRINTER.wrap(type) }
+      # the inverse attributes printer
+      inv_prn = @attributes.to_compact_hash do |pa|
+         prop = property(pa)
+         "#{prop.type.qp}.#{prop.inverse}" if prop.inverse
+      end
+      # the domain attribute printer
+      dom_prn = domain_attributes.to_compact_hash { |pa| domain_type(pa).qp }
+      # the description => printable hash
+      {
+        'Java attributes' => prop_prn,
+        'standard attributes' => attributes,
+        'aliases to standard attributes' => alias_hash,
+        'secondary key' => secondary_key_attributes,
+        'mandatory attributes' => mandatory_attributes,
+        'domain attributes' => dom_prn,
+        'owners' => own_prn,
+        'owner attributes' => owner_attributes,
+        'inverse attributes' => inv_prn,
+        'dependent attributes' => dep_prn,
+        'default values' => defaults
+      }
+    end
+
+    # @return [PrintWrapper] a proc to print the dependent attributes
+    def dependent_attributes_print_wrapper
+      PrintWrapper.new do |prop|
+        flags = pretty_print_attribute_flags(prop)
+        flags.empty? ? "#{prop}" : "#{prop}(#{flags.join(',')})"
+      end
+    end
+
+    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

data/lib/jinx/metadata/attribute_enumerator.rb

@@ -0,0 +1,73 @@
+module Jinx
+  # A filter on the standard attribute symbol => metadata hash that yields
+  # each attribute which satisfies the attribute metadata condition.
+  class AttributeEnumerator
+    include Enumerable
+
+    # @param [{Symbol => Property}] hash the attribute symbol => metadata hash
+    # @yield [prop] optional condition which determines whether the attribute is
+    #   selected (default is all attributes)
+    # @yieldparam [Property] the metadata for the standard attribute
+    # @raise [ArgumentError] if a parameter is missing 
+    def initialize(hash, &filter)
+      Jinx.fail(ArgumentError, "Attribute filter missing hash argument") if hash.nil?
+      @hash = hash
+      @filter = block_given? ? filter : Proc.new { true }
+    end
+
+    # @yield [attribute, prop] the block to apply to the filtered attribute metadata and attribute
+    # @yieldparam [Symbol] attribute the attribute
+    # @yieldparam [Property] prop the attribute metadata
+    def each_pair
+      @hash.each { |pa, prop| yield(pa, prop) if @filter.call(prop) }
+    end
+    
+    # @return [<(Symbol, Property)>] the (symbol, attribute) enumerator
+    def enum_pairs
+      enum_for(:each_pair)
+    end
+    
+    # @yield [attribute] block to apply to each filtered attribute
+    # @yieldparam [Symbol] the attribute which satisfies the filter condition
+    def each_attribute(&block)
+      each_pair { |pa, prop| yield(pa) }
+    end
+    
+    alias :each :each_attribute
+
+    # @yield [prop] the block to apply to the filtered attribute metadata
+    # @yieldparam [Property] prop the attribute metadata
+    def each_property
+      each_pair { |pa, prop| yield(prop) }
+    end
+    
+    # @return [<Property>] the property enumerator
+    def properties
+      @prop_enum ||= enum_for(:each_property)
+    end
+    
+    # @yield [attribute] the block to apply to the attribute
+    # @yieldparam [Symbol] attribute the attribute to detect
+    # @return [Property] the first attribute metadata whose attribute satisfies the block
+    def detect_property
+      each_pair { |pa, prop| return prop if yield(pa) }
+      nil
+    end
+    
+    # @yield [prop] the block to apply to the attribute metadata
+    # @yieldparam [Property] prop the attribute metadata
+    # @return [Symbol] the first attribute whose metadata satisfies the block
+    def detect_with_property
+      each_pair { |pa, prop| return pa if yield(prop) }
+      nil
+    end
+
+    # @yield [prop] the attribute selection filter
+    # @yieldparam [Property] prop the candidate attribute metadata
+    # @return [AttributeEnumerator] a new eumerator which applies the filter block given to this
+    #   method with the Property enumerated by this enumerator
+    def compose
+      AttributeEnumerator.new(@hash) { |prop| @filter.call(prop) and yield(prop) }
+    end
+  end
+end

data/lib/jinx/metadata/dependency.rb

@@ -0,0 +1,244 @@
+require 'jinx/helpers/validation'
+
+module Jinx
+  # Metadata mix-in to capture Resource dependency.
+  module Dependency
+    # @return [<Class>] the owner classes
+    attr_reader :owners
+    
+    # @return [<Symbol>] the owner reference attributes
+    attr_reader :owner_attributes
+
+    # Adds the given attribute as a dependent.
+    #
+    # 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)
+      prop = property(attribute)
+      logger.debug { "Marking #{qp}.#{attribute} as a dependent attribute of type #{prop.type.qp}..." }
+      flags << :dependent unless flags.include?(:dependent)
+      prop.qualify(*flags)
+      inverse = prop.inverse
+      inv_type = prop.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)
+      logger.debug { "Marked #{qp}.#{attribute} as a dependent attribute with inverse #{inv_type.qp}#{inverse}." }
+    end
+    
+    # @return [Boolean] whether this class depends on an owner
+    def dependent?
+      not owners.empty?
+    end
+
+    # @param [Class] other the class to check
+    # @param [Boolean] recursive whether to check if this class depends on a dependent
+    #   of the other class
+    # @return [Boolean] whether this class depends on the other class
+    def depends_on?(other, recursive=false)
+      owners.detect do |owner|
+        other <= owner or (recursive and depends_on_recursive?(owner, other))
+      end
+    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)
+      most_specific_domain_attribute(klass, dependent_attributes)
+    end
+    
+    # @return [<Property>] the owner properties
+    def owner_properties
+      @ops ||= create_owner_properties_enumerator
+    end
+
+    # @return [<Symbol>] this class's owner attributes
+    def owner_attributes
+      @oas ||= owner_properties.transform { |op| op.attribute }
+    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 { |da| da.type }
+    end
+
+    # @return [<Class>] this class's owner types
+    def owners
+      @owners ||= Enumerable::Enumerator.new(owner_property_hash, :each_key)
+    end
+
+    # @return [Property, nil] the sole owner attribute metadata of this class, or nil if there
+    #   is not exactly one owner
+    def owner_property
+      props = owner_properties
+      props.first if props.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
+      prop = owner_property || return
+      prop.attribute
+    end
+    
+    # @return [Class, nil] the sole owner type of this class, or nil if there
+    #   is not exactly one owner
+    def owner_type
+      prop = owner_property || return
+      prop.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
+        Jinx.fail(ValidationError, "Owner #{klass.qp} missing dependent attribute for dependent #{qp}")
+      end
+      logger.debug { "Adding #{qp} owner #{klass.qp}#{' attribute ' + attribute.to_s if attribute} with inverse #{inverse}..." }
+      if @owner_prop_hash then
+        Jinx.fail(MetadataError, "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)
+      prop = property(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_property_hash[klass] = prop
+      # If the dependency is unidirectional, then our job is done.
+      if attribute.nil? then
+        logger.debug { "#{qp} owner #{klass.qp} has unidirectional inverse #{inverse}." }
+        return
+      end
+
+      # Bi-directional: add the owner property
+      local_owner_properties << prop
+      # set the inverse if necessary
+      unless prop.inverse then
+        set_attribute_inverse(attribute, inverse)
+      end
+      # set the owner flag if necessary
+      unless prop.owner? then prop.qualify(:owner) end
+
+      # Redefine the writer method to warn when changing the owner.
+      rdr, wtr = prop.accessors
+      redefine_method(wtr) do |old_wtr|
+        lambda do |ref|
+          prev = send(rdr)
+          send(old_wtr, ref)
+          if prev and prev != ref then
+            if ref.nil? then
+              logger.warn("Unset the #{self} owner #{attribute} #{prev}.")
+            elsif ref.key != prev.key then
+              logger.warn("Reset the #{self} owner #{attribute} from #{prev} to #{ref}.")
+            end
+          end
+          ref
+        end
+      end
+      logger.debug { "Injected owner change warning into #{qp}.#{attribute} writer method #{wtr}." }
+      logger.debug { "#{qp} owner #{klass.qp} attribute is #{attribute} with inverse #{inverse}." }
+    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)
+      prop = property(attribute)
+      otype = prop.type
+      hash = local_owner_property_hash
+      if hash.include?(otype) then
+        oa = hash[otype]
+        unless oa.nil? then
+          Jinx.fail(MetadataError, "Cannot set #{qp} owner attribute to #{attribute} since it is already set to #{oa}")
+        end
+        hash[otype] = prop
+      else
+        add_owner(otype, prop.inverse, attribute)
+      end
+    end
+
+    # @return [{Class => Property}] this class's owner type => property hash
+    def owner_property_hash
+      @op_hash ||= create_owner_property_hash
+    end
+    
+    private
+
+    # @param [Class] klass the class to check
+    # @param [Boolean] recursive whether to check whether this class depends on a dependent
+    #   of the other class
+    # @return [Boolean] whether the owner class depends on the other class
+    def depends_on_recursive?(klass, other)
+      klass != self and klass.owners.any? { |owner| owner.depends_on?(other, true) }
+    end
+    
+    # @param [<Symbol>] attributes the order in which the effective owner attribute should be determined
+    def order_owner_attributes(*attributes)
+      @ops = @ops_local = attributes.map { |oa| property(oa) }
+    end
+    
+    def local_owner_property_hash
+      @local_oa_hash ||= {}
+    end
+
+    # @return [{Class => Property}] a new owner type => attribute hash
+    def create_owner_property_hash
+      local = local_owner_property_hash
+      Class === self && superclass < Resource ? local.union(superclass.owner_property_hash) : local
+    end
+    
+    # @return [<Property>] the owner properties defined in this class
+    def local_owner_properties
+      @ops_local ||= []
+    end
+    
+    # @return [<Property>] the owner properties defined in the class hierarchy
+    def create_owner_properties_enumerator
+      local = local_owner_properties
+      Class === self && superclass < Resource ? local.union(superclass.owner_properties) : local
+    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)
+      ia = klass.property(inverse).inverse || detect_inverse_attribute(klass)
+      if ia then
+        logger.debug { "#{qp} reference to owner #{klass.qp} with inverse #{inverse} is #{ia}." }
+      else
+        logger.debug { "#{qp} reference to owner #{klass.qp} with inverse #{inverse} was not detected." }
+      end
+      ia
+    end
+  end
+end