caruby-core 1.5.5 → 2.1.1

data/lib/caruby/database/persistence_service.rb

@@ -1,18 +1,10 @@
-require 'caruby/util/version'
-require 'caruby/database'
-require 'caruby/util/stopwatch'
+require 'jinx/helpers/stopwatch'
+require 'caruby/helpers/version'
+require 'caruby/database/application_service'
 
 module CaRuby
-  # HQLCriteria is required for the query_hql method.
-  java_import Java::gov.nih.nci.common.util.HQLCriteria
-  
-  # The encapsulated caBIG service class.
-  java_import Java::gov.nih.nci.system.applicationservice.ApplicationServiceProvider
-  
-  # This import is not strictly necessary, but works around Ticket #5.
-  java_import Java::gov.nih.nci.system.comm.client.ApplicationServiceClientImpl
-  
-  # A PersistenceService wraps a caCORE application service.
+  # A PersistenceService is a database mediator which implements the {#query} {#create}, {#update}
+  # and {#delete} methods.
   class PersistenceService
     # The service name.
     attr_reader :name
@@ -27,13 +19,14 @@ module CaRuby
     # @option opts [String] :host the service host (default +localhost+)
     # @option opts [String] :version the caTissue version identifier
     def initialize(name, opts={})
+      CaRuby::PersistenceService.import_java_classes
       @name = name
       ver_opt = opts[:version]
       @version = ver_opt.to_s.to_version if ver_opt
       @host = opts[:host] || default_host
       @port = opts[:port] || 8080
       @url = "http://#{@host}:#{@port}/#{@name}/http/remoteService"
-      @timer = Stopwatch.new
+      @timer = Jinx::Stopwatch.new
       logger.debug { "Created persistence service #{name} at #{@host}:#{@port}." }
     end
 
@@ -63,7 +56,7 @@ module CaRuby
         dispatch { |svc| svc.create_object(obj) }
       rescue Exception => e
         logger.error("Error creating #{obj} - #{e.message}\n#{dump(obj)}")
-        raise
+        raise e
       end
     end
 
@@ -73,8 +66,8 @@ module CaRuby
       begin
         dispatch { |svc| svc.update_object(obj) }
       rescue Exception => e
-        logger.error("Error updating #{obj} -  #{e.message}\n#{dump(obj)}")
-        raise
+        logger.error("Error updating #{obj} - #{e.message}\n#{dump(obj)}")
+        raise e
       end
    end
 
@@ -84,21 +77,16 @@ module CaRuby
       begin
         dispatch { |svc| svc.remove_object(obj) }
       rescue Exception => e
-        logger.error("Error deleting #{obj}  - #{e.message}\n#{dump(obj)}")
-        raise
+        logger.error("Error deleting #{obj} - #{e.message}\n#{dump(obj)}")
+        raise e
       end
     end
 
-    # Returns a freshly initialized ApplicationServiceProvider remote instance.
+    # Returns the {ApplicationService} remote instance.
     #
-    # @quirk caCORE When more than one application service is used, each call to the service
-    #   must reinitialize the remote instance. E.g. this is done in the caTissue DE examples,
-    #  and is a good general practice.
-    #
-    # @return [ApplicationServiceProvider] the CaCORE service provider wrapped by this PersistenceService
+    # @return the CaCORE service provider wrapped by this PersistenceService
     def app_service
-      logger.debug { "Connecting to service provider at #{@url}..." }
-      ApplicationServiceProvider.remote_instance(@url)
+      ApplicationService.for(@url)
     end
 
     private
@@ -144,13 +132,13 @@ module CaRuby
       logger.debug { "Building HQLCriteria..." }
       criteria = HQLCriteria.new(hql)
       target = hql[/from\s+(\S+)/i, 1]
-      raise DatabaseError.new("HQL does not contain a FROM clause: #{hql}") unless target
+      Jinx.fail(DatabaseError, "HQL does not contain a FROM clause: #{hql}") unless target
       logger.debug { "Submitting search on target class #{target} with the following HQL:\n  #{hql}" }
       begin
         dispatch { |svc| svc.query(criteria, target) }
       rescue Exception => e
         logger.error("Error querying on HQL - #{$!}:\n#{hql}")
-        raise
+        raise e
       end
     end
 
@@ -161,9 +149,9 @@ module CaRuby
       logger.debug { "Searching using template #{template.qp}#{', path ' + path.join('.') unless path.empty?}..." }
       # collect the class search path from the reference attribute domain type Java class names
       class_name_path = []
