caruby-core 2.1.1 → 2.1.2

data/Gemfile

@@ -2,6 +2,7 @@ source :rubygems
 gemspec
 
 group :development do
+  # Uncomment to bind local gems in a local branch. Do not check in.
   #gem 'jinx', :path => File.dirname(__FILE__) + '/../../jinx/core'
   #gem 'jinx-json', :path => File.dirname(__FILE__) + '/../../jinx/json'
   #gem 'jinx-migrate', :path => File.dirname(__FILE__) + '/../../jinx/migrate'

data/History.md

@@ -1,7 +1,11 @@
 This history lists major release themes. See the GitHub Commits (https://github.com/caruby/core)
 for change details.
 
-2.1.1 / 2011-04-13
+2.1.2 / 2012-06-12
+------------------
+* Support caSmall.
+
+2.1.1 / 2012-04-13
 ------------------
 * Simpler, more flexible meta-data loading.
 

data/lib/caruby/database/cache.rb

@@ -1,21 +1,32 @@
 require 'jinx/helpers/lazy_hash'
-require 'jinx/helpers/key_transformer_hash'
+require 'jinx/helpers/associative'
 
 module CaRuby
   # Cache for objects held in memory and accessed by key.
   class Cache
-    # The classes which are not cleared when {#clear} is called without the +all+ flag.
+    # The classes which are not cleared when {#clear} is called.
     attr_reader :sticky
     
-    # @yield [item] returns the key for the given item to cache
-    # @yieldparam item the object to cache
+    # @yield [obj] returns the key for the given object to cache
+    # @yieldparam obj the object to cache
     def initialize
-      # Make the class => {key => item} hash.
-      # The {key => item} hash takes an item as an argument and converts
-      # it to the key by calling the block given to this initializer.
+      # Make the class => {object => {key => object}} hash.
+      # The {object => {key => object}} hash is an Associative which converts the given
+      # object to its key by calling the block given to this initializer.
+      # The {{key => object} hash takes a key as an argument and returns the cached object.
+      # If there is no cached object, then the object passed to the Associative is cached. 
       @ckh = Jinx::LazyHash.new do
-        Jinx::KeyTransformerHash.new do |obj|
-          yield(obj) or Jinx.fail(ArgumentError, "The object to cache does not have a key: #{obj}")
+        kh = Hash.new 
+        # the obj => key associator
+        assoc = Jinx::Associative.new do |obj|
+          key = yield(obj)
+          kh[key] if key
+        end
+        # the obj => key => value writer  
+        assoc.writer do |obj, value|
+          key = yield(obj)                                                                       
+          raise ArgumentError.new("caRuby cannot cache object without a key: #{obj}") if key.nil?
+          kh[key] = value
         end
       end
       @sticky = Set.new

data/lib/caruby/database/lazy_loader.rb

@@ -23,7 +23,7 @@ module CaRuby
       # @return the attribute value loaded from the database
       # @raise [RuntimeError] if this loader is disabled
       def load(subject, attribute)
-        if disabled? then Jinx.fail(RuntimeError, "#{subject.qp} lazy load called on disabled loader") end
+        if disabled? then raise RuntimeError.new("#{subject.qp} lazy load called on disabled loader") end
         logger.debug { "Lazy-loading #{subject.qp} #{attribute}..." }
         # the current value
         oldval = subject.send(attribute)

data/lib/caruby/database/operation.rb

@@ -29,6 +29,8 @@ module CaRuby
       def to_s
         "#{@subject.qp} #{attribute} #{type}"
       end
+      
+      alias :inspect :to_s
     end
   end
 end

data/lib/caruby/database/persistable.rb

@@ -34,7 +34,7 @@ module CaRuby
     # @return [Database] the data access mediator for this Persistable, if any
     # @raise [DatabaseError] if the subclass does not override this method
     def database
-      Jinx.fail(ValidationError, "#{self} database is missing")
+      raise ValidationError.new("#{self} database is missing")
     end
     
     # @return [PersistenceService] the database application service for this Persistable
@@ -113,6 +113,12 @@ module CaRuby
     def delete
       database.delete(self)
     end
+    
+    # @return [Boolean] whether this domain object can be updated
+    #   (default is true, subclasses can override)
+    def updatable?
+      true
+    end
 
     alias :== :equal?
 
@@ -138,7 +144,7 @@ module CaRuby
     # @raise [ValidationError] if this domain object does not have a snapshot
     def merge_into_snapshot(other)
       if @snapshot.nil? then
-        Jinx.fail(ValidationError, "Cannot merge #{other.qp} content into #{qp} snapshot, since #{qp} does not have a snapshot.")
+        raise ValidationError.new("Cannot merge #{other.qp} content into #{qp} snapshot, since #{qp} does not have a snapshot.")
       end
       # the non-domain attribute => [target value, other value] difference hash
       delta = diff(other)
@@ -164,7 +170,7 @@ module CaRuby
 
     # @return [<Symbol>] the attributes which differ between the {#snapshot} and current content
     def changed_attributes
-      if @snapshot then
+     if @snapshot then
         ovh = value_hash(self.class.updatable_attributes)
         diff = @snapshot.diff(ovh) { |pa, v, ov| Jinx::Resource.value_equal?(v, ov) }
         diff.keys
@@ -190,7 +196,7 @@ module CaRuby
     # @param loader [LazyLoader] the lazy loader to add
     def add_lazy_loader(loader, attributes=nil)
       # guard against invalid call
-      if identifier.nil? then Jinx.fail(ValidationError, "Cannot add lazy loader to an unfetched domain object: #{self}") end
+      if identifier.nil? then raise ValidationError.new("Cannot add lazy loader to an unfetched domain object: #{self}") end
       # the attributes to lazy-load
       attributes ||= loadable_attributes
       return if attributes.empty?
@@ -252,16 +258,16 @@ module CaRuby
 
     # Validates this domain object and its #{Propertied#unproxied_savable_template_attributes}
     # for consistency and completeness prior to a database create operation.
-    # An object without an identifer is valid if it contains a non-nil value for each mandatory attribute.
-    # Objects which have an identifier or have already been validated are skipped.
+    # An object is valid if it contains a non-nil value for each mandatory attribute.
+    # Objects which have already been validated are skipped.
     #
-    # A Persistable class should not override this method, but override the private {#validate_local}
-    # method instead.
+    # A Persistable class should not override this method, but override the
+    # private {#validate_local} method instead.
     #
     # @return [Persistable] this domain object
     # @raise [Jinx::ValidationError] if the object state is invalid
-    def validate
-      if identifier.nil? and not @validated then
+    def validate(autogenerated=false)
+      if (identifier.nil? or autogenerated) and not @validated then
         validate_local
         @validated = true
       end
@@ -386,7 +392,6 @@ module CaRuby
     def copy_volatile_attributes(other)
       pas = self.class.volatile_nondomain_attributes
       return if pas.empty?
-      logger.debug { "Merging volatile attributes #{pas.to_series} from #{other.qp} into #{qp}..." }
       pas.each do |pa|
         val = send(pa)
         oval = other.send(pa)
@@ -396,9 +401,10 @@ module CaRuby
           logger.debug { "Set #{qp} volatile #{pa} to the fetched #{other.qp} database value #{oval.qp}." }
         elsif oval != val and pa == :identifier then
           # If this error occurs, then there is a serious match-merge flaw. 
-          Jinx.fail(DatabaseError, "Can't copy #{other} to #{self} with different identifier")
+          raise DatabaseError.new("Can't copy #{other} to #{self} with different identifier")
         end
       end
+      logger.debug { "Merged auto-generated attribute values #{pas.to_series} from #{other.qp} into #{self}..." }
     end
     
     private
@@ -515,7 +521,7 @@ module CaRuby
           end
         end
       end
-      
+
       merged
     end
     

data/lib/caruby/database/persistence_service.rb

@@ -19,11 +19,10 @@ module CaRuby
     # @option opts [String] :host the service host (default +localhost+)
     # @option opts [String] :version the caTissue version identifier
     def initialize(name, opts={})
-      CaRuby::PersistenceService.import_java_classes
       @name = name
       ver_opt = opts[:version]
       @version = ver_opt.to_s.to_version if ver_opt
-      @host = opts[:host] || default_host
+      @host = opts[:host] || 'localhost'
       @port = opts[:port] || 8080
       @url = "http://#{@host}:#{@port}/#{@name}/http/remoteService"
       @timer = Jinx::Stopwatch.new
@@ -52,34 +51,19 @@ module CaRuby
     #   create method. Calling reference attributes of this result is broken by +caCORE+ design.
     def create(obj)
       logger.debug { "Submitting create #{obj.pp_s(:single_line)} to application service #{name}..." }
-      begin
-        dispatch { |svc| svc.create_object(obj) }
-      rescue Exception => e
-        logger.error("Error creating #{obj} - #{e.message}\n#{dump(obj)}")
-        raise e
-      end
+      dispatch { |svc| svc.create_object(obj) }
     end
 
     # Submits the update to the application service and returns obj.
    def update(obj)
       logger.debug { "Submitting update #{obj.pp_s(:single_line)} to application service #{name}..." }
-      begin
-        dispatch { |svc| svc.update_object(obj) }
-      rescue Exception => e
-        logger.error("Error updating #{obj} - #{e.message}\n#{dump(obj)}")
-        raise e
-      end
+      dispatch { |svc| svc.update_object(obj) }
    end
 
     # Submits the delete to the application service.
     def delete(obj)
       logger.debug { 'Deleting #{obj}.' }
-      begin
-        dispatch { |svc| svc.remove_object(obj) }
-      rescue Exception => e
-        logger.error("Error deleting #{obj} - #{e.message}\n#{dump(obj)}")
-        raise e
-      end
+      dispatch { |svc| svc.remove_object(obj) }
     end
 
     # Returns the {ApplicationService} remote instance.
@@ -113,16 +97,6 @@ module CaRuby
       time { yield app_service }
     end
     
-    # @return [String] the default host name
-    def default_host
-#      # TODO - extract from the service config file
-#      xml = JRuby.runtime.jruby_class_loader.getResourceAsStream('remoteService.xml')
-#      if xml then
-#        # parse xml file
-#      end
-      'localhost'
-    end
-    
     # Dispatches the given HQL to the application service.
     #
     # @quirk caCORE query target parameter is necessary for caCORE 3.x but deprecated in caCORE 4+.
@@ -132,7 +106,7 @@ module CaRuby
       logger.debug { "Building HQLCriteria..." }
       criteria = HQLCriteria.new(hql)
       target = hql[/from\s+(\S+)/i, 1]
-      Jinx.fail(DatabaseError, "HQL does not contain a FROM clause: #{hql}") unless target
+      raise DatabaseError.new("HQL does not contain a FROM clause: #{hql}") unless target
       logger.debug { "Submitting search on target class #{target} with the following HQL:\n  #{hql}" }
       begin
         dispatch { |svc| svc.query(criteria, target) }
@@ -151,7 +125,7 @@ module CaRuby
       class_name_path = []
       path.inject(template.class) do |type, pa|
         ref_type = type.domain_type(pa)
-        Jinx.fail(DatabaseError, "Property in search attribute path #{path.join('.')} is not a #{type} domain reference attribute: #{pa}") if ref_type.nil?
+        raise DatabaseError.new("Property in search attribute path #{path.join('.')} is not a #{type} domain reference attribute: #{pa}") if ref_type.nil?
         class_name_path << ref_type.java_class.name
         ref_type
       end
@@ -180,7 +154,7 @@ module CaRuby
      begin
         result = dispatch { |svc| svc.association(obj, assn) }
       rescue Exception => e
-        logger.error("Error fetching association #{obj} - #{e.message}\n#{dump(obj)}")
+        logger.error("Error fetching association #{obj} - #{e}")
         raise
       end
     end
@@ -191,11 +165,13 @@ module CaRuby
     
     private
     
-    # Imports this class's Java classes on demand.
-    def self.import_java_classes
-      return if const_defined?(:HQLCriteria)
-      # HQLCriteria is required for the query_hql method.
-      java_import Java::gov.nih.nci.common.util.HQLCriteria
+    # Imports the caCORE +HQLCriteria+ Java class on demand.
+    def self.const_missing(sym)
+      if sym == :HQLCriteria then
+        java_import Java::gov.nih.nci.common.util.HQLCriteria
+      else
+        super
+      end
     end
 
   end

data/lib/caruby/database/persistifier.rb

@@ -13,7 +13,18 @@ module CaRuby
       # Adds query capability to this Database.
       def initialize
         super
-        @ftchd_vstr = Jinx::ReferenceVisitor.new { |ref| ref.class.fetched_domain_attributes }
+        # the fetched object cache
+        @cache = create_cache
+        # the general fetched visitor
+        @ftchd_vstr = Jinx::ReferenceVisitor.new() { |ref| ref.class.fetched_domain_attributes }
+        # The persistifier visitor recurses to references before adding a lazy loader to the parent.
+        # The fetched filter foregoes the visit to a previously fetched reference. The visitor
+        # replaces fetched objects with matching cached objects where possible. It is unnecessary
+        # to visit a previously persistified cached object.
+        pst_flt = Proc.new { |ref| @cache[ref].nil? and not ref.fetched? }
+        @pst_vstr = Jinx::ReferenceVisitor.new(:filter => pst_flt, :depth_first => true) do |ref|
+          ref.class.fetched_domain_attributes
+        end
         # the demand loader
         @lazy_loader = LazyLoader.new { |obj, pa| lazy_load(obj, pa) }
       end
@@ -73,8 +84,14 @@ module CaRuby
       end
 
       # This method clears the given toxic domain objects fetched from the database.
-      # The copy nondomain attribute values are set to the fetched object values.
-      # The copy fetched reference attribute values are set to a copy of the result references.
+      #
+      # Detoxification consists of the following:
+      # * The fetched object's class might not have been previously referenced. In that
+      #   case, introspect the fetched object's class.
+      # * Clear toxic references that will result in a caCORE missing session error
+      #   due to the caCORE API deficiency described below.
+      # * Replaced fetched objects with the corresponding cached objects where possible.
+      # * Set inverses to enforce inverse integrity where necessary.
       #
       # @quirk caCORE Dereferencing a caCORE search result uncascaded collection attribute
       #   raises a Hibernate missing session error.
@@ -88,27 +105,63 @@ module CaRuby
       #   This situation is rectified in this detoxify method by setting the dependent owner
       #   attribute to the fetched owner in the detoxification {Jinx::ReferenceVisitor} copy-match-merge.
       #
-      # @return [Jinx::Resource, <Jinx::Resource>] the detoxified object(s)
+      # @param [Resource] toxic the fetched object to detoxify
+      # @return [Resource, <Resource>] the detoxified object(s)
       def detoxify(toxic)
         return if toxic.nil?
         if toxic.collection? then
           toxic.each { |obj| detoxify(obj) }
         else
           logger.debug { "Detoxifying the toxic caCORE result #{toxic.qp}..." }
-          @ftchd_vstr.visit(toxic) { |ref| clear_toxic_attributes(ref) }
+          @ftchd_vstr.visit(toxic) { |ref| detoxify_object(ref) }
           logger.debug { "Detoxified the toxic caCORE result #{toxic.qp}." }
         end
         toxic
       end
       
+      # Detoxifies the given domain object. This method is called by {#detoxify} to detoxify a visited
+      # object fetched from the database. This method does not detoxify referenced objects.
+      # 
+      # @param (see #detoxify)
+      def detoxify_object(toxic)
+        ensure_introspected(toxic.class)
+        reconcile_fetched_attributes(toxic)
+        clear_toxic_attributes(toxic)
+      end
+      
+      # Replaces fetched references with cached references where possible.
+      # 
+      # @param (see #detoxify)
+      def reconcile_fetched_attributes(toxic)
+        toxic.class.fetched_domain_attributes.each_pair do |fa, fp|
+          # the fetched reference
+          ref = toxic.send(fa) || next
+          # the inverse attribute
+          fi = fp.inverse
+          # Replace each fetched reference with the cached equivalent, if it exists.
+          if fp.collection? then
+            ref.to_compact_hash { |mbr| @cache[mbr] }.each do |fmbr, cmbr|
+              if fmbr != cmbr and (fi.nil? or cmbr.send(fi).nil?) then
+                ref.delete(fmbr)
+                ref << cmbr
+                logger.debug { "Replaced fetched #{toxic} #{fa} #{fmbr} with cached #{cmbr}." }
+              end
+            end
+          else
+            cref = @cache[ref]
+            if cref and cref != ref and (fi.nil? or cref.send(fi).nil?) then
+              toxic.set_property_value(fa, cref)
+              logger.debug { "Replaced fetched #{toxic} #{fa} #{ref} with cached #{cref}." }
+            end
+          end
+        end
+      end
+      
       # Sets each of the toxic attributes in the given domain object to the corresponding
       # {Metadata#empty_value}.
-      #
-      # @param [Jinx::Resource] toxic the toxic domain object
+      # 
+      # @param (see #detoxify)
       def clear_toxic_attributes(toxic)
-        # The result class might not have been previously referenced. In that case,
-        # introspect the class.
-        ensure_introspected(toxic.class)
         pas = toxic.class.toxic_attributes
         return if pas.empty?
         logger.debug { "Clearing toxic #{toxic.qp} attributes #{pas.to_series}..." }
@@ -117,12 +170,11 @@ module CaRuby
           next unless prop.java_property?
           # the empty or nil value to set
           value = toxic.class.empty_value(pa)
-          # Use the Java writer method rather than the standard attribute writer method.
-          # The standard attribute writer enforces inverse integrity, which potential requires
-          # accessing the current toxic value. The Java writer bypasses inverse integrity.
-          reader, writer = prop.property_accessors
-          # clear the attribute
-          toxic.send(writer, value)
+          # Clear the attribute. Use the Java writer method rather than the standard
+          # attribute writer method. The standard attribute writer enforces inverse integrity,
+          # which potential requires accessing the current toxic value. The Java writer
+          # bypasses inverse integrity.
+          toxic.send(prop.java_writer, value)
         end
       end
       
@@ -131,21 +183,25 @@ module CaRuby
       # * Set the inverses to enforce inverse integrity.
       #
       # @param (see #persistify_object)
+      # @param [Jinx::Resource] other the source domain object
       # @raise [ArgumentError] if obj is a collection and other is not nil
       def persistify(obj, other=nil)
         if obj.collection? then
-          if other then Jinx.fail(ArgumentError, "Database reader persistify other argument not supported") end
+          # A source object is not meaningful for a collection.
+          if other then
+            raise DatabaseError.new("Database reader persistify other argument is not supported for collection #{obj.qp}")
+          end
           obj.each { |ref| persistify(ref) }
           return obj
         end
-        # The attribute type is introspected, but the object might be an unintrospected
-        # subtype. Introspect the object class if necessary.
-        ensure_introspected(obj.class)
-        # set the inverses before recursing to dependents
+        # set the inverses before recursing to references
         set_inverses(obj)
-        # recurse to dependents before adding a lazy loader to the owner
-        obj.dependents.each { |dep| persistify(dep) if dep.identifier }
-        persistify_object(obj, other)
+        @pst_vstr.visit(obj) do |ref|
+          persistify_object(ref) if ref.identifier and ref.snapshot.nil?
+        end
+        # merge the other object content if available
+        obj.merge_into_snapshot(other) if other
+        obj
       end
       
       # Introspects the given class, if necessary. The class must be either introspected
@@ -166,19 +222,22 @@ module CaRuby
       # Takes a {Persistable#snapshot} of obj to track changes, adds a lazy loader and
       # adds the object to the cache.
       #
-      # If the other fetched source object is given, then the obj snapshot is updated
+      # If the other fetched source object is given, then the snapshot is updated
       # with the non-nil values from other.
       #
       # @param [Jinx::Resource] obj the domain object to make persistable
       # @param [Jinx::Resource] other the source domain object
       # @return [Jinx::Resource] obj
       def persistify_object(obj, other=nil)
+        # The attribute type is introspected, but the object might be an unintrospected
+        # subtype. Introspect the object class if necessary.
+        ensure_introspected(obj.class)
         # take a snapshot of the database content
         snapshot(obj, other)
         # add lazy loader to the unfetched attributes
         add_lazy_loader(obj)
         # add to the cache
-        encache(obj)
+        @cache.add(obj)
         obj
       end
       
@@ -214,13 +273,6 @@ module CaRuby
         # merge the other object content if available
         obj.merge_into_snapshot(other) if other
       end
-
-      # @param [Jinx::Resource] obj the object to cache
-      # @raise [ArgumentError] if the given item does not have an identifier
-      def encache(obj)
-        @cache ||= create_cache
-        @cache.add(obj)
-      end    
     
       # @quirk JRuby identifier is not a stable object when fetched from the database, i.e.:
       #     obj.identifier.equal?(obj.identifier) #=> false
@@ -231,10 +283,7 @@ module CaRuby
       # @return [Cache] a new object cache
       def create_cache
         Cache.new do |obj|
-          if obj.identifier.nil? then
-            Jinx.fail(ArgumentError, "Can't cache object without identifier: #{obj}")
-          end
-          obj.identifier.to_s.to_i
+          obj.identifier.to_s.to_i if obj.identifier
         end
       end
     end