caruby-core 2.1.1 → 2.1.2

data/lib/caruby/database/writer.rb

@@ -75,9 +75,9 @@ module CaRuby
         # guard against recursive call back into the same operation
         # the only allowed recursive call is a dependent create which first creates the owner
         if recursive_save?(obj, :create) then
-          Jinx.fail(DatabaseError, "Create #{obj.qp} recursively called in context #{print_operations}")
+          raise DatabaseError.new("Create #{obj.qp} recursively called in context #{print_operations}")
         elsif obj.identifier then
-          Jinx.fail(DatabaseError, "Create unsuccessful since #{obj.qp} already has identifier #{obj.identifier}")
+          raise DatabaseError.new("Create unsuccessful since #{obj.qp} already has identifier #{obj.identifier}")
         end
         # create the object
         perform(:create, obj) { create_object(obj) }
@@ -97,7 +97,7 @@ module CaRuby
       def update(obj)
         # guard against a recursive call back into the same operation.
         if recursive_save?(obj, :update) then
-          Jinx.fail(DatabaseError, "Update #{obj.qp} recursively called in context #{print_operations}")
+          raise DatabaseError.new("Update #{obj.qp} recursively called in context #{print_operations}")
         end
         # update the object
         perform(:update, obj) { update_object(obj) }
@@ -140,7 +140,7 @@ module CaRuby
       # @raise [ArgumentError] if obj is nil or empty
       # @raise [DatabaseError] if obj could not be created
       def ensure_exists(obj)
-        Jinx.fail(ArgumentError, "Database ensure_exists is missing a domain object argument") if obj.nil_or_empty?
+        raise ArgumentError.new("Database ensure_exists is missing a domain object argument") if obj.nil_or_empty?
         obj.enumerate { |ref| find(ref, :create) unless ref.identifier }
         
       end
@@ -190,7 +190,7 @@ module CaRuby
           result = create_dependent(owner, obj) if owner
           result ||= create_from_template(obj)
           if result.nil? then
-            Jinx.fail(DatabaseError, "#{obj.class.qp} is not creatable in context #{print_operations}")
+            raise DatabaseError.new("#{obj.class.qp} is not creatable in context #{print_operations}")
           end
         ensure
           # since obj now has an id, removed from transients set
@@ -242,7 +242,7 @@ module CaRuby
       # @raise [DatabaseError] if obj does not have a proxy
       def save_with_proxy(obj)
         proxy = obj.saver_proxy
-        if proxy.nil? then Jinx.fail(DatabaseError, "#{obj.class.qp} does not have a proxy") end
+        if proxy.nil? then raise DatabaseError.new("#{obj.class.qp} does not have a proxy") end
         if recursive_save?(proxy, :create) then
           logger.debug { "Foregoing #{obj.qp} save, since it  will be handled by creating the proxy #{proxy}." }
           return
@@ -419,7 +419,7 @@ module CaRuby
       def update_object(obj)
         # database identifier is required for update
         if obj.identifier.nil? then
-          Jinx.fail(DatabaseError, "Update target is missing a database identifier: #{obj}")
+          raise DatabaseError.new("Update target is missing a database identifier: #{obj}")
         end
         
         # If this object is proxied, then delegate to the proxy.
@@ -435,7 +435,9 @@ module CaRuby
         
         # Update a cascaded dependent by updating the owner.
         owner = cascaded_dependent_owner(obj)
-        if owner then return update_cascaded_dependent(owner, obj) end
+        if owner and owner.updatable? then
+          return update_cascaded_dependent(owner, obj)
+        end
         # Not a cascaded dependent; update using a template.
         update_from_template(obj)
       end
@@ -460,6 +462,9 @@ module CaRuby
       end
       
       def update_from_template(obj)
+        unless obj.updatable? then
+          raise DatabaseError.new("#{obj.class.qp} update is not allowed by caTissue")
+        end
         tmpl = build_update_template(obj)
         # call the caCORE service with an obj update template
         save_with_template(obj, tmpl) { |svc| svc.update(tmpl) }
@@ -512,7 +517,7 @@ module CaRuby
       # @param [TemplateBuilder] builder the builder to use
       # @return [Jinx::Resource] the template to use as the save argument
       def build_save_template(obj, builder)
-        builder.build_template(obj)
+        builder.build_template(obj, @operations.last.autogenerated?)
       end
 
       # @param (see #delete)
