caruby-core 1.5.5 → 2.1.1

data/lib/caruby/database/reader_template_builder.rb

@@ -0,0 +1,60 @@
+require 'jinx/resource'
+require 'jinx/helpers/pretty_print'
+
+module CaRuby
+  class Database
+    module Reader
+      # TemplateBuilder builds a template suitable for a caCORE saarch database operation.
+      class TemplateBuilder
+        # Returns a template for matching the domain object obj and the optional hash values.
+        # The default hash attributes are the {Propertied#searchable_attributes}.
+        # The template includes only the non-domain attributes of the hash references.
+        #
+        # @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
+        #
+        # @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.
+          # the reference attributes values are copied and added.
+          logger.debug { "Building search template for #{obj.qp}..." }
+          hash ||= obj.value_hash(obj.class.searchable_attributes)
+          # the searchable attribute => value hash
+          rh, nrh = hash.split { |pa, value| Jinx::Resource === value }
+          # make the search template from the non-reference attributes
+          tmpl = obj.class.new.merge_attributes(nrh)
+          # get references for the search template
+          unless rh.empty? then
+            logger.debug { "Collecting search reference parameters for #{obj.qp} from attributes #{rh.keys.to_series}..." }
+          end
+          rh.each { |pa, ref| add_search_template_reference(tmpl, ref, pa) }
+          tmpl
+        end
+
+        private
+
+        # Sets the template attribute to a new search reference object created from the given
+        # source domain object. The reference contains only the source identifier, if it exists,
+        # or the source non-domain attributes otherwise.
+        #
+        # @return [Jinx::Resource] the search reference
+        def add_search_template_reference(template, source, attribute)
+          ref = source.identifier ? source.copy(:identifier) : source.copy
+          # Disable inverse integrity, since the template attribute assignment might have added a reference
+          # from ref to template, which introduces a template => ref => template cycle that causes a caCORE
+          # search infinite loop. Use the Java property writer instead.
+          wtr = template.class.property(attribute).property_writer
+          template.send(wtr, ref)
+          logger.debug { "Search reference parameter #{attribute} for #{template.qp} set to #{ref} copied from #{source.qp}" }
+          ref
+        end
+      end
+    end
+  end
+end

data/lib/caruby/database/saved_matcher.rb

@@ -26,7 +26,7 @@ module CaRuby
       #
       # @param sources (see #match_fetched)
       # @param targets (see #match_fetched)
-      # @param [{Resource => Resource}] the source => target matches so far
+      # @param [{Jinx::Resource => Jinx::Resource}] the source => target matches so far
       def match_fetched_residual(sources, targets, matches)
         unmtchd_tgts = targets.to_set - matches.keys.delete_if { |tgt| tgt.identifier }
         unmtchd_srcs = sources.to_set - matches.values
@@ -34,8 +34,8 @@ module CaRuby
         matches.merge!(min_mtchs)
       end
       
-      #@param [<Resource>] sources the source objects to match
-      #@param [<Resource>] targets the potential match target objects
+      #@param [<Jinx::Resource>] sources the source objects to match
+      #@param [<Jinx::Resource>] targets the potential match target objects
       # @return (see #match_saved)
       def match_minimal(sources, targets)
         matches = {}

data/lib/caruby/database/sql_executor.rb

@@ -1,10 +1,5 @@
-require 'rubygems'
-gem 'dbi'
-
-require 'dbi'
-require 'caruby/util/options'
-require 'caruby/util/log'
-require 'caruby/domain/properties'
+require 'jinx/helpers/options'
+require 'caruby/rdbi/driver/jdbc'
 
 module CaRuby
   # SQLExecutor executes an SQL statement against the database.
@@ -23,19 +18,22 @@ module CaRuby
     # The default database driver class is +com.mysql.jdbc.Driver+ for MySQL,
     # +oracle.jdbc.OracleDriver+ for Oracle.
     #
+    # The default database URI is +dbi:+_db_driver_+://+_db_host_+:+_db_port_+/+_db_name_.
+    #
     # @param [Hash] opts the connect options
     # @option opts [String] :database the mandatory database name
     # @option opts [String] :database_user the mandatory database username (not the application login name)
     # @option opts [String] :database_password the optional database password (not the application login password)
     # @option opts [String] :database_host the optional database host
     # @option opts [Integer] :database_port the optional database port number
-    # @option opts [String] :database_type the optional DBI database type, e.g. +mysql+
+    # @option opts [Integer] :database_port the optional database port number
     # @option opts [String] :database_driver the optional DBI connect driver string, e.g. +jdbc:mysql+
+    # @option opts [String] :database_url the optional database connection URL
     # @option opts [String] :database_driver_class the optional DBI connect driver class name
     # @raise [CaRuby::ConfigurationError] if an option is invalid
     def initialize(opts)
       if opts.empty? then
-        raise CaRuby::ConfigurationError.new("The caRuby database connection properties were not found.") 
+        Jinx.fail(CaRuby::ConfigurationError, "The caRuby database connection properties were not found.") 
       end
       app_host = Options.get(:host, opts, 'localhost')
       db_host = Options.get(:database_host, opts, app_host)
@@ -43,7 +41,8 @@ module CaRuby
       db_driver = Options.get(:database_driver, opts) { default_driver_string(db_type) }
       db_port = Options.get(:database_port, opts) { default_port(db_type) }
       db_name = Options.get(:database, opts) { raise_missing_option_exception(:database) }
-      @address = "dbi:#{db_driver}://#{db_host}:#{db_port}/#{db_name}"
+      @db_url = Options.get(:database_url, opts) { "#{db_driver}://#{db_host}:#{db_port}/#{db_name}" }
+      @dbi_url = 'dbi:' + @db_url
       @username = Options.get(:database_user, opts) { raise_missing_option_exception(:database_user) }
       @password = Options.get(:database_password, opts)
       @driver_class = Options.get(:database_driver_class, opts, default_driver_class(db_type))
