caruby-core 1.4.1

data/lib/caruby/database/saved_merger.rb

@@ -0,0 +1,131 @@
+require 'caruby/util/collection'
+require 'caruby/util/pretty_print'
+require 'caruby/domain/reference_visitor'
+require 'caruby/database/fetched_matcher'
+require 'caruby/database/store_template_builder'
+
+module CaRuby
+  class Database
+    # Merges database content sources into saved targets.
+    class SavedMerger
+      # @param [Database] database the database performing the save
+      def initialize(database)
+        @database = database
+        # the save result matchers
+        cr_mtchr = FetchedMatcher.new(:relaxed)
+        upd_mtchr = FetchedMatcher.new
+        # the save result merge visitors
+        @cr_mrg_vstr = MergeVisitor.new(:matcher => cr_mtchr) { |src, tgt| mergeable_saved_attributes(tgt) }
+        @upd_mrg_vstr = MergeVisitor.new(:matcher => upd_mtchr) { |src, tgt| mergeable_saved_attributes(tgt) }
+      end
+      
+            
+      # Merges the database content into the given saved domain object.
+      # Dependents are merged recursively.
+      #
+      # @param [Resource] obj the saved domain object
+      # @param [Resource] result the caCORE result
+      # @return [Resource] the object representing the persistent state
+      def merge(saved, result)
+        # the sync source reflecting the database content
+        src = saved_source(saved, result)
+        # merge the source into obj, including all cascaded dependents
+        merge_saved(saved, src)
+        src
+      end
+
+      # @param [Resource] obj the saved domain object
+      # @param [Resource] result the caCORE result domain object
+      # @return [Resource] the source domain object which accurately reflects the database state
+      # @see #fetch_saved?
+      def saved_source(obj, result)
+        # The true stored content might need to be fetched from the database.
+        if obj.fetch_saved? then
+          tmpl = result.copy(:identifier)
+          logger.debug { "Fetching saved #{obj.qp} using template #{tmpl}..." }
+          tmpl.find
+        else
+          result
+        end
+      end
+      
+      # Merges the content of the source domain object into the saved domain object obj.
+      # If obj differs from source, then obj is resaved. Dependents are merged recursively.
+      #
+      # @param [Resource] obj the saved domain object
+      # @param [Resource] source object holding the stored content
+      def merge_saved(obj, source)
+        logger.debug { "Merging database content #{source} into saved #{obj.qp}..." }
+        visitor = @database.mergeable_autogenerated_operation? ? @cr_mrg_vstr : @upd_mrg_vstr
+        visitor.visit(obj, source) do |tgt, src|
+          logger.debug { "Saved #{obj.qp} merge visitor merged database content #{src.qp} into #{tgt.qp}..." }
+          merge_saved_reference(tgt, src)
+        end
+      end
+      
+      # Sets the target snapshot attribute values from the given source, if different.
+      #
+      # @param [Resource] target the saved domain object
+      # @param [Resource] source the domain object reflecting the database state
+      # @return [Resource] the synced target
+      def merge_saved_reference(target, source)
+        # set each unsaved non-domain attribute from the source to reflect the database value
+        target.copy_volatile_attributes(source)
+        
+        # take a snapshot of the saved target
+        target.take_snapshot
+        logger.debug { "A snapshot was taken of the saved #{target.qp}." }
+        
+        # the non-domain attribute => [target value, source value] difference hash
+        diff = target.diff(source)
+        # the difference attribute => source value hash, excluding nil source values
+        dvh = diff.transform { |vdiff| vdiff.last }.compact
+        return if dvh.empty?
+        logger.debug { "Saved #{target} differs from database content #{source.qp} as follows: #{diff.filter_on_key { |attr| dvh.has_key?(attr) }.qp}" }
+        logger.debug { "Setting saved #{target.qp} snapshot values from source values to reflect the database state: #{dvh.qp}..." }
+        # update the snapshot from the source value to reflect the database state
+        target.snapshot.merge!(dvh)
+        
+        target
+      end
+    
+      # Returns the dependent attributes that can be copied from a save result to
+      # the given save argument object. This method qualifies the obj class
+      # {AttributeMetadata#copyable_saved_attributes} by whether the attribute is
+      # actually auto-generated for the saved object, i.e. the object was itself
+      # created or auto-generated. If obj was created or auto-generated, then
+      # this method returns the {AttributeMetadata#copyable_saved_attributes}.
+      # Otherwise, this method returns the {AttributeMetadata#cascaded_attributes}.
+      #
+      # @param [Resource] obj the domain object which was saved 
+      # @return  [<Symbol>] the attributes to copy
+      def mergeable_saved_attributes(obj)
+        fa = obj.class.fetched_domain_attributes
+        obj.suspend_lazy_loader do
+          attrs = obj.class.cascaded_attributes.filter do |attr|
+            fa.include?(attr) or not obj.send(attr).nil_or_empty?
+          end
+          if @database.mergeable_autogenerated_operation? then
+            ag_attrs = mergeable_saved_autogenerated_attributes(obj)
+            unless ag_attrs.empty? then
+              logger.debug { "Adding #{obj.qp} mergeable saved auto-generated #{ag_attrs.to_series} to the merge set..." }
+              attrs = attrs.to_set.merge(ag_attrs)
+            end
+          end
+          logger.debug { "Mergeable saved #{obj.qp} attributes: #{attrs.qp}." } unless attrs.empty?
+          attrs
+        end
+      end
+      
+      # Returns the autogenerated dependent attributes that can be copied from a save result to
+      # the given save argument object.
+      #
+      # @param [Resource] obj the domain object which was saved 
+      # @return [<Symbol>] the attributes to copy, or nil if no such attributes
+      def mergeable_saved_autogenerated_attributes(obj)
+        attrs = obj.class.mergeable_saved_autogenerated_attributes
+        attrs.reject { |attr| obj.send(attr).nil_or_empty? }
+      end
+    end
+  end
+end

