caruby-core 1.4.1

data/lib/caruby/domain/annotatable.rb

@@ -0,0 +1,25 @@
+require 'caruby/resource'
+
+module CaRuby
+  # The Annotatable module marks a domain class as an anchor which holds at least one annotation attribute.
+  module Annotatable
+    include Resource
+
+    # Dynamically creates a new annotation reference method with the given symbol if symbol is the camelized form of a
+    # class in one of the Annotatable class's annotation modules.
+    def method_missing(symbol, *args)
+      name = symbol.to_s
+      # remove trailing assignment = if present
+      name.chop! if name =~ /=$/
+      # the class with the camelized form of the name
+      klass = self.class.annotation_class(name.camelize)
+      # delegate to super to print an error if no class
+      super if klass.nil?
+      # add the annotation attribute
+      klass.add_annotation(self.class)
+      raise NotImplementedError.new("#{self.class.qp} annotation method not created: #{symbol}") unless respond_to?(symbol)
+      #call the annotation attribute method
+      send(symbol, *args)
+    end
+  end
+end

data/lib/caruby/domain/annotation.rb

@@ -0,0 +1,23 @@
+require 'caruby/resource'
+
+module CaRuby
+  # The Annotation module marks a domain object as an Annotation.
+  module Annotation
+    include Resource
+
+    # Dynamically creates a new annotable owner attribute with the given symbol if symbol is an annotatable owner attribute
+    # accessor method.
+    #
+    # @see #attribute_missing
+    def method_missing(symbol, *args)
+      name = symbol.to_s
+      # remove trailing assignment = if present
+      name.chop! if name =~ /=$/
+      # try to make the owner attribute
+      self.class.attribute_metadata(name.to_sym)
+      # if we reached here, then the owner was created so verify and call the new method
+      raise NoMethodError.new("#{name.demodulize} owner attribute #{name} created but accessor method not found: #{symbol}") unless method_defined?(symbol)
+      send(symbol, *args)
+    end
+  end
+end

data/lib/caruby/domain/attribute_metadata.rb