@@ -56,16 +55,56 @@ module CaRuby
         :database_port => db_port,
         :database_driver => db_driver,
         :database_driver_class => @driver_class,
-        :address => @address
+        :database_url => @db_url
       }
       logger.debug { "Database connection parameters (excluding password): #{eff_opts.qp}" }
     end
 
     # Connects to the database, yields the DBI handle to the given block and disconnects.
     #
-    # @return [Array] the execution result
+    # @yield [dbh] the transaction statements
+    # @yieldparam [RDBI::Database] dbh the database handle
     def execute
-      DBI.connect(@address, @username, @password, 'driver'=> @driver_class) { |dbh| yield dbh }
+      RDBI.connect(:JDBC, :database => @db_url, :user => @username, :password => @password, :driver_class=> @driver_class) do |dbh|
+        yield dbh
+      end
+    end
+
+    # Runs the given query.
+    #
+    # @param [String] sql the SQL to execute
+    # @param [Array] args the SQL bindings
+    # @return [Array] the query result
+    def query(sql, *args)
+      fetched = nil
+      execute do |dbh|
+        res = dbh.execute(sql, *args)
+        fetched = res.fetch(:all)
+        res.finish
+      end
+      fetched
+    end
+
+    # Runs the given SQL or block in a transaction. If SQL is provided, then that
+    # SQL is executed. Otherwise, the block is called.
+    #
+    # @quirk RDBI RDBI converts nil args to 12. Work-around this bug by embedding
+    #   +NULL+ in the SQL instead.
+    #
+    # @param [String] sql the SQL to execute
+    # @param [Array] args the SQL bindings
+    # @yield [dbh] the transaction statements
+    # @yieldparam [RDBI::Database] dbh the database handle
+    def transact(sql=nil, *args)
+      # Work-around for rcbi nil substitution.
+      if sql then
+        sql, *args = replace_nil_binds(sql, args)
+        transact { |dbh| dbh.execute(sql, *args) }
+      elsif block_given? then
+        execute { |dbh| dbh.transaction { yield dbh } }
+      else
+        raise ArgumentError.new("SQL executor is missing the required execution block")
+      end
     end
 
     private
@@ -73,12 +112,44 @@ module CaRuby
     MYSQL_DRIVER_CLASS_NAME = 'com.mysql.jdbc.Driver'
     
     ORACLE_DRIVER_CLASS_NAME = 'oracle.jdbc.OracleDriver'
+    
+    # Replaces nil arguments with a +NULL+ literal in the given SQL.
+    # 
+    # @param (see #transact)
+    # @return [Array] the (possibly modified) SQL followed by the non-nil arguments
+    def replace_nil_binds(sql, args)
+      nils = []
+      args.each_with_index { |value, i| nils << i if value.nil? }
+      unless nils.empty? then
+        logger.debug { "SQL executor working around RDBI bug by eliminating the nil arguments #{nils.to_series} for the SQL:\n#{sql}..." }
+        # Quoted ? is too much of a pain for this hack; bail out.
+        raise ArgumentError.new("RDBI work-around does not support quoted ? in transactional SQL: #{sql}") if sql =~ /'[^,]*[?][^,]*'/
+        prefix, binds_s, suffix = /(.+\s*values\s*\()([^)]*)(\).*)/i.match(sql).captures
+        sql = prefix
+        binds = binds_s.split('?')
+        last = binds_s[-1, 1]
+        del_cnt = 0
+        binds.each_with_index do |s, i|
+          sql << s
+          if nils.include?(i) then
+            args.delete_at(i - del_cnt)
+            del_cnt += 1
+            sql << 'NULL'
+          elsif i < binds.size - 1 or last == '?'
+            sql << '?'
+          end
+        end
+        sql << suffix
+      end
+      logger.debug { "SQL executor converted the SQL to:\n#{sql}\nwith arguments #{args.qp}" }
+      return args.unshift(sql)
+    end
 
     def default_driver_string(db_type)
       case db_type.downcase
         when 'mysql' then 'Jdbc:mysql'
         when 'oracle' then 'Oracle'
-        else raise CaRuby::ConfigurationError.new("Default database connection driver string could not be determined for database type #{db_type}")
+        else Jinx.fail(CaRuby::ConfigurationError, "Default database connection driver string could not be determined for database type #{db_type}")
       end
     end
     
@@ -86,7 +157,7 @@ module CaRuby
       case db_type.downcase
         when 'mysql' then MYSQL_DRIVER_CLASS_NAME
         when 'oracle' then ORACLE_DRIVER_CLASS_NAME
-        else raise CaRuby::ConfigurationError.new("Default database connection driver class could not be determined for database type #{db_type}")
+        else Jinx.fail(CaRuby::ConfigurationError, "Default database connection driver class could not be determined for database type #{db_type}")
       end
     end
 
@@ -94,12 +165,12 @@ module CaRuby
       case db_type.downcase
         when 'mysql' then 3306
         when 'oracle' then 1521
-        else raise CaRuby::ConfigurationError.new("Default database connection port could not be determined for database type #{db_type}")
+        else Jinx.fail(CaRuby::ConfigurationError, "Default database connection port could not be determined for database type #{db_type}")
       end
     end
 
     def raise_missing_option_exception(option)
-      raise CaRuby::ConfigurationError.new("Database connection property not found: #{option}")
+      Jinx.fail(CaRuby::ConfigurationError, "Database connection property not found: #{option}")
     end
   end
 end

data/lib/caruby/database/writer.rb

