caruby-core 1.5.5 → 2.1.1

data/Gemfile

@@ -0,0 +1,9 @@
+source :rubygems
+gemspec
+
+group :development do
+  #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'
+  gem 'caruby-core', :path => File.dirname(__FILE__), :require => 'caruby'
+end

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.
 
-1.5.4 / 2011-09-22
+2.1.1 / 2011-04-13
+------------------
+* Simpler, more flexible meta-data loading.
+
+1.5.5 / 2011-09-22
 ------------------
 * Support mixed-case custom DE package name.
 

data/lib/caruby.rb

@@ -1,5 +1,3 @@
-require 'caruby/resource'
-
-# CaRuby is a JRuby facade for the caBIG application APIs.
-# See the [http://http://caruby.rubyforge.org/](caRuby) home page for more information.
-module CaRuby;end
+require 'jinx'
+require 'jinx/helpers/log'
+require 'jinx/helpers/error'

data/lib/caruby/database.rb

@@ -1,20 +1,17 @@
 require 'generator'
-require 'caruby/util/log'
-require 'caruby/util/collection'
-require 'caruby/util/validation'
-require 'caruby/util/options'
-require 'caruby/util/visitor'
-require 'caruby/util/inflector'
+require 'jinx/helpers/collection'
+require 'jinx/helpers/validation'
+require 'jinx/helpers/options'
+require 'jinx/helpers/visitor'
+require 'jinx/helpers/inflector'
 require 'caruby/database/persistable'
 require 'caruby/database/persistence_service'
+require 'caruby/database/operation'
 require 'caruby/database/reader'
 require 'caruby/database/writer'
 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
 
@@ -39,36 +36,27 @@ module CaRuby
   # The {Writer#save} method creates or updates references as necessary to persist its argument domain object.
   # It is not necessary to fetch references first or follow dependency ordering rules, which can be
   # implicit and tortuous in caBIG applications. Build the object you want to persist and call the
-  # store method. {Resource} sets reasonable default values, recognizes application dependencies and steers
+  # store method. {Jinx::Resource} sets reasonable default values, recognizes application dependencies and steers
   # around caBIG idiosyncracies to the extent possible.
   class Database
     include Reader, Writer, Persistifier
 
-    # Database CRUD operation.
-    class Operation
-      attr_reader :type, :subject, :attribute
-
-      # @param [:find, :query, :create, :udate, :delete] type the database operation type
-      # @param [Persistable] subject the domain object on which the operation is performed
-      # @param [{Symbol => Object}, Symbol, nil] the operation characteristics
-      # @option opts [Symbol] :attribute the query attribute
-      # @option opts [Boolean] :autogenerated whether this is an auto-generated subject update
-      def initialize(type, subject, opts=nil)
-        @type = type
-        @subject = subject
-        @attribute = Options.get(:attribute, opts)
-        @autogenerated = Options.get(:autogenerated, opts, false)
-      end
-      
-      # @return [Boolean] whether this operation is an update of an auto-generated subject
-      def autogenerated?
-        @autogenerated
-      end
-      
-      def to_s
-        "#{@subject.qp} #{attribute} #{type}"
-      end
-    end
+    # The application and database connection access command line options.
+    ACCESS_OPTS = [
+        [:user, "--user USER", "the application login user"],
+        [:password, "--password PSWD", "the application login password"],
+        [:host, "--host HOST", "the application host name"],
+        [:port, "--port PORT", "the application port number"],
+        [:classpath, "--classpath PATH", "the application client classpath"],
+        [:database_host, "--database_host HOST", "the database host name"],
+        [:database_type, "--database_type TYPE", "the database type (mysql or oracle)"],
+        [:database_driver, "--database_driver DRIVER", "the database driver string"],
+        [:database_driver_class, "--database_driver_class CLASS", "the database driver class name"],
+        [:database_port, "--database_port PORT", Integer, "the database port number"],
+        [:database, "--database NAME", "the database name"],
+        [:database_user, "--database_user USER", "the database login user"],
+        [:database_password, "--database_password PSWD", "the database login password"]
+      ]
     
     attr_reader :operations
     
