caruby-core 1.4.7 → 1.4.9

data/lib/caruby/database/search_template_builder.rb

@@ -4,10 +4,6 @@ require 'caruby/util/pretty_print'
 module CaRuby
   # SearchTemplateBuilder builds a template suitable for a caCORE saarch database operation.
   class SearchTemplateBuilder
-    def initialize(database)
-      @database = database
-    end
-
     # Returns a template for matching the domain object obj and the optional hash values.
     # The default hash attributes are the {ResourceAttributes#searchable_attributes}.
     # The template includes only the non-domain attributes of the hash references.
@@ -42,16 +38,18 @@ module CaRuby
 
     private
 
-    # 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.
+    # 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 [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.
-      writer = template.class.attribute_metadata(attribute).property_accessors.last
-      template.send(writer, ref)
+      wtr = template.class.attribute_metadata(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

data/lib/caruby/database/sql_executor.rb

@@ -13,53 +13,78 @@ module CaRuby
   class SQLExecutor
     # Creates a new SQLExecutor with the given options.
     #
-    # The default :database_host is the application :host property value, which in turn
-    # defaults to 'localhost'.
+    # The default database host is the application :host property value, which in turn
+    # defaults to +localhost+.
     #
-    # The default :database_type is 'mysql'. The optional :database_port property overrides
+    # The default database type is +mysql+. The optional :database_port property overrides
     # the default port for the database type.
     #
-    # The default :database_driver is 'jdbc:mysql' for MySQL or 'Oracle' for Oracle.
+    # The default database driver is +jdbc:mysql+ for MySQL, +Oracle+ for Oracle.
+    # The default database driver class is +com.mysql.jdbc.Driver+ for MySQL,
+    # +oracle.jdbc.OracleDriver+ for Oracle.
     #
-    # @option options [String] :database_host the database host
-    # @option options [String] :database the database name
-    # @option options [Integer] :database_port the database password (not the application login password)
-    # @option options [String] :database_type the DBI database type, e.g. +mysql+
-    # @option options [String] :database_driver the DBI connect driver string, e.g. +jdbc:mysql+
-    # @option options [String] :database_user the database username (not the application login name)
-    # @option options [String] :database_password the database password (not the application login password)
-    # Raises CaRuby::ConfigurationError if an option is invalid.
-    def initialize(options)
-      app_host = Options.get(:host, options, "localhost")
-      db_host = Options.get(:database_host, options, app_host)
-      db_type = Options.get(:database_type, options, "mysql")
-      db_driver = Options.get(:database_driver, options) { default_driver_string(db_type) }
-      db_port = Options.get(:database_port, options) { default_port(db_type) }
-      db_name = Options.get(:database, options) { raise_missing_option_exception(:database) }
+    # @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 [String] :database_driver the optional DBI connect driver string, e.g. +jdbc:mysql+
+    # @option opts [String] :database_driver_class the optional DBI connect driver class name
+    # @raise [CaRuby::ConfigurationError] if an option is invalid
+    def initialize(opts)
+      app_host = Options.get(:host, opts, 'localhost')
+      db_host = Options.get(:database_host, opts, app_host)
+      db_type = Options.get(:database_type, opts, 'mysql')
+      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}"
-      @username = Options.get(:database_user, options) { raise_missing_option_exception(:database_user) }
-      @password = Options.get(:database_password, options) { raise_missing_option_exception(:database_password) }
+      @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))
+      # The effective connection options.
+      eff_opts = {
+        :database => db_name,
+        :database_host => db_host,
+        :database_user => @username,
+        :database_type => db_type,
+        :database_port => db_port,
+        :database_driver => db_driver,
+        :database_driver_class => @driver_class
+      }      
+      logger.debug { "Database connection options (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
     def execute
-      logger.debug { "Connecting to database with user #{@username}, address #{@address}..." }
-      result = DBI.connect(@address, @username, @password, "driver"=>"com.mysql.jdbc.Driver") { |dbh| yield dbh }
-      logger.debug { "Disconnected from the database." }
-      result
+      DBI.connect(@address, @username, @password, 'driver'=> @driver_class) { |dbh| yield dbh }
     end
 
     private
+    
+    MYSQL_DRIVER_CLASS_NAME = 'com.mysql.jdbc.Driver'
+    
+    ORACLE_DRIVER_CLASS_NAME = 'oracle.jdbc.OracleDriver'
 
     def default_driver_string(db_type)
       case db_type.downcase
-        when 'mysql' then 'jdbc:mysql'
+        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}")
       end
     end