@@ -1,8 +1,10 @@
-require 'caruby/util/collection'
-require 'caruby/util/pretty_print'
-require 'caruby/domain/reference_visitor'
+require 'jinx/helpers/collection'
+require 'jinx/helpers/pretty_print'
+require 'jinx/resource/reference_visitor'
+require 'jinx/resource/match_visitor'
+require 'jinx/resource/merge_visitor'
 require 'caruby/database/saved_matcher'
-require 'caruby/database/store_template_builder'
+require 'caruby/database/writer_template_builder'
 
 module CaRuby
   class Database
@@ -11,23 +13,23 @@ module CaRuby
       # Adds store capability to this Database.
       def initialize
         super
-        @ftchd_vstr = ReferenceVisitor.new { |tgt| tgt.class.fetched_domain_attributes }
-        @cr_tmpl_bldr = StoreTemplateBuilder.new(self) { |ref| creatable_domain_attributes(ref) }
-        @upd_tmpl_bldr = StoreTemplateBuilder.new(self) { |ref| updatable_domain_attributes(ref) }
+        @ftchd_vstr = Jinx::ReferenceVisitor.new { |tgt| tgt.class.fetched_domain_attributes }
+        @cr_tmpl_bldr = TemplateBuilder.new(self) { |ref| creatable_domain_attributes(ref) }
+        @upd_tmpl_bldr = TemplateBuilder.new(self) { |ref| updatable_domain_attributes(ref) }
         # the save result => argument reference matcher
         svd_mtchr = SavedMatcher.new
         # the save (result, argument) synchronization visitor
-        @svd_sync_vstr = MatchVisitor.new(:matcher => svd_mtchr) { |ref| ref.class.dependent_attributes }
+        @svd_sync_vstr = Jinx::MatchVisitor.new(:matcher => svd_mtchr) { |ref| ref.class.dependent_attributes }
         # the attributes to merge from the save result
         mgbl = Proc.new { |ref| ref.class.domain_attributes }
         # the save result => argument merge visitor
-        @svd_mrg_vstr = MergeVisitor.new(:matcher => svd_mtchr, :mergeable => mgbl) { |ref| ref.class.dependent_attributes }
+        @svd_mrg_vstr = Jinx::MergeVisitor.new(:matcher => svd_mtchr, :mergeable => mgbl) { |ref| ref.class.dependent_attributes }
       end
 
       # Creates the specified domain object obj and returns obj. The pre-condition for this method is as
       # follows:
       # * obj is a well-formed domain object with the necessary required attributes as determined by the
-      #   {Resource#validate} method
+      #   {Jinx::Resource#validate} method
       # * obj does not have a database identifier attribute value
       # * obj does not yet exist in the database
       # The post-condition is that obj is created and assigned a database identifier.
@@ -55,8 +57,8 @@ module CaRuby
       #   owner.dependents.size == dependents_count #=> true
       #
       # If obj is not dependent, then the create strategy is as follows:
-      # * add default attribute values using {Resource#add_defaults}
-      # * validate obj using {Resource#validate}
+      # * add default attribute values using {Jinx::Resource#add_defaults}
+      # * validate obj using {Jinx::Resource#validate}
       # * ensure that all saved independent reference attribute values exist in the database, creating
       #   them if necessary
       # * ensure that all dependent reference attribute values can be created according to this set of rules
@@ -66,16 +68,16 @@ module CaRuby
       # * copy the new database identifier to each created object, i.e. the transitive closure of obj and
       #   its dependents
       #
-      # @param [Resource] the domain object to create
-      # @return [Resource] obj
+      # @param [Jinx::Resource] the domain object to create
+      # @return [Jinx::Resource] obj
       # @raise [DatabaseError] if the database operation fails
       def create(obj)
         # guard against recursive call back into the same operation
         # the only allowed recursive call is a dependent create which first creates the owner
         if recursive_save?(obj, :create) then
-          raise DatabaseError.new("Create #{obj.qp} recursively called in context #{print_operations}")
+          Jinx.fail(DatabaseError, "Create #{obj.qp} recursively called in context #{print_operations}")
         elsif obj.identifier then
-          raise DatabaseError.new("Create unsuccessful since #{obj.qp} already has identifier #{obj.identifier}")
+          Jinx.fail(DatabaseError, "Create unsuccessful since #{obj.qp} already has identifier #{obj.identifier}")
         end
         # create the object
         perform(:create, obj) { create_object(obj) }
@@ -90,11 +92,12 @@ module CaRuby
       # * validate that obj has a database identifier
       # * the template is submitted to the application service update method
       #
-      # Raises DatabaseError if the database operation fails.
+      # @param [Jinx::Resource] the object to update
+      # @raise [DatabaseError] if the database operation fails
       def update(obj)
         # guard against a recursive call back into the same operation.
         if recursive_save?(obj, :update) then
-          raise DatabaseError.new("Update #{obj.qp} recursively called in context #{print_operations}")
+          Jinx.fail(DatabaseError, "Update #{obj.qp} recursively called in context #{print_operations}")
         end
         # update the object
         perform(:update, obj) { update_object(obj) }
@@ -109,8 +112,8 @@ module CaRuby
       # @see #create 
       # @see #update
       #
-      #@param [Resource] obj the domain object to save
-      # @return [Resource] obj
+      #@param [Jinx::Resource] obj the domain object to save
+      # @return [Jinx::Resource] obj
       # @raise [DatabaseError] if the database operation fails
       def save(obj)
         logger.debug { "Saving #{obj}..." }
@@ -125,7 +128,7 @@ module CaRuby
       # Note that some applications restrict or forbid delete operations. Check the specific application
       # documentation to determine whether deletion is supported.
       #
-      # @param [Resource] obj the domain object to delete
+      # @param [Jinx::Resource] obj the domain object to delete
       # @raise [DatabaseError] if the database operation fails
       def delete(obj)
         perform(:delete, obj) { delete_object(obj) }