-      path.inject(template.class) do |type, attr|
-        ref_type = type.domain_type(attr)
-        raise DatabaseError.new("Attribute in search attribute path #{path.join('.')} is not a #{type} domain reference attribute: #{attr}") if ref_type.nil?
+      path.inject(template.class) do |type, pa|
+        ref_type = type.domain_type(pa)
+        Jinx.fail(DatabaseError, "Property in search attribute path #{path.join('.')} is not a #{type} domain reference attribute: #{pa}") if ref_type.nil?
         class_name_path << ref_type.java_class.name
         ref_type
       end
@@ -175,7 +163,7 @@ module CaRuby
         dispatch { |svc| svc.search(reverse_class_name_path.join(','), template) }
       rescue Exception => e
         logger.error("Error searching on template #{template}#{', path ' + path.join('.') unless path.empty?} - #{$!}\n#{dump(template)}")
-        raise
+        raise e
       end
     end
 
@@ -198,7 +186,17 @@ module CaRuby
     end
 
     def dump(obj)
-      Resource === obj ? obj.dump : obj.to_s
+      Jinx::Resource === obj ? obj.dump : obj.to_s
     end
+    
+    private
+    
+    # Imports this class's Java classes on demand.
+    def self.import_java_classes
+      return if const_defined?(:HQLCriteria)
+      # HQLCriteria is required for the query_hql method.
+      java_import Java::gov.nih.nci.common.util.HQLCriteria
+    end
+
   end
 end

data/lib/caruby/database/persistifier.rb

@@ -1,3 +1,4 @@
+require 'jinx/resource/reference_visitor'
 require 'caruby/database/persistable'
 require 'caruby/database/lazy_loader'
 
@@ -6,42 +7,53 @@ module CaRuby
     # @return [LazyLoader] this database's lazy loader
     attr_reader :lazy_loader
     
-    # Database Persistable mediator.
+    # Database {Persistable} mediator.
+    # A module which includes {Persistifier} must implement the {Reader#fetch_association} method.
     module Persistifier
       # Adds query capability to this Database.
       def initialize
         super
-        @ftchd_vstr = ReferenceVisitor.new { |ref| ref.class.fetched_domain_attributes }
+        @ftchd_vstr = Jinx::ReferenceVisitor.new { |ref| ref.class.fetched_domain_attributes }
         # the demand loader
-        @lazy_loader = LazyLoader.new { |obj, attr| lazy_load(obj, attr) }
+        @lazy_loader = LazyLoader.new { |obj, pa| lazy_load(obj, pa) }
+      end
+    
+      # Clears the cache.
+      def clear
+        @cache.clear if @cache
       end
       
       private
 
       # Adds this database's lazy loader to the given domain object.
       #
-      # @param [Resource] obj the domain object to lazy-load
+      # @param [Jinx::Resource] obj the domain object to lazy-load
       def add_lazy_loader(obj, attributes=nil)
         obj.add_lazy_loader(@lazy_loader, attributes)
       end
 
-      # Loads the content of the given attribute.
-      # The fetched references are persistified with {#persistify}.
+      # Loads the content of the given attribute. If the attribute is independent,
+      # then the fetched objects are replaced by corresponding cached objects,
+      # if cached. The fetched references are persistified with {#persistify}.
       #
-      # @param [Resource] obj the domain object whose content is to be loaded
+      # @param [Jinx::Resource] obj the domain object whose content is to be loaded
       # @param [Symbol] attribute the attribute to load
-      # @return [Resource, <Resource>, nil] the loaded value
+      # @return [Jinx::Resource, <Jinx::Resource>, nil] the loaded value
       def lazy_load(obj, attribute)
-        fetched = fetch_association(obj, attribute)
-        reconcile_fetched(fetched) if fetched
+        fetched = fetch_association(obj, attribute) || return
+        if obj.class.property(attribute).dependent? then
+          persistify(fetched)
+        else
+          reconcile_fetched(fetched)
+        end
       end
       
       # For each fetched domain object, if there is a corresponding cached object,
       # then the reconciled value is that cached object. Otherwise, the reconciled
       # object is the persistified fetched object.
       #
-      # @param [Resource, <Resource>] fetched the fetched domain object(s)
-      # @return [Resource, <Resource>] the reconciled domain object(s)
+      # @param [Jinx::Resource, <Jinx::Resource>] fetched the fetched domain object(s)
+      # @return [Jinx::Resource, <Jinx::Resource>] the reconciled domain object(s)
       def reconcile_fetched(fetched)
         if Enumerable === fetched then
           fetched.map { |ref| reconcile_fetched(ref) }
@@ -50,18 +62,17 @@ module CaRuby
         end
       end
       
-      # @param [Resource] fetched the fetched domain object
-      # @return [Resource] the corresponding cached object, if cached,
-      #   otherwise the fetched object
+      # @param [Jinx::Resource] fetched the fetched domain object
+      # @return [Jinx::Resource, nil] the corresponding cached object, if any
       def reconcile_cached(fetched)