+    
+    def default_driver_class(db_type)
+      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}")
+      end
+    end
 
     def default_port(db_type)
       case db_type.downcase
@@ -70,7 +95,7 @@ module CaRuby
     end
 
     def raise_missing_option_exception(option)
-      raise CaRuby::ConfigurationError.new("database connection property not found: #{option}")
+      raise CaRuby::ConfigurationError.new("Database connection property not found: #{option}")
     end
   end
 end

data/lib/caruby/database/store_template_builder.rb

@@ -113,11 +113,11 @@ module CaRuby
     
     # Returns the attributes to visit in building the template for the given
     # domain object. The visitable attributes consist of the following:
-    # * The {ResourceAttributes#unproxied_cascaded_attributes} filtered as follows:
+    # * The {ResourceAttributes#unproxied_save_template_attributes} filtered as follows:
     #   * If the database operation is a create, then exclude the cascaded attributes.
     #   * If the given object has an identifier, then exclude the attributes which
     #     have the the :no_cascade_update_to_create flag set.
-    # * The {ResourceAttributes#proxied_cascaded_attributes} are included if and
+    # * The {ResourceAttributes#proxied_save_template_attributes} are included if and
     #   only if every referenced object has an identifier, and therefore does not
     #   need to be proxied.
     #
@@ -130,15 +130,16 @@ module CaRuby
     # @return [<Symbol>] the reference attributes to include in the update template
     def savable_cascaded_attributes(obj)
       # The starting set of candidate attributes is the unproxied cascaded references.
-      unproxied = savable_attributes(obj, obj.class.unproxied_cascaded_attributes)
+      unproxied = savable_attributes(obj, obj.class.unproxied_save_template_attributes)
       # The proxied attributes to save.
       proxied = savable_proxied_attributes(obj)
       # The combined set of savable attributes
       proxied.empty? ? unproxied : unproxied + proxied
     end
     
-    # Composes the given attributes, if necessary, to exclude attributes as follows:
-    # * If the save operation is a create, then exclude the auto-generated attributes.
+    # Filters the given attributes, if necessary, to exclude attributes as follows:
+    # * If the save operation is a create, then exclude the
+    #   {AttributeMetadata#autogenerated_on_create?} attributes.
     #
     # @param [Resource] obj the visited domain object
     # @param [ResourceAttributes::Filter] the savable attribute filter
@@ -148,7 +149,7 @@ module CaRuby
       return attributes if @subject.identifier
       # This is a create: ignore the optional auto-generated attributes.
       mas = obj.mandatory_attributes.to_set
-      attributes.compose { |attr_md| mas.include?(attr_md.to_sym) or not attr_md.autogenerated? }
+      attributes.compose { |attr_md| mas.include?(attr_md.to_sym) or not attr_md.autogenerated_on_create? }
     end
     
     # Composes the given attributes, if necessary, to exclude attributes as follows:
@@ -177,7 +178,7 @@ module CaRuby
     def savable_proxied_attributes(obj)
       # Include a proxied reference only if the proxied dependents have an identifier,
       # since those without an identifer are created separately via the proxy.
-      obj.class.proxied_cascaded_attributes.reject do |attr|
+      obj.class.proxied_save_template_attributes.reject do |attr|
         ref = obj.send(attr)
         case ref
           when Enumerable then ref.any? { |dep| not dep.identifier }
