caruby-core 1.4.7 → 1.4.9

data/lib/caruby/domain/resource_dependency.rb

@@ -1,3 +1,5 @@
+require 'caruby/util/validation'
+
 module CaRuby
   # ResourceMetadata mix-in to capture Resource dependency.
   module ResourceDependency
@@ -25,24 +27,49 @@ module CaRuby
     # * _inverse_ is the owner inverse attribute defined in the dependent class
     #
     # @param [Symbol] attribute the dependent to add
-    # @param [<Symbol>] the attribute qualifier flags
+    # @param [<Symbol>] flags the attribute qualifier flags
     def add_dependent_attribute(attribute, *flags)
       attr_md = attribute_metadata(attribute)
       flags << :dependent unless flags.include?(:dependent)
       attr_md.qualify(*flags)
       inverse = attr_md.inverse
       inv_type = attr_md.type
-      # example: Parent.add_dependent_attribute(:children) with inverse :parent calls
-      # Child.add_owner(Parent, :children, :parent)
+      # example: Parent.add_dependent_attribute(:children) with inverse :parent calls the following:
+      #   Child.add_owner(Parent, :children, :parent)
       inv_type.add_owner(self, attribute, inverse)
     end
-
-    # Returns whether this metadata's subject class depends on an owner.
+    
+    # Makes a new owner attribute. The attribute name is the lower-case demodulized
+    # owner class name. The owner class must reference this class via the given
+    # inverse dependent attribute.
+    #
+    # @param klass (see #detect_owner_attribute)
+    # @param [Symbol] the owner -> dependent inverse attribute 
+    # @return [Symbol] this class's new owner attribute
+    # @raise [ArgumentError] if the inverse is nil
+    def create_owner_attribute(klass, inverse)
+      if inverse.nil? then
+        raise ArgumentError.new("Cannot create a #{qp} owner attribute to #{klass} without a dependent attribute to this class.")
+      end
+      attr = klass.name.demodulize.underscore.to_sym
+      attr_accessor(attr)
+      add_attribute(attr, klass)
+      attribute_metadata(attr).inverse = inverse
+      logger.debug { "Created #{qp} owner attribute #{attr} with inverse #{klass.qp}.#{inverse}." }
+      attr
+    end
+    
+    # @return [Boolean] whether this class depends on an owner
     def dependent?
       not owners.empty?
     end
+    
+    # @return [Boolean] whether this class has an owner which cascades save operations to this dependent
+    def cascaded_dependent?
+      owner_attribute_metadata_enumerator.any? { |attr_md| attr_md.cascaded? }
+    end
 
-    # Returns whether this metadata's subject class depends the given other class.
+    # @return [Boolean] whether this class depends the given other class
     def depends_on?(other)
       owners.detect { |owner| owner === other }
     end
@@ -58,73 +85,133 @@ module CaRuby
     # @return [Symbol, nil] the sole owner attribute of this class, or nil if there
     #   is not exactly one owner
     def owner_attribute
-      if @local_owner_attr_hash then
-        # the sole attribute in the owner class => attribute hash
-        @local_owner_attr_hash.each_value { |attr| return attr } if @local_owner_attr_hash.size == 1
-      elsif superclass < Resource
-        # delegate to superclass
-        superclass.owner_attribute
+      attr_md = owner_attribute_metadata_enumerator.first || return
+      # There is at most one non-nil value in the owner class => AttributeMetadata hash.
+      # If there is such a value, then return the attribute symbol.
+      if owner_attribute_metadata_enumerator.size == 1 then
+        attr_md.to_sym
       end
     end
 
-    # Returns this Resource class's owner types.
+    # @return [<Symbol>] this class's owner attributes
     def owner_attributes
-      if @local_owner_attr_hash then
-        @local_owner_attrs ||= Enumerable::Enumerator.new(@local_owner_attr_hash, :each_value).filter
-      elsif superclass < Resource
-        superclass.owner_attributes
-      else
-        Array::EMPTY_ARRAY
-      end
+      owner_attribute_metadata_enumerator.transform { |attr_md| attr_md.to_sym }
     end
 
-    # Returns this Resource class's dependent types.
+    # @return [<Class>] this class's dependent types
     def dependents
       dependent_attributes.wrap { |attr| attr.type }
     end
 
-    # Returns this Resource class's owner types.
+    # @return [<Class>] this class's owner types
     def owners