-        cached = @cache[fetched]
+        cached = @cache[fetched] if @cache
         if cached then
           logger.debug { "Replaced fetched #{fetched} with cached #{cached}." }
         end
         cached
       end
 
-      # This method copies each result domain object into a new object of the same type.
+      # This method clears the given toxic domain objects fetched from the database.
       # The copy nondomain attribute values are set to the fetched object values.
       # The copy fetched reference attribute values are set to a copy of the result references.
       #
@@ -75,9 +86,9 @@ module CaRuby
       #   set to the parent. Rather, it is a toxic caCORE reference which must be purged. This
       #   leaves an empty reference which must be lazy-loaded, which is inefficient and inconsistent.
       #   This situation is rectified in this detoxify method by setting the dependent owner
-      #   attribute to the fetched owner in the detoxification {ReferenceVisitor} copy-match-merge.
+      #   attribute to the fetched owner in the detoxification {Jinx::ReferenceVisitor} copy-match-merge.
       #
-      # @return [Resource, <Resource>] the detoxified object(s)
+      # @return [Jinx::Resource, <Jinx::Resource>] the detoxified object(s)
       def detoxify(toxic)
         return if toxic.nil?
         if toxic.collection? then
@@ -85,6 +96,7 @@ module CaRuby
         else
           logger.debug { "Detoxifying the toxic caCORE result #{toxic.qp}..." }
           @ftchd_vstr.visit(toxic) { |ref| clear_toxic_attributes(ref) }
+          logger.debug { "Detoxified the toxic caCORE result #{toxic.qp}." }
         end
         toxic
       end
@@ -92,59 +104,81 @@ module CaRuby
       # Sets each of the toxic attributes in the given domain object to the corresponding
       # {Metadata#empty_value}.
       #
-      # @param [Resource] toxic the toxic domain object
+      # @param [Jinx::Resource] toxic the toxic domain object
       def clear_toxic_attributes(toxic)
-        attrs = toxic.class.toxic_attributes
-        return if attrs.empty?
-        logger.debug { "Clearing toxic #{toxic.qp} attributes #{attrs.to_series}..." }
-        attrs.each_pair do |attr, attr_md|
+        # The result class might not have been previously referenced. In that case,
+        # introspect the class.
+        ensure_introspected(toxic.class)
+        pas = toxic.class.toxic_attributes
+        return if pas.empty?
+        logger.debug { "Clearing toxic #{toxic.qp} attributes #{pas.to_series}..." }
+        pas.each_pair do |pa, prop|
           # skip non-Java attributes
-          next unless attr_md.java_property?
+          next unless prop.java_property?
           # the empty or nil value to set
-          value = toxic.class.empty_value(attr)
+          value = toxic.class.empty_value(pa)
           # Use the Java writer method rather than the standard attribute writer method.
           # The standard attribute writer enforces inverse integrity, which potential requires
           # accessing the current toxic value. The Java writer bypasses inverse integrity.
-          reader, writer = attr_md.property_accessors
+          reader, writer = prop.property_accessors
           # clear the attribute
           toxic.send(writer, value)
         end
       end
       
-      # Persistifies the given domain object and all of its dependents. Sets the inverses
-      # using #{#set_inverses} to enforce inverse integrity.
+      # Persistifies the given domain object and all of its dependents as follows:
+      # * Ensure that the object class is introspected.
+      # * Set the inverses to enforce inverse integrity.
       #
       # @param (see #persistify_object)
       # @raise [ArgumentError] if obj is a collection and other is not nil
       def persistify(obj, other=nil)
         if obj.collection? then
-          if other then raise ArgumentError.new("Database reader persistify other argument not supported") end
+          if other then Jinx.fail(ArgumentError, "Database reader persistify other argument not supported") end
           obj.each { |ref| persistify(ref) }
           return obj
         end
+        # The attribute type is introspected, but the object might be an unintrospected
+        # subtype. Introspect the object class if necessary.
+        ensure_introspected(obj.class)
         # set the inverses before recursing to dependents
         set_inverses(obj)
         # recurse to dependents before adding a lazy loader to the owner
-        obj.each_dependent { |dep| persistify(dep) if dep.identifier }
+        obj.dependents.each { |dep| persistify(dep) if dep.identifier }
         persistify_object(obj, other)
       end
       
+      # Introspects the given class, if necessary. The class must be either introspected
+      # or a subclass of an introspected class.
+      #
+      # @param [Class] klass the class to introspect if necessary 
+      def ensure_introspected(klass)
+        unless klass.introspected? then
+          sc = klass.superclass
+          ensure_introspected(sc)
+          logger.debug { "Introspecting the fetched object class #{klass}..." }
+          # Resolving the class name in the context of the domain module
+          # introspects the class. 
+          sc.domain_module.const_get(klass.name.demodulize)
+        end
+      end
+      
       # Takes a {Persistable#snapshot} of obj to track changes, adds a lazy loader and
       # adds the object to the cache.
       #
       # If the other fetched source object is given, then the obj snapshot is updated
       # with the non-nil values from other.
       #
