caruby-core 1.4.7 → 1.4.9

data/lib/caruby/database.rb

@@ -6,16 +6,15 @@ require 'caruby/util/options'
 require 'caruby/util/visitor'
 require 'caruby/util/inflector'
 require 'caruby/database/persistable'
-require 'caruby/database/persistifier'
+require 'caruby/database/persistence_service'
 require 'caruby/database/reader'
 require 'caruby/database/writer'
-require 'caruby/database/persistence_service'
-
-# the caBIG client classes
-import 'gov.nih.nci.system.applicationservice.ApplicationServiceProvider'
-import 'gov.nih.nci.system.comm.client.ClientSession'
+require 'caruby/database/persistifier'
 
 module CaRuby
+  # The caBIG client session class.
+  java_import Java::gov.nih.nci.system.comm.client.ClientSession
+  
   # Database operation error.
   class DatabaseError < RuntimeError; end
 
@@ -43,7 +42,7 @@ module CaRuby
   # store method. CaRuby::Resource sets reasonable default values, recognizes application dependencies and steers
   # around caBIG idiosyncracies to the extent possible.
   class Database
-    include Reader, Writer, Persistifier, Validation
+    include Reader, Writer, Persistifier
 
     # Database CRUD operation.
     class Operation
@@ -78,6 +77,24 @@ module CaRuby
 
     # Creates a new Database with the specified service name and options.
     #
+    # caCORE alert - obtaining a caCORE session instance mysteriously depends on referencing the
+    # application service first. Therefore, the default persistence service appService method must
+    # be called after it is instantiated and before the session is instantiated. However, when
+    # the appService method is called just before a session is acquired, then this call corrupts
+    # the object state of existing objects.
+    #
+    # Specifically, when a CaTissue::CollectionProtocol is created which references a
+    # CaTissue::CollectionProtocolRegistration which in turn references a CaTissue::Participant,
+    # then the call to PersistenceService.appService replaces the CaTissue::Participant
+    # reference with a difference CaTissue::Participant instance. The work-around for
+    # this extremely bizarre bug is to call appService immediately after instantiating
+    # the default persistence service.
+    #
+    # This bug might be a low-level JRuby-Java-caCORE-Hibernate confusion where something in
+    # caCORE stomps on an existing JRuby object graph. To reproduce, move the appService call
+    # to the start_session method and run PCBIN::MigrationTest#test_save with all but the
+    # verify_save(:biopsy, BIOPSY_OPTS) line commented out.
+    #
     # @param [String] service_name the name of the default {PersistenceService}
     # @param [{Symbol => String}] opts access options
     # @option opts [String] :host application service host name
@@ -96,6 +113,7 @@ module CaRuby
       port = Options.get(:port, opts)
       # class => service hash; default is the catissuecore app service
       @def_persist_svc = PersistenceService.new(service_name, :host => host, :port => port)
+      @def_persist_svc.app_service
       @persistence_services = [@def_persist_svc].to_set
       @cls_svc_hash = Hash.new(@def_persist_svc)
       # the create/update nested operations
@@ -149,11 +167,12 @@ module CaRuby
     # Subclasses can override for specialized services. A session is
     # started on demand if necessary.
     #
-    # @param [Persistable] obj the domain object
+    # @param [Persistable, Class] obj the domain object or {Resource} class
     # @return [PersistanceService] the service for the domain object
-    def persistence_service(obj)
-      start_session if @session.nil?
-      @def_persist_svc
+    def persistence_service(klass)
+       unless Class === klass then raise ArgumentError.new("#{self} persistence_service argument is not a Class: {#klass.qp}") end
+       start_session if @session.nil?
+       @def_persist_svc
     end
     
     # Adds the given service to this database.
@@ -244,11 +263,9 @@ module CaRuby
     
     # Initializes the default application service.
     def start_session
-      raise DatabaseError.new('Application user option missing') if @user.nil?
-      raise DatabaseError.new('Application password option missing') if @password.nil?
-      # caCORE alert - obtaining a caCORE session instance mysteriously depends on referencing the application service first
-      @def_persist_svc.app_service
-      @session = ClientSession.instance()
+      if @user.nil? then raise DatabaseError.new('Application user option missing') end
+      if @password.nil? then raise DatabaseError.new('Application password option missing') end
+      @session = ClientSession.instance
       connect(@user, @password)
     end
 

data/lib/caruby/database/lazy_loader.rb

@@ -3,19 +3,40 @@ require 'caruby/database/fetched_matcher'
 module CaRuby
   class Database
     # A LazyLoader fetches an association from the database on demand.