-      if @local_owner_attr_hash then
-        @local_owners ||= Enumerable::Enumerator.new(@local_owner_attr_hash, :each_key)
-      elsif superclass < Resource
-        superclass.owners
-      else
-        Array::EMPTY_ARRAY
-      end
+      @owners ||= Enumerable::Enumerator.new(owner_attribute_metadata_hash, :each_key)
     end
 
     protected
 
     # Adds the given owner class to this dependent class.
     # This method must be called before any dependent attribute is accessed.
+    # If the attribute is given, then the attribute inverse is set.
+    # Otherwise, if there is not already an owner attribute, then a new owner attribute is created.
+    # The name of the new attribute is the lower-case demodulized owner class name.
     #
     # @param [Class] the owner class
-    # @param [Symbol, nil] inverse the owner -> dependent attribute
+    # @param [Symbol] inverse the owner -> dependent attribute
     # @param [Symbol, nil] attribute the dependent -> owner attribute, if known
-    # @raise [ValidationError] if there is no owner -> dependent inverse attribute
-    # @raise [MetadataError] if this method is called after a dependent attribute has been accessed
+    # @raise [ValidationError] if the inverse is nil
     def add_owner(klass, inverse, attribute=nil)
+      if inverse.nil? then raise ValidationError.new("Owner #{klass.qp} missing dependent attribute for dependent #{qp}") end
       logger.debug { "Adding #{qp} owner #{klass.qp}#{' attribute ' + attribute.to_s if attribute}#{' inverse ' + inverse.to_s if inverse}..." }
       if @owner_attr_hash then
         raise MetadataError.new("Can't add #{qp} owner #{klass.qp} after dependencies have been accessed")
       end
-      @local_owner_attr_hash ||= {}
-      @local_owner_attr_hash[klass] = attribute ||= detect_inverse_attribute(klass)
+      
+      # detect the owner attribute, if necessary
+      attribute ||= detect_owner_attribute(klass, inverse)
+      attr_md = attribute_metadata(attribute) if attribute
+      # Add the owner class => attribute entry.
+      # The attribute is nil if the dependency is unidirectional, i.e. there is an owner class which
+      # references this class via a dependency attribute but there is no inverse owner attribute.
+      local_owner_attribute_metadata_hash[klass] = attr_md
+      # If the dependency is unidirectional, then our job is done.
+      return if attribute.nil?
 
-      # set the inverse
-      if attribute then
-        if inverse.nil? then raise ValidationError.new("Owner #{klass.qp} missing dependent attribute for dependent #{qp}") end
+      # set the inverse if necessary
+      unless attr_md.inverse then
         set_attribute_inverse(attribute, inverse)
-        attribute_metadata(attribute).qualify(:owner)
+      end
+      # set the owner flag if necessary
+      unless attr_md.owner? then attr_md.qualify(:owner) end
+      # Redefine the writer method to warn when changing the owner
+      rdr, wtr = attr_md.accessors
+      logger.debug { "Injecting owner change warning into #{qp}.#{attribute} writer method #{wtr}..." }
+      redefine_method(wtr) do |old_wtr|
+        lambda do |ref|
+          prev = send(rdr)
+          if prev and prev != ref then
+            if ref.nil? then
+              logger.warn("Unsetting the #{self} owner #{attribute} #{prev}.")
+            elsif ref.identifier != prev.identifier then
+              logger.warn("Resetting the #{self} owner #{attribute} from #{prev} to #{ref}.")
+            end
+          end
+          send(old_wtr, ref)
+        end
+      end
+    end
+    
+    # Adds the given attribute as an owner. This method is called when a new attribute is added that
+    # references an existing owner.
+    #
+    # @param [Symbol] attribute the owner attribute
+    def add_owner_attribute(attribute)
+      attr_md = attribute_metadata(attribute)
+      otype = attr_md.type
+      hash = local_owner_attribute_metadata_hash
+      if hash.include?(otype) then
+        oattr = hash[otype]
+        unless oattr.nil? then
+          raise MetadataError.new("Cannot set #{qp} owner attribute to #{attribute} since it is already set to #{oattr}")
+        end
+        hash[otype] = attr_md
       else
-        logger.debug { "No #{qp} owner attribute detected for #{klass.qp}." }
+        add_owner(otype, attr_md.inverse, attribute)
       end
     end
 