@@ -95,24 +83,28 @@ module CaRuby
     #   to the start_session method and run the +PSBIN::MigrationTest+ biopsy save test case.
     #
     # @param [String] service_name the name of the default {PersistenceService}
-    # @param [{Symbol => String}] opts access options
+    # @param [{Symbol => String}, nil] opts the access options, or nil if specified as a block
     # @option opts [String] :host application service host name
     # @option opts [String] :login application service login user
     # @option opts [String] :password application service login password
+    # @yield the access options defined by a block rather than a parameter
     # @example
     #   Database.new(:user => 'perdita', :password => 'changeMe')
-    def initialize(service_name, opts)
+    def initialize(service_name, opts=nil)
       super()
+      # the options can be defined in a block
+      opts ||= yield if block_given?
+      # import the Java classes on demand
+      Database.import_java_classes
       # the fetched object cache
-      @cache = create_cache
       @defaults = {}
+      if opts.nil? then Jinx.fail(ArgumentError, "Missing required database access properties") end
       @user = Options.get(:user, opts)
       @password = Options.get(:password, opts)
       host = Options.get(:host, opts)
       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
@@ -132,11 +124,6 @@ module CaRuby
       # call the block and close when done
       yield(self) ensure close
     end
-    
-    # Clears the cache.
-    def clear
-      @cache.clear
-    end
 
     # Releases database resources. This method should be called when database interaction
     # is completed.
@@ -161,15 +148,17 @@ module CaRuby
       end
     end
 
-    # Returns the PersistanceService to use for the given domain object.
+    # Returns the PersistanceService to use for the given {Jinx::Resource} class.
     # This base method always returns the standard application service.
-    # Subclasses can override for specialized services. A session is
-    # started on demand if necessary.
+    # Subclasses can override for specialized services. A session is started
+    # on demand if necessary.
     #
-    # @param [Persistable, Class] obj the domain object or {Resource} class
-    # @return [PersistanceService] the service for the domain object
+    # @param [Class] klass the domain object class
+    # @return [PersistanceService] the corresponding service
     def persistence_service(klass)
-       unless Class === klass then raise ArgumentError.new("#{self} persistence_service argument is not a Class: {#klass.qp}") end
+       unless Class === klass then
+         Jinx.fail(ArgumentError, "#{self} persistence_service argument is not a Class: {#klass.qp}")
+       end
        start_session if @session.nil?
        @def_persist_svc
     end
@@ -188,12 +177,18 @@ module CaRuby
     ## Utility classes and methods, used by Query and Store mix-ins ##
 
     private
+
+    # Imports this class's Java classes on demand.
+    def self.import_java_classes
+      # The caBIG client session class.
+      java_import Java::gov.nih.nci.system.comm.client.ClientSession unless const_defined?(:ClientSession)
+    end
     
     # A mergeable autogenerated operation is recursively defined as:
     # * a create of an object with auto-generated dependents
     # * an update of an auto-generated dependent in the context of a mergeable autogenerated operation
     #
-    # @return whether the innermost operation conforms to the above criterion
+    # @return [Boolean] whether the innermost operation conforms to the above criterion
     def mergeable_autogenerated_operation?
       # the inner operation subject
       inner = nil
@@ -219,14 +214,14 @@ module CaRuby
     # Lazy loading is suspended during the operation.
     #
     # @param [:find, :query, :create, :udate, :delete] op the database operation type
-    # @param [Resource] obj the domain object on which the operation is performed
+    # @param [Jinx::Resource] obj the domain object on which the operation is performed
     # @param opts (#see Operation#initialize)
     # @yield the database operation block
     # @return the result of calling the operation block
     def perform(op, obj, opts=nil)
       op_s = op.to_s.capitalize_first
-      attr = Options.get(:attribute, opts)
-      attr_s = " #{attr}" if attr
+      pa = Options.get(:attribute, opts)
+      attr_s = " #{pa}" if pa
       ag_s = " autogenerated" if Options.get(:autogenerated, opts)
       ctxt_s = " in context #{print_operations}" unless @operations.empty?
       logger.info(">> #{op_s}#{ag_s} #{obj.pp_s(:single_line)}#{attr_s}#{ctxt_s}...")
@@ -248,22 +243,10 @@ module CaRuby
       ObjectSpace.each_object(PersistenceService, &block)
     end
     