-      # @param [Resource] obj the domain object to make persistable
-      # @param [Resource] other the source domain object
-      # @return [Resource] obj
+      # @param [Jinx::Resource] obj the domain object to make persistable
+      # @param [Jinx::Resource] other the source domain object
+      # @return [Jinx::Resource] obj
       def persistify_object(obj, other=nil)
         # take a snapshot of the database content
         snapshot(obj, other)
         # add lazy loader to the unfetched attributes
         add_lazy_loader(obj)
         # add to the cache
-        @cache.add(obj)
+        encache(obj)
         obj
       end
       
@@ -155,12 +189,12 @@ module CaRuby
       #
       # @param obj (see #persistify_object)
       def set_inverses(obj)
-        obj.class.domain_attributes.each_pair do |attr, attr_md|
-          inv_md = attr_md.inverse_metadata || next
-          if inv_md.collection? then
-            obj.send(attr).enumerate { |ref| ref.send(inv_md.to_sym) << obj }
+        obj.class.domain_attributes.each_pair do |pa, prop|
+          inv_prop = prop.inverse_property || next
+          if inv_prop.collection? then
+            obj.send(pa).enumerate { |ref| ref.send(inv_prop.attribute) << obj }
           else
-            obj.send(attr).enumerate { |ref| ref.set_attribute(inv_md.to_sym, obj) }
+            obj.send(pa).enumerate { |ref| ref.set_property_value(inv_prop.attribute, obj) }
           end
         end
       end
@@ -170,9 +204,9 @@ module CaRuby
       # values into the obj snapshot, replacing an existing obj non-domain value with the
       # corresponding other attribute value if and only if the other attribute value is non-nil.
       #
-      # @param [Resource] obj the domain object to snapshot
-      # @param [Resource] the source domain object
-      # @return [Resource] the obj snapshot, updated with source content if necessary
+      # @param [Jinx::Resource] obj the domain object to snapshot
+      # @param [Jinx::Resource] the source domain object
+      # @return [Jinx::Resource] the obj snapshot, updated with source content if necessary
       def snapshot(obj, other=nil)
         # take a fresh snapshot
         obj.take_snapshot
@@ -180,6 +214,29 @@ module CaRuby
         # merge the other object content if available
         obj.merge_into_snapshot(other) if other
       end
+
+      # @param [Jinx::Resource] obj the object to cache
+      # @raise [ArgumentError] if the given item does not have an identifier
+      def encache(obj)
+        @cache ||= create_cache
+        @cache.add(obj)
+      end    
+    
+      # @quirk JRuby identifier is not a stable object when fetched from the database, i.e.:
+      #     obj.identifier.equal?(obj.identifier) #=> false
+      #   This is probably an artifact of jRuby Numeric -> Java Long conversion interaction
+      #   combined with hash access use of the eql? method. Work-around is to convert the
+      #   identifier to a Ruby Integer.
+      #
+      # @return [Cache] a new object cache
+      def create_cache
+        Cache.new do |obj|
+          if obj.identifier.nil? then
+            Jinx.fail(ArgumentError, "Can't cache object without identifier: #{obj}")
+          end
+          obj.identifier.to_s.to_i
+        end
+      end
     end
   end
 end

data/lib/caruby/database/reader.rb

@@ -1,9 +1,9 @@
-require 'caruby/util/collection'
-require 'caruby/util/cache'
-require 'caruby/util/pretty_print'
-require 'caruby/domain/reference_visitor'
+require 'jinx/helpers/collection'
+require 'jinx/helpers/pretty_print'
+require 'jinx/resource/merge_visitor'
+require 'caruby/database/cache'
 require 'caruby/database/fetched_matcher'
-require 'caruby/database/search_template_builder'
+require 'caruby/database/reader_template_builder'
 
 module CaRuby
   class Database
@@ -13,7 +13,7 @@ module CaRuby
       def initialize
         super
         # the query template builder
-        @srch_tmpl_bldr = SearchTemplateBuilder.new
+        @srch_tmpl_bldr = TemplateBuilder.new
         # the fetch result matcher
         @matcher = FetchedMatcher.new
         # the fetched copier
@@ -23,7 +23,7 @@ module CaRuby
           copy
         end
         # visitor that merges the fetched object graph
-        @ftchd_mrg_vstr = MergeVisitor.new(:matcher => @matcher, :copier => copier) { |ref| ref.class.fetched_domain_attributes }
+        @ftchd_mrg_vstr = Jinx::MergeVisitor.new(:matcher => @matcher, :copier => copier) { |ref| ref.class.fetched_domain_attributes }
       end
 
       # Returns an array of objects matching the specified query template and attribute path.
