caruby-core 1.4.9 → 1.5.1

data/History.md

@@ -0,0 +1,48 @@
+This history lists major release themes. See the GitHub Commits (https://github.com/caruby/core)
+for change details.
+
+1.5.1 / 2011-06-28
+------------------
+* Domain refactoring.
+
+1.4.9 / 2011-05-04
+------------------
+* Support Oracle driver.
+
+1.4.8 / 2011-05-03
+------------------
+* Fix annotation migration error.
+
+* Refactor resource import.
+
+* Add attribute filters.
+
+1.4.7 / 2011-03-04
+------------------
+* Support annotation migration.
+
+1.4.6 / 2011-02-26
+------------------
+* Upgrade to JRuby 1.5.
+
+1.4.5 / 2011-02-26
+------------------
+* Fix default option.
+
+1.4.4 / 2011-02-25
+------------------
+* Support default migration option.
+
+* Merge nondomain collection value properly.
+
+1.4.3 / 2011-02-18
+------------------
+* Refactor Persistifier
+
+1.4.2 / 2010-11-30
+------------------
+* Minor Migrator fixes.
+
+1.4.1 / 2010-11-23
+------------------
+* Initial public release.

data/lib/caruby/cli/command.rb

@@ -79,7 +79,8 @@ module CaRuby
         [:file, "--file FILE", "Configuration file containing other options"],
         [:log, "--log FILE", "Log file"],
         [:debug, "--debug", "Display debug log messages"],
-        [:quiet, "-q", "--quiet", "Suppress printing messages to stdout"]
+        [:quiet, "-q", "--quiet", "Suppress printing messages to stdout"],
+        [:verbose, "-v", "--verbose", "Print additional messages to stdout"]
       ]
       
       # @param [{Symbol => Object}] opts the option => value hash

data/lib/caruby/csv/csv_mapper.rb

@@ -55,18 +55,18 @@ module CaRuby
       @string_headers = Set.new
       @hdr_map.each do |path, cls_hdr_hash|
         last = path.last
-        @string_headers.merge!(cls_hdr_hash.values) if AttributeMetadata === last and last.type == String
+        @string_headers.merge!(cls_hdr_hash.values) if Attribute === last and last.type == String
       end
     end
 
-    # Returns the given klass's mapped AttributeMetadata paths.
+    # Returns the given klass's mapped Attribute paths.
     # The default klass is the target class.
     def paths(klass=nil)
       klass ||= @target
       @cls_paths_hash[klass]
     end
 
-    # Returns the header mapped by the given AttributeMetadata path and starting klass.
+    # Returns the header mapped by the given Attribute path and starting klass.
     # The default klass is the target class.
     def header(path, klass=nil)
       klass ||= @target
@@ -90,8 +90,8 @@ module CaRuby
       end
     end
 
-    # @param [{Symbol => <AttributeMetadata>}] config the field => path list configuration
-    # @return [({Symbol => <AttributeMetadata>}, {Class => {<AttributeMetadata> => Symbol>}})]
+    # @param [{Symbol => <Attribute>}] config the field => path list configuration
+    # @return [({Symbol => <Attribute>}, {Class => {<Attribute> => Symbol>}})]
     #   the class => paths hash and the path => class => header hash
     def map_headers(config)
       # the class => paths hash; populated in map_headers
@@ -112,7 +112,7 @@ module CaRuby
       [cls_paths_hash, hdr_map]
     end
 
-    # Returns an array of AttributeMetadata or symbol objects for the period-delimited path string path_s in the
+    # Returns an array of Attribute or symbol objects for the period-delimited path string path_s in the
     # pattern (_class_|_attribute_)(+.+_attribute_)*, e.g.:
     #   ClinicalStudy.status
     #   study.status
@@ -127,7 +127,7 @@ module CaRuby
       if names.empty? then
         raise ConfigurationError.new("Attribute entry in CSV field mapping is not in <class>.<attribute> format: #{value}")
       end
-      # build the AttributeMetadata path by traversing the names path
+      # build the Attribute path by traversing the names path
       # if the name corresponds to a parent attribute, then add the attribute metadata.
       # otherwise, if the name is a method, then add the method.
       path = []
@@ -150,7 +150,7 @@ module CaRuby
       tail = names[path.size..-1].map { |name| name.to_sym }
       path.concat(tail)
       # return the starting class and path
-      # Note that the starting class is not necessarily the first path AttributeMetadata declarer, since the
+      # Note that the starting class is not necessarily the first path Attribute declarer, since the
       # starting class could be a concrete subclass of an abstract declarer. this is important, since the class
       # must be instantiated.
       [klass, path]