@@ -520,7 +525,7 @@ module CaRuby
       def delete_object(obj)
         # database identifier is required for delete
         if obj.identifier.nil? then
-          Jinx.fail(DatabaseError, "Delete target is missing a database identifier: #{obj}")
+          raise DatabaseError.new("Delete target is missing a database identifier: #{obj}")
         end
         persistence_service(obj.class).delete_object(obj)
       end
@@ -561,8 +566,7 @@ module CaRuby
       # @param [Jinx::Resource] target the save argument
       # @param [Jinx::Resource] source the caCORE save result
       def sync_saved(target, source)
-        # clear the toxic source attributes
-        detoxify(source)
+        detoxify_save_result(source)
         # sync the save result source with the database
         sync_saved_result_with_database(source, target)
         # merge the source into the target
@@ -578,6 +582,10 @@ module CaRuby
         save_changed_dependents(target)
       end
       
+      def detoxify_save_result(source)
+        detoxify(source)
+      end
+      
       # Synchronizes the given save result with the database content.
       # The source is synchronized by {#sync_save_result}.
       #

data/lib/caruby/database/writer_template_builder.rb

@@ -18,7 +18,7 @@ module CaRuby
         def initialize(database)
           @database = database
           unless block_given? then
-            Jinx.fail(ArgumentError, "@{qp} is missing the required template copy attribute selector block")
+            raise ArgumentError.new("@{qp} is missing the required template copy attribute selector block")
           end
       
           # the mergeable attributes filter the given block with exclusions
@@ -79,12 +79,13 @@ module CaRuby
         #   objects. These uncascaded objects should be ignored by the application but aren't.
         #
         # @param [Jinx::Resource] obj the domain object to save
+        # @param [Boolean] autogenerated whether the save is an auto-generated object update
         # @return [Jinx::Resource] the template to use as the caCORE argument
         def build_template(obj, autogenerated=false)
           # set the database operation subject
           @subject = obj
           # prepare the object for a store operation
-          ensure_savable(obj)
+          ensure_savable(obj, autogenerated)
           # copy the cascade hierarchy
           logger.debug { "Building savable template for #{obj.qp}..." }
           tmpl = @copy_vstr.visit(obj)
@@ -105,8 +106,9 @@ module CaRuby
         #   metadata and creates them if necessary.
         #
         # @param [Jinx::Resource] obj the object to save
+        # @param [Boolean] autogenerated whether the save is an auto-generated object update
         # @raise [ValidationError] if the object is invalid
-        def ensure_savable(obj)
+        def ensure_savable(obj, autogenerated)
           # Ensure that an update is fetched to complete the object state with any missing references.
           if obj.identifier and not obj.fetched? then
             logger.debug { "Fetching #{obj} prior to building a save template..." }
@@ -123,8 +125,8 @@ module CaRuby
             @database.ensure_exists(prereqs)
             logger.debug { "Prerequisite references for #{obj.qp} exist: #{prereqs.map { |ref| ref }.to_series}." }
           end
-          # Verify that the object is complete
-          obj.validate
+          # Verify that the object is complete.
+          obj.validate(autogenerated)
         end
         
         # Fetches the given update object savable references on demand.
@@ -293,7 +295,7 @@ module CaRuby
         # @param [Jinx::Resource] obj the domain object to save
         # @return [<Jinx::Resource>] the references which must be created in order to store the object
         def collect_prerequisites(obj)
-          prereqs = Set.new
+          prereqs = Array.new
           # visit the cascaded attributes
           @prereq_vstr.visit(obj) do |pref|
             # Check each mergeable attribute for prerequisites. The mergeable attributes includes
@@ -326,6 +328,8 @@ module CaRuby
               end
             end
           end
+          # Remove duplicates.
+          prereqs.uniq!
           prereqs
         end
       end

data/lib/caruby/database.rb

@@ -36,27 +36,28 @@ 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. {Jinx::Resource} sets reasonable default values, recognizes application dependencies and steers
-  # around caBIG idiosyncracies to the extent possible.
+  # 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
 
     # 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"]
-      ]
+      [:user, '-u USER', '--user USER', 'the application login user'],
+      [:password, '-p PSWD', '--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_port, '--database_port PORT', Integer, 'the database port number'],
+      [:database, '--database NAME', 'the database name'],
+      [:database_url, '--database_url URL', 'the database connection URL'],
+      [: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_user, '--database_user USER', 'the database login user'],
+      [:database_password, '--database_password PSWD', 'the database login password']
+    ]
     
     attr_reader :operations
     