-    class LazyLoader < Proc
+    class LazyLoader
       # Creates a new LazyLoader which calls the loader block on the subject.
       #
       # @yield [subject, attribute] fetches the given subject attribute value from the database
       # @yieldparam [Resource] subject the domain object whose attribute is to be loaded
       # @yieldparam [Symbol] attribute the domain attribute to load
       def initialize(&loader)
-        super { |sbj, attr| load(sbj, attr, &loader) }
+        @loader = loader
         # the fetch result matcher
         @matcher = FetchedMatcher.new
         @enabled = true
       end
   
+      # @param [Resource] subject the domain object whose attribute is to be loaded
+      # @param [Symbol] the domain attribute to load
+      # @yield (see #initialize)
+      # @yieldparam (see #initialize)
+      # @return the attribute value loaded from the database
+      # @raise [RuntimeError] if this loader is disabled
+      def load(subject, attribute)
+        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)
+        # load the fetched value
+        fetched = @loader.call(subject, attribute)
+        # nothing to merge if nothing fetched
+        return oldval if fetched.nil_or_empty?
+        # merge the fetched into the attribute
+        logger.debug { "Merging #{subject.qp} fetched #{attribute} value #{fetched.qp}#{' into ' + oldval.qp if oldval}..." }
+        matches = @matcher.match(fetched.to_enum, oldval.to_enum)
+        subject.merge_attribute(attribute, fetched, matches)
+      end
+      
       # Disables this lazy loader. If the loader is already disabled, then this method is a no-op.
       # Otherwise, if a block is given, then the lazy loader is reenabled after the block is executed.
       #
@@ -74,27 +95,6 @@ module CaRuby
       # @return [Boolean] true if this loader was previously disabled, false otherwise
       def set_enabled
         disabled? and (@enabled = true)
-      end
-  
-      # @param [Resource] subject the domain object whose attribute is to be loaded
-      # @param [Symbol] the domain attribute to load
-      # @yield (see #initialize)
-      # @yieldparam (see #initialize)
-      # @return the attribute value loaded from the database
-      # @raise [RuntimeError] if this loader is disabled
-      def load(subject, attribute)
-        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)
-        # load the fetched value
-        fetched = yield(subject, attribute)
-        # nothing to merge if nothing fetched
-        return oldval if fetched.nil_or_empty?
-        # merge the fetched into the attribute
-        logger.debug { "Merging #{subject.qp} fetched #{attribute} value #{fetched.qp}#{' into ' + oldval.qp if oldval}..." }
-        matches = @matcher.match(fetched.to_enum, oldval.to_enum)
-        subject.merge_attribute(attribute, fetched, matches)
       end    
     end
   end

data/lib/caruby/database/persistable.rb

@@ -8,10 +8,8 @@ module CaRuby
   # The Persistable mixin adds persistance capability. Every instance which includes Persistable
   # must respond to an overrided {#database} method.
   module Persistable
-    include Validation
-
-    # @return [{Symbol => Object}] the content value hash at the point of the last
-    #  take_snapshot call
+    # @return [{Symbol => Object}] the content value hash at the point of the last {#take_snapshot}
+    #   call
     attr_reader :snapshot
       
     # @param [Resource, <Resource>, nil] obj the object(s) to check
@@ -30,10 +28,17 @@ module CaRuby
       not saved?(obj)
     end
     
-    # @return [Database] the data access mediator for this Persistable
-    # @raise [NotImplementedError] if the Persistable subclass does not define this method
+    # Returns the data access mediator for this domain object, if any. The default implementation
+    # returns nil. Application #{Resource} modules can override this method.
+    #
+    # @return [Database, nil] the data access mediator for this Persistable, if any
     def database
-      raise NotImplementedError.new("Database operations are not available for #{self}")
+      nil
+    end
+    
+    # @return [PersistenceService, nil] the database application service for this Persistable, if any
+    def persistence_service
+      database.persistence_service(self.class) if database
     end
 
     # Fetches the domain objects which match this template from the {#database}.
@@ -177,13 +182,12 @@ module CaRuby
     def add_lazy_loader(loader, attributes=nil)
       # guard against invalid call
       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?
       # define the reader and writer method overrides for the missing attributes
-      loaded = attributes.select { |attr| inject_lazy_loader(attr) }
-      logger.debug { "Lazy loader added to #{qp} attributes #{loaded.to_series}." } unless loaded.empty?
+      attrs = attributes.select { |attr| inject_lazy_loader(attr) }
+      logger.debug { "Lazy loader added to #{qp} attributes #{attrs.to_series}." } unless attrs.empty?
     end
     
     # Returns the attributes to load on demand. The base attribute list is given by the