data/lib/caruby/database/persistable.rb

@@ -28,17 +28,18 @@ module CaRuby
       not saved?(obj)
     end
     
-    # Returns the data access mediator for this domain object, if any. The default implementation
-    # returns nil. Application #{Resource} modules can override this method.
+    # Returns the data access mediator for this domain object.
+    # Application #{Resource} modules are required to override this method.
     #
-    # @return [Database, nil] the data access mediator for this Persistable, if any
+    # @return [Database] the data access mediator for this Persistable, if any
+    # @raise [DatabaseError] if the subclass does not override this method
     def database
-      nil
+      raise ValidationError.new("#{self} database is missing")
     end
     
-    # @return [PersistenceService, nil] the database application service for this Persistable, if any
+    # @return [PersistenceService] the database application service for this Persistable
     def persistence_service
-      database.persistence_service(self.class) if database
+      database.persistence_service(self.class)
     end
 
     # Fetches the domain objects which match this template from the {#database}.
@@ -74,6 +75,13 @@ module CaRuby
       database.create(self)
     end
 
+    # Creates this domain object, if necessary.
+    #
+    # @raise (see Database#ensure_exists)
+    def ensure_exists
+      database.ensure_exists(self)
+    end
+    
     # Saves this domain object in the {#database}.
     #
     # @return (see Writer#save)
@@ -109,7 +117,7 @@ module CaRuby
     alias :== :equal?
 
     alias :eql? :==
-    
+
     # Captures the Persistable's updatable attribute base values.
     # The snapshot is subsequently accessible using the {#snapshot} method.
     #
@@ -156,8 +164,7 @@ module CaRuby
     def changed_attributes
       if @snapshot then
         ovh = value_hash(self.class.updatable_attributes)
-        diff = @snapshot.diff(ovh) { |attr, v, ov|
-        Resource.value_equal?(v, ov) }
+        diff = @snapshot.diff(ovh) { |attr, v, ov| Resource.value_equal?(v, ov) }
         diff.keys
       else
         self.class.updatable_attributes
@@ -191,8 +198,8 @@ module CaRuby
     end
     
     # Returns the attributes to load on demand. The base attribute list is given by the
-    # {ResourceAttributes#loadable_attributes} whose value is nil or empty.
-    # In addition, if this Persistable has more than one {ResourceDependency#owner_attributes}
+    # {Attributes#loadable_attributes} whose value is nil or empty.
+    # In addition, if this Persistable has more than one {Dependency#owner_attributes}
     # and one is non-nil, then none of the owner attributes are loaded on demand,
     # since there can be at most one owner and ownership cannot change.
     #
@@ -225,52 +232,23 @@ module CaRuby
       disable_singleton_method(writer)
     end
     
-    # Returns whether this domain object must be fetched to reflect the database state.
-    # This default implementation returns whether this domain object was created and
-    # there are any autogenerated attributes. Subclasses can override to relax or restrict
-    # the condition.
-    #
-    # caCORE alert - the auto-generated criterion is a necessary but not sufficient condition
-    # to determine whether a save caCORE result reflects the database state. Example:
-    # * caTissue SCG event parameters are not auto-generated on SCG create if the SCG collection
-    #   status is Pending, but are auto-generated on SCG update if the SCG status is changed
-    #   to Complete. By contrast, the SCG specimens are auto-generated on SCG create, even if
-    #   the status is +Pending+.
-    # The caBIG application can override this method in a Database subclass to fine-tune the
-    # fetch criteria. Adding a more restrictive {#fetch_saved?} condition will will improve
-    # performance but not change functionality.
-    #
-    # caCORE alert - a saved attribute which is cascaded but not fetched must be fetched in
-    # order to reflect the database identifier in the saved object.
-    #
-    # @return [Boolean] whether this domain object must be fetched to reflect the database state
-    def fetch_saved?
-      # only fetch a create, not an update (note that subclasses can override this condition)
-      return false if identifier
-      # Check for an attribute with a value that might need to be changed in order to
-      # reflect the auto-generated database content.
-      ag_attrs = self.class.autogenerated_attributes
-      return false if ag_attrs.empty?
-      ag_attrs.any? { |attr| not send(attr).nil_or_empty? }
-    end
-    
     # Returns this domain object's attributes which must be fetched to reflect the database state.
