caruby-core 2.1.1 → 2.1.2

data/lib/caruby/database/reader.rb

@@ -13,7 +13,7 @@ module CaRuby
       def initialize
         super
         # the query template builder
-        @srch_tmpl_bldr = TemplateBuilder.new
+        @rdr_tmpl_bldr = TemplateBuilder.new
         # the fetch result matcher
         @matcher = FetchedMatcher.new
         # the fetched copier
@@ -25,7 +25,7 @@ module CaRuby
         # visitor that merges the fetched object graph
         @ftchd_mrg_vstr = Jinx::MergeVisitor.new(:matcher => @matcher, :copier => copier) { |ref| ref.class.fetched_domain_attributes }
       end
-
+      
       # Returns an array of objects matching the specified query template and attribute path.
       # The obj_or_hql argument is either a domain object template or a
       # Hibernate[http://www.hibernate.org/docs.html] HQL statement. If obj_or_hql
@@ -57,36 +57,46 @@ module CaRuby
         # enable change tracking and lazy-loading
         persistify(result)
       end
-
-      # Fetches the given domain object from the database.
-      # Only secondary key attributes are used in the match.
-      # If no secondary key is defined for the object's class, then this method returns nil.
-      # The {#query} method is used to fetch records on non-secondary key attributes.
+      
+      # Fetches the given target domain object from the database. The target
+      # domain object class {Propertied#searchable_attributes} are used in the match.
+      # If this domain object does not have a set of searchable attributes with
+      # non-nil values, then this method returns nil.
       #
       # If the :create option is set, then this method creates an object if the
       # find is unsuccessful.
       #
-      # @param [Jinx::Resource] obj the domain object to find
+      # If the fetched domain object is the same class as the target domain object,
+      # then the fetched content is merged into the target and this method returns
+      # the target. If the fetched domain object is a subclass of the target domain
+      # object, then the fetched domain object is returned.
+      #
+      # @param [Jinx::Resource] obj the target domain object to find
       # @param [Hash, Symbol] opts the find options
       # @option opts [Boolean] :create whether to create the object if it is not found
       # @return [Jinx::Resource, nil] the domain object if found, nil otherwise
       # @raise [DatabaseError] if obj is not a domain object or more than object
       #   matches the obj attribute values
+      # @see #query
       def find(obj, opts=nil)
         return if obj.nil?
         perform(:find, obj) do
-          if find_object(obj) then
+          fetched = find_object(obj)
+          if fetched.nil? then
+            logger.info { "#{obj.qp} not found." }
+            create(obj) if Options.get(:create, opts)
+          elsif fetched.equal?(obj) then
             logger.info { "Found #{obj}." }
             obj
           else
-            logger.info { "#{obj.qp} not found." }
-            if Options.get(:create, opts) then create(obj) end
+            logger.info { "Found #{fetched} matching the find template #{obj}." }
+            fetched
           end
         end
       end
-
-      # Returns whether the given domain object has a database identifier or exists in the database.
-      # This method fetches the object from the database if necessary.
+      
+      # Returns whether the given domain object has a database identifier or exists
+      # in the database. This method fetches the object from the database if necessary.
       #
       # @param [Jinx::Resource, <Jinx::Resource>] obj the domain object(s) to find
       # @return [Boolean] whether the domain object(s) exist in the database
@@ -96,14 +106,14 @@ module CaRuby
         elsif obj.collection? then
           obj.all? { |item| exists?(item) }
         else
-          obj.identifier or find(obj)
+          !!obj.identifier or find(obj).equal?(obj)
         end
       end
       
       private
-
+      
       RESULT_PRINTER = PrintWrapper.new { |obj| obj.pp_s }
-
+      
       # Queries the given obj_or_hql as described in {#query} and makes a detoxified copy of the
       # toxic caCORE search result.
       #
@@ -121,7 +131,7 @@ module CaRuby
         # detoxify the toxic caCORE result
         detoxify(toxic)
       end
