caruby-core 1.4.2 → 1.4.3

data/lib/caruby/database.rb

@@ -6,6 +6,7 @@ require 'caruby/util/options'
 require 'caruby/util/visitor'
 require 'caruby/util/inflector'
 require 'caruby/database/persistable'
+require 'caruby/database/persistifier'
 require 'caruby/database/reader'
 require 'caruby/database/writer'
 require 'caruby/database/persistence_service'
@@ -42,9 +43,38 @@ 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, Validation
+    include Reader, Writer, Persistifier, Validation
+
+    # 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
     
     attr_reader :operations
+    
+    # @return [PersistenceService] the services used by this database
+    attr_reader :persistence_services
 
     # Creates a new Database with the specified service name and options.
     #
@@ -64,6 +94,7 @@ module CaRuby
       @host = Options.get(:host, opts)
       # class => service hash; default is the catissuecore app service
       @def_persist_svc = PersistenceService.new(service_name, :host => @host)
+      @persistence_services = [@def_persist_svc].to_set
       @cls_svc_hash = Hash.new(@def_persist_svc)
       # the create/update nested operations
       @operations = []
@@ -82,6 +113,11 @@ 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.
@@ -93,46 +129,49 @@ module CaRuby
         logger.error("Session termination unsuccessful - #{e.message}")
       end
       # clear the cache
-      @cache.clear
+      clear
       logger.info("Disconnected from application server.")
       @session = nil
     end
     
-   # Returns the execution time spent since the last open.
-   def execution_time
+    # @return [Numeric] the execution time in seconds spent since the last open
+    def execution_time
       persistence_services.inject(0) do |total, svc|
         st = svc.timer.elapsed
         total + st
       end
     end
 
-    # Returns the PersistanceService to use for the given domain object obj,
-    # or the default service if obj is nil.
-    def persistence_service(obj=nil)
+    # Returns the PersistanceService to use for the given domain object.
+    # This base method always returns the standard application service.
+    # Subclasses can override for specialized services. A session is
+    # started on demand if necessary.
+    #
+    # @param [Persistable] obj the domain object
+    # @return [PersistanceService] the service for the domain object
+    def persistence_service(obj)
       start_session if @session.nil?
-      return @def_persist_svc if obj.nil?
-      klass = Class === obj ? obj : obj.class
-      @cls_svc_hash[klass]
-    end
-
-    # Returns all PersistanceServices used by this database.
-    def persistence_services
-      [@def_persist_svc].to_set.merge!(@cls_svc_hash.values)
+      @def_persist_svc
     end
     
-    # Returns the database operation elapsed real time since the last open.
-    def database_time
-      persistence_services.inject(0) do |total, svc|
-        st = svc.timer.elapsed
-        # reset the timer for the next test case
-        svc.timer.reset
-        total + st
-      end
+    # Adds the given service to this database.
+    #
+    # @param [PersistenceService] service the service to add
+    def add_persistence_service(service)
+      @persistence_services << service
     end
+
+    alias :to_s :print_class_and_id
+
+    alias :inspect :to_s
+
+    ## Utility classes and methods, used by Query and Store mix-ins ##
+
+    private
     
     # A mergeable autogenerated operation is recursively defined as:
-    # * a create
-    # * an update in the context of a mergeable autogenerated operation
+    # * 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
     def mergeable_autogenerated_operation?
@@ -145,7 +184,7 @@ module CaRuby
         end
         if op.type == :create then
           # innermost or owner create
-          return true
+          return (not op.subject.class.autogenerated_dependent_attributes.empty?)
         elsif op.type != :update then
           # not a save
           return false
@@ -155,65 +194,47 @@ module CaRuby
       end
       false
     end
-
-    alias :to_s :print_class_and_id
-
-    alias :inspect :to_s
-
-    private
-
-    ## Utility classes and methods, used by Query and Store mix-ins ##
-
-    # Database CRUD operation.
-    class Operation
-      attr_reader :type, :subject, :attribute
-
-      def initialize(type, subject, attribute=nil)
-        @type = type
-        @subject = subject
-        @attribute = attribute
-      end
-    end
-
+    
     # Performs the operation given by the given op symbol on obj by calling the block given to this method.