-    # This default implementation returns the {ResourceAttributes#autogenerated_logical_dependent_attributes}
+    # This default implementation returns the {Attributes#autogenerated_logical_dependent_attributes}
     # if this domain object does not have an identifier, or an empty array otherwise.
     # Subclasses can override to relax or restrict the condition.
     #
-    # caCORE alert - the auto-generated criterion is a necessary but not sufficient condition
-    # to determine whether a save caCORE result reflects the database state. Example:
-    # * caTissue SCG event parameters are not auto-generated on SCG create if the SCG collection
-    #   status is Pending, but are auto-generated on SCG update if the SCG status is changed
-    #   to Complete. By contrast, the SCG specimens are auto-generated on SCG create, even if
-    #   the status is +Pending+.
-    # The caBIG application can override this method in a Database subclass to fine-tune the
-    # fetch criteria. Adding a more restrictive {#fetch_saved?} condition will will improve
-    # performance but not change functionality.
+    # @quirk caCORE the auto-generated criterion is a necessary but not sufficient condition
+    #   to determine whether a save caCORE result reflects the database state. Example:
+    #   * caTissue SCG event parameters are not auto-generated on SCG create if the SCG collection
+    #     status is Pending, but are auto-generated on SCG update if the SCG status is changed
+    #     to Complete. By contrast, the SCG specimens are auto-generated on SCG create, even if
+    #     the status is +Pending+.
+    #   The caBIG application can override this method in a Database subclass to fine-tune the
+    #   fetch criteria. Adding a more restrictive {#fetch_saved?} condition will will improve
+    #   performance but not change functionality.
     #
-    # caCORE alert - a saved attribute which is cascaded but not fetched must be fetched in
-    # order to reflect the database identifier in the saved object.
+    # @quirk caCORE a saved attribute which is cascaded but not fetched must be fetched in
+    #   order to reflect the database identifier in the saved object.
     #
     # @param [Database::Operation] the save operation
     # @return [<Symbol>] whether this domain object must be fetched to reflect the database state
@@ -306,18 +284,19 @@ module CaRuby
     # there are any autogenerated attributes. Subclasses can override to relax or restrict
     # the condition.
     #
-    # caCORE alert - the auto-generated criterion is a necessary but not sufficient condition
-    # to determine whether a save caCORE result reflects the database state. Example:
-    # * caTissue SCG event parameters are not auto-generated on SCG create if the SCG collection
-    #   status is Pending, but are auto-generated on SCG update if the SCG status is changed
-    #   to Complete. By contrast, the SCG specimens are auto-generated on SCG create, even if
-    #   the status is +Pending+.
-    # The caBIG application can override this method in a Database subclass to fine-tune the
-    # fetch criteria. Adding a more restrictive {#fetch_saved?} condition will will improve
-    # performance but not change functionality.
+    # @quirk caCORE The auto-generated criterion is a necessary but not sufficient condition
+    #   to determine whether a save caCORE result reflects the database state. Example:
+    #   * caTissue SCG event parameters are not auto-generated on SCG create if the SCG collection
+    #     status is Pending, but are auto-generated on SCG update if the SCG status is changed
+    #     to Complete. By contrast, the SCG specimens are auto-generated on SCG create, even if
+    #     the status is +Pending+.
+    #
+    #   The caBIG application can override this method in a Database subclass to fine-tune the
+    #   fetch criteria. Adding a more restrictive {#fetch_saved?} condition will will improve
+    #   performance but not change functionality.
     #
-    # caCORE alert - a saved attribute which is cascaded but not fetched must be fetched in
-    # order to reflect the database identifier in the saved object.
+    # @quirk caCORE A saved attribute which is cascaded but not fetched must be fetched in
+    #   order to reflect the database identifier in the saved object.
     #
     # @return [Boolean] whether this domain object must be fetched to reflect the database state
     def fetch_saved?
@@ -330,7 +309,7 @@ module CaRuby
       ag_attrs.any? { |attr| not send(attr).nil_or_empty? }
     end
 
-    # Sets the {ResourceAttributes#volatile_nondomain_attributes} to the other fetched value,
+    # Sets the {Attributes#volatile_nondomain_attributes} to the other fetched value,
     # if different.
     #
     # @param [Resource] other the fetched domain object reflecting the database state
@@ -470,7 +449,7 @@ module CaRuby
       # dissociate the method from this instance
       method = self.method(name_or_sym.to_sym)
       method.unbind