-    # @return [{Class => Symbol}] this Resource class's owner type => attribute hash
-    def owner_attribute_hash
-      @local_owner_attr_hash or (superclass.owner_attribute_hash if superclass < Resource) or Hash::EMPTY_HASH
+    # @return [{Class => AttributeMetadata}] this class's owner type => attribute hash
+    def owner_attribute_metadata_hash
+      @oa_hash ||= create_owner_attribute_metadata_hash
+    end
+    
+    private
+    
+    def local_owner_attribute_metadata_hash
+      @local_oa_hash ||= {}
+    end
+
+    # @return [{Class => AttributeMetadata}] a new owner type => attribute hash
+    def create_owner_attribute_metadata_hash
+      local = local_owner_attribute_metadata_hash
+      superclass < Resource ? local.union(superclass.owner_attribute_metadata_hash) : local
+    end
+    
+    # @return [<AttributeMetadata>] the owner attributes
+    def owner_attribute_metadata_enumerator
+      # Enumerate each owner AttributeMetadata, filtering out nil values.
+      @oa_enum ||= Enumerable::Enumerator.new(owner_attribute_metadata_hash, :each_value).filter
+    end
+    
+    # Returns the attribute which references the owner. The owner attribute is the inverse
+    # of the given owner class inverse attribute, if it exists. Otherwise, the owner
+    # attribute is inferred by #{ResourceInverse#detect_inverse_attribute}.
+
+    # @param klass (see #add_owner)
+    # @param [Symbol] inverse the owner -> dependent attribute
+    # @return [Symbol, nil] this class's owner attribute
+    def detect_owner_attribute(klass, inverse)
+      klass.attribute_metadata(inverse).inverse or detect_inverse_attribute(klass)
     end
   end
 end

data/lib/caruby/domain/resource_introspection.rb

@@ -96,7 +96,7 @@ module CaRuby
       logger.debug { "Filtered #{qp} #{attribute} and #{awtr} methods with Java Date <-> Ruby Date converter." }
     end
 
-    # Aliases the methods aliaz and _aliaz= to _property_ and _property=_, resp.,
+    # Aliases the methods _aliaz_ and _aliaz=_ to _property_ and _property=_, resp.,
     # where _property_ is the Java property name for the attribute.
     def alias_attribute_property(aliaz, attribute)
       # strip the Java reader and writer is/get/set prefix and make a symbol

data/lib/caruby/domain/resource_inverse.rb

@@ -7,6 +7,21 @@ module CaRuby
     
     protected
     
+    # Infers the inverse of the given attribute declared by this class. A domain attribute is
+    # recognized as an inverse according to the {ResourceInverse#detect_inverse_attribute}
+    # criterion.
+    #
+    # @param [AttributeMetadata] attr_md the attribute to check
+    def infer_attribute_inverse(attr_md)
+      inv = attr_md.type.detect_inverse_attribute(self)
+      if inv then
+        logger.debug { "Detected #{qp} #{attr_md} inverse #{inv.qp}." }
+        set_attribute_inverse(attr_md.to_sym, inv)
+      else
+        logger.debug { "No inverse detected for #{qp} #{attr_md}." }
+      end
+    end
+    
     # Sets the given bi-directional association attribute's inverse.
     #
     # @param [Symbol] attribute the subject attribute
@@ -29,13 +44,15 @@ module CaRuby
         raise TypeError.new("Cannot set #{qp}.#{attribute} inverse to #{attr_md.type.qp}.#{attribute} with incompatible type #{inv_md.type.qp}")
       end
 
-      # if the attribute is defined by this class, then set the inverse in the attribute metadata.
-      # otherwise, make a new attribute metadata specialized for this class.
+      # if the attribute is not declared by this class, then make a new attribute
+      # metadata specialized for this class.
       unless attr_md.declarer == self then
         attr_md = attr_md.dup
         attr_md.declarer = self
         add_attribute_metadata(attribute, inverse)
+        logger.debug { "Copied #{attr_md.declarer}.#{attribute} to #{qp} with restricted inverse return type #{qp}." }
       end
+      # Set the inverse in the attribute metadata.
       attr_md.inverse = inverse
 
       # If attribute is the one side of a 1:M or non-reflexive 1:1 relation, then add the inverse updater.
@@ -57,7 +74,7 @@ module CaRuby
     #   or nil if no owner attribute was detected
     def detect_inverse_attribute(klass)
       # the candidate attributes which return the referencing type
