caruby-core 1.4.9 → 1.5.1

data/lib/caruby/domain/resource_dependency.rb

@@ -1,217 +0,0 @@
-require 'caruby/util/validation'
-
-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>] 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)
-      add_attribute(attr, klass)
-      attribute_metadata(attr).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.cascaded? }
-    end
-
-    # @return [Boolean] whether this class depends the given other class
-    def depends_on?(other)
-      owners.detect { |owner| owner === other }
-    end
-
-    # @return [Symbol, nil] 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
-
-    # @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_enumerator.first || return
-      # There is at most one non-nil value in the owner class => AttributeMetadata hash.
-      # If there is such a value, then return the attribute symbol.
-      if owner_attribute_metadata_enumerator.size == 1 then
-        attr_md.to_sym
-      end
-    end
-
-    # @return [<Symbol>] this class's owner attributes
-    def owner_attributes
-      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
-
-    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 => AttributeMetadata}] 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 => AttributeMetadata}] 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 [<AttributeMetadata>] the owner attributes
-    def owner_attribute_metadata_enumerator
-      # Enumerate each owner AttributeMetadata, 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 #{ResourceInverse#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

data/lib/caruby/domain/resource_introspection.rb

@@ -1,160 +0,0 @@
-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
-
-    # Makes a standard attribute for the given property descriptor.
-    # Adds a camelized Java-like alias to the standard attribute.
-    #
-    # caTissue alert - 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 = 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
-      
-      # 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)
-      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

data/lib/caruby/domain/resource_inverse.rb

@@ -1,151 +0,0 @@
-require 'caruby/import/java'
-require 'caruby/domain/java_attribute_metadata'
-
-module CaRuby
-  # ResourceMetadata mix-in to infer and set inverse attributes.
-  module ResourceInverse
-    
-    protected
-    
-    # Infers the inverse of the given attribute declared by this class. A domain attribute is
-    # recognized as an inverse according to the {ResourceInverse#detect_inverse_attribute}
-    # criterion.
-    #
-    # @param [AttributeMetadata] attr_md the attribute to check
-    def infer_attribute_inverse(attr_md)
-      inv = attr_md.type.detect_inverse_attribute(self)
-      if inv then
-        logger.debug { "Detected #{qp} #{attr_md} inverse #{inv.qp}." }
-        set_attribute_inverse(attr_md.to_sym, inv)
-      else
-        logger.debug { "No inverse detected for #{qp} #{attr_md}." }
-      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)
-      attr_md = attribute_metadata(attribute)
-      # return if inverse is already set
-      return if attr_md.inverse == inverse
-      # the default inverse
-      inverse ||= attr_md.type.detect_inverse_attribute(self)
-      # the inverse attribute meta-data
-      inv_md = attr_md.type.attribute_metadata(inverse)
-      # if the attribute is the many side of a 1:M relation, then delegate to the one side.
-      if attr_md.collection? and not inv_md.collection? then
-        return attr_md.type.set_attribute_inverse(inverse, attribute)
-      end
-      # this class must be the same as or a subclass of the inverse attribute type
-      unless self <= inv_md.type then
-        raise TypeError.new("Cannot set #{qp}.#{attribute} inverse to #{attr_md.type.qp}.#{attribute} with incompatible type #{inv_md.type.qp}")
-      end
-
-      # if the attribute is not declared by this class, then make a new attribute
-      # metadata specialized for this class.
-      unless attr_md.declarer == self then
-        attr_md = attr_md.dup
-        attr_md.declarer = self
-        add_attribute_metadata(attribute, inverse)
-        logger.debug { "Copied #{attr_md.declarer}.#{attribute} to #{qp} with restricted inverse return type #{qp}." }
-      end
-      # Set the inverse in the attribute metadata.
-      attr_md.inverse = inverse
-
-      # If attribute is the one side of a 1:M or non-reflexive 1:1 relation, then add the inverse updater.
-      unless attr_md.collection? then
-        add_inverse_updater(attribute, inverse)
-        unless attr_md.type == inv_md.type or inv_md.collection? then
-          attr_md.type.delegate_writer_to_inverse(inverse, attribute)
-        end
-      end
-    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 which return the referencing type
-      candidates = domain_attributes.compose { |attr_md| klass <= attr_md.type }
-      attr = detect_inverse_attribute_from_candidates(klass, candidates)
-      if attr then
-        logger.debug { "#{qp} #{klass.qp} inverse attribute is #{attr}." }
-      else
-        logger.debug { "#{qp} #{klass.qp} inverse attribute was not detected." }
-      end
-      attr
-    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)
-      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.qp}.#{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_inverse method
-        lambda { |dep| set_inverse(dep, old_writer, inv_attr_md.writer) }
-      end
-    end
-
-    private
-
-    # @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 { |attr| attr == tgt }
-    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 #set_attribute_inverse
-    def add_inverse_updater(attribute, inverse)
-      attr_md = attribute_metadata(attribute)
-      # the reader and writer methods
-      rdr, wtr = attr_md.accessors
-      logger.debug { "Injecting inverse #{inverse} updater into #{qp}.#{attribute} writer method #{wtr}..." }
-      # 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 inverse
-      redefine_method(wtr) do |old_wtr|
-        # the attribute reader and (superseded) writer
-        accessors = [rdr, old_wtr]
-        if inv_attr_md.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
-    end
-  end
-end

data/lib/caruby/domain/resource_metadata.rb

@@ -1,155 +0,0 @@
-require 'caruby/util/collection'
-require 'caruby/import/java'
-require 'caruby/domain/java_attribute_metadata'
-require 'caruby/domain/resource_introspection'
-require 'caruby/domain/resource_inverse'
-require 'caruby/domain/resource_dependency'
-require 'caruby/domain/resource_attributes'
-
-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, ResourceInverse, ResourceDependency, ResourceAttributes
-
-    attr_reader :domain_module
-      
-    # JRuby 1.6 alert - if a concrete class implements a constructor, then calling super in an
-    # included module initialize method results in a recursive call back into that initialize. 
-    # The work-around is to redefine each domain class new method to call the initalize_content
-    # method instead. All Resource domain classes or included modules must not override
-    # initialize. They can implement initialize_content instead.
-    def self.extended(klass)
-      klass.class_eval do
-        class << self
-          def new(opts=nil)
-            obj = super()
-            obj.merge_attributes(opts) if opts
-            obj
-          end
-        end
-      end
-    end
-
-    # 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
-      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
-
-    # 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
-        attr_md = attribute_metadata(attribute)
-        # the Java property type
-        jtype = attr_md.property_descriptor.property_type if JavaAttributeMetadata === attr_md
-        # 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)
-      # KLUDGE - if not inited then bail.
-      # TODO - isolate when this occurs.
-      if @attr_md_hash.nil? then
-        q.text(qp)
-        return
-      end
-      
-      # 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
-
-    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