caruby-core 2.1.1 → 2.1.2

data/lib/caruby/metadata/property_characteristics.rb

@@ -9,37 +9,38 @@ module CaRuby
     # +:autogenerated+ flag.
     SUPPORTED_FLAGS = [
       :autogenerated, :logical, :cascaded, :no_cascade_update_to_create, :saved, :unsaved, :fetched,
-      :unfetched, :include_in_save_template, :fetch_saved, :create_only, :update_only, :nosync,
-      :volatile].to_set
+      :unfetched, :transient, :include_in_save_template, :fetch_saved, :create_only, :update_only,
+      :nosync, :volatile].to_set
 
-    # Returns whether the subject attribute is fetched, determined as follows:
-    # * An attribute marked with the :fetched flag is fetched.
-    # * An attribute marked with the :unfetched flag is not fetched.
-    # Otherwise, a non-domain attribute is fetched, and a domain attribute is
-    # fetched if one of the following conditions hold:
-    # * A dependent domain attribute is fetched if it is not logical.
-    # * An owner domain attribute is fetched by default.
-    # * An independent domain attribute is fetched if it is abstract and not derived.
+    # Returns whether this property is fetched, determined as follows:
+    # * this property is marked with the +:fetched+ flag
+    # * this property is not marked with the +:transient+ or +:unfetched+ flag
+    # * otherwise, this is a non-domain property
+    # * otherwise, this is a domain property and one of the following conditions hold:
+    #   * this is a non-logical dependent domain property
+    #   * this is an owner property
+    #   * this is an abstract, non-derived independent property
     #
-    # @return [Boolean] whether the attribute is fetched
+    # @return [Boolean] whether this property is fetched
     def fetched?
       return true if @flags.include?(:fetched)
-      return false if @flags.include?(:unfetched)
+      return false if @flags.include?(:transient) or @flags.include?(:unfetched)
       nondomain? or dependent? ? fetched_dependent? : fetched_independent?
     end
-
-    # Returns whether the subject attribute is not saved.
+    
+    # Returns whether this property is unfetched, unsaved and should not be
+    # lazy-loaded, determined by whether it is marked with the +:transient+ flag.
     #
-    # @return [Boolean] whether the attribute is unsaved
-    def unsaved?
-      @flags.include?(:unsaved)
+    # @return [Boolean] whether this property is transient
+    def transient?
+      @flags.include?(:transient)
     end
-
-    # Returns whether the subject attribute is a dependent whose value is automatically generated
+    
+    # Returns whether this property is a dependent whose value is automatically generated
     # with place-holder domain objects when the parent is created. An attribute is auto-generated
     # if the +:autogenerated+ flag is set.
     #
-    # @return [Boolean] whether the attribute is auto-generated
+    # @return [Boolean] whether this property is auto-generated
     def autogenerated?
       @flags.include?(:autogenerated)
     end
@@ -50,34 +51,34 @@ module CaRuby
     # * it is {#cascaded?} and marked with the +:unfetched+ flag
     # * it is marked with the +:fetch_saved+ flag
     #
-    # @return [Boolean] whether the subject attribute must be refetched in order to reflect
+    # @return [Boolean] whether this property must be refetched in order to reflect
     #   the database content
     def fetch_saved?
        @flags.include?(:fetch_saved) or autogenerated? or (cascaded? and @flags.include?(:unfetched))
     end
 
-    # Returns whether the subject attribute is either:
+    # Returns whether this property is either:
     # 1. an owner attribute which does not automatically cascade application service creation
     #    or update to the referenced dependent, or
     # 2. the dependent attribute whose inverse is a logical owner attribute
     #
-    # @return [Boolean] whether the attribute is an uncascaded dependent
+    # @return [Boolean] whether this property is an uncascaded dependent
     def logical?
       @flags.include?(:logical) or (owner? and inverse_property and inverse_property.logical?)
     end
 
-    # A Java attribute is creatable if all of the following conditions hold:
-    # * the attribute is {#saved?}
-    # * the attribute :update_only flag is not set
+    # This property is creatable if all of the following conditions hold:
+    # * it is {#saved?}
+    # * the +:update_only+ flag is not set
     #
     # @return [Boolean] whether this attribute is saved in a create operation
     def creatable?
       saved? and not @flags.include?(:update_only)
     end
 
-    # A Java attribute is updatable if all of the following conditions hold:
-    # * the attribute is {#saved?}
-    # * the attribute :create_only flag is not set
+    # This property is updatable if all of the following conditions hold:
+    # * it is {#saved?}
+    # * the +:create_only+ flag is not set
     #
     # @return [Boolean] whether this attribute is saved in a update operation
     def updatable?
@@ -86,7 +87,7 @@ module CaRuby
 
     # Indicates whether this reference propery is saved when its owner is saved.
     #
