caruby-core 1.5.5 → 2.1.1

data/lib/caruby/database/search_template_builder.rb

@@ -1,56 +0,0 @@
-require 'caruby/util/log'
-require 'caruby/util/pretty_print'
-
-module CaRuby
-  # SearchTemplateBuilder builds a template suitable for a caCORE saarch database operation.
-  class SearchTemplateBuilder
-    # Returns a template for matching the domain object obj and the optional hash values.
-    # The default hash attributes are the {Domain::Attributes#searchable_attributes}.
-    # The template includes only the non-domain attributes of the hash references.
-    #
-    # @quirk caCORE Because of caCORE API limitations, the obj searchable attribute
-    #   values are limited to the following:
-    #   * non-domain attribute values
-    #   * non-collection domain attribute references which contain a key
-    #
-    # @quirk caCORE the caCORE query builder breaks on reference cycles and is easily confused
-    #   by extraneous references, so it is necessary to search with a template instead that contains
-    #   only references essential to the search. Each reference is confirmed to exist and the
-    #   reference content in the template consists entirely of the fetched identifier attribute.
-    def build_template(obj, hash=nil)
-      # split the attributes into reference and non-reference attributes.
-      # the new search template object is built from the non-reference attributes.
-      # the reference attributes values are copied and added.
-      logger.debug { "Building search template for #{obj.qp}..." }
-      hash ||= obj.value_hash(obj.class.searchable_attributes)
-      # the searchable attribute => value hash
-      rh, nrh = hash.split { |attr, value| Resource === value }
-      # make the search template from the non-reference attributes
-      tmpl = obj.class.new.merge_attributes(nrh)
-      # get references for the search template
-      unless rh.empty? then
-        logger.debug { "Collecting search reference parameters for #{obj.qp} from attributes #{rh.keys.to_series}..." }
-      end
-      rh.each { |attr, ref| add_search_template_reference(tmpl, ref, attr) }
-      tmpl
-    end
-
-    private
-
-    # Sets the template attribute to a new search reference object created from the given
-    # source domain object. The reference contains only the source identifier, if it exists,
-    # or the source non-domain attributes otherwise.
-    #
-    # @return [Resource] the search reference
-    def add_search_template_reference(template, source, attribute)
-      ref = source.identifier ? source.copy(:identifier) : source.copy
-      # Disable inverse integrity, since the template attribute assignment might have added a reference
-      # from ref to template, which introduces a template => ref => template cycle that causes a caCORE
-      # search infinite loop. Use the Java property writer instead.
-      wtr = template.class.attribute_metadata(attribute).property_writer
-      template.send(wtr, ref)
-      logger.debug { "Search reference parameter #{attribute} for #{template.qp} set to #{ref} copied from #{source.qp}" }
-      ref
-    end
-  end
-end

data/lib/caruby/database/store_template_builder.rb