@@ -32,7 +32,7 @@ module CaRuby
       # is a String, then the HQL statement String is executed.
       #
       # Otherwise, the query condition is determined by the values set in the template.
-      # The non-nil {Domain::Attributes#searchable_attributes} are used in the query.
+      # The non-nil {Propertied#searchable_attributes} are used in the query.
       #
       # The optional path arguments are attribute symbols from the template to the
       # destination class, e.g.:
@@ -48,9 +48,9 @@ module CaRuby
       # By contrast, caCORE API search result property access, by design, fails with an
       # obscure exception when the property is not lazy-loaded in Hibernate.
       #
-      # @param [Resource, String] obj_or_hql the domain object or HQL to query
-      # @param [<Attribute>] path the attribute path to search
-      # @return [<Resource>] the domain objects which match the query
+      # @param [Jinx::Resource, String] obj_or_hql the domain object or HQL to query
+      # @param [<Property>] path the attribute path to search
+      # @return [<Jinx::Resource>] the domain objects which match the query
       def query(obj_or_hql, *path)
         # the detoxified caCORE query result
         result = query_safe(obj_or_hql, *path)
@@ -66,10 +66,10 @@ module CaRuby
       # If the :create option is set, then this method creates an object if the
       # find is unsuccessful.
       #
-      # @param [Resource] obj the domain object to find
+      # @param [Jinx::Resource] obj the domain object to find
       # @param [Hash, Symbol] opts the find options
       # @option opts [Boolean] :create whether to create the object if it is not found
-      # @return [Resource, nil] the domain object if found, nil otherwise
+      # @return [Jinx::Resource, nil] the domain object if found, nil otherwise
       # @raise [DatabaseError] if obj is not a domain object or more than object
       #   matches the obj attribute values
       def find(obj, opts=nil)
@@ -88,7 +88,7 @@ module CaRuby
       # Returns whether the given domain object has a database identifier or exists in the database.
       # This method fetches the object from the database if necessary.
       #
-      # @param [Resource, <Resource>] obj the domain object(s) to find
+      # @param [Jinx::Resource, <Jinx::Resource>] obj the domain object(s) to find
       # @return [Boolean] whether the domain object(s) exist in the database
       def exists?(obj)
         if obj.nil? then
@@ -131,7 +131,7 @@ module CaRuby
         path_s = path.join('.') unless path.empty?
         # guard against recursive call back into the same operation
         if query_redundant?(obj_or_hql, path_s) then
-          raise DatabaseError.new("Query #{obj_or_hql.qp} #{path_s} recursively called in context #{print_operations}")
+          Jinx.fail(DatabaseError, "Query #{obj_or_hql.qp} #{path_s} recursively called in context #{print_operations}")
         end
         # perform the query
         perform(:query, obj_or_hql, :attribute => path_s) { query_with_path(obj_or_hql, path) }
@@ -142,7 +142,7 @@ module CaRuby
       end
 
       def query_subject_redundant?(s1, s2)
-        s1 == s2 or (Resource === s1 and Resource === s2 and s1.identifier and s1.identifier == s2.identifier)
+        s1 == s2 or (Jinx::Resource === s1 and Jinx::Resource === s2 and s1.identifier and s1.identifier == s2.identifier)
       end
 
       # @return an array of objects matching the given query template and path
@@ -154,7 +154,7 @@ module CaRuby
         # gather the results of querying on those penultimate result objects with the last
         # attribute as the path
         unless path.empty? then
-          if attribute.nil? then raise DatabaseError.new("Query path includes empty attribute: #{path.join('.')}.nil") end
+          if attribute.nil? then Jinx.fail(DatabaseError, "Query path includes empty attribute: #{path.join('.')}.nil") end
           logger.debug { "Decomposing query on #{obj_or_hql} with path #{path.join('.')}.#{attribute} into query on #{path.join('.')} followed by #{attribute}..." }
           return query_safe(obj_or_hql, *path).map { |parent| query_toxic(parent, attribute) }.flatten
         end
@@ -183,8 +183,15 @@ module CaRuby
       
       # Merges fetched into target. The fetched references are recursively merged.
       #
-      # @param [Resource] source the fetched domain object result
-      # @param [Resource] target the domain object find argument
+      # @quirk caCORE caCORE does not enforce reference integrity, i.e. if object _a_ has
+      #   a reference path _a_.+b+ = _b_ and _b_.+a+ = _a_, then a search on _a_ with path
+      #   +:b+ results in the reference path _a_ => _b_ => _a'_, where
+      #   _a.identifier_ == _a'.identifier_ but _a_ != _a_'.
+      #   This method remedies the caCORE defect by matching source references on a previously
+      #   matched identifier where possible.
+      #
+      # @param [Jinx::Resource] source the fetched domain object result
+      # @param [Jinx::Resource] target the domain object find argument
       def merge_fetched(source, target)
         @ftchd_mrg_vstr.visit(source, target) { |src, tgt| tgt.copy_volatile_attributes(src) }
       end