data/lib/caruby/database/search_template_builder.rb

@@ -0,0 +1,59 @@
+require 'caruby/util/log'
+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.
+    #
+    # 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
+    #
+    # 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.
+    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
+      ref_hash, nonref_hash = hash.hash_partition { |attr, value| Resource === value }
+      # make the search template from the non-reference attributes
+      tmpl = obj.class.new(nonref_hash)
+      # get references for the search template
+      unless ref_hash.empty? then
+        logger.debug { "Collecting search reference parameters for #{obj.qp} from attributes #{ref_hash.keys.to_series}..." }
+      end
+      ref_hash.each { |attr, ref| add_search_template_reference(tmpl, ref, attr) }
+      tmpl
+    end
+
+    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.
+    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)
+      logger.debug { "Search reference parameter #{attribute} for #{template.qp} set to #{ref} copied from #{source.qp}" }
+      ref
+    end
+  end
+end

data/lib/caruby/database/sql_executor.rb

@@ -0,0 +1,75 @@
+require 'rubygems'
+gem 'dbi'
+
+require 'dbi'
+require 'caruby/util/options'
+require 'caruby/util/log'
+require 'caruby/domain/properties'
+
+module CaRuby
+  # SQLExecutor executes an SQL statement against the database.
+  # Use of this class requires the dbi gem.
+  # SQLExecutor is an auxiliary utility class and is not used by the rest of the CaRuby API.
+  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_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.
+    #
+    # @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) }
+      @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) }
+    end
+
+    # Connects to the database, yields the DBI handle to the given block and disconnects.
+    # Returns 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
+    end
+
+    private
+
+    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}")
+      end
+    end
+
+    def default_port(db_type)
+      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}")
+      end
+    end
+
+    def raise_missing_option_exception(option)
+      raise CaRuby::ConfigurationError.new("database connection property not found: #{option}")
+    end
+  end
+end

data/lib/caruby/database/store_template_builder.rb