-    # Returns the result of calling the block.
-    # Valid op symbols are described in {Operation#initialize}.
-    def perform(op, obj, attribute=nil)
+    # 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 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_s = " #{attribute}" if attribute
+      attr = Options.get(:attribute, opts)
+      attr_s = " #{attr}" if attr
+      ag_s = " autogenerated" if Options.get(:autogenerated, opts)
       ctxt_s = " in context #{print_operations}" unless @operations.empty?
-      logger.info(">> #{op_s} #{obj.pp_s(:single_line)}#{attr_s}#{ctxt_s}...")
-      @operations.push(Operation.new(op, obj, attribute))
+      logger.info(">> #{op_s}#{ag_s} #{obj.pp_s(:single_line)}#{attr_s}#{ctxt_s}...")
+      @operations.push(Operation.new(op, obj, opts))
       begin
         # perform the operation
-        result = yield
+        result = @lazy_loader.suspend { yield }
       ensure
         # the operation is done
         @operations.pop
-        # If this is a top-level operation, then clear the cache and transient set.
-        if @operations.empty? then
-          @cache.clear
-          @transients.clear
-        end
+        # If this is a top-level operation, then clear the transient set.
+        if @operations.empty? then @transients.clear end
       end
       logger.info("<< Completed #{obj.qp}#{attr_s} #{op}.")
       result
     end
-      
+    
+    def each_persistence_service(&block)
+      ObjectSpace.each_object(PersistenceService, &block)
+    end
+    
     # @return [Cache] a new object cache.
     def create_cache
       # JRuby alert - 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.
-      # the fetched object copier
-      copier = Proc.new do |src|
-        copy = src.copy
-        logger.debug { "Fetched #{src.qp} copied to #{copy.qp}." }
-        copy
-      end
-      # the fetched object cache
-      Cache.new(copier) do |obj|
+      Cache.new do |obj|
         raise ArgumentError.new("Can't cache object without identifier: #{obj}") unless obj.identifier
         obj.identifier.to_s.to_i
       end

data/lib/caruby/domain/attribute_initializer.rb

@@ -0,0 +1,16 @@
+module CaRuby
+  module AttributeInitializer
+    # Initializes a new instance of this Resource class with optional attribute => value hash
+    # @param [{Symbol => Object}] the optional attribute => value hash
+    # @return 
+    def initialize(hash=nil)
+      super()
+      if hash then
+        unless Hashable === hash then
+          raise ArgumentError.new("#{qp} initializer argument type not supported: #{hash.class.qp}")
+        end
+        merge_attributes(hash)
+      end
+    end
+  end
+end

data/lib/caruby/domain/attribute_metadata.rb

@@ -14,23 +14,22 @@ module CaRuby
     # The supported attribute qualifier flags.
     SUPPORTED_FLAGS = [
       :autogenerated, :collection, :dependent, :derived, :logical, :disjoint, :owner, :cascaded,
-      :no_cascade_update_to_create, :saved, :unsaved, :saved_unmergeable, :optional, :fetched, :unfetched,
+      :no_cascade_update_to_create, :saved, :unsaved, :optional, :fetched, :unfetched,
       :create_only, :update_only, :unidirectional, :volatile].to_set
 
-    # The standard attribute reader and writer methods.
+    # @return [(Symbol, Symbol)] the standard attribute reader and writer methods
     attr_reader :accessors
 
-    # The declaring class.
+    # @return [Class] the declaring class
     attr_accessor :declarer
+    protected :declarer=
     
-    # The return class.
-    attr_accessor :type
+    # @return [Class] the return type
+    attr_reader :type
     
-    # The qualifier flags.
+    # @return [<Symbol>] the qualifier flags
     # @see SUPPORTED_FLAGS
     attr_accessor :flags
-    
-    protected :declarer=
 
     # Creates a new AttributeMetadata from the given attribute.
     #
@@ -82,33 +81,41 @@ module CaRuby
     def unidirectional?
       inverse.nil?
     end
+    
+    # @param [Class] the attribute return type
+    def type=(klass)
+      return if klass == @type
+      @type = klass
+      if @inv_md then
+        self.inverse = @inv_md.to_sym
+        logger.debug { "Reset #{@declarer.qp}.#{self} inverse from #{@inv_md.type}.#{@inv_md} to #{klass}#{inv_md}." }
+      end
+    end
 
     # Creates a new declarer attribute which restricts this attribute {#type} to the given type.
     #