@@ -1,278 +0,0 @@
-require 'caruby/domain/reference_visitor'
-
-module CaRuby
-  # StoreTemplateBuilder creates a template suitable for a create or update database operation.
-  class StoreTemplateBuilder
-    # Creates a new StoreTemplateBuilder for the given database. The attributes to merge into
-    # the template are determined by the block given to this initializer, filtered as follows:
-    # * If the save operation is a create, then exclude the auto-generated attributes.
-    # * If the visited object has an identifier, then include only those attributes
-    #   which {Domain::Attribute#cascade_update_to_create?} or have an identifier. 
-    #
-    # @param [Database] database the target database 
-    # @yield [ref] the required selector block which determines which attributes are copied into the template
-    # @yieldparam [Resource] ref the domain object to copy
-    def initialize(database)
-      @database = database
-      unless block_given? then
-        raise ArgumentError.new("StoreTemplateBuilder is missing the required template copy attribute selector block")
-      end
-      
-      # the mergeable attributes filter the given block with exclusions
-      @mergeable = Proc.new { |obj| mergeable_attributes(obj, yield(obj)) }
-      # the storable prerequisite reference visitor
-      @prereq_vstr = ReferenceVisitor.new(:prune_cycle) { |ref| savable_template_attributes(ref) }
-      
-      # the savable attributes filter the given block with exclusions
-      savable = Proc.new { |obj| savable_attributes(obj, yield(obj)) }
-      # the domain attributes to copy is determined by the constructor caller
-      # @quirk caTissue must copy all of the non-domain attributes rather than just the identifier,
-      # since caTissue auto-generated Specimen update requires the parent collection status. This
-      # is the only known occurrence of a referenced object required non-identifier attribute.
-      # The copy attributes are parameterized by the top-level save target.
-      copier = Proc.new do |src|
-        tgt = src.copy
-        logger.debug { "Store template builder copied #{src.qp} into #{tgt}." }
-        copy_proxied_save_references(src, tgt)
-        tgt
-      end
-      # the template copier
-      @copy_vstr = CopyVisitor.new(:mergeable => savable, :copier => copier) { |ref| savable_template_attributes(ref) }
-    end
-
-    # Returns a new domain object which serves as the argument for obj create or update.
-    #
-    # This method copies a portion of the obj object graph to a template object.
-    # The template object graph consists of copies of obj object graph which are necessary
-    # to store obj. The template object graph contains only those references which are
-    # essential to the store operation.
-    #
-    # @quirk caCORE +caCORE+ expects the store argument to be carefully prepared prior to
-    #   the create or update. build_storable_template culls the target object with a template
-    #   which includes only those references which are necessary for the store to succeed.
-    #   This template builder ensures that mandatory independent references exist. Cascaded
-    #   dependent references are included in the template but are not created before submission
-    #   to +caCORE+. These reference attribute distinctions are implicit application rules which
-    #   are explicated in the +caRuby+ application domain class definition using Metadata
-    #   methods.
-    #
-    # @quirk caCORE +caCORE+ create issues an error if a create argument directly or
-    #   indirectly references a non-cascaded domain object without an identifier, even if the
-    #   reference is not relevant to the create. The template returned by this method elides
-    #   all non-essential references.
-    #
-    # @quirk caCORE application business logic performs unnecessary verification
-    #   of uncascaded references as if they were a cascaded create. This can result in
-    #   an obscure ApplicationException. The server.log stack trace indicates the
-    #   extraneous verification code. For example, +caTissue+ +NewSpecimenBizLogic.validateStorageContainer+
-    #   is unnecessarily called on a SpecimenCollectionGroup (SCG) update. SCG does not
-    #   cascade to Specimen, but caTissue considers the SCG update a Specimen create
-    #   anyway if the SCG references a Specimen without an identifier. The Specimen
-    #   business logic then raises an exception when it finds a StorageContainer
-    #   without an identifier in the Specimen object graph. Therefore, an update must
-    #   build a storable template which prunes the update object graph to exclude uncascaded
-    #   objects. These uncascaded objects should be ignored by the application but aren't.
-    #
-    # @param [Resource] obj the domain object to save
-    # @return [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_storable(obj)
-      # copy the cascade hierarchy
-      logger.debug { "Building storable template for #{obj.qp}..." }
-      tmpl = @copy_vstr.visit(obj)
-      logger.debug { "Built #{obj.qp} template #{tmpl.qp} by mapping references #{@copy_vstr.matches.qp}" }
-      tmpl
-    end
-
-    private
-  
-    # Ensure that the given domain object obj can be created or updated by setting the identifier for
-    # each independent reference in the create template object graph.
-    #
-    # @quirk caCORE +caCORE+ raises an ApplicationException if an independent reference in the create or
-    #   update argument does not have an identifier. The +caCORE+ server log error is as follows:
-    #     java.lang.IllegalArgumentException: id to load is required for loading
-    #   The server log stack trace indicates a bizlogic line that offers a clue to the offending reference.
-    def ensure_storable(obj)
-      # Add defaults, which might introduce independent references. Enable the lazy loader to fetch
-      # create references from the database where needed to build defaults.
-      obj.add_defaults
-      # create the prerequisite references if necessary
-      prereqs = collect_prerequisites(obj)
-      unless prereqs.empty? then
-        logger.debug { "Ensuring references for #{obj.qp} exist: #{prereqs.map { |ref| ref.qp }.to_series}..." }
-        @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
-    end
-    
-    # Returns the attributes to visit in building the template for the given
-    # domain object. The visitable attributes consist of the following:
-    # * The {Domain::Attributes#unproxied_savable_template_attributes} filtered as follows:
-    #   * If the database operation is a create, then exclude the cascaded attributes.
-    #   * If the given object has an identifier, then exclude the attributes which
-    #     have the the :no_cascade_update_to_create flag set.
-    # * The {Domain::Attributes#proxied_savable_template_attributes} are included if and
-    #   only if every referenced object has an identifier, and therefore does not
-    #   need to be proxied.
-    #
-    # @quirk caTissue caTissue ignores some references, e.g. Participant CPR, and auto-generates
-    #   the values instead. Therefore, the create template builder excludes these auto-generated
-    #   attributes. After the create, the auto-generated references are merged into the created
-    #   object graph and the references are updated if necessary.
-    #
-    # @param [Resource] obj the domain object copied to the update template
-    # @return [<Symbol>] the reference attributes to include in the update template
-    def savable_template_attributes(obj)
-      # The starting set of candidate attributes is the unproxied cascaded references.
-      unproxied = savable_attributes(obj, obj.class.unproxied_savable_template_attributes)
-      # The proxied attributes to save.
-      proxied = savable_proxied_attributes(obj)
-      # The combined set of savable attributes
-      proxied.empty? ? unproxied : unproxied + proxied
-    end
-    
-    # Filters the given attributes, if necessary, to exclude attributes as follows:
-    # * If the save operation is a create, then exclude the
-    #   {Domain::Attribute#autogenerated_on_create?} attributes.
-    #
-    # @param [Resource] obj the visited domain object
-    # @param [Attributes::Filter] the savable attribute filter
-    # @return [Attributes::Filter] the composed attribute filter
-    def mergeable_attributes(obj, attributes)
-      # If this is an update, then there is no filter on the given attributes.
-      return attributes if @subject.identifier
-      # This is a create: ignore the optional auto-generated attributes.
-      mas = obj.mandatory_attributes.to_set
-      attributes.compose { |attr_md| mas.include?(attr_md.to_sym) or not attr_md.autogenerated_on_create? }
-    end
-    
-    # Composes the given attributes, if necessary, to exclude attributes as follows:
-    # * If the save operation is a create, then exclude the auto-generated attributes.
-    # * If the visited object has an identifier, then include only those attributes
-    #   which {Domain::Attribute#cascade_update_to_create?} or have an identifier. 
-    #
-    # @param (see #mergeable_attributes)
-    # @return (see #mergeable_attributes)
-    def savable_attributes(obj, attributes)
-      mgbl = mergeable_attributes(obj, attributes)
-      return mgbl if obj.identifier.nil?
-      # The currently visited object is an update: include attributes which
-      # either cascade update to create or have saved references.
-      mgbl.compose do |attr_md|
-        attr_md.cascade_update_to_create? or Persistable.saved?(obj.send(attr_md.to_sym))
-      end
-    end
-   
-    # Returns the proxied attributes to save. A proxied attribute is included only if the proxied
-    # dependents have an identifier, since those without an identifer are created separately via
-    # the proxy.
-    #
-    # @param [Resource] obj the visited domain object
-    # @return [<Attribute>] the proxied cascaded attributes with an unsaved reference
-    def savable_proxied_attributes(obj)
-      # Include a proxied reference only if the proxied dependents have an identifier,
-      # since those without an identifer are created separately via the proxy.
-      obj.class.proxied_savable_template_attributes.reject do |attr|
-        ref = obj.send(attr)
-        case ref
-          when Enumerable then ref.any? { |dep| not dep.identifier }
-          when Resource then not ref.identifier
-        end
-      end
-    end
-    
-    # Copies proxied references as needed.
-    #
-    # @quirk caTissue even though Specimen save cascades to SpecimenPosition,
-    #   SpecimenPosition cannot be updated directly. Rather than simply not
-    #   cascading to the SpecimenPosition, caTissue checks a Specimen save argument
-    #   to ensure that the SpecimenPosition reflects the current database state
-    #   rather than the desired cascaded state. Play along with this bizarre
-    #   mechanism by adding our own bizarre work-around mechanism to copy a
-    #   proxied reference only if it has an identifier. This works only because
-    #   another work-around in the #{Writer} updates proxied
-    #   references via the proxy create before building the update template.
-    def copy_proxied_save_references(obj, template)
-      return unless obj.identifier
-      obj.class.proxied_savable_template_attributes.each do |attr|
-        # the proxy source
-        ref = obj.send(attr)
-        case ref
-          when Enumerable then
-            # recurse on the source collection
-            coll = template.send(attr)
-            ref.each do |dep|
-              copy = copy_proxied_save_reference(obj, attr, template, dep)
-              coll << copy if copy
-            end
-          when Resource then
-            # copy the source
-            copy = copy_proxied_save_reference(obj, attr, template, ref)
-            # set the attribute to the copy
-            template.set_attribute(attr, copy) if copy
-        end
-      end
-    end
-    
-    # Copies a proxied reference.
-    #
-    # @return [Resource, nil] the copy, or nil if no copy is made
-    def copy_proxied_save_reference(obj, attribute, template, proxied)
-      # only copy an existing proxied
-      return unless proxied.identifier
-      # the proxied attribute => value hash
-      vh = proxied.value_hash
-      # map references to either the copied owner or a new copy of the reference
-      tvh = vh.transform { |value| Resource === value ? (value == obj ? template : value.copy) : value }
-      # the copy with the adjusted values
-      copy = proxied.class.new.merge_attributes(tvh)
-      logger.debug { "Created #{obj.qp} proxied #{attribute} save template copy #{proxied.pp_s}." }
-      copy
-    end
-    
-    # @param [Resource] obj the domain object to store
-    # @return [<Resource>] the references which must be created in order to store the object
-    def collect_prerequisites(obj)
-      prereqs = Set.new
-      # visit the cascaded attributes 
-      @prereq_vstr.visit(obj) do |stbl|
-        # Check each mergeable attribute for prerequisites. The mergeable attributes includes
-        # both cascaded and independent attributes. The selection block filters for independent
-        # domain objects which don't have an identifier.
-        @mergeable.call(stbl).each_pair do |attr, attr_md|
-          # Cascaded attributes are not prerequisite, since they are created when the owner is created.
-          # Note that each non-prerequisite cascaded reference is still visited in order to ensure
-          # that each independent object referenced by a cascaded reference is recognized as a
-          # candidate prerequisite.
-          next if attr_md.cascaded?
-          # add qualified prerequisite attribute references
-          stbl.send(attr).enumerate do |ref|
-            # Add the prerequisite if it satisfies the prerequisite? condition.
-            prereqs << ref if prerequisite?(ref, obj, attr)
-          end
-        end
-      end    
-      prereqs
-    end
-    
-    # A referenced object is a target object save prerequisite if none of the follwing is true:
-    # * it is the target object
-    # * it was already created
-    # * it is in an immediate or recursive dependent of the target object
-    # * the current save operation is in the context of creating the referenced object
-    #
-    # @param [Resource] ref the reference to check
-    # @param [Resource] obj the object being stored
-    # @param [Symbol] attribute the reference attribute
-    # @return [Boolean] whether the reference should exist before storing the object
-    def prerequisite?(ref, obj, attribute)
-      not (ref == obj or ref.identifier or ref.owner_ancestor?(obj))
-    end
-  end
-end