-      candidates = domain_attributes.compose { |attr_md| klass <= attr_md.type }.to_a
+      candidates = domain_attributes.compose { |attr_md| klass <= attr_md.type }
       attr = detect_inverse_attribute_from_candidates(klass, candidates)
       if attr then
         logger.debug { "#{qp} #{klass.qp} inverse attribute is #{attr}." }

data/lib/caruby/domain/resource_metadata.rb

@@ -15,6 +15,23 @@ module CaRuby
     include ResourceIntrospection, ResourceInverse, ResourceDependency, ResourceAttributes
 
     attr_reader :domain_module
+      
+    # JRuby 1.6 alert - if a concrete class implements a constructor, then calling super in an
+    # included module initialize method results in a recursive call back into that initialize. 
+    # The work-around is to redefine each domain class new method to call the initalize_content
+    # method instead. All Resource domain classes or included modules must not override
+    # initialize. They can implement initialize_content instead.
+    def self.extended(klass)
+      klass.class_eval do
+        class << self
+          def new(opts=nil)
+            obj = super()
+            obj.merge_attributes(opts) if opts
+            obj
+          end
+        end
+      end
+    end
 
     # Associates meta-data with a Resource class. When a Resource class is added to a ResourceModule,
     # the ResourceModule extends the Resource class with ResourceMetadata and calls this
@@ -59,15 +76,13 @@ module CaRuby
     
    # Prints this classifier's content to the log.
     def pretty_print(q)
-      
-      
-      # KLUDGE - if not inited then bail
+      # KLUDGE - if not inited then bail.
+      # TODO - isolate when this occurs.
       if @attr_md_hash.nil? then
         q.text(qp)
         return
       end
       
-      
       # the Java property descriptors
       property_descriptors = java_attributes.wrap { |attr| attribute_metadata(attr).property_descriptor }
       # build a map of relevant display label => attributes
@@ -99,6 +114,7 @@ module CaRuby
         "dependent attributes" => dependents_printer,
         "default values" => defaults
       }.delete_if { |key, value| value.nil_or_empty? }
+      
       # one indented line per entry, all but the last line ending in a comma
       content = map.map { |label, value| "  #{label}=>#{format_print_value(value)}" }.join(",\n")
       # print the content to the log

data/lib/caruby/domain/resource_module.rb