-    #@param [Class] declarer the class for which the restriction holds 
-    # @return [AttributeMetadata] the metadata for the new declarer attribute
-    def restrict(declarer, type)
-      unless declarer < self.type then
-        raise ArgumentError.new("Cannot restrict #{self.declarer}.#{self} to incompatible declarer type #{declarer}")
-      end
+    # @param declarer (see #restrict)
+    # @param [Class] type the restricted subclass of this attribute's return type
+    # @return (see #restrict)
+    def restrict_type(declarer, type)
       if self.type and not type < self.type then
-        raise ArgumentError.new("Cannot restrict #{self.declarer}.#{self} to incompatible type #{type}")
+        raise ArgumentError.new("Cannot restrict #{self.declarer.qp}.#{self} to incompatible attribute type #{type.qp}")
       end
-      # set aside the restrictions prior to the copy
-      rstr = @restrictions
-      @restrictions = nil
-      copy = dup
-      # Restore the restrictions. Initialize the array if necessary, since the copy
-      # will be added to the list.
-      @restrictions = rstr || []
-      # specialize the copy declarer and type
-      copy.declarer = declarer
+      copy = restrict(declarer)
       copy.type = type
       # specialize the inverse to the restricted type attribute, if necessary
-      if inverse then copy.inverse = inverse end
-      # Capture the restriction to propagate modifications to this metadata, esp.
-      # adding an inverse.
-      @restrictions << copy
+      copy.restrict_inverse_type
+      copy
+    end
+    
+    # Creates a new declarer attribute which qualifies this attribute for the given declarer.
+    #
+    # @param declarer (see #restrict)
+    # @param [<Symbol>] flags the additional flags for the restricted attribute
+    # @return (see #restrict)
+    def restrict_flags(declarer, *flags)
+      copy = restrict(declarer)
+      copy.qualify(*flags)
       copy
     end
 
@@ -118,26 +125,34 @@ module CaRuby
     #
     # @param attribute the inverse attribute
     def inverse=(attribute)
+      return if inverse == attribute
+      # if no attribute, then the clear the existing inverse, if any
+      return clear_inverse if attribute.nil?
+      
       logger.debug { "Set #{@declarer.qp}.#{self} inverse to #{type.qp}.#{attribute}." }
-      @inv_md = type.attribute_metadata(attribute)
-      unless @inv_md then
-        raise MetadataError.new("#{@declarer.qp}.#{self} inverse attribute #{type.qp}.#{attribute} not found")
+      begin
+        @inv_md = type.attribute_metadata(attribute)
+      rescue NameError
+        raise MetadataError.new("#{@declarer.qp}.#{self} inverse attribute #{type.qp}.#{attribute} not found - #{$!}")
       end
+      
+      # the inverse of the inverse
       inv_inv_md = @inv_md.inverse_attribute_metadata
+      # If the inverse of the inverse is already set to a different attribute, then raise an exception.
+      # Otherwise, it there is an inverse, then set the inverse of the inverse to this attribute.
       if inv_inv_md then
         unless inv_inv_md == self then
-          if @inv_md.inverse == @symbol then
-            @inv_md.inverse = @symbol
-          else
-            raise MetadataError.new("Cannot set #{type.qp}.#{@inv_md} inverse attribute to #{@declarer.qp}.#{self} since it conflicts with existing inverse #{@inv_md.inverse}")
-          end
+         raise MetadataError.new("Cannot set #{type.qp}.#{@inv_md} inverse attribute to #{@declarer.qp}.#{self} since it conflicts with existing inverse #{@inv_md.inverse}")
         end
       else
+        # set the inverse of the inverse
         @inv_md.inverse = @symbol
-        @inv_md.set_flag(:disjoint) if disjoint?
+        # if this attribute is disjoint, then so is the inverse.
+        @inv_md.qualify(:disjoint) if disjoint?
       end
+      
       # propagate to restrictions
-      if @restrictions then @restrictions.each { |attr_md| attr_md.inverse = attribute } end
+      if @restrictions then @restrictions.each { |attr_md| attr_md.restrict_inverse_type } end
     end
 
     # @return [AttributeMetadata, nil] the metadata for the {#inverse} attribute, if any