-      # JRuby alert - Unbind doesn't work in JRuby 1.1.6. In that case, redefine the singleton method to delegate
+      # JRuby unbind doesn't work in JRuby 1.1.6. In that case, redefine the singleton method to delegate
       # to the class instance method.
       if singleton_methods.include?(name_or_sym.to_s) then
         args = (1..method.arity).map { |argnum| "arg#{argnum}" }.join(', ')

data/lib/caruby/database/persistence_service.rb

@@ -47,16 +47,16 @@ module CaRuby
     # object following the given attribute path. The query condition is determined by the values set in the
     # template. Every non-nil attribute in the template is used as a select condition.
     #
-    # caCORE alert - this method returns the direct result of calling the +caCORE+ application service
-    # search method. Calling reference attributes of this result is broken by +caCORE+ design.
+    # @quirk caCORE this method returns the direct result of calling the +caCORE+ application service
+    #   search method. Calling reference attributes of this result is broken by +caCORE+ design.
     def query(template_or_hql, *path)
       String === template_or_hql ? query_hql(template_or_hql) : query_template(template_or_hql, path)
     end
 
     # Submits the create to the application service and returns the created object.
     #
-    # caCORE alert - this method returns the direct result of calling the +caCORE+ application service
-    # create method. Calling reference attributes of this result is broken by +caCORE+ design.
+    # @quirk caCORE this method returns the direct result of calling the +caCORE+ application service
+    #   create method. Calling reference attributes of this result is broken by +caCORE+ design.
     def create(obj)
       logger.debug { "Submitting create #{obj.pp_s(:single_line)} to application service #{name}..." }
       begin
@@ -91,9 +91,9 @@ module CaRuby
 
     # Returns a freshly initialized ApplicationServiceProvider remote instance.
     #
-    # caCORE alert - 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.
+    # @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
     def app_service
@@ -135,11 +135,14 @@ module CaRuby
       'localhost'
     end
     
+    # Dispatches the given HQL to the application service.
+    #
+    # @quirk caCORE query target parameter is necessary for caCORE 3.x but deprecated in caCORE 4+.
+    #
+    # @param [String] hql the HQL to submit
     def query_hql(hql)
       logger.debug { "Building HQLCriteria..." }
       criteria = HQLCriteria.new(hql)
-      # caCORE alert - query target parameter is necessary for caCORE 3.x but deprecated in caCORE 4+
-      # TODO caCORE 4 - remove target parameter
       target = hql[/from\s+(\S+)/i, 1]
       raise DatabaseError.new("HQL does not contain a FROM clause: #{hql}") unless target
       logger.debug { "Submitting search on target class #{target} with the following HQL:\n  #{hql}" }

data/lib/caruby/database/persistifier.rb

@@ -61,22 +61,22 @@ module CaRuby
         cached
       end
 
-      # caCORE alert - Dereferencing a caCORE search result uncascaded collection attribute
-      # raises a Hibernate missing session error.
-      # This problem is addressed by post-processing the +caCORE+ search result to set the
-      # toxic attributes to an empty value.
-      #
-      # caCORE alert - The caCORE search result does not set the obvious inverse attributes,
-      # e.g. children fetched with a parent do not have the children inverse parent attribute
-      # 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.
-      #
       # This method copies each result domain object into a new object of the same type.
       # 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.
       #
+      # @quirk caCORE Dereferencing a caCORE search result uncascaded collection attribute
+      #   raises a Hibernate missing session error.
+      #   This problem is addressed by post-processing the +caCORE+ search result to set the
+      #   toxic attributes to an empty value.
+      #
+      # @quirk caCORE The caCORE search result does not set the obvious inverse attributes,
+      #   e.g. children fetched with a parent do not have the children inverse parent attribute
+      #   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.
+      #
       # @return [Resource, <Resource>] the detoxified object(s)
       def detoxify(toxic)
         return if toxic.nil?
@@ -90,7 +90,7 @@ module CaRuby
       end
       
       # Sets each of the toxic attributes in the given domain object to the corresponding
-      # {ResourceMetadata#empty_value}.
+      # {Metadata#empty_value}.
       #
       # @param [Resource] toxic the toxic domain object
       def clear_toxic_attributes(toxic)
@@ -156,7 +156,7 @@ 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_attribute_metadata || next
+          inv_md = attr_md.inverse_metadata || next
           if inv_md.collection? then
             obj.send(attr).enumerate { |ref| ref.send(inv_md.to_sym) << obj }
           else

data/lib/caruby/database/reader.rb