-
+      
       # Queries the given obj_or_hql as described in {#query} and returns the toxic caCORE search result.
       #
       # @param (see #query)
@@ -131,7 +141,7 @@ module CaRuby
         path_s = path.join('.') unless path.empty?
         # guard against recursive call back into the same operation
         if query_redundant?(obj_or_hql, path_s) then
-          Jinx.fail(DatabaseError, "Query #{obj_or_hql.qp} #{path_s} recursively called in context #{print_operations}")
+          raise DatabaseError.new("Query #{obj_or_hql.qp} #{path_s} recursively called in context #{print_operations}")
         end
         # perform the query
         perform(:query, obj_or_hql, :attribute => path_s) { query_with_path(obj_or_hql, path) }
@@ -140,11 +150,11 @@ module CaRuby
       def query_redundant?(obj_or_hql, path)
         @operations.detect { |op| op.type == :query and query_subject_redundant?(op.subject, obj_or_hql) and op.attribute == path }
       end
-
+      
       def query_subject_redundant?(s1, s2)
         s1 == s2 or (Jinx::Resource === s1 and Jinx::Resource === s2 and s1.identifier and s1.identifier == s2.identifier)
       end
-
+      
       # @return an array of objects matching the given query template and path
       # @see #query
       def query_with_path(obj_or_hql, path)
@@ -154,14 +164,14 @@ module CaRuby
         # gather the results of querying on those penultimate result objects with the last
         # attribute as the path
         unless path.empty? then
-          if attribute.nil? then Jinx.fail(DatabaseError, "Query path includes empty attribute: #{path.join('.')}.nil") end
+          if attribute.nil? then raise DatabaseError.new("Query path includes empty attribute: #{path.join('.')}.nil") end
           logger.debug { "Decomposing query on #{obj_or_hql} with path #{path.join('.')}.#{attribute} into query on #{path.join('.')} followed by #{attribute}..." }
           return query_safe(obj_or_hql, *path).map { |parent| query_toxic(parent, attribute) }.flatten
         end
         # perform the attribute query
         query_with_attribute(obj_or_hql, attribute)
       end
-
+      
       # Returns an array of objects matching the given query template and optional attribute.
       # @see #query
       def query_with_attribute(obj_or_hql, attribute=nil)
@@ -195,20 +205,20 @@ module CaRuby
       def merge_fetched(source, target)
         @ftchd_mrg_vstr.visit(source, target) { |src, tgt| tgt.copy_volatile_attributes(src) }
       end
-
+      
       def print_query_result(result)
         count_s = 'result object'.quantify(result.size)
         result_printer = result.wrap { |item| RESULT_PRINTER.wrap(item) }
         "Persistence service query returned #{count_s}: #{result_printer.pp_s(:single_line)}"
       end
-
+      
       def query_hql(hql)
         java_name = hql[/from\s+(\S+)/i, 1]
-        Jinx.fail(DatabaseError, "Could not determine target type from HQL: #{hql}") if java_name.nil?
+        raise DatabaseError.new("Could not determine target type from HQL: #{hql}") if java_name.nil?
         tgt = Class.to_ruby(java_name)
         persistence_service(tgt).query(hql)
       end
-
+      
       # Returns an array of objects fetched from the database which matches
       # a template and follows the given optional domain attribute, if present.
       #
@@ -228,12 +238,12 @@ module CaRuby
         elsif invertible_query?(obj, attribute) then
           query_with_inverted_reference(obj, attribute)
         else
-          tmpl = @srch_tmpl_bldr.build_template(obj)
+          tmpl = @rdr_tmpl_bldr.build_template(obj)
           return Array::EMPTY_ARRAY if tmpl.nil?
           query_on_template(tmpl, attribute)
         end
       end
-
+      
       # Returns an array of objects fetched from the database which matches
       # the given template and follows the given optional domain attribute.
       def query_on_template(template, attribute=nil)