@@ -197,7 +212,7 @@ module CaRuby
     #
     # @return [Boolean] whether the attribute references a dependent
     def dependent?
-      annotation? or @flags.include?(:dependent)
+      @flags.include?(:dependent)
     end
 
     # Returns whether the subject attribute is marked as optional in a create.
@@ -224,39 +239,44 @@ module CaRuby
     def autogenerated?
       @flags.include?(:autogenerated)
     end
-
-    # Returns whether the subject attribute is  either an #autogenerated? {#dependent?}
-    # or {#cascaded?} and marked with the :unfetched flag.
-    def unfetched_created?
-      (dependent? and autogenerated?) or (cascaded? and @flags.include?(:unfetched))
+    
+    # Returns whether this attribute must be fetched when a declarer instance is saved.
+    # An attribute is a saved fetch attribute if either of the following conditions hold:
+    # * it is {#autogenerated?}
+    # * it is {#cascaded?} and marked with the +:unfetched+ flag.
+    #
+    # @return [Boolean] whether the subject attribute must be refetched in order to reflect
+    #   the database content
+    def saved_fetch?
+       autogenerated? or (cascaded? and @flags.include?(:unfetched))
     end
 
     # Returns whether the subject attribute is a dependent whose owner does not automatically
     # cascade application service creation or update to the dependent. It is incumbent upon
     # CaRuby::Database to cascade the changes.
+    #
+    # @return [Boolean] whether the attribute is an uncascaded dependent
     def logical?
-      annotation? or @flags.include?(:logical)
+      @flags.include?(:logical)
     end
 
-    # @return whether the subject attribute is an annotation
-    def annotation?
-      false
-      # TODO - enable when annotation enabled
-    end
-
-    # @return whether this attribute is derived from another attribute
-    # This occurs when the attribute value is set by setting another attribute, e.g. if this
+    # An attribute is derived if the attribute value is set by setting another attribute, e.g. if this
     # attribute is the inverse of a dependent owner attribute.
+    #
+    # @return [Boolean] whether this attribute is derived from another attribute
     def derived?
       @flags.include?(:derived) or (dependent? and not inverse.nil?)
     end
 
-    # @return this attribute's inverse attribute if the inverse is a derived attribute, or nil otherwise
+    # @return [Boolean] this attribute's inverse attribute if the inverse is a derived attribute, or nil otherwise
     def derived_inverse
       @inv_md.to_sym if @inv_md and @inv_md.derived?
     end
 
-    # @return whether the subject attribute is a non-dependent domain attribute
+    # An independent attribute is a reference to one or more non-dependent Resource objects.
+    # An {#owner?} attribute is independent.
+    #
+    # @return [Boolean] whether the subject attribute is a non-dependent domain attribute
     def independent?
       domain? and not dependent?
     end
@@ -323,8 +343,9 @@ module CaRuby
     #
     # @return [Boolean] whether this attribute is saved in a create or update operation
     def saved?
-      java_property? and not @flags.include?(:unsaved) and not proxied_save? and
-      (nondomain? or cascaded? or not collection? or inverse.nil? or unidirectional_java_dependent? or @flags.include?(:saved))
+      @flags.include?(:saved) or
+      (java_property? and not @flags.include?(:unsaved) and not proxied_save? and
+       (nondomain? or cascaded? or not collection? or inverse.nil? or unidirectional_java_dependent?))
     end
     
     # @return [Boolean] whether this attribute is not {#saved?}
@@ -337,12 +358,6 @@ module CaRuby
     def proxied_save?
       domain? and type.method_defined?(:saver_proxy)
     end
-    
-    # Each saved attribute is a saved mergeable attribute unless the :saved_unmergeable flag is set.
-    # @return [Boolean] whether this attribute can be merged from a save result
-    def saved_mergeable?
-      not @flags.include?(:saved_unmergeable)
-    end
 
     # Returns whether this attribute's referents must exist before an instance of the
     # declarer class can be created. An attribute is a storable prerequisite if it is
@@ -396,7 +411,13 @@ module CaRuby
     def disjoint?
       @flags.include?(:disjoint)
     end