@@ -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 {ResourceAttributes#searchable_attributes} are used in the query.
+      # The non-nil {Attributes#searchable_attributes} are used in the query.
       #
       # The optional path arguments are attribute symbols from the template to the
       # destination class, e.g.:
@@ -107,11 +107,11 @@ module CaRuby
       # Queries the given obj_or_hql as described in {#query} and makes a detoxified copy of the
       # toxic caCORE search result.
       #
-      # caCORE alert - The query result consists of new domain objects whose content is copied
-      # from the caBIG application search result. The caBIG result is Hibernate-enhanced but
-      # sessionless. This result contains toxic broken objects whose access methods fail.
-      # Therefore, this method sanitizes the toxic caBIG result to reflect the persistent state
-      # of the domain objects.
+      # @quirk caCORE The query result consists of new domain objects whose content is copied
+      #   from the caBIG application search result. The caBIG result is Hibernate-enhanced but
+      #   sessionless. This result contains toxic broken objects whose access methods fail.
+      #   Therefore, this method sanitizes the toxic caBIG result to reflect the persistent state
+      #   of the domain objects.
       #
       # @param (see #query)
       # @return (see #query)
@@ -209,8 +209,8 @@ module CaRuby
       # If a template could not be built and obj is dependent, then this method
       # queries the obj owner with a dependent filter.
       #
-      # caCORE alert - Bug #79 - API search with only id returns entire table.
-      # Work around this bug by issuing a HQL query instead.
+      # @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 [Symbol, nil] attribute the optional attribute to fetch
@@ -267,15 +267,15 @@ module CaRuby
         return false if attribute.nil?
         attr_md = obj.class.attribute_metadata(attribute)
         return false if attr_md.type.abstract?
-        inv_md = attr_md.inverse_attribute_metadata
+        inv_md = attr_md.inverse_metadata
         inv_md and inv_md.searchable? and finder_parameters(obj)
       end
 
       # Queries the given query object attribute by querying an attribute type template which references obj.
       #
-      # caCORE alert - caCORE caCORE search enters an infinite loop when the search argument has an object
-      # reference graph cycle. Work-around is to ensure that reference integrity is broken in the search
-      # argument by not setting inverse attributes.
+      # @quirk caCORE caCORE caCORE search enters an infinite loop when the search argument has an object
+      #   reference graph cycle. Work-around is to ensure that reference integrity is broken in the search
+      #   argument by not setting inverse attributes.
       #
       # @param (see #query_object)
       def query_with_inverted_reference(obj, attribute=nil)
@@ -308,6 +308,9 @@ module CaRuby
       # If a match is found, then each missing search object non-domain-valued attribute is set to
       # the fetched attribute value and this method returns the search object.
       #
+      # @quirk caCORE there is no caCORE find utility method to update a search target with persistent content,
+      #   so it is done manually here.
+      #
       # @param obj (see #find)
       # @return [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
@@ -323,14 +326,11 @@ module CaRuby
         fetched = fetch_object(obj) || return
         # fetch_object can return obj; if so, then done
         return obj if obj.equal?(fetched)
+        
         logger.debug { "Fetch #{obj.qp} matched database object #{fetched}." }
         @transients.delete(obj)
-        
-        # caCORE alert - there is no caCORE find utility method to update a search target with persistent content,
-        # so it is done manually here.
-        # recursively copy the nondomain attributes, esp. the identifer, of the fetched domain object references
+        #   recursively copy the nondomain attributes, esp. the identifer, of the fetched domain object references
         merge_fetched(fetched, obj)
-        # caCORE alert - see query method alerts.
         # Inject the lazy loader for loadable domain reference attributes.
         persistify(obj, fetched)
         obj
@@ -407,38 +407,38 @@ module CaRuby
 
       # Returns a copy of obj containing only those key attributes used in a find operation.
       #
-      # caCORE alert - Bug #79: caCORE search fetches on all non-nil attributes, except
-      # occasionally the identifier. There is no indication of how to identify uniquely
-      # searchable attributes, so the secondary and alternate key is added manually in the
-      # application configuration.
+      # @quirk caCORE Bug #79: caCORE search fetches on all non-nil attributes, except
+      #   occasionally the identifier. There is no indication of how to identify uniquely
+      #   searchable attributes, so the secondary and alternate key is added manually in the
+      #   application configuration.
       def finder_template(obj)
         hash = finder_parameters(obj) || return
         @srch_tmpl_bldr.build_template(obj, hash)
       end
 
       # Fetches the given obj attribute from the database.
-      # caCORE alert - 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
-      # following alert.
-      #
-      # caCORE alert - caCORE search on a non-collection attribute returns a collection result,
-      # even with the caCORE 4 association search. caRuby rectifies this by returning
-      # an association fetch result consistent with the association attribute return type.
-      #
-      # caCORE alert - Preliminary indication is that caCORE 4 does not validate that
-      # a non-collection association search returns at most one item.
-      #
-      # caCORE alert - Since the caCORE search result has toxic references which must be purged,
-      # 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.
+      # @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
+      #  following alert.
+      #
+      # @quirk caCORE caCORE search on a non-collection attribute returns a collection result,
+      #   even with the caCORE 4 association search. caRuby rectifies this by returning
+      #   an association fetch result consistent with the association attribute return type.
+      #
+      # @quirk caCORE Preliminary indication is that caCORE 4 does not validate that
+      #   a non-collection association search returns at most one item.
+      #
+      # @quirk caCORE Since the caCORE search result has toxic references which must be purged,
+      #   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
       # @param [Symbol] attribute the association to fetch
@@ -452,7 +452,7 @@ module CaRuby
         # fetch the reference
         result = query_safe(obj, attribute)
         # set the result inverse references
-        inv_md = obj.class.attribute_metadata(attribute).inverse_attribute_metadata
+        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|
@@ -466,10 +466,10 @@ module CaRuby
 
       # Returns a copy of obj containing only those key attributes used in a find operation.
       #
-      # caCORE alert - caCORE search fetches on all non-nil attributes, except occasionally the identifier
-      # (cf. https://cabig-kc.nci.nih.gov/Bugzilla/show_bug.cgi?id=79).
-      # there is no indication of how to identify uniquely searchable attributes, so the secondary key
-      # is added manually in the application configuration.
+      # @quirk caCORE caCORE search fetches on all non-nil attributes, except occasionally the identifier
+      #   (cf. https://cabig-kc.nci.nih.gov/Bugzilla/show_bug.cgi?id=79).
+      #   there is no indication of how to identify uniquely searchable attributes, so the secondary key
+      #   is added manually in the application configuration.
       def finder_parameters(obj)
         key_value_hash(obj, obj.class.primary_key_attributes) or
         key_value_hash(obj, obj.class.secondary_key_attributes) or
@@ -513,13 +513,15 @@ module CaRuby
 
       # Sets the template attribute to a new search reference object created from source.
       # The reference contains only the source identifier.
-      # Returns the search reference, or nil if source does not exist in the database.
+      #
+      # @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
       def add_search_template_reference(template, source, attribute)
         return if not exists?(source)
         ref = source.copy(:identifier)
         template.set_attribute(attribute, ref)
-        # caCORE alert - clear an owner inverse reference, since the template attr assignment might have added a reference
-        # from ref to template, which introduces a template => ref => template cycle that causes a caCORE search infinite loop.
         inverse = template.class.attribute_metadata(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}" }

data/lib/caruby/database/search_template_builder.rb

@@ -5,19 +5,18 @@ module CaRuby
   # SearchTemplateBuilder builds a template suitable for a caCORE saarch database operation.
   class SearchTemplateBuilder
     # Returns a template for matching the domain object obj and the optional hash values.
-    # The default hash attributes are the {ResourceAttributes#searchable_attributes}.
+    # The default hash attributes are the {Attributes#searchable_attributes}.
     # The template includes only the non-domain attributes of the hash references.
     #
-    # caCORE alert - Because of caCORE API limitations, the obj searchable attribute
-    # values are limited to the following:
-    # * non-domain attribute values
-    # * non-collection domain attribute references which contain a key
+    # @quirk caCORE Because of caCORE API limitations, the obj searchable attribute
+    #   values are limited to the following:
+    #   * non-domain attribute values
+    #   * non-collection domain attribute references which contain a key
     #
-    # caCORE alert - the caCORE query builder breaks on reference cycles and
-    # is easily confused by extraneous references, so it is necessary to search
-    # with a template instead that contains only references essential to the
-    # search. Each reference is confirmed to exist and the reference content in
-    # the template consists entirely of the fetched identifier attribute.
+    # @quirk caCORE the caCORE query builder breaks on reference cycles and is easily confused
+    #   by extraneous references, so it is necessary to search with a template instead that contains
+    #   only references essential to the search. Each reference is confirmed to exist and the
+    #   reference content in the template consists entirely of the fetched identifier attribute.
     def build_template(obj, hash=nil)
       # split the attributes into reference and non-reference attributes.
       # the new search template object is built from the non-reference attributes.