@@ -197,7 +204,7 @@ module CaRuby
 
       def query_hql(hql)
         java_name = hql[/from\s+(\S+)/i, 1]
-        raise DatabaseError.new("Could not determine target type from HQL: #{hql}") if java_name.nil?
+        Jinx.fail(DatabaseError, "Could not determine target type from HQL: #{hql}") if java_name.nil?
         tgt = Class.to_ruby(java_name)
         persistence_service(tgt).query(hql)
       end
@@ -205,16 +212,16 @@ module CaRuby
       # Returns an array of objects fetched from the database which matches
       # a template and follows the given optional domain attribute, if present.
       #
-      # The search template is built by {SearchTemplateBuilder#build_template}.
+      # The search template is built by {TemplateBuilder#build_template}.
       # If a template could not be built and obj is dependent, then this method
       # queries the obj owner with a dependent filter.
       #
       # @quirk caCORE Bug #79 - API search with only id returns entire table.
       #   Work around this bug by issuing a HQL query instead.
       #
-      # @param [Resource] obj the query template object
+      # @param [Jinx::Resource] obj the query template object
       # @param [Symbol, nil] attribute the optional attribute to fetch
-      # @return [<Resource>] the query result
+      # @return [<Jinx::Resource>] the query result
       def query_object(obj, attribute=nil)
         if obj.identifier then
           query_on_identifier(obj, attribute)
@@ -248,7 +255,7 @@ module CaRuby
 
         # the join attribute property
         if attribute then
-          pd = obj.class.attribute_metadata(attribute).property_descriptor
+          pd = obj.class.property(attribute).property_descriptor
           hql.insert(0, "select #{sa}.#{pd.name} ")
         end
         logger.debug { "Querying on #{obj} #{attribute} using HQL identifier criterion..." }
@@ -265,10 +272,10 @@ module CaRuby
       # @return [Boolean] whether the query can be inverted
       def invertible_query?(obj, attribute=nil)
         return false if attribute.nil?
-        attr_md = obj.class.attribute_metadata(attribute)
-        return false if attr_md.type.abstract?
-        inv_md = attr_md.inverse_metadata
-        inv_md and inv_md.searchable? and finder_parameters(obj)
+        pa = obj.class.property(attribute)
+        return false if pa.type.abstract?
+        inv_prop = pa.inverse_property
+        inv_prop and inv_prop.searchable? and finder_parameters(obj)
       end
 
       # Queries the given query object attribute by querying an attribute type template which references obj.
@@ -279,18 +286,18 @@ module CaRuby
       #
       # @param (see #query_object)
       def query_with_inverted_reference(obj, attribute=nil)
-        attr_md = obj.class.attribute_metadata(attribute)
-        logger.debug { "Querying on #{obj.qp} #{attribute} by inverting the query as a #{attr_md.type.qp} #{attr_md.inverse} reference query..." }
+        pa = obj.class.property(attribute)
+        logger.debug { "Querying on #{obj.qp} #{attribute} by inverting the query as a #{pa.type.qp} #{pa.inverse} reference query..." }
         # the search reference template
         ref = finder_template(obj)
         # the attribute inverse query template
-        tmpl = attr_md.type.new
+        tmpl = pa.type.new
         # the inverse attribute
-        inv_md = tmpl.class.attribute_metadata(attr_md.inverse)
+        inv_prop = tmpl.class.property(pa.inverse)
         # The Java property writer to set the tmpl inverse to ref.
         # Use the property writer rather than the attribute writer in order to curtail automatically
-        # adding tmpl to the ref attribute value when the inv_md attribute is set to ref.
-        wtr = inv_md.property_writer
+        # adding tmpl to the ref attribute value when the inv_prop attribute is set to ref.
+        wtr = inv_prop.property_writer
         # parameterize tmpl with inverse ref
         tmpl.send(wtr, ref)
         # submit the query
@@ -312,7 +319,7 @@ module CaRuby
       #   so it is done manually here.
       #
       # @param obj (see #find)
-      # @return [Resource, nil] obj if there is a matching database record, nil otherwise
+      # @return [Jinx::Resource, nil] obj if there is a matching database record, nil otherwise
       # @raise [DatabaseError] if more than object matches the obj attribute values or if
       #   the search object is a dependent entity that does not reference an owner
       def find_object(obj)
@@ -339,7 +346,12 @@ module CaRuby
       #
       # @see #find_object
       def fetch_object(obj)