-
+    
+    # @param [Symbol] attribute the attribute to check
+    # @return [Boolean] whether the attribute is part of a 1:1 non-dependency association
+    def one_to_one_bidirectional_independent?
+      independent? and not owner? and not collection? and @inv_md and not @inv_md.collection?
+    end
+    
     # @return [Boolean] whether this attribute is a dependent which does not have a Java inverse owner attribute
     def unidirectional_java_dependent?
       # TODO - can this be relaxed to java_unidirectional? i.e. eliminate dependent filter
@@ -420,21 +441,89 @@ module CaRuby
 
     alias :qp :to_s
     
+    protected
+    
+    # Duplicates the mutable content as part of a {#deep_copy}.
+    def dup_content
+      # keep the copied flags but don't share them
+      @flags = @flags.dup
+      # restrictions are neither shared nor copied
+      @restrictions = nil
+    end
+    
+    # If there is a current inverse which can be restricted to an attribute in the scope of
+    # this metadata's restricted type, then reset the inverse to that attribute.
+    def restrict_inverse_type
+      return unless @inv_md
+      # the current inverse
+      attr = inverse
+      # the restricted type's metadata for the current inverse
+      rstr_inv_md = @type.attribute_metadata(attr)
+      # bail if the restricted type delegates to the current inverse metadata
+      return if rstr_inv_md == @inv_md
+      # clear the inverse
+      @inv_md = nil
+      # reset the inverse to the restricted attribute
+      self.inverse = attr
+    end
+    
     private
-
+    
+    # Creates a copy of this metadata which does not share mutable content.
+    def deep_copy
+      copy = dup
+      copy.dup_content
+      copy
+    end
+    
+    # Creates a new declarer attribute which restricts this attribute type or flags.
+    #
+    # @param [Class] declarer the class for which the restriction holds 
+    # @return [AttributeMetadata] the metadata for the new declarer attribute
+    def restrict(declarer)
+      unless declarer < self.declarer then
+        raise ArgumentError.new("Cannot restrict #{self.declarer.qp}.#{self} to incompatible declarer type #{declarer.qp}")
+      end
+      copy = deep_copy
+      # specialize the copy declarer and type
+      copy.declarer = declarer
+      # Capture the restriction to propagate modifications to this metadata, esp.
+      # adding an inverse.
+      @restrictions ||= []
+      @restrictions << copy
+      copy
+    end
+    
+    def clear_inverse
+      return unless @inv_md
+      logger.debug { "Clearing #{@declarer.qp}.#{self} inverse #{type.qp}.#{inverse}..." }
+      inv_inv_md = @inv_md.inverse_attribute_metadata
+      @inv_md = nil
+      if inv_inv_md then inv_inv_md.inverse = nil end
+      logger.debug { "Cleared #{@declarer.qp}.#{self} inverse." }
+    end
+    
     # @param [Symbol] the flag to set
     # @raise [ArgumentError] if flag is not supported
     def set_flag(flag)
       return if @flags.include?(flag)
       raise ArgumentError.new("Attribute flag not supported: #{flag}") unless SUPPORTED_FLAGS.include?(flag)
       @flags << flag
-      if flag == :owner then
-        inv_attr = type.dependent_attribute(@declarer)
-        if inv_attr.nil? then
-          raise MetadataError.new("#{@declarer.qp} owner attribute #{self} does not have a #{type.qp} dependent inverse")
-        end
-        self.inverse = type.dependent_attribute(@declarer)
-        @flags << :logical if inverse_attribute_metadata.logical?
+      case flag
+        when :owner then
+          if dependent? then
+            raise MetadataError.new("#{declarer.qp}.#{self} cannot be set as a #{type.qp} owner since it is already defined as a #{type.qp} dependent")
+          end
+          inv_attr = type.dependent_attribute(@declarer)
+          if inv_attr.nil? then
+            raise MetadataError.new("#{@declarer.qp} owner attribute #{self} does not have a #{type.qp} dependent inverse")
+          end
+          self.inverse = type.dependent_attribute(@declarer)
+          if inverse_attribute_metadata.logical? then @flags << :logical end
+        when :dependent then
+          if owner? then
+            raise MetadataError.new("#{declarer.qp}.#{self} cannot be set as a  #{type.qp} dependent since it is already defined as a #{type.qp} owner")
+          end
       end
     end