@@ -361,7 +365,6 @@ module CaRuby
       vh = @snapshot
       ovh = value_hash(self.class.updatable_attributes)
       
-      
       # KLUDGE TODO - confirm this is still a problem and fix
       # In Galena frozen migration example, SpecimenPosition snapshot doesn't include identifier; work around this here
       # This could be related to the problem of an abstract DomainObject not being added as a domain module class. See the
@@ -371,8 +374,6 @@ module CaRuby
       end
       # END OF KLUDGE
       
-      
-      
       if vh.size < ovh.size then
         attr, oval = ovh.detect { |a, v| not vh.has_key?(a) }
         logger.debug { "#{qp} is missing snapshot #{attr} compared to the current value #{oval.qp}." }
@@ -400,7 +401,7 @@ module CaRuby
     # @return [Boolean] whether a loader was added to the attribute
     def inject_lazy_loader(attribute)
       # bail if there is already a value
-      send(attribute).enumerate { |ref| return false unless ref.identifier }
+      return false if attribute_loaded?(attribute)
       # the accessor methods to modify
       reader, writer = self.class.attribute_metadata(attribute).accessors
       # The singleton attribute reader method loads the reference once and thenceforth calls the
@@ -411,6 +412,15 @@ module CaRuby
       instance_eval "def #{writer}(value); remove_lazy_loader(:#{attribute}); super; end"
       true
     end
+    
+    # @param (see #inject_lazy_loader)
+    # @return [Boolean] whether the attribute references one or more domain objects, and each
+    #   referenced object has an identifier
+    def attribute_loaded?(attribute)
+      value = transient_value(attribute)
+      return false if value.nil_or_empty?
+      Enumerable === value ? value.all? { |ref| ref.identifier } : value.identifier
+    end
 
     # Loads the reference attribute database value into this Persistable.
     #
@@ -419,14 +429,12 @@ module CaRuby
     def load_reference(attribute)
       ldr = database.lazy_loader
       # bypass the singleton method and call the class instance method if the lazy loader is disabled
-      unless ldr.enabled? then
-        return self.class.instance_method(attribute).bind(self).call
-      end
+      return transient_value(attribute) unless ldr.enabled?
       
       # Disable lazy loading first for the attribute, since the reader method is called by the loader.
       remove_lazy_loader(attribute)
       # load the fetched value
-      merged = ldr.call(self, attribute)
+      merged = ldr.load(self, attribute)
       
       # update dependent snapshots if necessary
       attr_md = self.class.attribute_metadata(attribute)
@@ -447,6 +455,12 @@ module CaRuby
       
       merged
     end
+    
+    # @param (see #load_reference)
+    # @return the in-memory attribute value, without invoking the lazy loader
+    def transient_value(attribute)
+      self.class.instance_method(attribute).bind(self).call
+    end
 
     # Disables the given singleton attribute accessor method.
     #

data/lib/caruby/database/persistence_service.rb

@@ -2,9 +2,16 @@ require 'caruby/util/version'
 require 'caruby/database'
 require 'caruby/util/stopwatch'
 
-import 'gov.nih.nci.common.util.HQLCriteria'
-
 module CaRuby
+  # HQLCriteria is required for the query_hql method.
+  java_import Java::gov.nih.nci.common.util.HQLCriteria
+  
+  # The encapsulated caBIG service class.
+  java_import Java::gov.nih.nci.system.applicationservice.ApplicationServiceProvider
+  
+  # This import is not strictly necessary, but works around Ticket #5.
+  java_import Java::gov.nih.nci.system.comm.client.ApplicationServiceClientImpl
+  
   # A PersistenceService wraps a caCORE application service.
   class PersistenceService
     # The service name.
@@ -17,14 +24,15 @@ module CaRuby
     #
     # @param [String] the caBIG application service name
     # @param [{Symbol => Object}] opts the options
-    # @option opts :host the service host (default +localhost+)
-    # @option opts :version the caTissue version identifier
+    # @option opts [String] :host the service host (default +localhost+)
+    # @option opts [String] :version the caTissue version identifier
     def initialize(name, opts={})
       @name = name
       ver_opt = opts[:version]
       @version = ver_opt.to_s.to_version if ver_opt
       @host = opts[:host] || default_host
       @port = opts[:port] || 8080
+      @url = "http://#{@host}:#{@port}/#{@name}/http/remoteService"
       @timer = Stopwatch.new
       logger.debug { "Created persistence service #{name} at #{@host}:#{@port}." }
     end
@@ -81,11 +89,16 @@ module CaRuby
       end
     end
 