@@ -92,18 +93,14 @@ module CaRuby
     #   Database.new(:user => 'perdita', :password => 'changeMe')
     def initialize(service_name, opts=nil)
       super()
-      # the options can be defined in a block
+      # 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
-      @defaults = {}
-      if opts.nil? then Jinx.fail(ArgumentError, "Missing required database access properties") end
+      if opts.nil? then raise ArgumentError.new("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
+      # The class => service hash is populated with the default service.
       @def_persist_svc = PersistenceService.new(service_name, :host => host, :port => port)
       @persistence_services = [@def_persist_svc].to_set
       @cls_svc_hash = Hash.new(@def_persist_svc)
@@ -112,33 +109,34 @@ module CaRuby
       # the objects for which exists? is unsuccessful in the context of a nested operation
       @transients = Set.new
     end
+    
+    # @return [Boolean] whether there is an active session
+    def open?
+      !!@session
+    end
+    
+    # @return [Boolean] whether this database is not {#open?}
+    def closed?
+      not open?
+    end
 
     # Calls the block given to this method with this database as an argument, and closes the
     # database when done.
     #
+    # @param [String, nil] user the application login user
+    # @param [String, nil] password the application login password
     # @yield [database] the operation to perform on the database
     # @yieldparam [Database] database self
-    def open
+    def open(user=nil, password=nil)
+      raise ArgumentError.new("Database open requires an execution block") unless block_given?
+      raise DatabaseError.new("The caRuby application database is already in use.") if open?
       # reset the execution timers
       persistence_services.each { |svc| svc.timer.reset }
-      # call the block and close when done
+      # Start the session.
+      start_session(user, password)
+      # Call the block and close when done.
       yield(self) ensure close
     end
-
-    # Releases database resources. This method should be called when database interaction
-    # is completed.
-    def close
-      return if @session.nil?
-      begin
-        @session.terminate_session
-      rescue Exception => e
-        logger.error("Session termination unsuccessful - #{e.message}")
-      end
-      # clear the cache
-      clear
-      logger.info("Disconnected from application server.")
-      @session = nil
-    end
     
     # @return [Numeric] the execution time in seconds spent since the last open
     def execution_time
@@ -157,9 +155,8 @@ module CaRuby
     # @return [PersistanceService] the corresponding service
     def persistence_service(klass)
        unless Class === klass then
-         Jinx.fail(ArgumentError, "#{self} persistence_service argument is not a Class: {#klass.qp}")
+         raise ArgumentError.new("#{self} persistence_service argument is not a Class: {#klass.qp}")
        end
-       start_session if @session.nil?
        @def_persist_svc
     end
     
@@ -169,6 +166,15 @@ module CaRuby
     def add_persistence_service(service)
       @persistence_services << service
     end
+    
+    # Imports the caCORE +ClientSession+ class on demand.
+    def self.const_missing(sym)
+      if sym == :ClientSession then
+        java_import Java::gov.nih.nci.system.comm.client.ClientSession
+      else
+        super
+      end
+    end
 
     alias :to_s :print_class_and_id
 
@@ -178,10 +184,19 @@ module CaRuby
 
     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)
+    # Releases database resources. This method should be called when database interaction
+    # is completed.
+    def close
+      return if @session.nil?
+      begin
+        @session.terminate_session
+      rescue Exception => e
+        logger.error("Session termination unsuccessful - #{e.message}")
+      end
+      # clear the cache
+      clear
+      logger.info("Disconnected from application server.")
+      @session = nil
     end
     
     # A mergeable autogenerated operation is recursively defined as:
@@ -213,22 +228,34 @@ module CaRuby
     # Performs the operation given by the given op symbol on obj by calling the block given to this method.
     # Lazy loading is suspended during the operation.
     #
-    # @param [:find, :query, :create, :udate, :delete] op the database operation type
-    # @param [Jinx::Resource] obj the domain object on which the operation is performed
+    # @param [:find, :query, :create, :update, :delete] op the database operation type
+    # @param [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)
+    def perform(op, obj, opts=nil, &block)
       op_s = op.to_s.capitalize_first
       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}...")