@@ -241,7 +251,7 @@ module CaRuby
         svc = persistence_service(tgt)
         attribute ? svc.query(template, attribute) : svc.query(template)
       end
-
+      
       # Queries on the given template and attribute by issuing a HQL query with an identifier condition.
       #
       # @param (see #query_object)
@@ -252,17 +262,17 @@ module CaRuby
         sa = source[/([[:alnum:]])[[:alnum:]]*$/, 1].downcase
         # the HQL condition
         hql = "from #{source} #{sa} where #{sa}.id = #{obj.identifier}"
-
+      
         # the join attribute property
         if attribute then
           pd = obj.class.property(attribute).property_descriptor
           hql.insert(0, "select #{sa}.#{pd.name} ")
         end
         logger.debug { "Querying on #{obj} #{attribute} using HQL identifier criterion..." }
-
+      
         query_hql(hql)
       end
-
+    
       # Returns whether the query specified by the given search object and attribute can be
       # inverted as a query on a template of type attribute which references the object.
       # This condition holds if the search object has a key and attribute is a non-abstract
@@ -277,10 +287,11 @@ module CaRuby
         inv_prop = pa.inverse_property
         inv_prop and inv_prop.searchable? and finder_parameters(obj)
       end
-
-      # Queries the given query object attribute by querying an attribute type template which references obj.
+      
+      # Queries the given query object attribute by querying an attribute type template which references
+      # the target object.
       #
-      # @quirk caCORE caCORE caCORE search enters an infinite loop when the search argument has an object
+      # @quirk caCORE caCORE search enters an infinite loop when the search argument has an object
       #   reference graph cycle. Work-around is to ensure that reference integrity is broken in the search
       #   argument by not setting inverse attributes.
       #
@@ -297,14 +308,14 @@ module CaRuby
         # The Java property writer to set the tmpl inverse to ref.
         # Use the property writer rather than the attribute writer in order to curtail automatically
         # adding tmpl to the ref attribute value when the inv_prop attribute is set to ref.
-        wtr = inv_prop.property_writer
+        wtr = inv_prop.java_writer
         # parameterize tmpl with inverse ref
         tmpl.send(wtr, ref)
         # submit the query
         logger.debug { "Submitting #{obj.qp} #{attribute} inverted query template #{tmpl.qp} ..." }
         persistence_service(tmpl.class).query(tmpl)
       end
-
+      
       # Finds the database content matching the given search object and merges the matching
       # database values into the object. The find uses the search object secondary or alternate
       # key for the search.
@@ -315,14 +326,16 @@ module CaRuby
       # If a match is found, then each missing search object non-domain-valued attribute is set to
       # the fetched attribute value and this method returns the search object.
       #
-      # @quirk caCORE there is no caCORE find utility method to update a search target with persistent content,
-      #   so it is done manually here.
+      # @quirk caCORE there is no caCORE find utility method to update a search target with persistent
+      #   content, so it is done manually here.
       #
-      # @param obj (see #find)
-      # @return [Jinx::Resource, nil] obj if there is a matching database record, nil otherwise
-      # @raise [DatabaseError] if more than object matches the obj attribute values or if
+      # @param (see #find)
+      # @return (see #find)
+      # @raise [DatabaseError] if more than object matches the target object attribute values or if
       #   the search object is a dependent entity that does not reference an owner
       def find_object(obj)
+        # The transient set includes every object for which a find failed. This set is used to preclude
+        # a recursive unsuccessful search.
         if @transients.include?(obj) then
           logger.debug { "Find #{obj.qp} obviated since the search was previously unsuccessful in the current database operation context." }
           return
@@ -334,23 +347,30 @@ module CaRuby
         return obj if obj.equal?(fetched)
         
         logger.debug { "Fetch #{obj.qp} matched database object #{fetched}." }
+        # The target is no longer a transient since the find succeeded (see above).
         @transients.delete(obj)