@@ -0,0 +1,447 @@
+require 'set'
+require 'caruby/util/inflector'
+require 'caruby/util/collection'
+require 'caruby/util/validation'
+
+module CaRuby
+  # An Attribute captures the following metadata about a domain class attribute:
+  # * attribute symbol
+  # * declarer type
+  # * return type
+  # * reader method symbol
+  # * writer method symbol
+  class AttributeMetadata
+    # 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,
+      :create_only, :update_only, :unidirectional, :volatile].to_set
+
+    # The standard attribute reader and writer methods.
+    attr_reader :accessors
+
+    # The declaring class.
+    attr_accessor :declarer
+    
+    # The return class.
+    attr_accessor :type
+    
+    # The qualifier flags.
+    # @see SUPPORTED_FLAGS
+    attr_accessor :flags
+    
+    protected :declarer=
+
+    # Creates a new AttributeMetadata from the given attribute.
+    #
+    # The type is the referenced entity type; an attribute whose return type is a collection
+    # of domain objects is thus the domain object class rather than a collection class.
+    #
+    # If the type is given, then the following flags are recognized:
+    # * +:dependent+ - the attribute references a dependent
+    # * +:collection+ - the attribute return type is a collection
+    # * +:owner+ - the attribute references the owner of a dependent
+    # * +:cascaded+ - a database create/update/delete operation propagates to the attribute reference
+    #
+    # @param [String,Symbol] attr the subject attribute
+    # @param [Class] declarer the declaring class
+    # @param [Class] declarer the return type
+    # @param [<Symbol>] flags the qualifying flags
+    def initialize(attribute, declarer, type=nil, *flags)
+      # the attribute symbol
+      @symbol = attribute.to_sym
+      # the declaring class
+      @declarer = declarer
+      # the Ruby class
+      @type = Class.to_ruby(type) if type
+      # the read and write methods
+      @accessors = [@symbol, "#{attribute}=".to_sym]
+      # the qualifier flags
+      @flags = Set.new
+      # identifier is always volatile
+      if @symbol == :identifier then flags << :volatile end
+      qualify(*flags)
+    end
+
+    # @return [Symbol] the reader method
+    def reader
+      accessors.first
+    end
+
+    # @return [Symbol] the writer method
+    def writer
+      accessors.last
+    end
+
+    # @return [Symbol, nil] the inverse of this attribute, if any
+    def inverse
+      @inv_md.to_sym if @inv_md
+    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
+      if self.type and not type < self.type then
+        raise ArgumentError.new("Cannot restrict #{self.declarer}.#{self} to incompatible type #{type}")
+      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.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
+    end
+
+    # Sets the inverse of the subject attribute to the given attribute.
+    # The inverse relation is symmetric, i.e. the inverse of the referenced AttributeMetadata
+    # is set to this AttributeMetadata's subject attribute.
+    #
+    # @param attribute the inverse attribute
+    def inverse=(attribute)
+      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")
+      end
+      inv_inv_md = @inv_md.inverse_attribute_metadata
+      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
+        end
+      else
+        @inv_md.inverse = @symbol
+        @inv_md.set_flag(:disjoint) if disjoint?
+      end
+      # propagate to restrictions
+      if @restrictions then @restrictions.each { |attr_md| attr_md.inverse = attribute } end
+    end
+
+    # @return [AttributeMetadata, nil] the metadata for the {#inverse} attribute, if any
+    def inverse_attribute_metadata
+      @inv_md
+    end
+
+    # Qualifies this attribute with the given flags. Supported flags are listed in {SUPPORTED_FLAGS}.
+    #
+    # @param [<Symbol>] the flags to add
+    # @raise [ArgumentError] if the flag is not supported
+    def qualify(*flags)
+      flags.each { |flag| set_flag(flag) }
+      # propagate to restrictions
+      if @restrictions then @restrictions.each { |attr_md| attr_md.qualify(*flags) } end
+    end
+
+    # @return whether the subject attribute encapsulates a Java property
+    def java_property?
+      CaRuby::JavaAttributeMetadata === self
+    end
+
+    # @return whether the subject attribute returns a domain object or collection of domain objects
+    def domain?
+      # the type must be a Ruby class rather than a Java Class, and include the Domain mix-in
+      Class === type and type < Resource
+    end
+
+    # @return whether the subject attribute is not a domain object attribute
+    def nondomain?
+      not domain?
+    end
+
+    # 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.
+    #
+    # @return [Boolean] whether the attribute is fetched
+    def fetched?
+      return true if @flags.include?(:fetched)
+      return false if @flags.include?(:unfetched)
+      nondomain? or dependent? ? fetched_dependent? : fetched_independent?
+    end
+
+    # @return whether the subject attribute return type is a collection
+    def collection?
+      @flags.include?(:collection)
+    end
+
+    # Returns whether the subject attribute is a dependent on a parent. See the caRuby configuration
+    # documentation for a dependency description.
+    #
+    # @return [Boolean] whether the attribute references a dependent
+    def dependent?
+      annotation? or @flags.include?(:dependent)
+    end
+
+    # Returns whether the subject attribute is marked as optional in a create.
+    # This method returns true only if the :optional flag is explicitly set.
+    # Other attributes are optional by default.
+    #
+    # @return [Boolean] whether the attribute is optional
+    # @see ResourceAttributes#mandatory_attributes.
+    def optional?
+      @flags.include?(:optional)
+    end
+
+    # Returns whether the subject attribute is not saved.
+    #
+    # @return [Boolean] whether the attribute is unsaved
+    def unsaved?
+      @flags.include?(:unsaved)
+    end
+
+    # Returns whether the subject attribute is a dependent whose value is automatically generated
+    # with place-holder domain objects when the parent is created.
+    #
+    # @return [Boolean] whether the attribute is auto-generated
+    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))
+    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.
+    def logical?
+      annotation? or @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
+    # attribute is the inverse of a dependent owner 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
+    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
+    def independent?
+      domain? and not dependent?
+    end
+
+    # A Java attribute is creatable if all of the following conditions hold:
+    # * the attribute is {#saved?}
+    # * the attribute is not a {#proxied_save?}
+    # * the attribute :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 an uncreated dependent if any of the following conditions hold:
+    # * the attribute is a {#logical?} dependent
+    # * the attribute is a #dependent? which is not {#creatable?}
+    #
+    # @return [Boolean] whether this attribute is saved in a create operation
+    def uncreated_dependent?
+      logical? or (dependent? and not creatable?)
+    end
+
+    # @return whether this attribute is saved in a update operation
+    #
+    # A Java attribute is updatable if all of the following conditions hold:
+    # * the attribute is {#saved?}
+    # * the attribute :create_only flag is not set
+    def updatable?
+      saved? and not @flags.include?(:create_only)
+    end
+
+    # @return whether this attribute is navigated to build a template used in a create or update operation
+    # A cascaded attribute determines where to prune a database create or update object graph.
+    #
+    # An attribute is cascaded if it is a physical dependent or the :cascaded flag is set.
+    def cascaded?
+      (dependent? and not logical?) or @flags.include?(:cascaded)
+    end
+    
+    # Returns whether this attribute is #{#cascaded} and cascades a parent update to a child
+    # create. This corresponds to the Hibernate +save-update+ cascade style but not the Hibernate
+    # +all+ cascade style.
+    #
+    # This method returns true if this attribute is cascaded and the +:no_cascade_update_to_create+
+    # flag is not set. Set this flag if the Hibernate mapping specifies the +all+ cascade style.
+    # Failure to set this flag will result in the caTissue Hibernate error:
+    #   Exception: gov.nih.nci.system.applicationservice.ApplicationException:
+    #   The given object has a null identifier:
+    # followed by the attribute type name.
+    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?}
+    # 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
+    #
+    # @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))
+    end
+    
+    # @return [Boolean] whether this attribute is not {#saved?}
+    def unsaved?
+      not saved?
+    end
+    
+    # @return [Boolean] whether the attribute return {#type} is a Resource class which
+    #   implements the saver_proxy method
+    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
+    # either:
+    # * a {#cascaded?} dependent which does not #{#cascade_update_to_create?}, or
+    # * a {#saved?} {#independent?} 1:M or M:N association.
+    #
+    # @return [Boolean] whether this attribute is a create prerequisite
+    def storable_prerequisite?
+      return true if cascaded? and @flags.include?(:no_cascade_update_to_create)
+      return false unless independent? and saved?
+      return true unless collection?
+      inv_md = inverse_attribute_metadata
+      inv_md.nil? or inv_md.collection?
+    end
+
+    # @return [Boolean] whether this attribute is a collection with a collection inverse
+    def many_to_many?
+      return false unless collection?
+      inv_md = inverse_attribute_metadata
+      inv_md and inv_md.collection?
+    end
+
+    # @return [Boolean] whether the subject attribute is not saved
+    def transient?
+      not saved?
+    end
+
+    # Returns whether this attribute is set on the server as a side-effect
+    # of a change to the declarer object. The volatile attributes include
+    # those which are {#unsaved?} and those which are saved but marked
+    # with the +:volatile+ flag.
+    #
+    # @return [Boolean] whether this attribute's value is determined by the server
+    def volatile?
+      unsaved? or @flags.include?(:volatile)
+    end
+
+    # @return [Boolean] whether this is a non-collection Java attribute
+    def searchable?
+      java_property? and not collection?
+    end
+
+    # @return [Boolean] whether the subject attribute is a dependency owner
+    def owner?
+      @flags.include?(:owner)
+    end
+
+    # @return [Boolean] whether this is a dependent attribute which has exactly one owner value chosen from
+    # several owner attributes.
+    def disjoint?
+      @flags.include?(:disjoint)
+    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
+      dependent? and not bidirectional_java_association?
+    end
+
+    # @return [Boolean] whether this is a Java attribute which has a Java inverse
+    def bidirectional_java_association?
+      inverse and java_property? and inverse_attribute_metadata.java_property?
+    end
+
+    def to_sym
+      @symbol
+    end
+
+    def to_s
+      @symbol.to_s
+    end
+
+    alias :inspect :to_s
+
+    alias :qp :to_s
+    
+    private
+
+    # @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?
+      end
+    end
+
+    # @return [Boolean] whether this dependent attribute is fetched. Only physical dependents are fetched by default.
+    def fetched_dependent?
+      not (logical? or @flags.include?(:unfetched))
+    end
+
+    # @return [Boolean] whether this independent attribute is fetched. Only abstract, non-derived independent
+    # references are fetched by default.
+    def fetched_independent?
+      type.abstract? and not (derived? or  @flags.include?(:unfetched))
+    end
+  end
+end