data/lib/caruby/domain.rb

@@ -1,193 +0,0 @@
-require 'fileutils'
-require 'caruby/util/collection'
-require 'caruby/util/log'
-require 'caruby/domain/importer'
-
-module CaRuby
-  class JavaImportError < StandardError; end;
-
-  # 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"]
-    ]
-
-  # Domain extends a Module with Java class {Metadata} support.
-  #
-  # A Java class is imported into Ruby either by including the given Resource module
-  # or by referenceing the class name for the first time. For example, the
-  # +ClinicalTrials+ wrapper for Java package +org.nci.ctms+ classes and
-  # Ruby class definitions in the +domain+ subdirectory is enabled as follows:
-  #   module ClinicalTrials
-  #     PKG = 'org.nci.ctms'
-  #     SRC_DIR = File.join(File.dirname(__FILE__), 'domain')
-  #     CaRuby::Domain.extend_module(self, :package => PKG, :directory => SRC_DIR)
-  #
-  # The first reference by name to +ClinicalTrials::Subject+ imports the Java class
-  # +org.nci.ctms.Subject+ into +ClinicalTrials+. The +Subject+ Java property meta-data
-  # is introspected and the {Resource} module is included.
-  module Domain
-    # Extends the given module with importable Java class {Metadata} support.
-    #
-    # @param [Module] mod the module to extend
-    # @param [{Symbol => Object}] opts the extension options
-    # @option opts [Module] :metadata the optional {Metadata} extension (default {Metadata})
-    # @option opts [Module] :mixin the optional mix-in module (default {Resource})
-    # @option opts [String] :package the required Java package name
-    # @option opts [String] :directory the optional directory of source class definitions to load
-    def self.extend_module(mod, opts)
-      mod.extend(self)
-      Importer.extend_module(mod, opts)
-    end
-    
-    # Loads the {#access_properties} and adds the +path+ property items to the Java classpath.
-    #
-    # @param [Module] mod the module to extend
-    def self.extended(mod)
-      super
-      mod.ensure_classpath_defined
-    end
-    
-    # Loads the application start-up properties on demand. The properties are defined in the properties
-    # file or as environment variables.
-    # The properties file path is a period followed by the lower-case application name in the home directory,
-    # e.g. +~/.clincaltrials+ for the +ClinicalTrials+ application.
-    #
-    # The property file format is a series of property definitions in the form _property_: _value_.
-    # The supported properties include the following:
-    # * +host+ - the application server host (default +localhost+)
-    # * +port+ - the application server port (default +8080+)
-    # * +user+ - the application server login
-    # * +password+ - the application service password
-    # * +path+ or +classpath+ - the application client Java directories
-    # * +database+ - the application database name
-    # * +database_user+ - the application database connection userid
-    # * +database_password+ - the application database connection password
-    # * +database_host+ - the application database connection host (default +localhost+)
-    # * +database_type+ - the application database type, + mysql+ or +oracle+ (default +mysql+)
-    # * +database_driver+ - the application database connection driver (default is the database type default)
-    # * +database_port+ - the application database connection port (default is the database type default)
-    #
-    # The +path+ value is one or more directories separated by a semi-colon(;) or colon (:)
-    # Each path directory and all jar files within the directory are added to the caRuby execution
-    # Java classpath.
-    #
-    # Each property has an environment variable counterpart given by 
-    #
-    # @return [{Symbol => Object}] the caBIG application access properties
-    def access_properties
-      @rsc_props ||= load_access_properties
-    end
-    
-    # Ensures that the application client classpath is defined. The classpath is defined
-    # in the {#access_properties}. This method is called when a module extends this
-    # Domain, before any application Java domain class is imported into JRuby.
-    def ensure_classpath_defined
-      # Loading the access properties on demand sets the classpath.
-      access_properties
-    end
-
-    private
-       
-    # Loads the application start-up properties in the given file path.
-    #
-    # @return (see #access_properties)
-    def load_access_properties
-      # the properties file
-      file = default_properties_file
-      # the access properties
-      props = file && File.exists?(file) ? load_properties_file(file) : {}
-      # Look for environment overrides preceded by the uppercase module name,
-      # e.g. CATISSUE_USER for the CaTissue module.
-      load_environment_properties(props)
-      
-      # load the Java application jar path
-      path = props[:classpath] || props[:path]
-      if path then
-        logger.info("Defining application classpath #{path}...")
-        Java.add_path(path)
-      end
-      
-      props
-    end
-    
-    def load_properties_file(file)
-      props = {}
-      logger.info("Loading application properties from #{file}...")
-      File.open(file).map do |line|
-        # match the tolerant property definition
-        match = PROP_DEF_REGEX.match(line.chomp.strip) || next
-        # the property [name, value] tokens
-        tokens = match.captures
-        pname = tokens.first.to_sym
-        # path is deprecated
-        name = pname == :path ? :classpath : pname
-        value = tokens.last
-        # capture the property
-        props[name] = value
-      end
-      props
-    end
-    
-    def load_environment_properties(props)
-      ACCESS_OPTS.each do |spec|
-        # the access option symbol is the first specification item
-        opt = spec[0]
-        # the envvar value
-        value = environment_property(opt) || next
-        # override the file property with the envar value
-        props[opt] = value
-        logger.info("Set application property #{opt} from environment variable #{ev}.")
-      end
-    end 
-    
-    # @param [Symbol] opt the property symbol, e.g. :user
-    # @return [String, nil] the value of the corresponding environment variable, e.g. +CATISSUE_USER+
-    def environment_property(opt)
-      @env_prefix ||= name.gsub('::', '_').upcase
-      ev = "#{@env_prefix}_#{opt.to_s.upcase}"
-      value = ENV[ev]
-      # If no classpath envvar, then try the deprecated path envvar.
-      if value.nil? and opt == :classpath then
-        environment_property(:path)
-      else
-        value
-      end
-    end
-
-    # The property/value matcher, e.g.:
-    #   host: jacardi
-    #   host = jacardi
-    #   host=jacardi
-    #   name: J. Edgar Hoover
-    # but not:
-    #   # host: jacardi
-    # The captures are the trimmed property and value.
-    PROP_DEF_REGEX = /^(\w+)(?:\s*[:=]\s*)([^#]+)/
-    
-    # @return [String] the default application properties file, given by +~/.+_name_,
-    #   where _name_ is the underscore unqualified module name, e.g. +~/.catissue+
-    #   for module +CaTissue+
-    def default_properties_file
-      home = ENV['HOME'] || ENV['USERPROFILE'] || '~'
-      file = File.expand_path("#{home}/.#{name[/\w+$/].downcase}")
-      if File.exists?(file) then
-        file
-      else
-        logger.warn("The default #{name} application property file was not found: #{file}.")
-        nil
-      end
-    end
-  end
-end