-        # recursively copy the nondomain attributes, esp. the identifer, of the fetched domain object references
+        # If the fetched object is a subclass of the target, then return the fetched object.
+        if fetched.class < obj.class then
+          # Clean up the fetched object before it is returned.
+          detoxify(fetched)
+          return persistify(fetched)
+        end
+        # Recursively copy the nondomain attributes of the fetched domain object references.
+        # This merge sets the target identifier and fills in missing values of other nondomain
+        # attributes.
         merge_fetched(fetched, obj)
         # Inject the lazy loader for loadable domain reference attributes.
         persistify(obj, fetched)
         obj
       end
-
-      # Fetches the object matching the specified object obj from the database.
+       
+      # Fetches the object matching the specified domain object from the database.
       #
       # @see #find_object
       def fetch_object(obj)
         # If there is an identifier, then work around the caCORE identifier query bug by delegating
         # to the HQL identifier query.
-        if obj.identifier then
-          return query_on_identifier(obj).first
-        end
+        return query_on_identifier(obj).first if obj.identifier
         # Make the finder template with key attributes.
         tmpl = finder_template(obj)
         # If a template could be made, then fetch on the template.
@@ -367,18 +387,14 @@ module CaRuby
         # submit the query on the template
         logger.debug { "Query template for finding #{obj.qp}: #{template}." }
         result = query_on_template(template)
-        # a fetch query which returns more than one result is an error.
-        # possible cause is an incorrect secondary key.
+        # It is an error to have an ambiguous result.
+        # A possible cause is an unenforced secondary or alternate key.
         if result.size > 1 then
-          msg = "More than one match for #{obj.class.qp} find with template #{template}."
-          # it is an error to have an ambiguous result
-          logger.error("Fetch error - #{msg}:\n#{obj}")
-          Jinx.fail(DatabaseError, msg)
+          raise DatabaseError.new("More than one match for #{obj.class.qp} find with template #{template.qp}:\n#{template.dump}")
         end
-
         result.first
       end
-
+      
       # If the given domain object is a dependent with an unfetched owner, then this method fetches
       # the owner and attempts to match the owner dependent to this object.
       #
@@ -388,11 +404,11 @@ module CaRuby
         owner = nil
         oattr = obj.class.owner_attributes.detect { |pa| owner = obj.send(pa) }
         return if owner.nil? or owner.fetched?
-
+      
         logger.debug { "Querying #{obj.qp} by matching on the #{oattr} owner #{owner.qp} dependents..." }
         inv_prop = obj.class.property(oattr)
         if inv_prop.nil? then
-          Jinx.fail(DatabaseError, "#{dep.class.qp} owner attribute #{oattr} does not have a #{owner.class.qp} inverse dependent attribute.")
+          raise DatabaseError.new("#{dep.class.qp} owner attribute #{oattr} does not have a #{owner.class.qp} inverse dependent attribute.")
         end
         inv = inv_prop.inverse
         # fetch the owner if necessary
@@ -402,19 +418,20 @@ module CaRuby
           logger.debug { "Found #{obj.qp} by fetching the owner #{owner}." }
           return obj
         end
-
+      
         # try to match a fetched owner dependent
         deps = lazy_loader.enable { owner.send(inv) }
         if obj.identifier then
           logger.debug { "Found #{obj.qp} by fetching the owner #{owner} #{inv} dependents." }
           return obj
         else
-          logger.debug { "#{obj.qp} does not match one of the fetched owner #{owner} #{inv} dependents #{deps}." }
+          logger.debug { "#{obj.qp} does not match one of the fetched owner #{owner} #{inv} dependents #{deps.qp}." }
           nil
         end
       end
-
-      # Returns a copy of obj containing only those key attributes used in a find operation.
+      
+      # Returns a copy of the given domain object containing only those key attributes used
+      # in a find operation.
       #
       # @quirk caCORE Bug #79: caCORE search fetches on all non-nil attributes, except
       #   occasionally the identifier. There is no indication of how to identify uniquely