@@ -133,51 +136,61 @@ module CaRuby
 
       # Creates the domain object obj, if necessary.
       #
-      # @param [Resource, <Resource>] obj the domain object or collection of domain objects to find or create 
+      # @param [Jinx::Resource, <Jinx::Resource>] obj the domain object or collection of domain objects to find or create 
       # @raise [ArgumentError] if obj is nil or empty
       # @raise [DatabaseError] if obj could not be created
       def ensure_exists(obj)
-        raise ArgumentError.new("Database ensure_exists is missing a domain object argument") if obj.nil_or_empty?
+        Jinx.fail(ArgumentError, "Database ensure_exists is missing a domain object argument") if obj.nil_or_empty?
         obj.enumerate { |ref| find(ref, :create) unless ref.identifier }
         
       end
 
       private
       
-      # Returns whether there is already the given object operation in progress that is not in the scope of
-      # an operation performed on a dependent obj owner, i.e. a second obj save operation of the same type
-      # is only allowed if the obj operation was delegated to an owner save which in turn saves the dependent
-      # obj.
+      # Returns whether the given operation is already in progress on the same object.
+      # The operation is only allowed if it is in the scope of a dependent owner
+      # operation of the same type.
+      #
+      # For example, if a StudyEvent is owned by a Study, then the following is allowed:
+      #   create StudyEvent
+      #   ...
+      #   create Study
+      #   ...
+      #   create StudyEvent
+      # 
+      # same type on the same dependent is only allowed if the precursor operation was delegated to an owner save which
+      # in turn saves the dependent.
       #
-      # @param [Resource] obj the domain object to save
+      # @param [Jinx::Resource] obj the domain object to save
       # @param [Symbol] operation the +:create+ or +:update+ save operation
       # @return [Boolean] whether the save operation is redundant
       def recursive_save?(obj, operation)
         @operations.any? { |op| op.type == operation and op.subject == obj } and
-          not obj.owner_ancestor?(@operations.last.subject)
+          not obj.owner_ancestor?(@operations.last.subject) and
+          not obj.dependent_update_only?(@operations.last.subject)
       end
       
-      # Creates obj as follows:
+      # Creates the given object as follows:
       # * if obj has an uncreated owner, then store the owner, which in turn will create a physical dependent
-      # * otherwise, create a storable template. The template is a copy of obj containing a recursive copy
+      # * otherwise, create a savable template. The template is a copy of obj containing a recursive copy
       #   of each saved obj reference and resolved independent references
       # * submit the template to the create application service
       # * update the obj dependency transitive closure content from the create result
       # * add a lazy-loader to obj for unfetched domain references
       #
       # @param (see #create)
-      # @return [Resource] obj
+      # @return [Jinx::Resource] obj
       def create_object(obj)
         # add obj to the transients set
         @transients << obj
         begin
           # A dependent is created by saving the owner.
           # Otherwise, create the object from a template.
-          owner = cascaded_owner(obj)
+          owner = cascaded_dependent_owner(obj)
           result = create_dependent(owner, obj) if owner
           result ||= create_from_template(obj)
           if result.nil? then
-            raise DatabaseError.new("#{obj.class.qp} is not creatable in context #{print_operations}")
+            Jinx.fail(DatabaseError, "#{obj.class.qp} is not creatable in context #{print_operations}")
           end
         ensure
           # since obj now has an id, removed from transients set
@@ -194,8 +207,8 @@ module CaRuby
       # A logical dependent is created by its parent unless the parent already exists.
       # If the logical parent exists, then dep must be created.
       #
-      #@param [Resource] dep the dependent domain object to create
-      # @return [Resource] dep
+      # @param [Jinx::Resource] dep the dependent domain object to create
+      # @return [Jinx::Resource] dep
       def create_dependent(owner, dep)
         if owner.identifier.nil? then
           logger.debug { "Adding #{owner.qp} dependent #{dep.qp} defaults..." }
@@ -211,22 +224,29 @@ module CaRuby
 
         # If there is a saver proxy, then use the proxy.
         if dep.class.method_defined?(:saver_proxy) then
-          save_with_proxy(dep)
-          # remove obj from transients to clear previous fetch, if any
-          @transients.delete(dep)
-          logger.debug { "Fetching #{dep.qp} to reflect the proxy save..." }
-          find(dep)
+          saved = save_with_proxy(dep)
+          if saved then
+            # remove obj from transients to clear previous fetch, if any
+            @transients.delete(dep)
+            logger.debug { "Fetching #{dep.qp} to reflect the proxy save..." }
+            find(dep)
+          end
+          dep
         end
       end
      
       # Saves the given domain object using a proxy.
       #
-      # @param [Resource] obj the proxied domain object
-      # @return [Resource] obj
+      # @param [Jinx::Resource] obj the proxied domain object
+      # @return [Jinx::Resource] obj
       # @raise [DatabaseError] if obj does not have a proxy
       def save_with_proxy(obj)
         proxy = obj.saver_proxy
-        if proxy.nil? then raise DatabaseError.new("#{obj.class.qp} does not have a proxy") end
+        if proxy.nil? then Jinx.fail(DatabaseError, "#{obj.class.qp} does not have a proxy") end
+        if recursive_save?(proxy, :create) then
+          logger.debug { "Foregoing #{obj.qp} save, since it  will be handled by creating the proxy #{proxy}." }
+          return
+        end
         logger.debug { "Saving #{obj.qp} by creating the proxy #{proxy}..." }
         create(proxy)
         logger.debug { "Created the #{obj.qp} proxy #{proxy}." }
@@ -235,17 +255,18 @@ module CaRuby
         obj
       end
 