+      # Clear the error flag.
+      @error = nil
+      # Push the operation on the nested operation stack.
       @operations.push(Operation.new(op, obj, opts))
       begin
         # perform the operation
-        result = @lazy_loader.suspend { yield }
+        result = perform_operation(&block)
+      rescue Exception => e
+        # If the current operation is the immediate cause, then print the
+        # error to the log.
+        if @error.nil? then
+          msg = "Error performing #{op} on #{obj}:\n#{e.message}\n#{obj.dump}\n#{e.backtrace.qp}"
+          logger.error(msg)
+          @error = e
+        end
+        raise e
       ensure
         # the operation is done
         @operations.pop
@@ -239,16 +266,31 @@ module CaRuby
       result
     end
     
+    # Calls the given block with the lazy loader suspended.
+    # The database is opened, if necessary.
+    #  
+    # @yield the database operation block
+    # @return the result of calling the operation block 
+    def perform_operation(&block)
+      if closed? then
+       open { perform_operation(&block) }
+      else  
+        @lazy_loader.suspend { yield }
+      end
+    end
+    
     def each_persistence_service(&block)
       ObjectSpace.each_object(PersistenceService, &block)
     end
     
     # Initializes the default application service.
-    def start_session
-      if @user.nil? then Jinx.fail(DatabaseError, 'Application user option missing') end
-      if @password.nil? then Jinx.fail(DatabaseError, 'Application password option missing') end
+    def start_session(user=nil, password=nil)
+      user ||= @user
+      password ||= @password
+      if user.nil? then raise DatabaseError.new('The caRuby application is missing the login user') end
+      if password.nil? then raise DatabaseError.new('The caRuby application is missing the login password') end
       @session = ClientSession.instance
-      connect(@user, @password)
+      connect(user, password)
     end
 
     # Returns the current database operation stack as a String.
@@ -266,7 +308,7 @@ module CaRuby
       begin
         @session.start_session(user, password)
       rescue Exception => e
-        logger.error("Login of #{user} unsuccessful - #{e.message}")
+        logger.error("Login of #{user} with password #{password} was unsuccessful - #{e.message}")
         raise e
       end
       logger.info("Connected to application server.")

data/lib/caruby/helpers/coordinate.rb

@@ -83,13 +83,13 @@ class Coordinate < Array
   # @raise [TypeError] if other is not a Coordinate
   def <=>(other)
     return 0 if equal?(other)
-    Jinx.fail(TypeError, "Can't compare #{self} with #{other} since it is not a Coordinate") unless Coordinate === other
-    Jinx.fail(ArgumentError, "Can't compare #{self} with #{other} since it has a different dimension count") unless size == other.size
+    raise TypeError.new("Can't compare #{self} with #{other} since it is not a Coordinate") unless Coordinate === other
+    raise ArgumentError.new("Can't compare #{self} with #{other} since it has a different dimension count") unless size == other.size
     REXML::SyncEnumerator.new(self.reverse, other.reverse).each_with_index do |pair, index|
       dim = pair.first
       odim = pair.last
-      Jinx.fail(ArgumentError, "Can't compare #{self} with missing dimension #{index} to #{other}") unless dim
-      Jinx.fail(ArgumentError, "Can't compare #{self} to #{other} with missing dimension #{index}") unless odim
+      raise ArgumentError.new("Can't compare #{self} with missing dimension #{index} to #{other}") unless dim
+      raise ArgumentError.new("Can't compare #{self} to #{other} with missing dimension #{index}") unless odim
       cmp = dim <=> odim
       return cmp unless cmp.zero?
     end

data/lib/caruby/helpers/person.rb

@@ -119,10 +119,10 @@ module CaRuby
       # or if there is a middle name but no first name
       def validate
         if last.nil? and first.nil? then
-          Jinx.fail(Jinx::ValidationError, "Name is missing both the first and last fields")
+          raise Jinx::ValidationError.new("Name is missing both the first and last fields")
         end
         if !middle.nil? and first.nil? then
-          Jinx.fail(Jinx::ValidationError, "Name with middle field #{middle} is missing the first field")
+          raise Jinx::ValidationError.new("Name with middle field #{middle} is missing the first field")
         end
       end
 

data/lib/caruby/helpers/properties.rb

@@ -66,12 +66,12 @@ module CaRuby
     #
     # Raises ConfigurationError if file doesn't exist or couldn't be parsed.
     def load_properties(file)