-    # @return [Cache] a new object cache.
-    def create_cache
-      # @quirk JRuby identifier is not a stable object when fetched from the database, i.e.:
-      #     obj.identifier.equal?(obj.identifier) #=> false
-      #   This is probably an artifact of jRuby Numeric - Java Long conversion interaction
-      #   combined with hash access use of the eql? method. Work-around is to make a Ruby Integer.
-      Cache.new do |obj|
-        raise ArgumentError.new("Can't cache object without identifier: #{obj}") unless obj.identifier
-        obj.identifier.to_s.to_i
-      end
-    end
-    
     # Initializes the default application service.
     def start_session
-      if @user.nil? then raise DatabaseError.new('Application user option missing') end
-      if @password.nil? then raise DatabaseError.new('Application password option missing') end
+      if @user.nil? then Jinx.fail(DatabaseError, 'Application user option missing') end
+      if @password.nil? then Jinx.fail(DatabaseError, 'Application password option missing') end
       @session = ClientSession.instance
       connect(@user, @password)
     end
@@ -283,7 +266,8 @@ module CaRuby
       begin
         @session.start_session(user, password)
       rescue Exception => e
-        logger.error("Login of #{user} unsuccessful - #{e.message}") and raise
+        logger.error("Login of #{user} unsuccessful - #{e.message}")
+        raise e
       end
       logger.info("Connected to application server.")
     end

data/lib/caruby/database/application_service.rb

@@ -0,0 +1,25 @@
+module CaRuby
+  # An ApplicationService wraps a caCORE application service.
+  class ApplicationService
+    # @quirk caCORE When more than one application service is used, then the remote
+    #   instance mustb e reinitialized every time a different application service
+    #   is used.
+    #
+    # @param [String] the service URL
+    # @return the caCORE application service remote instance
+    def self.for(url)
+      # Load the Java class on demand the first time this method is called.
+      if @url.nil? then
+        java_import Java::gov.nih.nci.system.applicationservice.ApplicationServiceProvider
+      end
+      # If the url differs from the current remote instance, then reinitialize.
+      unless @url == url then
+        @url = url
+        logger.debug { "Connecting to service provider at #{@url}..." }
+        @current = ApplicationServiceProvider.remote_instance(@url)
+      end
+      @current
+    end
+  end
+end
+  

data/lib/caruby/database/cache.rb

@@ -0,0 +1,60 @@
+require 'jinx/helpers/lazy_hash'
+require 'jinx/helpers/key_transformer_hash'
+
+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.
+    attr_reader :sticky
+    
+    # @yield [item] returns the key for the given item to cache
+    # @yieldparam item 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.
+      @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}")
+        end
+      end
+      @sticky = Set.new
+    end
+
+    # If there is already a cached object with the same key as the given item,
+    # then this method returns that cached object. Otherwise, this method caches
+    # the given item and returns that item.
+    #
+    # @param item the object to resolve
+    # @return the object cached with the same class and key as the given item
+    # @raise [ArgumentError] if the item does not have a key
+    def [](item)
+      @ckh[item.class][item]
+    end
+    
+    # Adds the given item to this cache, unless one already exists.
+    #
+    # @param item the object to cache
+    # @return the cached item
+    def add(item)
+      @ckh[item.class][item] ||= item
+    end
+    
+    # Adds the given item to this cache. Overwrites an existing cache entry
+    # for the given item's key, if one already exists.
+    #
+    # @param item the object to cache
+    def add!(item)
+      @ckh[item.class][item] = item
+    end
+
+    # Clears the non-sticky class caches.
+    def clear
+      if @sticky.empty? then
+        @ckh.clear
+      else
+        @ckh.each { |klass, ch| ch.clear unless @sticky.include?(klass) }
+      end
+    end
+  end
+end

data/lib/caruby/database/fetched_matcher.rb

@@ -1,58 +1,72 @@
-require 'caruby/util/options'
-require 'caruby/util/collection'
+require 'jinx/helpers/options'
+require 'jinx/helpers/collection'
 
 module CaRuby
   class Database
-    # Proc that matches fetched sources to targets.
+    # Helper that matches fetched sources to targets.
     class FetchedMatcher