-      # Creates obj by submitting a template to the persistence service. Ensures that the domain
-      # objects referenced by the created obj exist and are correctly stored.
+      # Creates the given domain object by submitting a template to the persistence service.
+      # This method ensures that the domain objects referenced by the created object exist
+      # and are correctly stored.
       #
       # @quirk caCORE submitting the object directly for create runs into various caTissue bizlogic
       #   traps, e.g. Participant CPR is not cascaded but Participant bizlogic checks that each CPR
       #   referenced by Participant is ready to be created. It is treacherous to make assumptions
       #   about what caTissue bizlogic will or will not check. Therefore, the safer strategy is to
-      #   build a template for submission that includes only the object cascaded and direct
-      #   non-cascaded independent references. The independent references are created if necessary.
-      #   The template thus includes only as much content as can safely pass through the caTissue
-      #   bizlogic minefield.
+      #   build a template for submission that includes only the cascaded and direct non-cascaded
+      #   independent references. The independent references are created if necessary. The template
+      #   thus includes only as much content as can safely pass through the caTissue bizlogic
+      #   minefield.
       #
       # @quirk caCORE caCORE create does not update the submitted object to reflect the created
       #   content. The create result is a separate object, which in turn does not always reflect
@@ -295,43 +316,45 @@ module CaRuby
       def build_create_template(obj)
         build_save_template(obj, @cr_tmpl_bldr)
       end
-#
+
       # @quirk caCORE application create logic might ignore a non-domain attribute value,
-      # e.g. the caTissue StorageContainer auto-generated name attribute. In other cases, the application
-      # always ignores a non-domain attribute value, so the object should not be saved even if it differs
-      # from the stored result, e.g. the caTissue CollectionProtocolRegistration unsaved
-      # registration_date. The work-around is to check whether the create result
-      # differs from the create argument for the auto-generated updatable attributes, and, if so,
-      # to update the saved object.
-      #
-      # This method returns whether the saved obj differs from the stored source for any
-      # {Attributes#autogenerated_nondomain_attributes}.
-      #
-      # @param [Resource] the created domain object
-      # @param [Resource] the stored database content source domain object
-      # @return [Boolean] whether obj differs from the source on the the non-domain attributes
+      # e.g. the caTissue StorageContainer auto-generated name attribute. In other cases,
+      # the application always ignores a non-domain attribute value, e.g. the caTissue
+      # CollectionProtocolRegistration registration_date. The work-around is to
+      # check whether the create result differs from the create argument for the
+      # {Propertied#autogenerated_nondomain_attributes}, and, if so, to perform an update
+      # on the save argument.
+      #
+      # This method returns whether the save result differs from the save source for any
+      # {Propertied#autogenerated_nondomain_attributes}.
+      #
+      # @param [Jinx::Resource] obj the save argument
+      # @param [Jinx::Resource] source the save result
+      # @return [Boolean] whether the save result differs from the save source on the
+      #   autogenerated non-domain attributes
       def update_saved?(obj, source)
-        obj.class.autogenerated_nondomain_attributes.any? do |attr|
-          intended = obj.send(attr)
-          stored = source.send(attr)
+        obj.class.autogenerated_nondomain_attributes.any? do |pa|
+          intended = obj.send(pa)
+          stored = source.send(pa)
           if intended != stored then
-            logger.debug { "Saved #{obj.qp} #{attr} value #{intended} differs from result value #{stored}..." }
+            logger.debug { "Saved #{obj.qp} #{pa} value #{intended} differs from result value #{stored}..." }
+            true
           end
         end
       end
       
-      # Returns the {MetadataAttributes#creatable_domain_attributes} which are not contravened by a
-      # one-to-one independent pending create.
+      # Returns the {MetadataPropertied#creatable_domain_attributes} which are not contravened
+      # by a one-to-one independent pending create.
       # 
       # @param (see #create)
       # @return [<Symbol>] the attributes to include in the create template
       def creatable_domain_attributes(obj)
         # filter the creatable attributes
-        obj.class.creatable_domain_attributes.compose do |attr_md|
-          if exclude_pending_create_attribute?(obj, attr_md) then
+        obj.class.creatable_domain_attributes.compose do |pa|
+          if exclude_pending_create_attribute?(obj, pa) then
             # Avoid printing duplicate log message.
             if obj != @cr_dom_attr_log_obj then
-              logger.debug { "Excluded #{obj.qp} #{attr_md} in the create template since it references a 1:1 bidirectional independent pending create." }
+              logger.debug { "Excluded #{obj.qp} #{pa} in the create template since it references a 1:1 bidirectional independent pending create." }
               @cr_dom_attr_log_obj = obj
             end
             false
@@ -343,24 +366,24 @@ module CaRuby
       
       # Returns whether the given creatable domain attribute with value obj satisfies
       # each of the following conditions:
-      # * the attribute is {Attribute#independent?}
-      # * the attribute is not an {Attribute#owner?}
+      # * the attribute is {Property#independent?}
+      # * the attribute is not an {Property#owner?}
       # * the obj value is unsaved
       # * the attribute is not mandatory
       # * the attribute references a {#pending_create?} save context.
       #
       # @param obj (see #create)
-      # @param [Attribute] attr_md the candidate attribute metadata
+      # @param [Property] pa the candidate attribute metadata
       # @return [Boolean] whether the attribute should not be included in the create template
-      def exclude_pending_create_attribute?(obj, attr_md)
-        attr_md.independent? and
-          not attr_md.owner? and
+      def exclude_pending_create_attribute?(obj, pa)
+        pa.independent? and
+          not pa.owner? and
           obj.identifier.nil? and
-          not obj.mandatory_attributes.include?(attr_md.to_sym) and
-          exclude_pending_create_value?(obj.send(attr_md.to_sym))
+          not obj.mandatory_attributes.include?(pa.to_sym) and
+          exclude_pending_create_value?(obj.send(pa.to_sym))
       end
       