-      Jinx.fail(ConfigurationError, "Properties file not found: #{File.expand_path(file)}") unless File.exists?(file)
+      raise ConfigurationError.new("Properties file not found: #{File.expand_path(file)}") unless File.exists?(file)
       properties = {}
       begin
-        YAML::load_file(file).each { |key, value| properties[key.to_sym] = value }
+        YAML.load_file(file).each { |key, value| properties[key.to_sym] = value }
       rescue
-        Jinx.fail(ConfigurationError, "Could not read properties file #{file}: " + $!)
+        raise ConfigurationError.new("Could not read properties file #{file}: " + $!)
       end
       # Uncomment the following line to print detail properties.
       #logger.debug { "#{file} properties:\n#{properties.pp_s}" }
@@ -103,7 +103,7 @@ module CaRuby
     # Validates that the required properties exist.
     def validate_properties
       @required_properties.each do |key|
-        Jinx.fail(ConfigurationError, "A required #{@application} property was not found: #{key}") unless has_property?(key)
+        raise ConfigurationError.new("A required #{@application} property was not found: #{key}") unless has_property?(key)
       end
     end
   end

data/lib/caruby/helpers/roman.rb

@@ -6,7 +6,7 @@ class String
       when /^(I{0,3})$/ then $1.size
       when /^(I{0,3})(V|X)$/ then ROMAN_UNITS[$2] - $1.size
       when /^(V)(I{0,3})$/ then ROMAN_UNITS[$1] + $2.size
-      else Jinx.fail(ArgumentError, "#{self} is not a roman numeral in the range I-X")
+      else raise ArgumentError.new("#{self} is not a roman numeral in the range I-X")
     end
   end
   
@@ -18,7 +18,7 @@ end
 class Integer
   # @return [String] the roman numeral equivalent of this integer
   def to_roman
-    if self < 1 or self > 10 then Jinx.fail(ArgumentError, "#{self} cannot be converted to a roman numeral in the range I-X")
+    if self < 1 or self > 10 then raise ArgumentError.new("#{self} cannot be converted to a roman numeral in the range I-X")
     elsif self < 4 then 'I' * self
     elsif self < 6 then ('I' * (5 - self)) + 'V'
     elsif self < 9 then 'V' + ('I' * (self - 5))

data/lib/caruby/helpers/version.rb

@@ -26,7 +26,7 @@ class Version < Array
   #   Version.new(1, 1, beta) > beta #=> true
   def <=>(other)
     return 0 if equal?(other)
-    Jinx.fail(ArgumentError, "Comparand is not a #{self.class}: #{other}") unless self.class === other
+    raise ArgumentError.new("Comparand is not a #{self.class}: #{other}") unless self.class === other
     return -1 if other.predecessor == self
     return 1 unless predecessor.nil? or predecessor < other
     each_with_index do |component, index|

data/lib/caruby/json/serializable.rb

@@ -0,0 +1,17 @@
+require 'jinx/json/serializable'
+
+module CaRuby
+  module JSON
+    module Serializable
+      include Jinx::JSON::Serializable
+      
+      # This method disables lazy-loading before delegating to Jinx.
+      #
+      # @param [State, Hash, nil] state the JSON state or serialization options
+      # @return [String] the JSON representation of this {Jinx::Resource}
+      def to_json(state=nil)
+        fetched? ? super : do_without_lazy_loader { super }
+      end
+    end
+  end
+end

data/lib/caruby/metadata/propertied.rb

@@ -168,9 +168,16 @@ module CaRuby
     
     alias :toxic_attributes :unfetched_attributes
 
+    # @quirk JRuby - This method body is copied to the +CaTissue::Metadata+ superclass since
+    #   calling super from that class's overloaded +loadable_attributes+ method results in
+    #   an infinite loop.
+    #
     # @return [<Symbol>] the Java attribute non-abstract {#unfetched_attributes}
     def loadable_attributes
-      @ld_flt ||= unfetched_attributes.compose { |prop| prop.java_property? and not prop.type.abstract? }
+      # A change to this method body must be copied to CaTissue::Metadata; see rubydoc above.
+      @ld_flt ||= unfetched_attributes.compose do |prop|
+        prop.java_property? and not prop.type.abstract? and not prop.transient?
+      end
     end
     
     private