@@ -422,9 +439,9 @@ module CaRuby
       #   application configuration.
       def finder_template(obj)
         hash = finder_parameters(obj) || return
-        @srch_tmpl_bldr.build_template(obj, hash)
+        @rdr_tmpl_bldr.build_template(obj, hash)
       end
-
+      
       # Fetches the given object attribute value from the database.
       #
       # @quirk caCORE there is no association fetch for caCORE 3.1 and earlier;
@@ -460,7 +477,7 @@ module CaRuby
         logger.debug { "Fetching association #{attribute} for #{obj}..." }
         # load the object if necessary
         unless exists?(obj) then
-          Jinx.fail(DatabaseError, "Can't fetch an association since the referencing object is not found in the database: #{obj}")
+          raise DatabaseError.new("Can't fetch an association since the referencing object is not found in the database: #{obj}")
         end
         # fetch the reference
         result = query_safe(obj, attribute)
@@ -476,7 +493,7 @@ module CaRuby
         # Unbracket the result if the search propery is not a collection.
         prop.collection? ? result : result.first
       end
-
+      
       # Fetches the given object attribute reference from the database and sets the property value.
       #
       # @param (see #fetch_association)
@@ -484,7 +501,7 @@ module CaRuby
       def load_association(obj, attribute)
         obj.set_property_value(attribute, fetch_association(obj, attribute))
       end
-
+      
       # @return [{Symbol => Object}, nil] the find operation key attributes, or nil if there is no complete key
       #
       # @quirk caCORE caCORE search fetches on all non-nil attributes, except occasionally the identifier
@@ -496,7 +513,7 @@ module CaRuby
         key_value_hash(obj, obj.class.secondary_key_attributes) or
         key_value_hash(obj, obj.class.alternate_key_attributes)
       end
-
+      
       # @return [{Symbol => Object}, nil] the attribute => value hash suitable for a finder template
       #   if obj has searchable values for all of the given key attributes, nil otherwise
       def key_value_hash(obj, attributes)
@@ -525,7 +542,7 @@ module CaRuby
           value
         end
       end
-
+      
       # Returns whether the obj attribute value is either not a domain object reference or exists
       # in the database.
       #
@@ -535,23 +552,6 @@ module CaRuby
         return false if value.nil?
         obj.class.nondomain_attribute?(pa) or value.identifier
       end
-
-      # Sets the template attribute to a new search reference object created from source.
-      # The reference contains only the source identifier.
-      #
-      # @quirk caCORE The search template must break inverse integrity by clearing an owner inverse reference,
-      #   since a dependent => onwer => dependent cycle causes a caCORE search infinite loop.
-      #
-      # @return [Jinx::Resource, nil] the search reference, or nil if source does not exist in the database
-      def add_search_template_reference(template, source, attribute)
-        return if not exists?(source)
-        ref = source.copy(:identifier)
-        template.set_property_value(attribute, ref)
-        inverse = template.class.property(attribute).derived_inverse
-        ref.clear_attribute(inverse) if inverse
-        logger.debug { "Search reference parameter #{attribute} for #{template.qp} set to #{ref} copied from #{source.qp}" }
-        ref
-      end
     end
   end
 end

data/lib/caruby/database/reader_template_builder.rb

@@ -43,13 +43,16 @@ module CaRuby
         # source domain object. The reference contains only the source identifier, if it exists,
         # or the source non-domain attributes otherwise.
         #
+        # @quirk caCORE The search template must break inverse integrity by clearing an owner inverse reference,
+        #   since a dependent => owner => dependent cycle causes a caCORE search infinite loop.
+        #
         # @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
+          # Disable inverse integrity by using the Java property writer instead of the attribute writer.
+          # The attribute writer will add a reference from ref to template, which introduces a
+          # template => ref => template cycle that causes a caCORE search infinite loop.
+          wtr = template.class.property(attribute).java_writer
           template.send(wtr, ref)
           logger.debug { "Search reference parameter #{attribute} for #{template.qp} set to #{ref} copied from #{source.qp}" }
           ref

