caruby-core 1.5.5 → 2.1.1

data/lib/caruby/resource.rb

@@ -1,828 +1,25 @@
-require 'forwardable'
-require 'caruby/util/inflector'
-require 'caruby/util/log'
-require 'caruby/util/pretty_print'
-require 'caruby/util/validation'
-require 'caruby/util/collection'
-require 'caruby/domain'
-require 'caruby/domain/mixin'
-require 'caruby/domain/merge'
-require 'caruby/json/serializer'
-require 'caruby/domain/reference_visitor'
-require 'caruby/database/persistable'
-require 'caruby/domain/inversible'
-require 'caruby/domain/metadata'
-require 'caruby/domain/mixin'
+require 'jinx/resource'
+require 'jinx/json/serializer'
 require 'caruby/migration/migratable'
+require 'caruby/database/persistable'
 
 module CaRuby
-  # The Domain module is included by Java domain classes.
-  # This module defines essential common domain methods that enable the jRuby-Java API bridge.
-  # Classes which include Domain must implement the +metadata+ Domain::Metadata accessor method.
+  # Augments +Jinx::Resource+ to inject {Propertied} persistence into introspected classes.
+  # A CaRuby application domain module includes +CaRuby::Resource+ and extends +CaRuby::Importer+.
+  #
+  # @example
+  #   # The application domain module.
+  #   module Domain
+  #     # Add persistence to the domain instances.
+  #     include CaRuby::Resource
+  #     # Add introspection to this domain module.
+  #     extend Jinx::Importer
+  #     # Add persistence to the domain classes.
+  #     @metadata_module = CaRuby::Metadata  
+  #   end
   module Resource