@@ -199,7 +200,7 @@ module CaRuby
     # references via the proxy create before building the update template.
     def copy_proxied_save_references(obj, template)
       return unless obj.identifier
-      obj.class.proxied_cascaded_attributes.each do |attr|
+      obj.class.proxied_save_template_attributes.each do |attr|
         # the proxy source
         ref = obj.send(attr)
         case ref
@@ -253,20 +254,24 @@ module CaRuby
           # add qualified prerequisite attribute references
           stbl.send(attr).enumerate do |ref|
             # Add the prerequisite if it satisfies the prerequisite? condition.
-            prereqs << ref if prerequisite?(ref, obj)
+            prereqs << ref if prerequisite?(ref, obj, attr)
           end
         end
-      end
+      end    
       prereqs
     end
     
-    # A referenced object is a target object save prerequisite if is the target object, was already created
-    # or is in an immediate or recursive dependent of the target object.
+    # A referenced object is a target object save prerequisite if none of the follwing is true:
+    # * it is the target object
+    # * it was already created
+    # * it is in an immediate or recursive dependent of the target object
+    # * the current save operation is in the context of creating the referenced object
     #
     # @param [Resource] ref the reference to check
     # @param [Resource] obj the object being stored
+    # @param [Symbol] attribute the reference attribute
     # @return [Boolean] whether the reference should exist before storing the object
-    def prerequisite?(ref, obj)
+    def prerequisite?(ref, obj, attribute)
       not (ref == obj or ref.identifier or ref.owner_ancestor?(obj))
     end
   end

data/lib/caruby/database/writer.rb

@@ -113,7 +113,7 @@ module CaRuby
       # @return [Resource] obj
       # @raise [DatabaseError] if the database operation fails
       def save(obj)
-        logger.debug { "Storing #{obj}..." }
+        logger.debug { "Saving #{obj}..." }
         # if obj exists then update it, otherwise create it
         exists?(obj) ? update(obj) : create(obj)
       end
@@ -140,8 +140,10 @@ module CaRuby
         raise ArgumentError.new("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 obj operation in progress that is not in the scope of
+      # 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.
@@ -153,9 +155,7 @@ module CaRuby
         @operations.any? { |op| op.type == operation and op.subject == obj } and
           not obj.owner_ancestor?(@operations.last.subject)
       end
-
-      private
-
+      
       # Creates obj 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
@@ -170,11 +170,14 @@ module CaRuby
         # add obj to the transients set
         @transients << obj
         begin
-          # A dependent of an uncreated owner can be created by creating the owner.
-          # Otherwise, create obj from a template.
-          create_as_dependent(obj) or
-            create_from_template(obj) or
+          # A dependent is created by saving the owner.
+          # Otherwise, create the object from a template.
+          owner = cascaded_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}")
+          end
         ensure
           # since obj now has an id, removed from transients set
           @transients.delete(obj)
@@ -192,18 +195,16 @@ module CaRuby
       #
       #@param [Resource] dep the dependent domain object to create
       # @return [Resource] dep
-      def create_as_dependent(dep)
-        # bail if not dependent or owner is not set
-        ownr = dep.owner || return
-        unless ownr.identifier then
-          logger.debug { "Adding #{ownr.qp} dependent #{dep.qp} defaults..." }
-          logger.debug { "Ensuring that dependent #{dep.qp} owner #{ownr.qp} exists..." }
-          ensure_exists(ownr)
+      def create_dependent(owner, dep)
+        if owner.identifier.nil? then
+          logger.debug { "Adding #{owner.qp} dependent #{dep.qp} defaults..." }
+          logger.debug { "Ensuring that dependent #{dep.qp} owner #{owner.qp} exists..." }
+          ensure_exists(owner)
         end
 
         # If the dependent was created as a side-effect of creating the owner, then we are done.
         if dep.identifier then
-          logger.debug { "Created dependent #{dep.qp} by saving owner #{ownr.qp}." }
+          logger.debug { "Created dependent #{dep.qp} by saving owner #{owner.qp}." }
           return dep
         end
 