@@ -0,0 +1,200 @@
+require 'caruby/domain/reference_visitor'
+
+module CaRuby
+  # StoreTemplateBuilder creates a template suitable for a create or update database operation.
+  class StoreTemplateBuilder
+    # Creates a new StoreTemplateBuilder for the given database.
+    #
+    # @param [Database] database the target database 
+    # @yield [ref] the required selector block which determines the attributes copied into the template
+    # @yieldparam [Resource] ref the domain object to copy
+    def initialize(database)
+      @database = database
+      unless block_given? then raise ArgumentError.new("StoreTemplateBuilder is missing the required template copy attribute selector block") end
+      # the domain attributes to copy
+      mgbl = Proc.new { |src, tgt| yield src }
+      # copy the reference
+      # caTissue alert - must copy all of the non-domain attributes rather than just the identifier,
+      # since caTissue auto-generated Specimen update requires the parent collection status. This
+      # is the only known occurrence of a referenced object required non-identifier attribute.
+      # The copy attributes are parameterized by the top-level save target.
+      copier = Proc.new do |src|
+        copy = src.copy
+        logger.debug { "Store template builder copied #{src.qp} into #{copy}." }
+        copy_proxied_save_references(src, copy)
+        copy
+      end
+     # the template copier
+      @copy_vstr = CopyVisitor.new(:mergeable => mgbl, :copier => copier) { |src, tgt| savable_cascaded_attributes(src) }
+      # the storable prerequisite reference visitor
+      @prereq_vstr = ReferenceVisitor.new(:prune_cycle) { |ref| savable_cascaded_attributes(ref) }
+    end
+
+    # Returns a new domain object which serves as the argument for obj create or update.
+    #
+    # This method copies a portion of the obj object graph to a template object.
+    # The template object graph consists of copies of obj object graph which are necessary
+    # to store obj. The template object graph contains only those references which are
+    # essential to the store operation.
+    #
+    # caCORE alert - +caCORE+ expects the store argument to be carefully prepared prior to
+    # the create or update. build_storable_template culls the target object with a template
+    # which includes only those references which are necessary for the store to succeed.
+    # This method ensures that mandatory independent references exist. Dependent references
+    # are included in the template but are not created before submission to +caCORE+ create
+    # or update. These fine distinctions are implicit application rules which are explicated
+    # in the +caRuby+ application domain class definition using ResourceMetadata methods.
+    #
+    # caCORE alert - +caCORE+ occasionally induces a stack overflow if a create argument
+    # contains a reference cycle. The template fixes this.
+    #
+    # caCORE alert - +caCORE+ create raises an error if a create argument directly or
+    # indirectly references a domain objects without an identifier, even if the
+    # reference is not relevant to the create. The template returned by this method elides
+    # all non-essential references.
+    #
+    # caCORE alert - application business logic performs unnecessary verification
+    # of uncascaded references as if they were a cascaded create. This can result in
+    # an obscure ApplicationException. The server.log stack trace indicates the
+    # extraneous verification code. For example, +caTissue+ +NewSpecimenBizLogic.validateStorageContainer+
+    # is unnecessarily called on a SpecimenCollectionGroup (SCG) update. SCG does not
+    # cascade to Specimen, but caTissue considers the SCG update a Specimen create
+    # anyway if the SCG references a Specimen without an identifier. The Specimen
+    # business logic then raises an exception when it finds a StorageContainer
+    # without an identifier in the Specimen object graph. Therefore, an update must
+    # build a storable template which prunes the update object graph to exclude uncascaded
+    # objects. These uncascaded objects should be ignored by the application but aren't.
+    #
+    # @param [Resource] obj the domain object to save
+    # @return [Resource] the template to use as the caCORE argument
+    def build_template(obj)
+      # prepare the object for a store operation
+      ensure_storable(obj)
+      # copy the cascade hierarchy
+      logger.debug { "Building storable template for #{obj.qp}..." }
+      tmpl = @copy_vstr.visit(obj)
+      logger.debug { "Built #{obj.qp} template #{tmpl.qp} by mapping references #{@copy_vstr.matches.qp}" }
+      tmpl
+    end
+
+    private
+  
+    # Ensure that the given domain object obj can be created or updated by setting the identifier for
+    # each independent reference in the create template object graph.
+    #
+    # caCORE alert - +caCORE+ raises an ApplicationException if an independent reference in the create or
+    # update argument does not have an identifier. The +caCORE+ server log error is as follows:
+    #   java.lang.IllegalArgumentException: id to load is required for loading
+    # The server log stack trace indicates a bizlogic line that offers a clue to the offending reference.
+    def ensure_storable(obj)
+      # Add defaults, which might introduce independent references.
+      obj.add_defaults
+      # create the prerequisite references if necessary
+      prereqs = collect_prerequisites(obj)
+      unless prereqs.empty? then
+        logger.debug { "Ensuring references for #{obj.qp} exist: #{prereqs.map { |ref| ref.qp }.to_series}..." }
+        @database.ensure_exists(prereqs)
+        logger.debug { "Prerequisite references for #{obj.qp} exist: #{prereqs.map { |ref| ref }.to_series}." }
+      end
+      # If obj is being created then add defaults again, since fetched independent references might introduce new defaults.
+      obj.add_defaults unless obj.identifier
+      # Verify that the object is complete
+      obj.validate
+    end
+      
+    # Filters the {ResourceAttributes#updatable_domain_attributes} to exclude
+    # the {ResourceAttributes#proxied_cascaded_attributes} whose reference value
+    # does not have an identifier. These references will be created by proxy
+    # instead.
+    #
+    # @param [Resource] obj the domain object copied to the update template
+    # @return [<Symbol>] the reference attributes to include in the update template
+    def savable_cascaded_attributes(obj)
+      # always include the unproxied cascaded references
+      unproxied = obj.class.unproxied_cascaded_attributes
+      if obj.identifier then
+        unproxied = unproxied.filter do |attr|
+          obj.class.attribute_metadata(attr).cascade_update_to_create? or
+          obj.send(attr).to_enum.all? { |ref| ref.identifier }
+        end
+      end
+      
+      # Include a proxied reference only if the proxied dependents have an identifier,
+      # since those without an identifer are created separately via the proxy.
+      proxied = obj.class.proxied_cascaded_attributes.reject do |attr|
+        ref = obj.send(attr)
+        case ref
+        when Enumerable then
+           ref.any? { |dep| not dep.identifier }
+        when Resource then
+          not ref.identifier
+        end
+      end
+      
+      proxied.empty? ? unproxied : unproxied + proxied
+    end
+    
+    # Copies proxied references as needed.
+    #
+    # caTissue alert - even though Specimen save cascades to SpecimenPosition,
+    # SpecimenPosition cannot be updated directly. Rather than simply not
+    # cascading to the SpecimenPosition, caTissue checks a Specimen save argument
+    # to ensure that the SpecimenPosition reflects the current database state
+    # rather than the desired cascaded state. Play along with this bizarre
+    # mechanism by adding our own bizarre work-around mechanism to copy a
+    # proxied reference only if it has an identifier. This works only because
+    # another work-around in the #{CaRuby::Database::Writer} updates proxied
+    # 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|
+        ref = obj.send(attr)
+        case ref
+        when Enumerable then
+          coll = template.send(attr)
+          ref.each do |dep|
+            copy = copy_proxied_save_reference(obj, attr, template, dep)
+            coll << copy if copy
+          end
+        when Resource then
+          copy = copy_proxied_save_reference(obj, attr, template, ref)
+          template.set_attribute(attr, copy) if copy
+        end
+      end
+    end
+    
+    # Copies a proxied reference.
+    #
+    # @return [Resource, nil] the copy, or nil if no copy is made
+    def copy_proxied_save_reference(obj, attribute, template, proxied)
+      # only copy an existing proxied
+      return unless proxied.identifier
+      # the proxied attribute => value hash
+      vh = proxied.value_hash
+      # map references to either the copied owner or a new copy of the reference
+      tvh = vh.transform { |value| Resource === value ? (value == obj ? template : value.copy) : value }
+      # the copy with the adjusted values
+      copy = proxied.class.new(tvh)
+      logger.debug { "Created #{obj.qp} proxied #{attribute} save template copy #{proxied.pp_s}." }
+      copy
+    end
+    
+    # Returns the references which must be created in order to store obj.
+    def collect_prerequisites(obj)
+      prereqs = Set.new
+      @prereq_vstr.visit(obj) do |stbl|
+        stbl.class.storable_prerequisite_attributes.each do |attr|
+          # add qualified prerequisite attribute references
+          stbl.send(attr).enumerate do |prereq|
+            # add the prerequisite unless it is the object being created, was already created or is
+            # in the owner hierarchy 
+            unless prereq == obj or prereq.identifier or prereq.owner_ancestor?(obj) then
+              prereqs << prereq
+            end
+          end
+        end
+      end
+      prereqs
+    end
+  end
+end