-    # @return [Boolean] whether the attribute is a physical dependent or the +:cascaded+ flag is set
+    # @return [Boolean] whether this property is a physical dependent or the +:cascaded+ flag is set
     def cascaded?
       (dependent? and not logical?) or @flags.include?(:cascaded)
     end
@@ -110,25 +111,23 @@ module CaRuby
     #   The given object has a null identifier:
     # followed by the attribute type name.
     #
-    # @return [Boolean] whether the attribute cascades to crate when the owner is updated
+    # @return [Boolean] whether this property cascades to crate when the owner is updated
     def cascade_update_to_create?
       cascaded? and not @flags.include?(:no_cascade_update_to_create)
     end
 
-    # A Java property attribute is saved if none of the following conditions hold:
-    # *  the attribute :unsaved flag is set
-    # *  the attribute is {#proxied_save?}
+    # This property is saved if it is a Java property that is not {#unsaved} or {#proxied_save?}
     # and any of the following conditions hold:
-    # * the attibute is {#nondomain?}
-    # * the attribute is cascaded
-    # * the attribute value is not a collection
-    # * the attribute does not have an inverse
-    # * the attribute :saved flag is set
+    # * it is {#nondomain?}
+    # * it is {#cascaded?}
+    # * it is not a {#collection?}
+    # * it does not have an inverse
+    # * it is a {#unidirectional_java_dependent?}
     #
     # @return [Boolean] whether this attribute is saved in a create or update operation
     def saved?
       @flags.include?(:saved) or