@@ -279,6 +280,7 @@ module CaRuby
         # The create template. Independent saved references are created as necessary.
         tmpl = build_create_template(obj)        
         save_with_template(obj, tmpl) { |svc| svc.create(tmpl) }
+
         # If obj is a top-level create, then ensure that remaining references exist.
         if @operations.first.subject == obj then
           refs = obj.references.reject { |ref| ref.identifier }
@@ -340,20 +342,34 @@ module CaRuby
         end
       end
       
-      # Returns whether the given creatable domain attribute with value obj is a 
-      # {AttributeMetadata#one_to_one_bidirectional_independent?}
-      # unsaved optional attribute without an obj {#pending_create?} save context.
+      # Returns whether the given creatable domain attribute with value obj satisfies
+      # each of the following conditions:
+      # * the attribute is {AttributeMetadata#independent?}
+      # * the attribute is not an {AttributeMetadata#owner?}
+      # * the obj value is unsaved
+      # * the attribute is not mandatory
+      # * the attribute references a {#pending_create?} save context.
       #
       # @param obj (see #create)
       # @param [AttributeMetadata] attr_md 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.one_to_one_bidirectional_independent? and
+        attr_md.independent? and
+          not attr_md.owner? and
           obj.identifier.nil? and
           not obj.mandatory_attributes.include?(attr_md.to_sym) and
-          ref = obj.send(attr_md.to_sym) and
-          ref.identifier.nil? and
-          pending_create?(ref)
+          exclude_pending_create_value?(obj.send(attr_md.to_sym))
+      end
+      
+      # @param [Resource, <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?
+        if Enumerable === value then
+           value.any? { |ref| exclude_pending_create_value?(ref) }
+        else
+          value.identifier.nil? and pending_create?(value)
+        end
       end
       
       # @param [Resource] obj the object to check
@@ -395,6 +411,12 @@ module CaRuby
           proxied.each { |dep| update(dep) }
         end
         
+        # update a cascaded dependent by updating the owner
+        owner = cascaded_owner(obj)
+        result = update_dependent(owner, obj) if owner
+        # if not cascaded, then update directly with a template
+        result ||= create_from_template(obj)
+        
         # update using a template
         tmpl = build_update_template(obj)
         
@@ -404,6 +426,38 @@ module CaRuby
         obj.take_snapshot
       end
       
+      # Returns the owner that can cascade update to the given object.
+      # The owner is the #{Resource#effective_owner_attribute_metadata} value
+      # for which the owner attribute {AttributeMetadata#inverse_attribute_metadata}
+      # is {AttributeMetadata#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
+      # @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_attribute_metadata
+        if dep_md and dep_md.cascaded? then
+          obj.send(oattr)
+        end
+      end
+      
+      def update_dependent(owner, obj)
+        logger.debug { "Updating #{obj} by saving the owner #{owner}..." }
+        update(owner)
+      end
+      
+      def update_from_template(obj)
+        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
+      end
+      
       # caTissue alert - the conditions for when and how to include a proxied dependent are
       # are intricate and treacherous. So far as can be determined, in the case of a
       # SpecimenPosition proxied by a TransferEventParameters, the sequence is as follows:
@@ -427,10 +481,10 @@ module CaRuby
       #   must be created via the proxy after the Specimen is created.
       #
       # @param (see #update)
-      # @return [<Resource>] the #{ResourceAttributes#proxied_cascaded_attributes} dependents
+      # @return [<Resource>] the #{ResourceAttributes#proxied_save_template_attributes} dependents
       #   which are #{Persistable#changed?}
       def updatable_proxied_dependents(obj)
-        attrs = obj.class.proxied_cascaded_attributes
+        attrs = obj.class.proxied_save_template_attributes
         return Array::EMPTY_ARRAY if attrs.empty?
         deps = []
         attrs.each do |attr|