-      # @param [Resource, <Resource>, nil] value the referenced value
+      # @param [Jinx::Resource, <Jinx::Resource>, nil] value the referenced value
       # @return [Boolean] whether the value includes a {#pending_create?} save context object
       def exclude_pending_create_value?(value)
         return false if value.nil?
@@ -371,7 +394,7 @@ module CaRuby
         end
       end
       
-      # @param [Resource] obj the object to check
+      # @param [Jinx::Resource] obj the object to check
       # @return [Boolean] whether the penultimate create operation is on the object
       def pending_create?(obj)
         op = penultimate_create_operation
@@ -384,7 +407,7 @@ module CaRuby
         nil
       end
       
-      # Returns the {MetadataAttributes#updatable_domain_attributes}.
+      # Returns the {MetadataPropertied#updatable_domain_attributes}.
       # 
       # @param (see #update)
       # @return the attributes to include in the update template
@@ -396,49 +419,39 @@ module CaRuby
       def update_object(obj)
         # database identifier is required for update
         if obj.identifier.nil? then
-          raise DatabaseError.new("Update target is missing a database identifier: #{obj}")
+          Jinx.fail(DatabaseError, "Update target is missing a database identifier: #{obj}")
         end
         
-        # if this object is proxied, then delegate to the proxy
+        # If this object is proxied, then delegate to the proxy.
         if obj.class.method_defined?(:saver_proxy) then
           return save_with_proxy(obj)
         end
         
-        # if a changed dependent is saved with a proxy, then update that dependent first
+        # If a changed dependent is saved with a proxy, then update that dependent first.
         proxied = updatable_proxied_dependents(obj)
         unless proxied.empty? then
           proxied.each { |dep| update(dep) }
         end
         
-        # update a cascaded dependent by updating the owner
-        owner = cascaded_owner(obj)
+        # Update a cascaded dependent by updating the owner.
+        owner = cascaded_dependent_owner(obj)
         if owner then return update_cascaded_dependent(owner, obj) end
-
-        # Not cascaded dependent; update using a template,
-        tmpl = build_update_template(obj)
-        # call the caCORE service with an obj update template
-        save_with_template(obj, tmpl) { |svc| svc.update(tmpl) }
-        # take a snapshot of the updated content
-        obj.take_snapshot
+        # Not a cascaded dependent; update using a template.
+        update_from_template(obj)
       end
       
-      # Returns the owner that can cascade update to the given object.
-      # The owner is the #{Resource#effective_owner_attribute} value
-      # for which the owner attribute {Attribute#inverse_metadata}
-      # is {Attribute#cascaded?}.
+      # Returns the owner that can cascade update to the given object. The owner is the
+      # {Jinx::Resource#effective_owner_attribute} value for which the owner attribute
+      # {Property#inverse_property} is {Property#cascaded?}.
       # 
-      # @param [Resource] obj the domain object to update
-      # @return [Resource, nil] the owner which can cascade an update to the object, or nil if none
+      # @param [Jinx::Resource] obj the domain object to update
+      # @return [Jinx::Resource, nil] the owner which can cascade an update to the object, or nil if none
       # @raise [DatabaseError] if the domain object is a cascaded dependent but does not have an owner
-      def cascaded_owner(obj)
-        return unless obj.class.cascaded_dependent?
-        # the owner attribute
-        oattr = obj.effective_owner_attribute
-        if oattr.nil? then raise DatabaseError.new("Dependent #{obj} does not have an owner") end
-        dep_md = obj.class.attribute_metadata(oattr).inverse_metadata
-        if dep_md and dep_md.cascaded? then
-          obj.send(oattr)
-        end
+      def cascaded_dependent_owner(obj)
+        # the owner attribute and value
+        op, oref = obj.effective_owner_property_value || return
+        dp = op.inverse_property
+        oref if dp and dp.cascaded?
       end
       
       def update_cascaded_dependent(owner, obj)
@@ -477,14 +490,14 @@ module CaRuby
       #     must be created via the proxy after the Specimen is created.
       #
       # @param (see #update)
-      # @return [<Resource>] the #{Attributes#proxied_savable_template_attributes} dependents
+      # @return [<Jinx::Resource>] the #{Propertied#proxied_savable_template_attributes} dependents
       #   which are #{Persistable#changed?}
       def updatable_proxied_dependents(obj)
-        attrs = obj.class.proxied_savable_template_attributes
-        return Array::EMPTY_ARRAY if attrs.empty?
+        pas = obj.class.proxied_savable_template_attributes
+        return Array::EMPTY_ARRAY if pas.empty?
         deps = []
-        attrs.each do |attr|
-          obj.send(attr).enumerate { |dep| deps << dep if dep.identifier and dep.changed? }
+        pas.each do |pa|
+          obj.send(pa).enumerate { |dep| deps << dep if dep.identifier and dep.changed? }
         end
         deps
       end
@@ -496,8 +509,8 @@ module CaRuby
       end
       
       # @param obj (see #save)
-      # @param [StoreTemplateBuilder] builder the builder to use
-      # @return [Resource] the template to use as the save argument
+      # @param [TemplateBuilder] builder the builder to use
+      # @return [Jinx::Resource] the template to use as the save argument
       def build_save_template(obj, builder)
         builder.build_template(obj)
       end
@@ -507,7 +520,7 @@ module CaRuby
       def delete_object(obj)
         # database identifier is required for delete
         if obj.identifier.nil? then
-          raise DatabaseError.new("Delete target is missing a database identifier: #{obj}")
+          Jinx.fail(DatabaseError, "Delete target is missing a database identifier: #{obj}")
         end
         persistence_service(obj.class).delete_object(obj)
       end
@@ -518,7 +531,7 @@ module CaRuby
       # create method is called on the template. Dependents are saved as well, if necessary.
       #
       # @param obj (see #store)