data/lib/caruby/database/sql_executor.rb

@@ -24,26 +24,34 @@ module CaRuby
     # @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_type the optional database type (default +mysql+)
     # @option opts [String] :database_host the optional database host
     # @option opts [Integer] :database_port the optional database port number
-    # @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
-        Jinx.fail(CaRuby::ConfigurationError, "The caRuby database connection properties were not found.") 
+        raise CaRuby::ConfigurationError.new("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)
       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) }
-      @db_url = Options.get(:database_url, opts) { "#{db_driver}://#{db_host}:#{db_port}/#{db_name}" }
+      db_name = Options.get(:database, opts)
+      @db_url = Options.get(:database_url, opts) do
+        # If there is a db name, then make the default db url.
+        # Otherwise, raise an error.
+        if db_name then
+         "#{db_driver}://#{db_host}:#{db_port}/#{db_name}"
+        else
+          raise_missing_option_error(:database)
+        end
+      end 
       @dbi_url = 'dbi:' + @db_url
-      @username = Options.get(:database_user, opts) { raise_missing_option_exception(:database_user) }
+      @username = Options.get(:database_user, opts) { raise_missing_option_error(: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.
@@ -65,7 +73,7 @@ module CaRuby
     # @yield [dbh] the transaction statements
     # @yieldparam [RDBI::Database] dbh the database handle
     def execute
-      RDBI.connect(:JDBC, :database => @db_url, :user => @username, :password => @password, :driver_class=> @driver_class) do |dbh|
+      RDBI.connect(:JDBC, :database => @db_url, :user => @username, :password => @password, :driver_class => @driver_class) do |dbh|
         yield dbh
       end
     end
@@ -74,13 +82,19 @@ module CaRuby
     #
     # @param [String] sql the SQL to execute
     # @param [Array] args the SQL bindings
+    # @yield [row] operate on the result 
+    # @yield [Array] the result row 
     # @return [Array] the query result
-    def query(sql, *args)
+    def query(sql, *args, &block)
       fetched = nil
       execute do |dbh|
-        res = dbh.execute(sql, *args)
-        fetched = res.fetch(:all)
-        res.finish
+        result = dbh.execute(sql, *args)
+        if block_given? then
+          result.each(&block)
+        else
+          fetched = result.fetch(:all)
+        end
+        result.finish
       end
       fetched
     end
@@ -149,7 +163,8 @@ module CaRuby
       case db_type.downcase
         when 'mysql' then 'Jdbc:mysql'
         when 'oracle' then 'Oracle'
-        else Jinx.fail(CaRuby::ConfigurationError, "Default database connection driver string could not be determined for database type #{db_type}")
+        when 'jdbc' then 'Jdbc'
+        else raise CaRuby::ConfigurationError.new("Default database connection driver string could not be determined for database type #{db_type}")
       end
     end
     
@@ -157,7 +172,8 @@ module CaRuby
       case db_type.downcase
         when 'mysql' then MYSQL_DRIVER_CLASS_NAME
         when 'oracle' then ORACLE_DRIVER_CLASS_NAME
-        else Jinx.fail(CaRuby::ConfigurationError, "Default database connection driver class could not be determined for database type #{db_type}")
+        when 'jdbc' then ''
+        else raise CaRuby::ConfigurationError.new("Default database connection driver class could not be determined for database type #{db_type}")
       end
     end
 
@@ -165,12 +181,13 @@ module CaRuby
       case db_type.downcase
         when 'mysql' then 3306
         when 'oracle' then 1521
-        else Jinx.fail(CaRuby::ConfigurationError, "Default database connection port could not be determined for database type #{db_type}")
+        when 'jdbc' then -1
+        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)
-      Jinx.fail(CaRuby::ConfigurationError, "Database connection property not found: #{option}")
+    def raise_missing_option_error(option)
+      raise CaRuby::ConfigurationError.new("Database connection property not found: #{option}")
     end
   end
 end