@@ -459,7 +513,7 @@ module CaRuby
         if obj.identifier.nil? then
           raise DatabaseError.new("Delete target is missing a database identifier: #{obj}")
         end
-        persistence_service(obj).delete_object(obj)
+        persistence_service(obj.class).delete_object(obj)
       end
 
       # Saves the given template built from the given domain object obj. The persistence operation
@@ -471,15 +525,22 @@ module CaRuby
       # @param [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}" }
-        # call the application service
-        # dispatch to the app service
-        svc = persistence_service(template)
-        result = template.identifier ? svc.update(template) : svc.create(template)
-        logger.debug { "Store #{obj.qp} with template #{template.qp} produced caCORE result: #{result}." }
+        # dispatch to the application service
+        result = submit_save_template(obj, template)
         # sync the result
         sync_saved(obj, result)
       end
       
+      # Dispatches the given template to the application service.
+      #
+      # @param (see #save_with_template)
+      def submit_save_template(obj, template)
+        svc = persistence_service(template.class)
+        result = template.identifier ? svc.update(template) : svc.create(template)
+        logger.debug { "Store #{obj.qp} with template #{template.qp} produced caCORE result: #{result}." }
+        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.
@@ -551,7 +612,6 @@ module CaRuby
       def sync_save_result(source, target)
         # Bail if the result is the same as the source, as occurs, e.g., with caTissue annotations.
         return if source == target
-        logger.debug { "Synchronizing #{target} save result #{source} with the database..." }
         # 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
@@ -559,7 +619,6 @@ module CaRuby
         sync_save_result_references(source, target)
         # Set inverses consistently in the source object graph
         set_inverses(source)
-        logger.debug { "Synchronized #{target} save result #{source} with the database." }
       end
       
       # Refetches the given create result source if there are any {ResourceAttributes#autogenerated_nondomain_attributes}
@@ -626,9 +685,6 @@ module CaRuby
       #
       # @param [Resource] obj the owner domain object
       def save_changed_dependents(obj)
-        # JRuby alert - copy the Resource dependents call result to an array, since iteration based on
-        # Forwardable enum_for breaks here with an obscure Java ConcurrentModificationException
-        # in the CaTissue SCG save test case. TODO - isolate and fix at source.
         obj.class.dependent_attributes.each do |attr|
           deps = obj.send(attr).to_enum
           logger.debug { "Saving the #{obj} #{attr} dependents #{deps.qp} which have changed..." } unless deps.empty?
@@ -639,7 +695,9 @@ module CaRuby
       # Saves the given dependent domain object if necessary.
       # Recursively saves the obj dependents as necessary.
       #
-      # @param [Resource] obj the dependent domain object to save
+      # @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)
         if dependent.identifier.nil? then
           logger.debug { "Creating #{owner.qp} #{attribute} dependent #{dependent.qp}..." }
@@ -652,19 +710,24 @@ module CaRuby
           op = operations.last
           # The dependent is auto-generated if the owner was created or auto-generated and
           # the dependent attribute is auto-generated.
-          ag = (op.type == :create or op.autogenerated?) && owner.class.attribute_metadata(attribute).autogenerated?
+          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}..." }
-          perform(:update, dependent, :autogenerated => ag) { update_object(dependent) }
+          if ag then
+            logger.debug { "Adding defaults to the auto-generated #{owner.qp} #{attribute} dependent #{dependent.qp}..." }
+            dependent.add_defaults_autogenerated
+          end
+          update_changed_dependent(owner, attribute, dependent, ag)
         else
           save_changed_dependents(dependent)
         end
       end
       
-      # Creates the given dependent domain object.
+      # Updates the given dependent.
       #
-      # @param (see #save_dependent)
-      def create_dependent(owner, dep)
-        create(dep)
+      # @param (see #save_dependent_if_changed)
+      def update_changed_dependent(owner, attribute, dependent, autogenerated)
+        perform(:update, dependent, :autogenerated => autogenerated) { update_object(dependent) }
       end
     end
   end