-        (java_property? and not @flags.include?(:unsaved) and not proxied_save? and
+        (java_property? and not (@flags.include?(:unsaved) or transient? or proxied_save?) and
           (nondomain? or cascaded? or not collection? or inverse.nil? or unidirectional_java_dependent?))
     end
     
@@ -143,7 +142,7 @@ module CaRuby
       not saved?
     end
     
-    # @return [Boolean] whether the attribute return {#type} is a Resource class which
+    # @return [Boolean] whether this property return {#type} is a Resource class which
     #   implements the saver_proxy method
     def proxied_save?
       domain? and type.method_defined?(:saver_proxy)
@@ -163,11 +162,6 @@ module CaRuby
       inv_prop = inverse_property
       inv_prop.nil? or inv_prop.collection?
     end
-
-    # @return [Boolean] whether the subject attribute is not saved
-    def transient?
-      not saved?
-    end
     
     # @return [Boolean] whether this is a non-collection Java attribute
     def searchable?
@@ -176,6 +170,7 @@ module CaRuby
          
     # @return [Boolean] whether this attribute is set by the server
     def volatile?
+      # TODO - subsume by autogenerated?
       to_sym == :identifier or @flags.include?(:volatile)
     end
 

data/lib/caruby/metadata.rb

@@ -1,10 +1,9 @@
-require 'jinx/json/deserializer'
 require 'caruby/metadata/propertied'
 
 module CaRuby
   # The metadata persistence mix-in.
   module Metadata
-    include Propertied, Jinx::JSON::Deserializer, Jinx::Metadata
+    include Propertied, Jinx::Metadata
     
     private
     

data/lib/caruby/migration/migrator.rb

@@ -0,0 +1,108 @@
+require 'jinx/helpers/stopwatch'
+require 'jinx/migration/migrator'
+
+module CaRuby
+  class Migrator < Jinx::Migrator
+    # Creates a new Migrator with the given options.
+    #
+    # The migration configuration must provide sufficient information to build a well-formed migration
+    # target object. For example, if the target object is a new +CaTissue::SpecimenCollectionGroup+,
+    # then the migrator must build that SCG's required +CollectionProtocolRegistration+. The CPR in
+    # turn must either exist in the database or the migrator must build the required CPR
+    # +participant+ and +collection_protocol+.
+    # 
+    # @option (see Jinx::Migrator#initialize)
+    # @option opts [Database] :database the target application database
+    # @see #migrate_to_database
+    def initialize(opts={})
+      super
+      @database = opts[:database]
+    end
+    
+    # Imports this migrator's file into the database with the given connect options.
+    # This method creates or updates the domain objects mapped from the migration source.
+    # If a block is given to this method, then the block is called on each migrated
+    # target object.
+    #
+    # The target object is saved in the database. Every referenced migrated object is created,
+    # if necessary. Finally, a migration target owner object is created, if necessary.
+    #
+    # For example, suppose a migration configuration specifies the following:
+    # * the target is a +CaTissue::SpecimenCollectionGroup+
+    # * the field mapping specifies a +Participant+ MRN,
+    # * the defaults specify a +CollectionProtocol+ title and a +Site+ name
+    #
+    # The migrator attempts to fetch the protocol and site from the database. If they do not
+    # exist, then they are created. In order to create the protocol and site, the migration
+    # configuration must specify sufficient information to validate the objects before creation,
+    # as described in {#initialize}. Finally, the SCG +CollectionProtocolRegistration+ owner
+    # is created. This CPR references the migration protocol and site.
+    #
+    # If the +:create+ option is set, then an input record for a target object which already
+    # exists in the database is noted in a debug log message and ignored rather than updated.
+    #
+    # @yield [target, row] operates on the migration target
+    # @yieldparam [Resource] target the migrated target domain object
+    # @yieldparam [{Symbol => Object}] row the migration source record
+    def migrate_to_database(&block)
+      # migrate with save
+      tm = Jinx::Stopwatch.measure { execute_save(&block) }.elapsed
+      logger.debug { format_migration_time_log_message(tm) }
+    end
+    
+    private
+
+    # {#migrate} with a {#save} block on the migration target. Each migrated object
+    # is created, if necessary, after the target save.
+    def execute_save
+      if @database.nil? then
+        raise MigrationError.new("Migrator cannot save records since the database option was not specified.")
+      end
+      @database.open do |db|
+        migrate do |tgt, rec|
+          # Save the target object.
+          save(tgt, db)
+          # Ensure that each migrated object is created if necessary.
+          @migrated.each { |obj| create(obj, db) unless db.exists?(obj) }
+          yield(tgt, rec) if block_given?
+          db.clear
+        end
+      end
+    end
+
+    # @param [Resource] obj the domain object to save in the database
+    # @return [Resource, nil] obj if the save is successful, nil otherwise
+    def save(obj, database)
+      if @create then
+        create(obj, database)
+      else
+        logger.debug { "Migrator saving #{obj}..." }
+        database.save(obj)
+        logger.debug { "Migrator saved #{obj}." }
+      end
+    end
+
+    # @param [Resource] obj the domain object to create in the database
+    # @return [Resource, nil] obj if the create is successful, nil otherwise
+    def create(obj, database)
+      logger.debug { "Migrator creating #{obj}..." }
+      database.create(obj)
+      logger.debug { "Migrator created #{obj}." }
+    end
+
+    # @return [String] a log message for the given migration time in seconds
+    def format_migration_time_log_message(time)
+      # the database execution time
+      dt = @database.execution_time
+      if time > 120 then
+        time /= 60
+        dt /= 60
+        unit = "minutes"
+      else
+        unit = "seconds"
+      end
+      "Migration took #{'%.2f' % time} #{unit}, of which #{'%.2f' % dt} were database operations."
+    end
+  end
+end
+    

data/lib/caruby/resource.rb

@@ -1,5 +1,5 @@
 require 'jinx/resource'
-require 'jinx/json/serializer'
+require 'caruby/json/serializable'
 require 'caruby/migration/migratable'
 require 'caruby/database/persistable'
 
@@ -18,7 +18,7 @@ module CaRuby
   #     @metadata_module = CaRuby::Metadata  
   #   end
   module Resource
-    include CaRuby::Migratable, CaRuby::Persistable, Jinx::JSON::Serializer, Jinx::Resource
+    include CaRuby::Migratable, CaRuby::Persistable, CaRuby::JSON::Serializable, Jinx::Resource
   end
 end
 

data/lib/caruby/version.rb

@@ -1,3 +1,3 @@
 module CaRuby
-  VERSION = "2.1.1"
+  VERSION = "2.1.2"
 end

data/lib/caruby.rb

@@ -1,3 +1 @@
 require 'jinx'
-require 'jinx/helpers/log'
-require 'jinx/helpers/error'

data/test/lib/caruby/database/cache_test.rb

@@ -12,8 +12,6 @@ class CacheTest < Test::Unit::TestCase
     b = Item.new(:a)
     assert_equal(a, cache[b], "Cached equivalent not found")
     assert_equal(a, cache.add(b), "Cached add replaced existing entry")
-    cache.add!(b)
-    assert_equal(b, cache.add(b), "Cached add! did not replace existing entry")
   end
   
   def test_add!
@@ -22,7 +20,7 @@ class CacheTest < Test::Unit::TestCase
     cache.add(a)
     b = Item.new(:a)
     cache.add!(b)
-    assert_equal(b, cache.add(b), "Cached add! did not replace existing entry")
+    assert_equal(b, cache[a], "Cached add! did not replace existing entry")
   end
   
   def test_clear

metadata

@@ -2,7 +2,7 @@
 name: caruby-core
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 2.1.1
+  version: 2.1.2
 platform: ruby
 authors: 
   - OHSU
@@ -10,8 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-04-13 00:00:00 -07:00
-default_executable: 
+date: 2012-06-12 00:00:00 Z
 dependencies: 
   - !ruby/object:Gem::Dependency 
     name: bundler
@@ -111,7 +110,6 @@ extra_rdoc_files: []
 
 files: 
   - lib/caruby.rb
-  - lib/caruby/caruby-src.tar.gz
   - lib/caruby/database.rb
   - lib/caruby/metadata.rb
   - lib/caruby/resource.rb
@@ -141,13 +139,13 @@ files:
   - lib/caruby/helpers/properties.rb
   - lib/caruby/helpers/roman.rb
   - lib/caruby/helpers/version.rb
-  - lib/caruby/json/deserializer.rb
-  - lib/caruby/json/serializer.rb
+  - lib/caruby/json/serializable.rb
   - lib/caruby/metadata/java_property.rb
   - lib/caruby/metadata/propertied.rb
   - lib/caruby/metadata/property.rb
   - lib/caruby/metadata/property_characteristics.rb
   - lib/caruby/migration/migratable.rb
+  - lib/caruby/migration/migrator.rb
   - lib/caruby/rdbi/driver/jdbc.rb
   - History.md
   - LEGAL
@@ -161,7 +159,6 @@ files:
   - test/lib/caruby/helpers/properties_test.rb
   - test/lib/caruby/helpers/roman_test.rb
   - test/lib/caruby/helpers/version_test.rb
-has_rdoc: yard
 homepage: http://caruby.rubyforge.org
 licenses: 
   - MIT
@@ -185,7 +182,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: caruby
-rubygems_version: 1.5.1
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
 summary: Ruby facade for caBIG applications.
@@ -197,3 +194,4 @@ test_files:
   - test/lib/caruby/helpers/properties_test.rb
   - test/lib/caruby/helpers/roman_test.rb
   - test/lib/caruby/helpers/version_test.rb
+has_rdoc: yard

data/lib/caruby/json/deserializer.rb

@@ -1,15 +0,0 @@
-require 'json'
-
-module CaRuby
-  module JSON
-    # JSON => {Jinx::Resource} deserializer.
-    module Deserializer
-      # @param [String] json the JSON to deserialize
-      # @return [Jinx::Resource] the deserialized object
-      def json_create(json)
-        # Make the new object from the json data attribute => value hash.
-        new(json['data'])
-      end
-    end
-  end
-end

data/lib/caruby/json/serializer.rb

@@ -1,69 +0,0 @@
-module CaRuby
-  module JSON
-    # {Jinx::Resource} => JSON serializer.
-    module Serializer
-      # @param args the JSON serialization options
-      # @return [String] the JSON representation of this {Jinx::Resource}
-      def to_json(*args)
-        database.lazy_loader.disable do
-          {
-            'json_class' => json_class_name,
-            'data' => json_value_hash
-          }.to_json(*args)
-        end
-      end
-      
-      private
-      
-      # The JSON class name must be scoped by the Resource package module, not the
-      # Java package, in order to recognize the Jinx::Resource JSON hooks.
-      #
-      # @return [String] the class name qualified by the Resource package module name context
-      def json_class_name
-        [self.class.domain_module, self.class.name.demodulize].join('::')
-      end
-      
-      # Builds a serializable attribute => value hash. An independent or owner attribute
-      # value is a copy of the referenced domain object consisting of only the key attributes.
-      #
-      # @return [{Symbol => Object}] the serializable value hash
-      def json_value_hash
-        vh = value_hash(self.class.nondomain_attributes)
-        vh.merge!(value_hash(self.class.dependent_attributes))
-        self.class.independent_attributes.each do |oa|
-          value = send(oa) || next
-          vh[oa] = owner.copy(owner.class.all_key_attributes)
-        end
-      end
-      
-      def json_independent_reference(ref)
-        return ref.map { |item| json_independent_reference(item) } if ref.collection?
-        ref.copy(json_foreign_key_value_hash(ref))
-      end
-      
-      def json_foreign_key_value_hash(ref)
-        json_key_value_hash(ref, ref.class.primary_key_attributes) or
-        json_key_value_hash(ref, ref.class.secondary_key_attributes) or
-        json_key_value_hash(ref, ref.class.alternate_key_attributes)
-        Hash::EMPTY_HASH
-      end
-      
-      def json_key_value_hash(ref, attributes)
-        attributes.to_compact_hash { |ka| json_foreign_key_value(ref, ka) || return }
-      end
-      
-      def json_foreign_key_value(ref, attribute)
-        value = ref.send(attribute) || return
-        Jinx::Resource === value ? json_foreign_key_value_hash(value) : value
-      end
-    end
-  end
-end
-
-module Enumerable
-  # @param args the JSON serialization options
-  # @return [String] the JSON representation of this Enumerable as an array
-  def to_json(*args)
-    to_a.to_json(*args)
-  end
-end