caruby-core 1.5.5 → 2.1.1

data/lib/caruby/json/serializer.rb

@@ -1,19 +1,61 @@
 module CaRuby
   module JSON
-    # {Resource} => JSON serializer.
+    # {Jinx::Resource} => JSON serializer.
     module Serializer
       # @param args the JSON serialization options
-      # @return [String] the JSON representation of this {Resource}
+      # @return [String] the JSON representation of this {Jinx::Resource}
       def to_json(*args)
         database.lazy_loader.disable do
-          # The JSON class must be scoped by the domain module, not the Java package, in order
-          # to recognize the Resource JSON hooks.
-          # The data is the attribute => value hash.
-         {'json_class' => [self.class.domain_module, self.class.name.demodulize].join('::'),
-            'data' => value_hash(self.class.nonowner_attributes)
+          {
+            '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

data/lib/caruby/metadata.rb

@@ -0,0 +1,30 @@
+require 'jinx/json/deserializer'
+require 'caruby/metadata/propertied'
+
+module CaRuby
+  # The metadata persistence mix-in.
+  module Metadata
+    include Propertied, Jinx::JSON::Deserializer, Jinx::Metadata
+    
+    private
+    
+    # @param [Property] the property to print
+    # @return [<Symbol>] the flags to modify the property
+    def pretty_print_attribute_flags(prop)
+      flags = super
+      flags << :logical if prop.logical?
+      flags << :autogenerated if prop.autogenerated?
+      flags
+    end
+
+    # @return [{String => <Symbol>}] the attributes to print
+    def pretty_print_attribute_hash
+      super.merge!({
+        'creatable domain attributes' => creatable_domain_attributes,
+        'updatable domain attributes' => updatable_domain_attributes,
+        'fetched domain attributes' => fetched_domain_attributes,
+        'cascaded domain attributes' => cascaded_attributes
+      })
+    end
+  end
+end

data/lib/caruby/metadata/java_property.rb

@@ -0,0 +1,21 @@
+require 'jinx/metadata/java_property'
+require 'caruby/metadata/property_characteristics'
+
+# Mix persistence into +Jinx::JavaProperty+.
+module CaRuby
+  class JavaProperty < Jinx::JavaProperty
+    include CaRuby::PropertyCharacteristics
+    
+    def initialize(pd, declarer, restricted_type=nil)
+      super
+    end
+
+    private
+    
+    # @param [Symbol] the flag to set
+    # @return [Boolean] whether the flag is supported
+    def flag_supported?(flag)
+      super or CaRuby::PropertyCharacteristics::SUPPORTED_FLAGS.include?(flag)
+    end
+  end
+end

data/lib/caruby/metadata/propertied.rb

@@ -0,0 +1,191 @@
+require 'jinx/metadata/propertied'
+require 'caruby/metadata/property'
+require 'caruby/metadata/java_property'
+
+module CaRuby
+  # Augments a caRuby application domain class with {PropertyCharacteristics} persistence meta-data.
+  #
+  # A Jinx-enabled caRuby application domain module enables CaRuby persistence by adding the following
+  # method definition:
+  #   def self.add_metadata(klass)
+  #     super
+  #     klass.extend(CaRuby::Propertied)
+  #   end
+  module Propertied
+    include Jinx::Propertied
+    
+    # @return [<Symbol>] the dependent attributes
+    def autogenerated_dependent_attributes
+      @ag_dep_flt ||= dependent_attributes.compose { |prop| prop.autogenerated? }
+    end
+
+    # @return [<Symbol>] the autogenerated logical dependent attributes
+    # @see #logical_dependent_attributes
+    # @see Property#autogenerated?
+    def autogenerated_logical_dependent_attributes
+      @ag_log_dep_flt ||= dependent_attributes.compose { |prop| prop.autogenerated? and prop.logical? }
+    end
+    
+    # @return [<Symbol>] the {Property#fetch_saved?} attributes
+    def saved_attributes_to_fetch
+      @sv_ftch_flt ||= domain_attributes.compose { |prop| prop.fetch_saved? }
+    end
+    
+    # @return [<Symbol>] the logical dependent attributes
+    # @see Property#logical?
+    def logical_dependent_attributes
+      @log_dep_flt ||= dependent_attributes.compose { |prop| prop.logical? }
+    end
+
+    # @return [<Symbol>] the auto-generated attributes
+    # @see Property#autogenerated?
+    def autogenerated_attributes
+      @ag_flt ||= attribute_filter { |prop| prop.autogenerated? }
+    end
+    
+    # @return [<Symbol>] the auto-generated non-domain attributes
+    # @see Property#nondomain?
+    # @see Property#autogenerated?
+    def autogenerated_nondomain_attributes
+      @ag_nd_flt ||= attribute_filter { |prop| prop.autogenerated? and prop.nondomain? }
+    end
+    
+    # @return [<Symbol>] the {Property#volatile?} non-domain attributes
+    def volatile_nondomain_attributes
+      @unsvd_nd_flt ||= attribute_filter { |prop| prop.volatile? and prop.nondomain? }
+    end
+
+    # @return [<Symbol>] the domain attributes which can serve as a query parameter
+    # @see Property#searchable?
+    def searchable_attributes
+      @srchbl_flt ||= attribute_filter { |prop| prop.searchable? }
+    end
+
+    # @return [<Symbol>] the create/update cascaded domain attributes
+    # @see Property#cascaded?
+    def cascaded_attributes
+      @cscd_flt ||= domain_attributes.compose { |prop| prop.cascaded? }
+    end
+
+    # @return [<Symbol>] the {#cascaded_attributes} which are saved with a proxy
+    #   using the dependent saver_proxy method
+    def proxied_savable_template_attributes
+      @px_cscd_flt ||= savable_template_attributes.compose { |prop| prop.proxied_save? }
+    end
+
+    # @return [<Symbol>] the {#cascaded_attributes} which do not have a
+    #   #{Property#proxied_save?}
+    def unproxied_savable_template_attributes
+      @unpx_sv_tmpl_flt ||= savable_template_attributes.compose { |prop| not prop.proxied_save? }
+    end
+
+    # @return [<Symbol>] the {#domain_attributes} to {Property#include_in_save_template?}
+    def savable_template_attributes
+      @sv_tmpl_flt ||= domain_attributes.compose { |prop| prop.include_in_save_template? }
+    end
+    
+    # Returns the physical or auto-generated logical dependent attributes that can
+    # be copied from a save result to the given save argument object.
+    #
+    # @return [<Symbol>] the attributes that can be copied from a save result to a
+    #  save argument object
+    # @see Property#autogenerated?
+    def copyable_saved_attributes
+      @cp_sv_flt ||= dependent_attributes.compose { |prop| prop.autogenerated? or not prop.logical? }
+    end
+
+    # @return [<Symbol>] the attributes which are {Property#creatable?}
+    def creatable_attributes
+      @cr_flt ||= attribute_filter { |prop| prop.creatable? }
+    end
+
+    # @return [<Symbol>] the attributes which are {Property#updatable?}
+    def updatable_attributes
+      @upd_flt ||= attribute_filter { |prop| prop.updatable? }
+    end
+
+    def fetched_dependent_attributes
+      @fch_dep_flt ||= (fetched_domain_attributes & dependent_attributes).to_a
+    end
+
+    # @return [<Symbol>] the saved dependent attributes
+    def saved_dependent_attributes
+      @sv_dep_flt ||= attribute_filter { |prop| prop.dependent? and prop.saved? }
+    end
+    
+    # @return [<Symbol>] the saved {Property#independent?} attributes
+    # @see Property#saved?
+    def saved_independent_attributes
+      @sv_ind_flt ||= attribute_filter { |prop| prop.independent? and prop.saved? }
+    end
+
+    # @return [<Symbol>] the domain {Property#sync?} attributes
+    def sync_domain_attributes
+      @sv_sync_dom_flt ||= domain_attributes.compose { |prop| prop.sync? }
+    end
+
+    # @return [<Symbol>] the non-domain {Property#saved?} attributes
+    def saved_nondomain_attributes
+      @sv_ndom_flt ||= nondomain_attributes.compose { |prop| prop.saved? }
+    end
+
+    # @return [<Symbol>] the {Property#volatile?} {#nondomain_attributes}
+    def volatile_nondomain_attributes
+      @vl_ndom_flt ||= nondomain_attributes.compose { |prop| prop.volatile? }
+    end
+
+    # @return [<Symbol>] the domain {#creatable_attributes}
+    def creatable_domain_attributes
+      @cr_dom_flt ||= domain_attributes.compose { |prop| prop.creatable? }
+    end
+
+    # @return [<Symbol>] the domain {#updatable_attributes}
+    def updatable_domain_attributes
+      @upd_dom_flt ||= domain_attributes.compose { |prop| prop.updatable? }
+    end
+
+    # @return [<Symbol>] the attributes which are populated from the database
+    # @see Property#fetched?
+    def fetched_attributes
+      @fch_flt ||= attribute_filter { |prop| prop.fetched? }
+    end
+
+    # Returns the domain attributes which are populated in a query on the given fetched instance of
+    # this metadata's subject class. The domain attribute is fetched if it satisfies the following 
+    # conditions:
+    # * the attribute is a dependent attribute or of abstract domain type
+    # * the attribute is not specified as unfetched in the configuration
+    #
+    # @return [<Symbol>] the attributes which are {Property#fetched?}
+    def fetched_domain_attributes
+      @fch_dom_flt ||= domain_attributes.compose { |prop| prop.fetched? }
+    end
+
+    #@return [<Symbol>] the #domain_attributes which are not #fetched_domain_attributes
+    def unfetched_attributes
+      @unftchd_flt ||= domain_attributes.compose { |prop| not prop.fetched? }
+    end
+    
+    alias :toxic_attributes :unfetched_attributes
+
+    # @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? }
+    end
+    
+    private
+
+    def create_nonjava_property(attribute, type, *flags)
+      Property.new(attribute, self, type, *flags)
+    end
+    
+    def create_java_property(pd)
+      JavaProperty.new(pd, self)
+    end
+          
+    # Augments +Jinx::Propertied#default_mandatory_local_attributes to exclude auto-generated properties.
+    def default_mandatory_local_attributes
+      super.delete_if { |ma| property(ma).autogenerated? }
+    end
+  end
+end

data/lib/caruby/metadata/property.rb

@@ -0,0 +1,22 @@
+require 'jinx/metadata/property'
+require 'caruby/metadata/property_characteristics'
+
+# Mix persistence into +Jinx::Property+.
+module CaRuby
+  class Property < Jinx::Property
+    include CaRuby::PropertyCharacteristics
+           
+    def initialize(attribute, declarer, type=nil, *flags)
+      super
+    end
+    
+    private
+    
+    # @param [Symbol] the flag to set
+    # @return [Boolean] whether the flag is supported
+    def flag_supported?(flag)
+      super or CaRuby::PropertyCharacteristics::SUPPORTED_FLAGS.include?(flag)
+    end
+  end
+end
+

data/lib/caruby/metadata/property_characteristics.rb

@@ -0,0 +1,201 @@
+require 'jinx/metadata/property_characteristics'
+
+module CaRuby
+  # The CaRuby::PropertyCharacteristics mixin captures persistence metadata.
+  module PropertyCharacteristics
+    # The supported persistence-specific property qualifier flags. This set augments the
+    # +Jinx::Property::SUPPORTED_FLAGS+ set for persistence adapters. See the complementary
+    # methods for an explanation of the flag option, e.g. {#autogenerated?} for the
+    # +: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
+
+    # 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
+
+    # 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. An attribute is auto-generated
+    # if the +:autogenerated+ flag is set.
+    #
+    # @return [Boolean] whether the attribute is auto-generated
+    def autogenerated?
+      @flags.include?(:autogenerated)
+    end
+    
+    # Returns whether this attribute must be fetched when a declarer instance is saved.
+    # An attribute is a saved fetch attribute if any of the following conditions hold:
+    # * it is {#autogenerated?}
+    # * 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
+    #   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:
+    # 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
+    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
+    #
+    # @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
+    #
+    # @return [Boolean] whether this attribute is saved in a update operation
+    def updatable?
+      saved? and not @flags.include?(:create_only)
+    end
+
+    # 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
+    def cascaded?
+      (dependent? and not logical?) or @flags.include?(:cascaded)
+    end
+    
+    # Determines whether this propery is included in a save operation argument.
+    #
+    # @return [Boolean] whether this attribute is {#cascaded?} or marked with the
+    #   +:include_in_save_template+ flag
+    def include_in_save_template?
+      cascaded? or @flags.include?(:include_in_save_template)
+    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.
+    #
+    # @return [Boolean] whether the attribute 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?}
+    # 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?
+      @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 #{#saved?} and does not have the
+    #   +:nosync+ flag set
+    def sync?
+      saved? and not @flags.include?(:nosync)
+    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
+
+    # Returns whether this attribute's referents must exist before an instance of the
+    # declarer class can be created. An attribute is a savable 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 savable_prerequisite?
+      return true if cascaded? and @flags.include?(:no_cascade_update_to_create)
+      return false unless independent? and saved?
+      return true unless collection?
+      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?
+      java_property? and not collection?
+    end
+         
+    # @return [Boolean] whether this attribute is set by the server
+    def volatile?
+      to_sym == :identifier or @flags.include?(:volatile)
+    end
+
+    private
+    
+    # @param [Symbol] the flag to set
+    # @return [Boolean] whether the flag is supported
+    def flag_supported?(flag)
+      super or SUPPORTED_FLAGS.include?(flag)
+    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