-      # @param [Resource] template the obj template to submit to caCORE
+      # @param [Jinx::Resource] template the obj template to submit to caCORE
       def save_with_template(obj, template)
         logger.debug { "Saving #{obj.qp} from template:\n#{template.dump}" }
         # dispatch to the application service
@@ -537,15 +550,16 @@ module CaRuby
         result
       end
       
-      # Synchronizes the content of the given saved domain object and the save result source as follows:
-      # 1. The save result source is first synchronized with the database content as necessary.
-      # 2. Then the source is merged into the target.
-      # 3. If the target must be resaved based on the call to {#update_saved?}, then the source
-      #    result is resaved.
-      # 4. Each target dependent which differs from the corresponding source dependent is saved.
-      #
-      # @param [Resource] target the saved domain object
-      # @param [Resource] source the caCORE save result
+      # Synchronizes the content of the given saved argument and result as follows:
+      # 1. The save result is first synchronized with the database content as necessary.
+      # 2. Then the result is merged into the argument.
+      # 3. If the argument must be resaved based on the call to {#update_saved?}, then the
+      #    argument is resaved.
+      # 4. Each argument dependent which differs from the corresponding result dependent
+      #    is saved.
+      #
+      # @param [Jinx::Resource] target the save argument
+      # @param [Jinx::Resource] source the caCORE save result
       def sync_saved(target, source)
         # clear the toxic source attributes
         detoxify(source)
@@ -564,7 +578,7 @@ module CaRuby
         save_changed_dependents(target)
       end
       
-      # Synchronizes the given saved target result source with the database content.
+      # Synchronizes the given save result with the database content.
       # The source is synchronized by {#sync_save_result}.
       #
       # @param (see #sync_saved)
@@ -583,7 +597,7 @@ module CaRuby
       #   the database, the difference induces an update of the reference.
       #
       # @param (see #sync_saved)
-      # @return [Resource] the merged target object
+      # @return [Jinx::Resource] the merged target object
       def merge_saved(target, source)
         logger.debug { "Merging saved result #{source} into saved #{target.qp}..." }
         # Update each saved reference snapshot to reflect the database state and add a lazy loader
@@ -612,33 +626,48 @@ module CaRuby
         return if source == target
         # If the target was created, then refetch and merge the source if necessary to reflect auto-generated
         # non-domain attribute values.
-       if target.identifier.nil? then sync_created_result_object(source) end
+       if target.identifier.nil? then sync_created_result_object(target, source) end
         # If there are auto-generated attributes, then merge them into the save result.
         sync_save_result_references(source, target)
         # Set inverses consistently in the source object graph
         set_inverses(source)
       end
       
-      # Refetches the given create result source if there are any {Attributes#autogenerated_nondomain_attributes}
+      # Refetches the given create result if there are any {#autogenerated_nondomain_attributes}
       # which must be fetched to reflect the database state.
       #
-      # @param source (see #sync_saved)
-      def sync_created_result_object(source)
-        attrs = source.class.autogenerated_nondomain_attributes
-        return if attrs.empty?
-        logger.debug { "Refetch #{source} to reflect auto-generated database content for attributes #{attrs.to_series}..." }
+      # @param (see #sync_save_result)
+      def sync_created_result_object(target, source)
+        pas = nondomain_sync_attributes(target, source)
+        return if pas.empty?
+        logger.debug { "Refetch #{source} to reflect auto-generated database content for attributes #{pas.to_series}..." }
         find(source)
       end
       
-      # Fetches the {#synchronization_attributes} into the given target save result source.
+      # Returns the attributes which must be fetched into the given source prior to a merge with
+      # the save argument target. This default implementation returns the subject class's
+      # {Propertied#autogenerated_nondomain_attributes} if the save is a create, the empty array
+      # otherwise. Subclasses can specialize this method for any special cases that depend on the
+      # instance state.
+      #
+      # @return [<Symbol>] the attributes which must be fetched into the source
+      def nondomain_sync_attributes(target, source)
+        if target.identifier.nil? then
+          source.class.autogenerated_nondomain_attributes
+        else
+          Array::EMPTY_ARRAY
+        end
+      end
+      
+      # Fetches the {#synchronization_attributes} into the given save result.
       #
       # @param (see #sync_saved)
       def sync_save_result_references(source, target)
-        attrs = synchronization_attributes(source, target)
-        return if attrs.empty?
-        logger.debug { "Fetching the saved #{target.qp} attributes #{attrs.to_series} into save result #{source.qp}..." }
-        attrs.each { |attr| sync_save_result_attribute(source, attr) }
-        logger.debug { "Fetched the saved #{target.qp} attributes #{attrs.to_series} into the save result #{source.qp}." }
+        pas = synchronization_attributes(source, target)
+        return if pas.empty?
+        logger.debug { "Fetching the saved #{target.qp} attributes #{pas.to_series} into the save result #{source.qp}..." }
+        pas.each { |pa| sync_save_result_attribute(source, pa) }
+        logger.debug { "Fetched the saved #{target.qp} attributes #{pas.to_series} into the save result #{source.qp}." }
       end
       
       # @see #sync_save_result_references
@@ -646,13 +675,13 @@ module CaRuby
         # fetch the value
         fetched = fetch_association(source, attribute)
         # set the attribute
-        source.set_attribute(attribute, fetched)
+        source.set_property_value(attribute, fetched)
       end
       
-      # Returns the saved target attributes which must be fetched to reflect the database content, consisting
-      # of the following:
-      # * {Persistable#saved_fetch_attributes}
-      # * {Attributes#domain_attributes} which include a source reference without an identifier
+      # Returns the saved target attributes which must be fetched to reflect the database content,
+      # consisting of the following:
+      # * {Persistable#saved_attributes_to_fetch}
+      # * {Propertied#domain_attributes} which include a source reference without an identifier
       #
       # @param (see #sync_saved)
       # @return [<Symbol>] the attributes which must be fetched