@@ -11,9 +11,11 @@ module CaRuby
       [: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"],
+      [: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"],
@@ -31,120 +33,98 @@ module CaRuby
   # The properties are read from a property file. See {Properties} for
   # more information.
   #
-  # A Java class is imported into Ruby either by directly calling the
-  # extended module {#java_import} method or on demand.
+  # A Java class is imported into Ruby either by directly calling the extended
+  # module {#resource_import} method or on demand by referencing the class name.
   # Import on demand is induced by a reference to the class, e.g.:
   #   module ClinicalTrials
-  #     extend Importable
+  #     extend CaRuby::ResourceModule
   #
-  #     def java_package
-  #       'org.nci.ctms'
-  #     end
+  #     @java_package = 'org.nci.ctms'
   #     ...
   # enables references by name to a +ClinicalTrials+ Ruby class wrapper of a
   # +org.nci.ctms+ Java class without an import statement, e.g.:
   #   ClinicalTrials::Participant.new
   # without defining the +Participant+ Ruby class.
   module ResourceModule
-    # Adds the given class to this ResourceModule. The class is extended with ResourceMetadata methods.
-    #
-    # @param [Class] the {Resource} class to add
-    def add_class(klass)
-      @rsc_classes ||= Set.new
-      # add superclass if necessary
-      unless @rsc_classes.include?(klass.superclass) or klass.superclass == Java::JavaLang::Object then
-        # the domain module includes the superclass on demand
-        const_get(klass.superclass.name[/\w+$/].to_sym)
-      end
-      ResourceMetadata.extend_class(klass, self)
-      @rsc_classes << klass
+    # 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
     
-    # @return [Module] the resource mix-in module (default {Resouce})
-    def mixin
-      @mixin || Resource
-    end
-
-    # @return [{Symbol => Object}] the caBIG application access properties
-    # @see #load_access_properties
-    def access_properties
-      @rsc_props ||= load_access_properties
-    end
-
-    # Loads the application start-up properties in the given file path.
-    # The default file path is a period followed by the lower-case application name in the home directory,
-    # e.g. +~/.clincaltrials+.
+    # 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:
-    # * +path+ - the application client Java directories
-    # * +user+ - the application service login
+    # * +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_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
+    # * +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.
     #
-    # @param [String, nil] file the property file, or nil for the default location
-    # @return [{Symbol => Object}] the loaded caBIG application access properties
-    def load_access_properties(file=nil)
-      # If a file was specified, then it must exist.
-      if file and not File.exists?(file) then
-        raise ArgumentError.new("Application access properties file does not exist: #{file}")
-      end
-      # the access properties
-      props ||= {}
-      # If no file was specified, then try the default.
-      # If the default does not exist, then use the empty properties hash.
-      # It is not an error to omit access properties, since the application domain classes
-      # can still be used but not queried or saved.
-      file ||= default_properties_file || return
-      
-      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) || next
-        # the property [name, value] tokens
-        tokens = match.captures
-        name = tokens.first.to_sym
-        value = tokens.last
-        # capture the property
-        props[name] = value
-      end
-      # Look for environment overrides preceded by the uppercase module name, e.g. CATISSUE
-      # for the CaTissue module.
-      env_prefix = name[/\w+$/].upcase
-      ACCESS_OPTS.each do |spec|
-        # the access option symbol is the first specification item
-        opt = spec[0]
-        # the envvar, e.g. CATISSUE_USER
-        ev = "#{env_prefix}_#{opt.to_s.upcase}"
-        # the envvar value
-        value = ENV[ev] || next
-        # override the file property with the envar value
-        props[opt] = value
-        logger.info("Set application property #{opt} from environment variable #{ev}.")
+    # 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
+    # ResourceModule, 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
+    
+    # @return [Module] the resource mix-in module (default {Resouce})
+    def mixin
+      @mixin || Resource
+    end
+    
+    # Adds the given class to this ResourceModule. The class is extended with ResourceMetadata methods.
+    #
+    # @param [Class] the {Resource} class to add
+    def add_class(klass)
+      logger.debug { "Adding #{klass.java_class.name} to #{qp}..." }
+      @rsc_classes ||= Set.new
+      # add superclass if necessary
+      sc = klass.superclass
+      unless @rsc_classes.include?(sc) then
+        # the domain module includes the superclass on demand
+        sc_pkg, sc_sym = Java.split_class_name(sc)
+        if const_defined?(sc_sym) or sc_pkg == @java_package then
+          const_get(sc_sym)
+        else
+          mod = mixin
+          klass.class_eval { include mod }
+        end
       end
-      
-      # load the Java application jar path
-      path_ev = "#{env_prefix}_PATH"
-      path = ENV[path_ev] || props[:path]
-      Java.add_path(path) if path
-      
-      props
+      ResourceMetadata.extend_class(klass, self)
+      @rsc_classes << klass
+      class_added(klass)
+      logger.debug { "#{klass.java_class.name} added to #{qp}." }
     end
 
-    # Loads the Ruby source files in the given directory.
+    # Auto-loads the Ruby source files in the given directory.
+    #
+    # @param [String] dir the source directory
     def load_dir(dir)
-      # load the properties on demand
-      load_access_properties if @rsc_props.nil?
       # the domain class definitions
       sources = Dir.glob(File.join(dir, "*.rb"))
 
@@ -171,21 +151,34 @@ module CaRuby
       end
     end
     
-    def java_import(klass)
+    # @param [Class, String] class_or_name the class to import into this module
+    # @return [Class] the imported class
+    def java_import(class_or_name)
       # JRuby 1.4.x does not support a class argument
-      Class === klass  ? super(klass.java_class.name) : super
+      Class === class_or_name ? super(class_or_name.java_class.name) : super
+    end
+    
+    # @param [Class, String] class_or_name the class to import into this module
+    # @return [Class] the imported {Resource} class
+    def resource_import(class_or_name)
+      klass = java_import(class_or_name)
+      mod = mixin
+      klass.instance_eval { include mod }
+      add_class(klass)
+      klass
     end
 
-    # Extends the mod module with Java class support. See the class documentation for details.
+    # Imports a class constant on demand. See the class documentation for details.
     #
     # @param [Symbol] symbol the missing constant
     def const_missing(symbol)
       autoload?(symbol) ? super : import_domain_class(symbol)
     end
 
-    # Returns the domain class for class_name, or nil if none in this module.
-    def domain_type_with_name(class_name)
-      pkg, base = split_class_name(class_name)
+    # @param [String] the class name to check
+    # @eturn [Class, nil] the domain class for the class name, or nil if none in this module
+    def domain_type_with_name(name)
+      pkg, base = Java.split_class_name(name)
       return unless pkg.nil? or pkg == @java_package
       begin
         type = const_get(base)
@@ -200,6 +193,77 @@ module CaRuby
 
     private
 
+    # Callback invoked after the given domain class is added to this domain module.
+    #
+    # @param [Class] klass the class that was added
+    def class_added(klass); end
+    
+    # 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) || 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
+    
     # Imports the domain Java class with specified class name_or_sym.
     # This method enables the domain class extensions for storing and retrieving domain objects.
     # The class is added to this module.
@@ -222,14 +286,10 @@ module CaRuby
     #
     # The optional aliases argument consists of additional alias => standard attribute associations.
     # The optional owner_attr argument is a non-Java annotation owner attribute.
-    def import_domain_class(name_or_sym)
-      name = name_or_sym.to_s
-      if name.include?('.') then
-        symbol = name[/[A-Z]\w*$/].to_sym
-      else
-        symbol = name_or_sym.to_sym
-        name = [@java_package, name].join('.')
-      end
+    #
+    # @param [Symbol] symbol the class symbol
+    # @param [String, nil] pkg the Java class package name, or nil for the default module package
+    def import_domain_class(symbol, pkg=nil)
       # check if the class is already defined
       if const_defined?(symbol) then
         klass = const_get(symbol)
@@ -239,35 +299,50 @@ module CaRuby
       end
       
       # import the Java class
-      logger.debug { "Importing #{qp} Java class #{symbol}..." }
+      pkg ||= @java_package
+      name = [pkg, symbol.to_s].join('.')
+      logger.debug { "Detecting whether #{symbol} is a #{pkg} Java class..." }
+      # Push each imported class onto a stack. When all referenced classes are imported,
+      # each class on the stack is post-initialized and the class structure is printed to
+      # the log.
+      @import_stack ||= []
+      @import_stack.push(symbol)
       begin
-        java_import(name)
-      rescue Exception => e
-        raise JavaIncludeError.new("#{symbol} is not a #{qp} Java class - #{e.message}")
+        resource_import(name)
+      rescue Exception
+        @import_stack.pop
+        if symbol.to_s =~ /Annotation/ then raise end
+        raise JavaIncludeError.new("#{symbol} is not a #{qp} Java class - #{$!}")
       end
       
       # the imported Java class is registered as a constant in this module
       klass = const_get(symbol)
-      # the Resource import stack
-      @import_stack ||= []
-      @import_stack.push klass
-      # include the Resource mixin in the imported class
-      inc = "include #{mixin}"
-      klass.instance_eval(inc)
-      
       # if we are back to top of the stack, then print the imported Resources
-      if klass == @import_stack.first then
+      if symbol == @import_stack.first then
         # a referenced class could be imported on demand in the course of printing a referencing class;
         # the referenced class is then pushed onto the stack. thus, the stack can grow during the
         # course of printing, but each imported class is consumed and printed in the end.
         until @import_stack.empty? do
-          ref = @import_stack.pop
-          logger.debug { ref.pp_s }
+          # the class constant
+          sym = @import_stack.pop
+          # the imported class
+          kls = const_get(sym)
+          # invoke the call-back
+          imported(kls)
+          # print the class structure to the log
+          logger.info(kls.pp_s)
         end
       end
+      
       klass
     end
 
+    # Call-back to perform post-import actions. This method is called after the
+    # given class and each of its referenced domain classes are introspected.
+    #
+    # @param [Class] the imported class
+    def imported(klass); end
+
     # The property/value matcher, e.g.:
     #   host: jacardi
     #   host = jacardi
@@ -287,18 +362,9 @@ module CaRuby
       if File.exists?(file) then
         file
       else
-        logger.warn { "Default application property file not found: #{file}." }
+        logger.debug { "Default #{name} application property file not found: #{file}." }
         nil
       end
     end
-    
-    # @return [(String, Symbol)] the [package prefix, base class symbol] pair
-    def split_class_name(class_name)
-      # the package prefix, including the period
-      package = Java.java_package_name(class_name)
-      # remove the package and base class name
-      base = package.nil? ? class_name : class_name[package.length + 1..-1]
-      [package, base.to_sym]
-    end
   end
 end