-        # make the finder template with key attributes
+        # If there is an identifier, then work around the caCORE identifier query bug by delegating
+        # to the HQL identifier query.
+        if obj.identifier then
+          return query_on_identifier(obj).first
+        end
+        # Make the finder template with key attributes.
         tmpl = finder_template(obj)
         # If a template could be made, then fetch on the template.
         # Otherwise, if there is an owner, then match on the fetched owner dependents.
@@ -361,45 +373,43 @@ module CaRuby
           msg = "More than one match for #{obj.class.qp} find with template #{template}."
           # it is an error to have an ambiguous result
           logger.error("Fetch error - #{msg}:\n#{obj}")
-          raise DatabaseError.new(msg)
+          Jinx.fail(DatabaseError, msg)
         end
 
         result.first
       end
 
-      # If obj is a dependent, then returns the obj owner dependent which matches obj.
-      # Otherwise, returns nil.
+      # If the given domain object is a dependent with an unfetched owner, then this method fetches
+      # the owner and attempts to match the owner dependent to this object.
       #
-      # @param [Resource] the domain object to fetch
-      # @return [Resource, nil] the domain object if it matches a dependent, nil otherwise 
+      # @param [Jinx::Resource] obj the domain object to fetch
+      # @return [Jinx::Resource, nil] the domain object if it matches a dependent, nil otherwise 
       def fetch_object_by_fetching_owner(obj)
         owner = nil
-        oattr = obj.class.owner_attributes.detect { |attr| owner = obj.send(attr) }
-        return unless owner
+        oattr = obj.class.owner_attributes.detect { |pa| owner = obj.send(pa) }
+        return if owner.nil? or owner.fetched?
 
-        logger.debug { "Querying #{obj.qp} by matching on the owner #{owner.qp} #{oattr} dependents..." }
-        inv_md = obj.class.attribute_metadata(oattr)
-        if inv_md.nil? then
-          raise DatabaseError.new("#{dep.class.qp} owner attribute #{oattr} does not have a #{owner.class.qp} inverse dependent attribute.")
+        logger.debug { "Querying #{obj.qp} by matching on the #{oattr} owner #{owner.qp} dependents..." }
+        inv_prop = obj.class.property(oattr)
+        if inv_prop.nil? then
+          Jinx.fail(DatabaseError, "#{dep.class.qp} owner attribute #{oattr} does not have a #{owner.class.qp} inverse dependent attribute.")
         end
-        inverse = inv_md.inverse
+        inv = inv_prop.inverse
         # fetch the owner if necessary
-        unless owner.identifier then
-          find(owner) || return
-          # if obj dependent was fetched with owner, then done
-          if obj.identifier then
-            logger.debug { "Found #{obj.qp} by fetching the owner #{owner}." }
-            return obj
-          end
+        find(owner) || return
+        # if obj dependent was fetched with owner, then done
+        if obj.identifier then
+          logger.debug { "Found #{obj.qp} by fetching the owner #{owner}." }
+          return obj
         end
 
         # try to match a fetched owner dependent
-        deps = lazy_loader.enable { owner.send(inverse) }
+        deps = lazy_loader.enable { owner.send(inv) }
         if obj.identifier then
-          logger.debug { "Found #{obj.qp} by fetching the owner #{owner} #{inverse} dependent #{deps.qp}." }
+          logger.debug { "Found #{obj.qp} by fetching the owner #{owner} #{inv} dependents." }
           return obj
         else
-          logger.debug { "#{obj.qp} does not match a fetched owner #{owner} #{inverse} dependent #{deps.qp}." }
+          logger.debug { "#{obj.qp} does not match one of the fetched owner #{owner} #{inv} dependents #{deps}." }
           nil
         end
       end
@@ -415,7 +425,8 @@ module CaRuby
         @srch_tmpl_bldr.build_template(obj, hash)
       end
 
-      # Fetches the given obj attribute from the database.
+      # Fetches the given object attribute value from the database.
+      #
       # @quirk caCORE there is no association fetch for caCORE 3.1 and earlier;
       #   caCORE 4 association search is not yet adequately proven in caRuby testing.
       #   Fall back on a general query instead (the devil we know). See also the
@@ -432,35 +443,46 @@ module CaRuby
       #   the detoxified copy loses reference integrity. E.g. a query on the children attribute of
       #   a parent object forces lazy load of each child => parent reference separately resolving
       #   in separate parent copies. There is no recognition that the children reference the parent