-      # Initializes a new FetchedMatcher.
-      def match(srcs, tgts)
-        match_fetched(srcs, tgts)
+      # Returns a target => source match hash for the given targets and sources using
+      # {Jinx::Resource#match_in_owner_scope}.
+      #
+      # caCORE alert = caCORE does not enforce reference identity integrity, i.e. a search on object _a_
+      # with database record references _a_ => _b_ => _a_, the search result might be _a_ => _b_ => _a'_,
+      # where _a.identifier_ == _a'.identifier_. This visit method remedies this caCORE defect by matching
+      # source references on a previously matched identifier where possible.
+      #
+      # @param [<Jinx::Resource>] sources the domain objects to match against
+      # @param [<Jinx::Resource>] targets the domain objects to match
+      # @param [Resource] from the visiting domain object
+      # @param [Symbol] attribute the visiting attribute
+      # @return [{Jinx::Resource => Jinx::Resource}] the source => target matches
+      def match(sources, targets, from, attribute)
+        if sources.empty? or targets.empty? then
+          Hash::EMPTY_HASH 
+        elsif from.class.property(attribute).owner? then
+          match_owner(sources.first, targets.first, from, attribute)
+        else
+          match_fetched(sources, targets)
+        end
       end
       
-      alias :call :match
-      
       private
+      
+      # @param [<Jinx::Resource>] source the fetched owner to match against
+      # @param [<Jinx::Resource>] target the owner to match
+      # @param [Resource] dependent the visiting dependent
+      # @param attribute (see #match)
+      # @return [{Resource => Resource}] the source => target singleton hash, if the source
+      #   and target identifiers don't conflict, otherwise an empty hash
+      def match_owner(source, target, dependent, attribute)
+        return Hash::EMPTY_HASH unless source.minimal_match?(target)
+        logger.debug { "Matched #{dependent} #{attribute} owner #{source} to #{target}." }
+        {source => target}
+      end
 
-      # Returns a target => source match hash for the given targets and sources using
-      # {Resource#match_in_owner_scope}.
-      #
-      # @param [<Resource>] sources the domain objects to match with targets
-      # @param [<Resource>] targets the domain objects to match with targets
-      # @return [{Resource => Resource}] the source => target matches
-      def match_fetched(sources, targets)
-        return Hash::EMPTY_HASH if sources.empty? or targets.empty?
-        # the domain class
-        klass = sources.first.class
-        # the non-owner secondary key domain attributes
-        attrs = klass.secondary_key_attributes.select do |attr|
-          attr_md = klass.attribute_metadata(attr)
-          attr_md.domain? and not attr_md.owner?
-        end
-        
-        # fetch the non-owner secondary key domain attributes as necessary 
-        unless attrs.empty? then
-          sources.each do |src|
-            attrs.each do |attr|
-              next if src.send(attr)
-              logger.debug { "Fetching #{src.qp} #{attr} in order to match on the secondary key..." }
-              ref = src.query(attr).first || next
-              src.set_attribute(attr, ref)
-              logger.debug { "Set fetched #{src.qp} secondary key attribute #{attr} to fetched #{ref}." }
-            end
+      # Fetches the given domain objects non-owner secondary key domain attributes as necessary.
+      def fetch_secondary_key_references(sources)
+        # fetch the secondary key reference if necessary
+        sources.each do |src|
+          src.class.secondary_key_non_owner_domain_attributes.each do |pa|
+            next if src.send(pa)
+            logger.debug { "Fetching #{src.qp} #{pa} in order to match on the secondary key..." }
+            ref = src.query(pa).first || next
+            src.set_property_value(pa, ref)
+            logger.debug { "Set fetched #{src.qp} secondary key attribute #{pa} to fetched #{ref}." }
           end
         end
-        
+      end
+      
+      def match_fetched(sources, targets)
+        # complete the key
+        fetch_secondary_key_references(sources)
         # match source => target based on the secondary key
         unmatched = Set === sources ? sources.dup : sources.to_set
         matches = {}
         targets.each do |tgt|
-          src = tgt.match_in_owner_scope(unmatched)
-          next unless src
+          src = tgt.match_in_owner_scope(unmatched) || next
           matches[src] = tgt
           unmatched.delete(src)
         end
-        
         matches
       end
     end