@@ -660,63 +689,69 @@ module CaRuby
         # the target save operation
         op = @operations.last
         # the attributes to fetch
-        attrs = target.saved_fetch_attributes(op).to_set
+        pas = target.saved_attributes_to_fetch(op).to_set
         # the pending create, if any
         pndg_op = penultimate_create_operation
         pndg = pndg_op.subject if pndg_op
         # add in the domain attributes whose identifier was not set in the result
-        source.class.saved_domain_attributes.select do |attr|
-          srcval = source.send(attr)
-          tgtval = target.send(attr)
+        source.class.sync_domain_attributes.select do |pa|
+          srcval = source.send(pa)
+          tgtval = target.send(pa)
           if Persistable.unsaved?(srcval) then
-            logger.debug { "Fetching save result #{source.qp} #{attr} since a referenced object identifier was not set in the result..." }
-            attrs << attr
+            logger.debug { "Fetching the save result #{source.qp} #{pa} since a referenced object identifier was not set in the result..." }
+            pas << pa
           elsif srcval.nil_or_empty? and Persistable.unsaved?(tgtval) and tgtval != pndg then
-            logger.debug { "Fetching save result #{source.qp} #{attr} since the target #{target.qp} value #{tgtval.qp} is missing an identifier..." }
-            attrs << attr
+            logger.debug { "Fetching the save result #{source.qp} #{pa} since the target #{target.qp} value #{tgtval.qp} is missing an identifier..." }
+            pas << pa
           end
         end
-        attrs
+        pas
       end
       
       # Saves the given domain object dependents.
       #
-      # @param [Resource] obj the owner domain object
+      # @param [Jinx::Resource] obj the owner domain object
       def save_changed_dependents(obj)
-        obj.class.dependent_attributes.each do |attr|
-          deps = obj.send(attr)
-          logger.debug { "Saving the #{obj} #{attr} dependents #{deps.to_enum.qp(:single_line)} which have changed..." } unless deps.nil_or_empty?
-          deps.enumerate { |dep| save_dependent_if_changed(obj, attr, dep) }
+        obj.class.dependent_attributes.each_property do |prop|
+          deps = obj.dependents(prop)
+          unless deps.nil_or_empty? then
+            logger.debug { "Saving the #{obj} dependents #{deps.to_enum.qp(:single_line)} which have changed..." }
+          end
+          deps.enumerate { |dep| save_dependent_if_changed(obj, prop, dep) }
         end
       end
       
       # Saves the given dependent domain object if necessary.
       # Recursively saves the obj dependents as necessary.
       #
-      # @param [Resource] owner the dependent owner
-      # @param [Symbol] attribute the dependent attribute
-      # @param [Resource] dependent the dependent to save
-      def save_dependent_if_changed(owner, attribute, dependent)
+      # @param [Jinx::Resource] owner the dependent owner
+      # @param [Property] property the dependent property
+      # @param [Jinx::Resource] dependent the dependent to save
+      def save_dependent_if_changed(owner, property, dependent)
+        # If the dependent identifier is missing, then the owner save did not cascade to the
+        # dependent. Create the dependent here.
         if dependent.identifier.nil? then
-          logger.debug { "Creating #{owner.qp} #{attribute} dependent #{dependent.qp}..." }
+          logger.debug { "Creating #{owner.qp} #{property} dependent #{dependent.qp}..." }
           return create(dependent)
         end
+        # Collect the changed attributes.
         changes = dependent.changed_attributes
-        # If the dependent identifier is missing, then the identifier was probably created on demand. 
-        logger.debug { "#{owner.qp} #{attribute} dependent #{dependent.qp} changed for attributes #{changes.to_series}." } unless changes.empty?
-        if changes.any? { |attr| not dependent.class.attribute_metadata(attr).dependent? } then
+        logger.debug { "#{owner.qp} #{property} dependent #{dependent.qp} changed for attributes #{changes.to_series}." } unless changes.empty?
+        # If any changed attribute is a reference to dependents, then check for
+        # special auto-generation handling. Otherwise, simpl save the referenced
+        # dependents.
+        if changes.any? { |pa| not dependent.class.property(pa).dependent? } then
           # the owner save operation
           op = operations.last
           # The dependent is auto-generated if the owner was created or auto-generated and
           # the dependent attribute is auto-generated.
-          attr_md = owner.class.attribute_metadata(attribute)
-          ag = (op.type == :create or op.autogenerated?) && attr_md.autogenerated?
-          logger.debug { "Updating the changed #{owner.qp} #{attribute} dependent #{dependent.qp}..." }
+          ag = (op.type == :create or op.autogenerated?) && property.autogenerated?
+          logger.debug { "Updating the changed #{owner.qp} #{property} dependent #{dependent.qp}..." }
           if ag then
-            logger.debug { "Adding defaults to the auto-generated #{owner.qp} #{attribute} dependent #{dependent.qp}..." }
+            logger.debug { "Adding defaults to the auto-generated #{owner.qp} #{property} dependent #{dependent.qp}..." }
             dependent.add_defaults_autogenerated
           end
-          update_changed_dependent(owner, attribute, dependent, ag)
+          update_changed_dependent(owner, property, dependent, ag)
         else
           save_changed_dependents(dependent)
         end
@@ -725,7 +760,8 @@ module CaRuby
       # Updates the given dependent.
       #
       # @param (see #save_dependent_if_changed)
-      def update_changed_dependent(owner, attribute, dependent, autogenerated)
+      # @param [Boolean] autogenerated flag indicating whether the dependent was auto-generated
+      def update_changed_dependent(owner, property, dependent, autogenerated)
         perform(:update, dependent, :autogenerated => autogenerated) { update_object(dependent) }
       end
     end