+    # Returns a freshly initialized ApplicationServiceProvider remote instance.
+    #
+    # caCORE alert - When more than one application service is used, each call to the service
+    # must reinitialize the remote instance. E.g. this is done in the caTissue DE examples,
+    # and is a good general practice.
+    #
     # @return [ApplicationServiceProvider] the CaCORE service provider wrapped by this PersistenceService
     def app_service
-      url = "http://#{@host}:#{@port}/#{@name}/http/remoteService"
-      logger.debug { "Connecting to service provider at #{url}..." }
-      ApplicationServiceProvider.remote_instance(url)
+      logger.debug { "Connecting to service provider at #{@url}..." }
+      ApplicationServiceProvider.remote_instance(@url)
     end
 
     private

data/lib/caruby/database/reader.rb

@@ -13,7 +13,7 @@ module CaRuby
       def initialize
         super
         # the query template builder
-        @srch_tmpl_bldr = SearchTemplateBuilder.new(self)
+        @srch_tmpl_bldr = SearchTemplateBuilder.new
         # the fetch result matcher
         @matcher = FetchedMatcher.new
         # the fetched copier
@@ -85,16 +85,18 @@ module CaRuby
         end
       end
 
-      # Returns whether domain object obj has a database identifier or exists in the database.
-      # This method fetches obj from the database if necessary.
-      # If obj is a domain object collection, then returns whether each item in the collection exists.
+      # 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 [Resource, <Resource>] obj the domain object(s) to find
+      # @return [Boolean] whether the domain object(s) exist in the database
       def exists?(obj)
         if obj.nil? then
           false
         elsif obj.collection? then
           obj.all? { |item| exists?(item) }
         else
-          obj.identifier or (obj.searchable? and find(obj))
+          obj.identifier or find(obj)
         end
       end
       
@@ -196,9 +198,8 @@ module CaRuby
       def query_hql(hql)
         java_name = hql[/from\s+(\S+)/i, 1]
         raise DatabaseError.new("Could not determine target type from HQL: #{hql}") if java_name.nil?
-        target = Class.to_ruby(java_name)
-        service = persistence_service(target)
-        service.query(hql)
+        tgt = Class.to_ruby(java_name)
+        persistence_service(tgt).query(hql)
       end
 
       # Returns an array of objects fetched from the database which matches
@@ -229,9 +230,9 @@ module CaRuby
       # 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)
-        target = attribute ? template.class.domain_type(attribute) : template.class
-        service = persistence_service(target)
-        attribute ? service.query(template, attribute) : service.query(template)
+        tgt = attribute ? template.class.domain_type(attribute) : template.class
+        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.
@@ -272,6 +273,10 @@ module CaRuby
 
       # Queries the given query object attribute by querying an attribute type template which references obj.
       #
+      # caCORE alert - 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.
+      #
       # @param (see #query_object)
       def query_with_inverted_reference(obj, attribute=nil)
         attr_md = obj.class.attribute_metadata(attribute)
@@ -282,17 +287,15 @@ module CaRuby
         tmpl = attr_md.type.new
         # the inverse attribute
         inv_md = tmpl.class.attribute_metadata(attr_md.inverse)
-        # 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
+        # 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_md attribute is set to ref.
-        # caCORE alert - caCORE query relies on a lack of inverse integrity, since caCORE search
-        # enters an infinite loop upon encountering an object graph cycle.
-        writer = inv_md.property_accessors.last
+        wtr = inv_md.property_writer
         # parameterize tmpl with inverse ref
-        tmpl.send(writer, ref)
+        tmpl.send(wtr, ref)
         # submit the query
         logger.debug { "Submitting #{obj.qp} #{attribute} inverted query template #{tmpl.qp} ..." }
-        persistence_service(tmpl).query(tmpl)
+        persistence_service(tmpl.class).query(tmpl)
       end
 
       # Finds the database content matching the given search object and merges the matching
@@ -310,7 +313,7 @@ module CaRuby
       # @raise [DatabaseError] if more than object matches the obj attribute values or if
       #   the search object is a dependent entity that does not reference an owner
       def find_object(obj)
-       if @transients.include?(obj) then
+        if @transients.include?(obj) then
           logger.debug { "Find #{obj.qp} obviated since the search was previously unsuccessful in the current database operation context." }
           return
         end
@@ -327,7 +330,6 @@ module CaRuby
         # so it is done manually here.
         # recursively copy the nondomain attributes, esp. the identifer, of the fetched domain object references
         merge_fetched(fetched, obj)
-
         # caCORE alert - see query method alerts.
         # Inject the lazy loader for loadable domain reference attributes.
         persistify(obj, fetched)
@@ -354,7 +356,6 @@ 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.
         if result.size > 1 then