-    include Mergeable, Migratable, Persistable, Inversible, JSON::Serializer
-    
-    # @quirk JRuby Bug #5090 - JRuby 1.5 object_id is no longer a reserved method, and results
-    #   in a String value rather than an Integer (cf. http://jira.codehaus.org/browse/JRUBY-5090).
-    #   Work-around is to make a proxy object id.
-    #
-    # @return [Integer] the object id
-    def proxy_object_id
-      # make a hash code on demand
-      @_hc ||= (Object.new.object_id * 31) + 17
-    end
-    
-    # Prints this object's class demodulized name and object id.
-    def print_class_and_id
-      "#{self.class.qp}@#{proxy_object_id}"
-    end
-
-    alias :qp :print_class_and_id
-
-    # Sets the default attribute values for this domain object and its dependents. If this Resource
-    # does not have an identifier, then missing attributes are set to the values defined by
-    # {Domain::Attributes#add_attribute_defaults}.
-    #
-    # Subclasses should override the private {#add_defaults_local} method rather than this method.
-    #
-    # @return [Resource] self
-    def add_defaults
-      # If there is an owner, then delegate to the owner.
-      # Otherwise, add defaults to this object.
-      par = owner
-      if par and par.identifier.nil? then
-        par.add_defaults
-      else
-        logger.debug { "Adding defaults to #{qp} and its dependents..." }
-        # apply the local and dependent defaults
-        add_defaults_recursive
-      end
-      self
-    end
-    
-    # Sets the default attribute values for this auto-generated domain object.
-    def add_defaults_autogenerated
-      add_defaults_recursive
-    end
-
-    # Validates this domain object and its #{Domain::Attributes#unproxied_savable_template_attributes}
-    # for completeness prior to a database create operation.
-    # An object without an identifer is valid if it contains a non-nil value for each mandatory property.
-    # Objects which have an identifier or have already been validated are skipped.
-    #
-    # Subclasses should not override this method, but override the private {#validate_local} instead.
-    #
-    # @return [Resource] this domain object
-    # @raise (see #validate_local)
-    def validate
-      if identifier.nil? and not @validated then
-        validate_local
-        @validated = true
-      end
-      self.class.unproxied_savable_template_attributes.each do |attr|
-        send(attr).enumerate { |dep| dep.validate }
-      end
-      self
-    end
-    
-    # Adds the default values to this object, if it is not already fetched, and its dependents.
-    #
-    # This method is intended for use only by the {#add_defaults} method.
-    def add_defaults_recursive
-      # Add the local defaults.
-      # The lazy loader is enabled in order to allow subclass add_defaults_local implementations
-      # to pick up load-on-demand references used to set defaults. 
-      database.lazy_loader.enable { add_defaults_local }
-      # add dependent defaults
-      each_defaults_dependent { |dep| dep.add_defaults_recursive }
-    end
-    
-    # @return [Boolean] whether this domain object has {#searchable_attributes}
-    def searchable?
-      not searchable_attributes.nil?
-    end
-
-    # Returns the attributes to use for a search using this domain object as a template, determined
-    # as follows:
-    # * If this domain object has a non-nil primary key, then the primary key is the search criterion.
-    # * Otherwise, if this domain object has a secondary key and each key attribute value is not nil,
-    #   then the secondary key is the search criterion.
-    # * Otherwise, if this domain object has an alternate key and each key attribute value is not nil,
-    #   then the aklternate key is the search criterion.
-    #
-    # @return [<Symbol>] the attributes to use for a search on this domain object
-    def searchable_attributes
-      key_attrs = self.class.primary_key_attributes
-      return key_attrs if key_searchable?(key_attrs)
-      key_attrs = self.class.secondary_key_attributes
-      return key_attrs if key_searchable?(key_attrs)
-      key_attrs = self.class.alternate_key_attributes
-      return key_attrs if key_searchable?(key_attrs)
-    end
-
-    # Returns a new domain object with the given attributes copied from this domain object.
-    # The attributes argument consists of either attribute Symbols or a single Enumerable
-    # consisting of Symbols.
-    # The default attributes are the {Domain::Attributes#nondomain_attributes}.
-    #
-    # @param [<Symbol>, (<Symbol>)] attributes the attributes to copy
-    # @return [Resource] a copy of this domain object
-    def copy(*attributes)
-      if attributes.empty? then
-        attributes = self.class.nondomain_attributes
-      elsif Enumerable === attributes.first then
-        raise ArgumentError.new("#{qp} copy attributes argument is not a Symbol: #{attributes.first}") unless attributes.size == 1
-        attributes = attributes.first
-      end
-      self.class.new.merge_attributes(self, attributes)
-    end
-
-    # Clears the given attribute value. If the current value responds to the +clear+ method,
-    # then the current value is cleared. Otherwise, the value is set to {Domain::Metadata#empty_value}.
-    #
-    # @param [Symbol] attribute the attribute to clear
-    def clear_attribute(attribute)
-      # the current value to clear
-      current = send(attribute)
-      return if current.nil?
-      # call the current value clear if possible.
-      # otherwise, set the attribute to the empty value.
-      if current.respond_to?(:clear) then
-        current.clear
-      else
-        writer = self.class.attribute_metadata(attribute).writer
-        value = self.class.empty_value(attribute)
-        send(writer, value)
-      end
-    end
-
-    # Sets this domain object's attribute to the value. This method clears the current attribute value,
-    # if any, and merges the new value. Merge rather than assignment ensures that a collection type
-    # is preserved, e.g. an Array value is assigned to a set domain type by first clearing the set
-    # and then merging the array content into the set.
-    #
-    # @see Mergeable#merge_attribute
-    def set_attribute(attribute, value)
-      # bail out if the value argument is the current value
-      return value if value.equal?(send(attribute))
-      clear_attribute(attribute)
-      merge_attribute(attribute, value)
-    end
-
-    # Returns the secondary key attribute values as follows:
-    # * If there is no secondary key, then this method returns nil.
-    # * Otherwise, if the secondary key attributes is a singleton Array, then the key is the
-    #   value of the sole key attribute.
-    # * Otherwise, the key is an Array of the key attribute values.
-    #
-    # @return [Array, Object] the key attribute values
-    def key
-      attrs = self.class.secondary_key_attributes
-      case attrs.size
-        when 0 then nil
-        when 1 then send(attrs.first)
-        else attrs.map { |attr| send(attr) }
-      end
-    end
-
-    # @return [Resource, nil] the domain object that owns this object, or nil if this object
-    #   is not dependent on an owner
-    def owner
-      self.class.owner_attributes.detect_value { |attr| send(attr) }
-    end
-
-    # @return [Symbol, nil] the attribute for which there is an owner reference,
-    #  or nil if this domain object does not reference an owner
-    def effective_owner_attribute
-      self.class.owner_attributes.detect { |attr| send(attr) }
-    end
-    
-    # Sets this dependent's owner attribute to the given domain object.
-    #
-    # @param [Resource] owner the owner domain object
-    # @raise [NoMethodError] if this Resource's class does not have exactly one owner attribute
-    def owner=(owner)
-      attr = self.class.owner_attribute
-      if attr.nil? then raise NoMethodError.new("#{self.class.qp} does not have a unique owner attribute") end
-      set_attribute(attr, owner)
-    end
-
-    # @param [Resource] other the domain object to check
-    # @return [Boolean] whether the other domain object is this object's {#owner} or an
-    #  {#owner_ancestor?} of this object's {#owner}
-    def owner_ancestor?(other)
-      owner = self.owner
-      owner and (owner == other or owner.owner_ancestor?(other))
-    end
-
-    # Returns an attribute => value hash for the specified attributes with a non-nil, non-empty value.
-    # The default attributes are this domain object's class {Domain::Attributes#attributes}.
-    # Only non-nil attributes defined by this Resource are included in the result hash.
-    #
-    # @param [<Symbol>, nil] attributes the attributes to merge
-    # @return [{Symbol => Object}] the attribute => value hash
-    def value_hash(attributes=nil)
-      attributes ||= self.class.attributes
-      attributes.to_compact_hash { |attr| send(attr) if self.class.method_defined?(attr) }
-    end
-
-    # Returns the domain object references for the given attributes.
-    #
-    # @param [<Symbol>, nil] the domain attributes to include, or nil to include all domain attributes
-    # @return [<Resource>] the referenced attribute domain object values
-    def references(attributes=nil)
-      attributes ||= self.class.domain_attributes
-      attributes.map { |attr| send(attr) }.flatten.compact
-    end
-
-    # @return [Boolean] whether this domain object is dependent on another entity
-    def dependent?
-      self.class.dependent?
-    end
-
-    # @return [Boolean] whether this domain object is not dependent on another entity
-    def independent?
-      not dependent?
-    end
-
-    # Enumerates over this domain object's dependents.
-    #
-    # @yield [dep] the block to execute on the dependent
-    # @yieldparam [Resource] dep the dependent
-    def each_dependent
-      self.class.dependent_attributes.each do |attr|
-       send(attr).enumerate { |dep| yield dep }
-      end
-    end
-    
-    # @return [Enumerable] this domain object's dependents
-    def dependents
-      enum_for(:each_dependent)
-    end
-    
-    # Returns the attributes which are required for save. This base implementation returns the
-    # class {Domain::Attributes#mandatory_attributes}. Subclasses can override this method
-    # for domain object state-specific refinements.
-    #
-    # @return [<Symbol>] the required attributes for a save operation
-    def mandatory_attributes
-      self.class.mandatory_attributes
-    end
-
-    # Returns the attribute references which directly depend on this owner.
-    # The default is the attribute value.
-    #
-    # Returns an Enumerable. If the value is not already an Enumerable, then this method
-    # returns an empty array if value is nil, or a singelton array with value otherwise.
-    #
-    # If there is more than one owner of a dependent, then subclasses should override this
-    # method to select dependents whose dependency path is shorter than an alternative
-    # dependency path, e.g. in caTissue a Specimen is owned by both a SCG and a parent
-    # Specimen. In that case, the SCG direct dependents consist of top-level Specimens
-    # owned by the SCG but not derived from another Specimen.
-    #
-    # @param [Symbol] attribute the dependent attribute
-    # @return [<Resource>] the attribute value, wrapped in an array if necessary
-    def direct_dependents(attribute)
-      deps = send(attribute)
-      case deps
-        when Enumerable then deps
-        when nil then Array::EMPTY_ARRAY
-        else [deps]
-      end
-    end
-
-    # @param [Resource] the domain object to match
-    # @return [Boolean] whether this object matches the fetched other object on class
-    #   and key values
-    def match?(other)
-      match_in([other])
-    end
-
-    # Matches this dependent domain object with the others on type and key attributes
-    # in the scope of a parent object.
-    # Returns the object in others which matches this domain object, or nil if none.
-    #
-    # The match attributes are, in order:
-    # * the primary key
-    # * the secondary key
-    # * the alternate key
-    #
-    # This domain object is matched against the others on the above attributes in succession
-    # until a unique match is found. The key attribute matches are strict, i.e. each
-    # key attribute value must be non-nil and match the other value.
-    #
-    # @param [<Resource>] the candidate domain object matches
-    # @return [Resource, nil] the matching domain object, or nil if no match
-    def match_in(others)
-      # trivial case: self is in others
-      return self if others.include?(self)
-      # filter for the same type
-      others = others.filter { |other| self.class === other }
-      # match on primary, secondary or alternate key
-      match_unique_object_with_attributes(others, self.class.primary_key_attributes) or
-      match_unique_object_with_attributes(others, self.class.secondary_key_attributes) or
-      match_unique_object_with_attributes(others, self.class.alternate_key_attributes)
-    end
-
-    # Returns the match of this domain object in the scope of a matching owner as follows:
-    # * If {#match_in} returns a match, then that match is the result is used.
-    # * Otherwise, if this is a dependent attribute then the match is attempted on a
-    #   secondary key without owner attributes. Defaults are added to this object in order
-    #   to pick up potential secondary key values.
-    #
-    # @param (see #match_in)
-    # @return (see #match_in)
-    def match_in_owner_scope(others)
-      match_in(others) or others.detect { |other| match_without_owner_attribute?(other) }
-    end
-
-    # @return [{Resouce => Resource}] a source => target hash of the given sources which match
-    #   the targets using the {#match_in} method
-    def self.match_all(sources, targets)
-      DEF_MATCHER.match(sources, targets)
-    end
-
-    # Returns the difference between this Persistable and the other Persistable for the
-    # given attributes. The default attributes are the {Domain::Attributes#nondomain_attributes}.
-    #
-    # @param [Resource] other the domain object to compare
-    # @param [<Symbol>, nil] attributes the attributes to compare
-    # @return (see Hashable#diff)
-    def diff(other, attributes=nil)
-      attributes ||= self.class.nondomain_attributes
-      vh = value_hash(attributes)
-      ovh = other.value_hash(attributes)
-      vh.diff(ovh) { |key, v1, v2| Resource.value_equal?(v1, v2) }
-    end
-
-    # Returns the domain object in others which matches this dependent domain object
-    # within the scope of a parent on a minimally acceptable constraint. This method
-    # is used when this object might be partially complete--say, lacking a secondary key
-    # value--but is expected to match one of the others, e.g. when matching a referenced
-    # object to its fetched counterpart.
-    #
-    # This base implementation returns whether the following conditions hold:
-    # 1. other is the same class as this domain object
-    # 2. if both identifiers are non-nil, then they are equal
-    #
-    # Subclasses can override this method to impose additional minimal consistency constraints.
-    #
-    # @param [Resource] other the domain object to match against
-    # @return [Boolean] whether this Resource equals other
-    def minimal_match?(other)
-      self.class === other and
-        (identifier.nil? or other.identifier.nil? or identifier == other.identifier)
-    end
-
-    # Returns an enumerator on the transitive closure of the reference attributes.
-    # If a block is given to this method, then the block called on each reference determines
-    # which attributes to visit. Otherwise, all saved references are visited.
-    #
-    # @yield [ref] reference visit attribute selector
-    # @yieldparam [Resource] ref the domain object to visit
-    # @return [Enumerable] the reference transitive closure
-    def reference_hierarchy
-      ReferenceVisitor.new { |ref| yield ref }.to_enum(self)
-    end
-
-    # Returns the value for the given attribute path Array or String expression, e.g.:
-    #   study.path_value("site.address.state")
-    # follows the +study+ -> +site+ -> +address+ -> +state+ accessors and returns the +state+
-    # value, or nil if any intermediate reference is nil.
-    # The array form for the above example is:
-    #  study.path_value([:site, :address, :state])
-    #
-    # @param [<Symbol>] path the attributes to navigate
-    # @return the attribute navigation result
-    def path_value(path)
-      path = path.split('.').map { |attr| attr.to_sym } if String === path
-      path.inject(self) do |parent, attr|
-        value = parent.send(attr)
-        return if value.nil?
-        value
-      end
-    end
-
-    # Applies the operator block to this object and each domain object in the reference path.
-    # This method visits the transitive closure of each recursive path attribute.
-    #
-    # For example, given the attributes:
-    #   treatment: BioMaterial -> Treatment
-    #   measurement: Treatment -> BioMaterial
-    # and +BioMaterial+ instance +biospecimen+, then:
-    #   biospecimen.visit_path[:treatment, :measurement, :biomaterial]
-    # visits +biospecimen+ and all biomaterial, treatments and measurements derived
-    # directly or indirectly from +biospecimen+.
-    #
-    # @param [<Symbol>] path the attributes to visit
-    # @yieldparam [Symbol] attribute the attribute to visit
-    # @return the visit result
-    def visit_path(path, &operator)
-      visitor = ReferencePathVisitorFactory.create(self.class, path)
-      visitor.visit(self, &operator)
-    end
-
-    # Applies the operator block to the transitive closure of this domain object's dependency relation.
-    # The block argument is a dependent.
-    #
-    # @yield [dep] operation on the visited domain object
-    # @yieldparam [Resource] dep the domain object to visit 
-    def visit_dependents(&operator) # :yields: dependent
-      DEPENDENT_VISITOR.visit(self, &operator)
-    end
-
-    # Applies the operator block to the transitive closure of this domain object's owner relation.
-    #
-    # @yield [dep] operation on the visited domain object
-    # @yieldparam [Resource] dep the domain object to visit 
-    def visit_owners(&operator) # :yields: owner
-      ref = owner
-      yield(ref) and ref.visit_owners(&operator) if ref
-    end
-
-    # @param q the PrettyPrint queue 
-    # @return [String] the formatted content of this Resource
-    def pretty_print(q)
-      q.text(qp)
-      content = printable_content
-      q.pp_hash(content) unless content.empty?
-    end
-
-    # Prints this domain object's content and recursively prints the referenced content.
-    # The optional selector block determines the attributes to print. The default is the
-    # {Domain::Attributes#java_attributes}. The database lazy loader is disabled during
-    # the execution of this method. Thus, the printed content reflects the transient
-    # in-memory object graph rather than the persistent content.
-    #
-    # @yield [owner] the owner attribute selector
-    # @yieldparam [Resource] owner the domain object to print
-    # @return [String] the domain object content
-    def dump(&selector)
-      do_without_lazy_loader { DetailPrinter.new(self, &selector).pp_s }
-    end
-
-    # Prints this domain object in the format:
-    #   class_name@object_id{attribute => value ...}
-    # The default attributes include identifying attributes.
-    #
-    # @param [<Symbol>] attributes the attributes to print
-    # @return [String] the formatted content
-    def to_s(attributes=nil)
-      content = printable_content(attributes)
-      content_s = content.pp_s(:single_line) unless content.empty?
-      "#{print_class_and_id}#{content_s}"
-    end
-
-    alias :inspect :to_s
-
-    # Returns this domain object's attributes content as an attribute => value hash
-    # suitable for printing.
-    #
-    # The default attributes are this object's saved attributes. The optional
-    # reference_printer is used to print a referenced domain object.
-    #
-    # @param [<Symbol>, nil] attributes the attributes to print
-    # @yield [ref] the reference print formatter 
-    # @yieldparam [Rresource] ref the referenced domain object to print
-    # @return [{Symbol => String}] the attribute => content hash
-    def printable_content(attributes=nil, &reference_printer) # :yields: reference
-      attributes ||= printworthy_attributes
-      vh = value_hash(attributes)
-      vh.transform { |value| printable_value(value, &reference_printer) }
-    end
-
-    # Returns whether value equals other modulo the given matches according to the following tests:
-    # * _value_ == _other_
-    # * _value_ and _other_ are Resource instances and _value_ is a {#match?} with _other_.
-    # * _value_ and _other_ are Enumerable with members equal according to the above conditions.
-    # * _value_ and _other_ are DateTime instances and are equal to within one second.
-    #
-    # The DateTime comparison accounts for differences in the Ruby -> Java -> Ruby roundtrip
-    # of a date attribute, which loses the seconds fraction.
-    #
-    # @return whether value and other are equal according to the above tests
-    def self.value_equal?(value, other, matches=nil)
-      if value == other then
-        true
-      elsif value.collection? and other.collection? then
-        collection_value_equal?(value, other, matches)
-      elsif DateTime === value and DateTime === other then
-        (value - other).abs.floor.zero?
-      elsif Resource === value and value.class === other then
-        value.match?(other)
-      elsif matches then
-        matches[value] == other
-      else
-        false
-      end
-    end
-    
-    protected
-
-    # Returns the required attributes for this domain object which are nil or empty.
-    #
-    # This method is in protected scope to allow the +CaTissue+ domain module to
-    # work around a caTissue bug (see that module for details). Other definitions
-    # of this method are discouraged.
-    def missing_mandatory_attributes
-      mandatory_attributes.select { |attr| send(attr).nil_or_empty? }
-    end
-
-    private
-
-    # The copy merge call options.
-    COPY_MERGE_OPTS = {:inverse => false}
-
-    # The dependent attribute visitor.
-    #
-    # @see #visit_dependents
-    DEPENDENT_VISITOR = CaRuby::ReferenceVisitor.new { |obj| obj.class.dependent_attributes }
-
-    # Matches the given targets to sources using {Resource#match_in}.
-    class Matcher
-      def match(sources, targets)
-        unmatched = Set === sources ? sources.dup : sources.to_set
-        matches = {}
-        targets.each do |tgt|
-          src = tgt.match_in(unmatched)
-          if src then
-            unmatched.delete(src)
-            matches[src] = tgt
-          end
-        end
-        matches
-      end
-    end
-
-    DEF_MATCHER = Matcher.new
-
-    # Sets the default attribute values for this domain object. Unlike {#add_defaults}, this
-    # method does not set defaults for dependents. This method sets the configuration values
-    # for this domain object as described in {#add_defaults}, but does not set defaults for
-    # dependents.
-    #
-    # This method is the integration point for subclasses to augment defaults with programmatic logic.
-    # If a subclass overrides this method, then it should call super before setting the local
-    # default attributes. This ensures that configuration defaults takes precedence.
-    def add_defaults_local
-      logger.debug { "Adding defaults to #{qp}..." }
-      merge_attributes(self.class.defaults)
-    end
-    
-    # Validates that this domain contains a non-nil value for each mandatory property.
-    #
-    # Subclasses can override this method for additional validation, but should call super first.
-    #
-    # @raise [ValidationError] if a mandatory attribute value is missing
-    def validate_local
-      logger.debug { "Validating #{qp} required attributes #{self.mandatory_attributes.to_a.to_series}..." }
-      invalid = missing_mandatory_attributes
-      unless invalid.empty? then
-        logger.error("Validation of #{qp} unsuccessful - missing #{invalid.join(', ')}:\n#{dump}")
-        raise ValidationError.new("Required attribute value missing for #{self}: #{invalid.join(', ')}")
-      end
-      if self.class.bidirectional_dependent? and not owner then
-        raise ValidationError.new("Dependent #{self} does not reference an owner")
-      end
-    end
-    
-    # Enumerates the dependents for setting defaults. Subclasses can override if the
-    # dependents must be visited in a certain order.
-    alias :each_defaults_dependent :each_dependent
-
-    # @return [Boolean] whether the given key attributes is non-empty and each attribute in the key has a non-nil value
-    def key_searchable?(attributes)
-      not (attributes.empty? or attributes.any? { |attr| send(attr).nil? })
-    end
-
-    def self.collection_value_equal?(value, other, matches=nil)
-      value.size == other.size and value.all? { |v| other.include?(v) or (matches and other.include?(matches[v])) }
-    end
-
-    # A DetailPrinter formats a domain object value for printing using {#to_s} the first time the object
-    # is encountered and a ReferencePrinter on the object subsequently.
-    class DetailPrinter
-      alias :to_s :pp_s
-
-      alias :inspect :to_s
-
-      # Creates a DetailPrinter on the base object.
-      def initialize(base, visited=Set.new, &selector)
-        @base = base
-        @visited = visited << base
-        @selector = selector || Proc.new { |ref| ref.class.printable_attributes }
-      end
-
-      def pretty_print(q)
-        q.text(@base.qp)
-        # pretty-print the standard attribute values
-        attrs = @selector.call(@base)
-        content = @base.printable_content(attrs) do |ref|
-          @visited.include?(ref) ? ReferencePrinter.new(ref) : DetailPrinter.new(ref, @visited) { |ref| @selector.call(ref) }
-        end
-        q.pp_hash(content)
-      end
-    end
-
-    # A ReferencePrinter formats a reference domain object value for printing with just the class and Ruby object_id.
-    class ReferencePrinter
-      extend Forwardable
-
-      def_delegator(:@base, :qp, :to_s)
-
-      alias :inspect :to_s
-
-      # Creates a ReferencePrinter on the base object.
-      def initialize(base)
-        @base = base
-      end
-    end
-
-    # Returns a value suitable for printing. If value is a domain object, then the block provided to this method is called.
-    # The default block creates a new ReferencePrinter on the value.
-    def printable_value(value, &reference_printer)
-      Collector.on(value) do |item|
-        if Resource === item then
-          block_given? ? yield(item) : printable_value(item) { |ref| ReferencePrinter.new(ref) }
-        else
-          item
-        end
-      end
-    end
-
-    # Returns an attribute => value hash for the +identifier+ attribute, if there is a non_nil +identifier+,
-    # If +identifier+ is nil, then this method returns the secondary key attributes, if they exist,
-    # or the mergeable attributes otherwise. If this is a dependent object, then the owner attribute is
-    # removed from the returned array.
-    def printworthy_attributes
-      return self.class.primary_key_attributes if identifier
-      attrs = self.class.secondary_key_attributes
-      attrs = self.class.nondomain_java_attributes if attrs.empty?
-      attrs = self.class.fetched_attributes if attrs.empty?
-      attrs
-    end
-
-    # Substitutes attribute with the standard attribute and a Java non-Domain instance value with a Domain object if necessary.
-    #
-    # Returns the [standard attribute, standard value] array.
-    def standardize_attribute_value(attribute, value)
-      attr_md = self.class.attribute_metadata(attribute)
-      if attr_md.nil? then
-        raise ArgumentError.new("#{attribute} is neither a #{self.class.qp} standard attribute nor an alias for a standard attribute")
-      end
-      # standardize the value if necessary
-      std_val = attr_md.type && attr_md.type < Resource ? standardize_domain_value(value) : value
-      [attr_md.to_sym, std_val]
-    end
-
-    # Returns a Domain object for a Java non-Domain instance value.
-    def standardize_domain_value(value)
-      if value.nil? or Resource === value then
-         value
-      elsif Enumerable === value then
-        # value is a collection; if value is a nested collection (highly unlikely), then recursively standarize
-        # the value collection members. otherwise, leave the value alone.
-        value.empty? || Resource === value.first ? value : value.map { |item| standardize_domain_value(item) }
-      else
-        # return a new Domain object built from the source Java domain object
-        # (unlikely unless value is a weird toxic Hibernate proxy)
-        logger.debug { "Creating standard domain object from #{value}..." }
-        Domain.const_get(value.class.qp).new.merge_attributes(value)
-      end
-    end
-
-    # Returns whether the other domain object matches this domain object on a secondary
-    # key without owner attributes. Defaults are added to this object in order to pick up
-    # potential secondary key values.
-    # 
-    # @param (see #match_in)
-    # @return [Boolean] whether the other domain object matches this domain object on a
-    #   secondary key without owner attributes
-    def match_without_owner_attribute?(other)
-      return unless other.class == self.class
-      oattrs = self.class.owner_attributes
-      return if oattrs.empty?
-      # match on the secondary key
-      self.class.secondary_key_attributes.all? do |attr|
-        oattrs.include?(attr) or matches_attribute_value?(other, attr, send(attr))
-      end
-    end
-
-    # @param [Attribute] attr_md the attribute to set
-    # @param [Resource] ref the inverse value
-    # @param [Symbol] the inverse => self writer method
-    def delegate_to_inverse_setter(attr_md, ref, writer)
-      logger.debug { "Setting #{qp} #{attr_md} by setting the #{ref.qp} inverse attribute #{attr_md.inverse}..." }
-      ref.send(writer, self)
-    end
-
-    # Returns 0 if attribute is a Java primitive number,
-    # +false+ if attribute is a Java primitive boolean,
-    # an empty collectin if the Java property is a collection,
-    # nil otherwise.
-    def empty_value(attribute)
-      type = java_type(attribute) || return
-      if type.primitive? then
-        type.name == 'boolean' ? false : 0
-      else
-        self.class.empty_value(attribute)
-      end
-    end
-
-    # Returns the Java type of the given attribute, or nil if attribute is not a Java property attribute.
-    def java_type(attribute)
-      attr_md = self.class.attribute_metadata(attribute)
-      attr_md.property_descriptor.property_type if JavaAttribute === attr_md
-    end
-    
-    # Executes the given block with the database lazy loader disabled, if any.
-    #
-    # @yield the block to execute
-    def do_without_lazy_loader(&block)
-      if database then
-        database.lazy_loader.disable(&block)
-      else
-        yield
-      end
-    end
-    
-    # Returns the source => target hash of matches for the given attr_md newval sources and
-    # oldval targets. If the matcher block is given, then that block is called on the sources
-    # and targets. Otherwise, {Resource.match_all} is called.
-    #
-    # @param [Attribute] attr_md the attribute to match
-    # @param newval the source value
-    # @param oldval the target value
-    # @yield [sources, targets] matches sources to targets
-    # @yieldparam [<Resource>] sources an Enumerable on the source value
-    # @yieldparam [<Resource>] targets an Enumerable on the target value
-    # @return [{Resource => Resource}] the source => target matches
-    def match_attribute_value(attr_md, newval, oldval)
-      # make Enumerable targets and sources for matching
-      sources = newval.to_enum
-      targets = oldval.to_enum
-      
-      # match sources to targets
-      logger.debug { "Matching source #{newval.qp} to target #{qp} #{attr_md} #{oldval.qp}..." } unless oldval.nil_or_empty?
-      matches = block_given? ? yield(sources, targets) : Resource.match_all(sources, targets)
-      logger.debug { "Matched #{qp} #{attr_md}: #{matches.qp}." } unless matches.empty?
-      matches
-    end
-    
-    # Returns the object in others which uniquely matches this domain object on the given attributes,
-    # or nil if there is no unique match. This method returns nil if any attributes value is nil.
-    def match_unique_object_with_attributes(others, attributes)
-      vh = value_hash(attributes)
-      return if vh.empty? or vh.size < attributes.size
-      matches = match_attribute_values(others, vh)
-      matches.first if matches.size == 1
-    end
-
-    # Returns the domain objects in others whose class is the same as this object's class
-    # and whose attribute values equal those in the given attr_value_hash.
-    def match_attribute_values(others, attr_value_hash)
-      others.select do |other|
-        self.class === other and attr_value_hash.all? do |attr, value|
-          matches_attribute_value?(other, attr, value)
-        end
-      end
-    end
-
-    # Returns whether this Resource's attribute value matches the fetched other attribute.
-    # A domain attribute match is determined by {#match?}.
-    # A non-domain attribute match is determined by an equality comparison.
-    def matches_attribute_value?(other, attribute, value)
-      other_val = other.send(attribute)
-      if Resource === value then
-        value.match?(other_val)
-      else
-        value == other_val
-      end
-    end
-
-    # Returns the attribute => value hash to use for matching this domain object as follows:
-    # * If this domain object has a database identifier, then the identifier is the sole match criterion attribute.
-    # * Otherwise, if a secondary key is defined for the object's class, then those attributes are used.
-    # * Otherwise, all attributes are used.
-    #
-    # If any secondary key value is nil, then this method returns an empty hash, since the search is ambiguous.
-    def search_attribute_values
-      # if this object has a database identifier, then the identifier is the search criterion
-      identifier.nil? ? non_id_search_attribute_values : { :identifier => identifier }
-    end
-
-    # Returns the attribute => value hash to use for matching this domain object.
-    # @see #search_attribute_values the method specification
-    def non_id_search_attribute_values
-      # if there is a secondary key, then search on those attributes.
-      # otherwise, search on all attributes.
-      key_attrs = self.class.secondary_key_attributes
-      attrs = key_attrs.empty? ? self.class.nondomain_java_attributes : key_attrs
-      # associate the values
-      attr_values = attrs.to_compact_hash { |attr| send(attr) }
-      # if there is no secondary key, then cull empty values
-      key_attrs.empty? ? attr_values.delete_if { |attr, value| value.nil? } : attr_values
-    end
+    include CaRuby::Migratable, CaRuby::Persistable, Jinx::JSON::Serializer, Jinx::Resource
   end
-end
+end
+
+