-      #   which generated the query. This anomaly is partially rectified in this fetch_association
-      #   method by setting the fetched objects inverse to the given search target object. The
-      #   inconsistent and inefficient caCORE behavior is further corrected by setting inverse
-      #   owners when the fetch result is persistified, as described in {Persistifier#persistify}.
-      #   Callers who do not persistify the result should call {Persistifier#set_inverses} on the
-      #   result.
-      #
-      # @param [Resource] obj the search target object
+      #   which generated the query. This anomaly cannot be rectified in this fetch_association
+      #   method by setting the fetched objects inverse to the given search target object, since
+      #   this method does not modify the search target. This hazardous and inefficient caCORE
+      #   behavior is partially rectified by setting the fetched object inverse references to
+      #   a copy of the search target. If the search target has been fetched, then it is cached.
+      #   Therefore, calling {Persistifier#persistify} on the fetched objects will reconcile
+      #   the referenced search target copy with the search target. This reconciliation is done
+      #   by the caller, e.g. the lazy loader.
+      #
+      # @param [Jinx::Resource] obj the search target object
       # @param [Symbol] attribute the association to fetch
+      # @return [Jinx::Resource, <Jinx::Resource>, nil] the attribute value
       # @raise [DatabaseError] if the search target object does not have an identifier
       def fetch_association(obj, attribute)
         logger.debug { "Fetching association #{attribute} for #{obj}..." }
         # load the object if necessary
         unless exists?(obj) then
-          raise DatabaseError.new("Can't fetch an association since the referencing object is not found in the database: #{obj}")
+          Jinx.fail(DatabaseError, "Can't fetch an association since the referencing object is not found in the database: #{obj}")
         end
         # fetch the reference
         result = query_safe(obj, attribute)
-        # set the result inverse references
-        inv_md = obj.class.attribute_metadata(attribute).inverse_metadata
-        if inv_md and not inv_md.collection? then
-          inv_obj = obj.copy(:identifier)
-          result.each do |ref|
-            logger.debug { "Setting fetched #{obj} #{attribute} value #{ref} inverse #{inv_md} to #{obj} copy #{inv_obj.qp}..." }
-            ref.send(inv_md.writer, inv_obj)
-          end
+        # Set the inverse to a place-holder copy of the search target.
+        # If this method is called by a lazy loader, then the caller will
+        # subsequently reconcile the reference with the cached search target.
+        prop = obj.class.property(attribute)
+        ip = prop.inverse_property
+        if ip and not ip.collection? then
+          place_holder = obj.copy(:identifier)
+          result.each { |ref| ref.send(ip.writer, place_holder) }
         end
-        # unbracket the result if the attribute is not a collection
-        obj.class.attribute_metadata(attribute).collection? ? result : result.first
+        # Unbracket the result if the search propery is not a collection.
+        prop.collection? ? result : result.first
+      end
+
+      # Fetches the given object attribute reference from the database and sets the property value.
+      #
+      # @param (see #fetch_association)
+      # @return (see #fetch_association)
+      def load_association(obj, attribute)
+        obj.set_property_value(attribute, fetch_association(obj, attribute))
       end
 
       # @return [{Symbol => Object}, nil] the find operation key attributes, or nil if there is no complete key
@@ -481,7 +503,7 @@ module CaRuby
         # the key must be non-trivial
         return if attributes.nil_or_empty?
         # the attribute => value hash
-        attributes.to_compact_hash { |attr| finder_parameter(obj, attr) or return }
+        attributes.to_compact_hash { |pa| finder_parameter(obj, pa) or return }
       end
       
       # @return a non-empty, existing find parameter for the given attribute
@@ -508,10 +530,10 @@ module CaRuby
       # in the database.
       #
       # Raises DatabaseError if the value is nil.
-      def finder_attribute_value_exists?(obj, attr)
-        value = obj.send(attr)
+      def finder_attribute_value_exists?(obj, pa)
+        value = obj.send(pa)
         return false if value.nil?
-        obj.class.nondomain_attribute?(attr) or value.identifier
+        obj.class.nondomain_attribute?(pa) or value.identifier
       end
 
       # Sets the template attribute to a new search reference object created from source.
@@ -520,12 +542,12 @@ module CaRuby
       # @quirk caCORE The search template must break inverse integrity by clearing an owner inverse reference,
       #   since a dependent => onwer => dependent cycle causes a caCORE search infinite loop.
       #
-      # @return [Resource, nil] the search reference, or nil if source does not exist in the database
+      # @return [Jinx::Resource, nil] the search reference, or nil if source does not exist in the database
       def add_search_template_reference(template, source, attribute)
         return if not exists?(source)
         ref = source.copy(:identifier)
-        template.set_attribute(attribute, ref)
-        inverse = template.class.attribute_metadata(attribute).derived_inverse
+        template.set_property_value(attribute, ref)
+        inverse = template.class.property(attribute).derived_inverse
         ref.clear_attribute(inverse) if inverse
         logger.debug { "Search reference parameter #{attribute} for #{template.qp} set to #{ref} copied from #{source.qp}" }
         ref