jinx 2.1.3 → 2.1.4

data/lib/jinx/helpers/module.rb

@@ -13,6 +13,6 @@ class Module
   #   A::B.parent_module #=> A
   # @return [Module] this module's definition context
   def parent_module
-    Kernel.module_with_name(name.split('::')[0..-2].join('::'))
+    module_with_name(name.split('::')[0..-2].join('::'))
   end
 end

data/lib/jinx/helpers/multi_enumerator.rb

@@ -1,6 +1,8 @@
+require 'jinx/helpers/collection'
+
 module Jinx
-  # A MultiEnumerator iterates over several Enumerators in sequence. Unlike Array#+, MultiEnumerator reflects changes to the
-  # underlying enumerators.
+  # A MultiEnumerator iterates over several Enumerators in sequence. Unlike Array#+,
+  # MultiEnumerator reflects changes to the underlying enumerators.
   #
   # @example
   #   a = [1, 2]
@@ -8,24 +10,38 @@ module Jinx
   #   ab = MultiEnumerator.new(a, b)
   #   ab.to_a #=> [1, 2, 4, 5]
   #   a << 3; b << 6; ab.to_a #=> [1, 2, 3, 4, 5, 6]
+  #   MultiEnumerator.new(ab, [7]).to_a #=> [1, 2, 3, 4, 5, 6, 7]
   class MultiEnumerator
-    include Collection
-
-    # @return [<Enumerable>] the enumerated collections
-    attr_reader :components
+    include Enumerable, Collection
 
     # Initializes a new {MultiEnumerator} on the given components.
     #
     # @param [<Enumerable>] the component enumerators to compose
-    def initialize(*enums)
+    # @yield [item] the optional appender block
+    # @yieldparam item the item to append
+    def initialize(*enums, &appender)
       super()
       @components = enums
       @components.compact!
+      @appender = appender
     end
 
-    # Iterates over each of this MultiEnumerator's Enumerators in sequence.
+    # Iterates over each of this MultiEnumerator's enumerators in sequence.
     def each
-      @components.each { |enum| enum.each { |item| yield item  } }
+      @components.each do |enum|
+        enum.each { |item| yield item }
+      end
+    end
+    
+    # @param item the item to append
+    # @raise [NoSuchMethodError] if this {MultiEnumerator} does not have an appender
+    def <<(item)
+      @appender ? @appender << item : super
+    end
+      
+    # Returns the union of the results of calling the given method symbol on each component.
+    def method_missing(symbol, *args)
+      self.class.new(@components.map { |enum|enum.send(symbol, *args) })
     end
   end
 end

data/lib/jinx/helpers/options.rb

@@ -3,7 +3,8 @@ require 'jinx/helpers/collections'
 require 'jinx/helpers/validation'
 require 'jinx/helpers/merge'
 
-# Options is a utility class to support method options.
+# Options is a utility class to support a method option parameter.
+# Option argument parsing is described in {Options.get}.
 class Options
   # Returns the value of option in options as follows:
   # * If options is a hash which contains the option key, then this method returns
@@ -80,8 +81,8 @@ class Options
 
   private
   
-  def self.detect_in_enumerable(key, options)
-    options.detect_value do |opt|
+  def self.detect_in_enumerable(key, opts)
+    opts.detect_value do |opt|
       Hash === opt ? opt[key] : opt == key
     end
   end

data/lib/jinx/helpers/partial_order.rb

@@ -1,12 +1,15 @@
 module Jinx
-  # A PartialOrder is a Comparable which restricted scope. Classes which include PartialOrder
-  # are required to implement the <=> operator with the following semantics:
-  # *  _a_ <=> _b_ returns -1, 0, or 1 if a and b are comparable, nil otherwise
-  # A PartialOrder thus relaxes comparison symmetry, e.g.
+  # A PartialOrder is a Comparable with restricted scope. Classes which include
+  # PartialOrder are required to implement the <=> operator with the following
+  # semantics:
+  # *  If if a and b are comparable, then return the value of the comparison.
+  # *  Otherwise, return nil.
+  # A PartialOrder thus relaxes comparison symmetry, e.g.:
   #   a < b
-  # does not imply
+  # does not imply:
   #   b >= a.
-  # Example:
+  #
+  # @example
   #   module Queued
   #     attr_reader :queue
   #     def <=>(other)
@@ -14,18 +17,23 @@ module Jinx
   #     end
   #   end
   #   q1 = [a, b] # a, b are Queued
-  #   q2 = [c]    # c is a Queued
+  #   q2 = [c]    # c is Queued
   #   a < b #=> true
   #   b < c #=> nil
   module PartialOrder
     include Comparable
   
+    # Override the Comparable instance methods to accomodate comparisons which return nil.
+    # Each method returns the following result:
+    # * If the method argument is comparable to this object, then delegate to the standard
+    #   Comparable method.
+    # * Otherwise, return nil.
     Comparable.instance_methods(false).each do |m|
       define_method(m.to_sym) do |other|
          self <=> other ? super : nil
       end
     end
-  
+    
     # @return [Boolean] true if other is an instance of this object's class and other == self,
     #   false otherwise
     def eql?(other)

data/lib/jinx/helpers/pretty_print.rb

@@ -154,8 +154,8 @@ module Enumerable
 end
 
 module Jinx
-  module Hashable
-    # qp, short for quick-print, prints this Hashable with a filter that calls qp on each key and value.
+  module Hasher
+    # qp, short for quick-print, prints this Hasher with a filter that calls qp on each key and value.
     #
     # @return [String] the quick-print result
     def qp
@@ -182,9 +182,19 @@ class String
 end
 
 class DateTime
-  # @return [String] the formatted +strftime+
+  # Pretty-prints the DateTime +strftime+ to the given queue in the format
+  # _date_+T+_hr_+h+_mm_+m+_ss_+s+, e.g. +2010-10-10T04h10m30+.
+  #
+  # @quirk JRuby pp standard libary bug - Printing the formatted date:time string sporadically
+  #   results in a corrupted line, e.g.:
+  #     at top level in 2010-10-10T00:00:00-07:00 at line 1 
+  #   The Jinx work-around is to substitute the colons with +h+, +m+ and +s+ and omit the GMT offset.
+  #   The bug cause is unknown. Perhaps it is a flaw in the line break logic.
+  #
+  # @param q the print queue
+  # @return [String] the formatted date and time
   def pretty_print(q)
-    q.text(strftime)
+    q.text(strftime.sub(/T(\d{2}):(\d{2}):(\d{2})-\d{2}:\d{2}/, 'T\1h\2m\3s'))
   end
   
   # qp, an abbreviation for quick-print, is an alias for {#to_s} in this primitive class.

data/lib/jinx/helpers/transformer.rb

@@ -1,7 +1,9 @@
+require 'jinx/helpers/collection'
+
 module Jinx
   # This Transformer helper class applies a transformer block to a base enumeration.
   class Transformer
-    include Collection
+    include Enumerable, Collection
 
     def initialize(enum=[], &transformer)
       @base = enum

data/lib/jinx/helpers/transitive_closure.rb

@@ -9,9 +9,6 @@ class Object
   # In either case, the call is expected to return an object or Enumerable of objects which also respond
   # to the method or block.
   #
-  # @param [Symbol, nil] method the child reference, or nil if a block is given
-  # @yield [node] the parent node's children
-  # @yieldparam node the parent node
   # @example
   #   class Node
   #     attr_reader :parent, :children
@@ -26,6 +23,9 @@ class Object
   #   a = Node.new('a'); b = Node.new('b', a), c = Node.new('c', a); d = Node.new('d', c)
   #   a.transitive_closure { |node| node.children }.to_a.join(", ") #=> a, b, c, d
   #   a.transitive_closure(:children).to_a.join(", ") #=> a, b, c, d
+  # @param [Symbol, nil] method the child reference, or nil if a block is given
+  # @yield [node] the parent node's children
+  # @yieldparam node the parent node
   def transitive_closure(method=nil)
     raise ArgumentError.new("Missing both a method argument and a block") if method.nil? and not block_given?
     # If there is a method argument, then the transitive closure is based on that method.

data/lib/jinx/helpers/visitor.rb

@@ -56,26 +56,15 @@ module Jinx
   #   Jinx::Visitor.new { |node| node.children }.to_enum(parent).detect { |node| node.value == 2 }
   class Visitor
   
-    attr_reader :options, :visited, :lineage, :cycles
+    attr_reader :options, :visited, :lineage
   
     # Creates a new Visitor which traverses the child objects returned by the navigator block.
     # The navigator block takes a parent node argument and returns an enumerator on the children
-    # to visit.
+    # to visit. The options argument is described in {Options.get}.
     #
-    # The options is a _symbol_, _symbol_ => _value_ hash or nil. A _symbol_ argument is the same
-    # as +{+_symbol_ +=> true}+. Supported options include the following:
-    # * +:depth_first+: +true+, +false+ or a Proc. If the value is a Proc, then
-    #   value determines whether a child is visited depth-first. See the {#visit} method for more
-    #   information.
-    #
-    # If the :operator option is set, then the visit operator block is called when a node is visited.
-    # The operator block argument is the visited node.
-    #
-    # @param [Symbol, {Symbol => Object}] opts the visit options. A symbol argument is the same
-    #   as symbol => true
-    # @option opts [String] :depth_first depth-first traversal
-    # @option opts [Proc] :operator the operator applied to each visited node
-    # @option opts [String] :prune_cycle flag indicating whether to exclude cycles to the root in a visit
+    # @param [Symbol, {Symbol => Object}] opts the visit options
+    # @option opts [Boolean] :depth_first depth-first traversal
+    # @option opts [Boolean] :prune_cycle flag indicating whether to exclude cycles in a visit
     # @option opts [Boolean] :verbose print navigation log messages
     # @yield [parent] returns an enumerator on the children to visit
     # @yieldparam parent the current node
@@ -86,7 +75,6 @@ module Jinx
       @depth_first_flag = @options[:depth_first]
       @prune_cycle_flag = @options[:prune_cycle]
       @lineage = []
-      @cycles = []
       @visited = {}
       @verbose = Options.get(:verbose, opts, false)
       @exclude = Set.new
@@ -197,7 +185,7 @@ module Jinx
     # @raise [ArgumentError] if a block is not given to this method
     def filter
       raise ArgumentError.new("A filter block is not given to the visitor filter method") unless block_given?
-      Visitor.new(@options) { |node| yield(node, node_children(node)) }
+      self.class.new(@options) { |node| yield(node, node_children(node)) }
     end
   
     protected
@@ -208,8 +196,6 @@ module Jinx
       @lineage.clear
       # if the visited hash is not shared, then clear it
       @visited.clear unless @options.has_key?(:visited)
-      # clear the cycles
-      @cycles.clear
     end
   
     # Returns the children to visit for the given node.
@@ -238,37 +224,42 @@ module Jinx
       result
     end
     
+    # Returns the nodes which occur within a cycle, excluding the cycle entry point.
+    #
     # @example
-    #   visitor.visit(a)
-    #   visit.to_enum #=> [a, b, c, u, v, x, y, z]
-    #   visit.cycles #=> [[a, b, u, x, a], [c, z, c]]
-    #   visit.cyclic_nodes #=> [b, u, x, c, z]
-    # @return [Array] the non-root nodes in visit cycles
+    #   graph.paths #=> a -> b -> a, a -> c -> d -> c
+    #   Visitor.new(graph, &navigator).cyclic_nodes(a) #=> [b, d]
+    # @param root the node to visit
+    # @return [Array] the nodes within visit cycles
     def cyclic_nodes(root)
       copts = @options.reject { |k, v| k == :prune_cycle }
-      cycler = Visitor.new(copts, &@navigator)
+      cyclic = Set.new
+      cycler = Visitor.new(copts) do |parent|
+        children = @navigator.call(parent)
+        # Look for a cycle back to the child.
+        children.each do |child|
+          index = cycler.lineage.index(child)
+          if index then
+            # The child is also a parent: add the nodes between
+            # the two occurrences of the child in the lineage.
+            cyclic.merge!(cycler.lineage[(index + 1)..-1])
+          end
+        end
+        children
+      end
       cycler.visit(root)
-      cyclic = cycler.cycles.flatten.uniq
-      cyclic.delete(root)
       cyclic
-    end
+    end    
   
     def visit_recursive(node, &operator)
-      # bail if no node or the node is specifically excluded
+      # Bail if no node or the node is specifically excluded.
       return if node.nil? or @exclude.include?(node)
-      # return the visited value if the node has already been visited
-      if @visited.has_key?(node) then
-        #capture a cycle
-        index = @lineage.index(node)
-        if index then
-          cycle = @lineage[index..-1] << node
-          @cycles << cycle
-        end
-        return @visited[node]
-      end
-      # return nil if the node has not been visited but has been navigated in a depth-first visit
+      # Return the visited value if the node has already been visited.
+      return @visited[node] if @visited.has_key?(node)
+      # Return nil if the node has not been visited but has been navigated in a
+      # depth-first visit.
       return if @lineage.include?(node)
-      # all systems go: visit the node graph
+      # All systems go: visit the node subgraph.
       visit_node_and_children(node, &operator)
     end
   

data/lib/jinx/import/java.rb

@@ -201,24 +201,49 @@ module Java
   NAME_SPLITTER_REGEX = /^([\w.]+)\.(\w+)$/
 end
 
-class Class
-  # Returns whether this is a Java wrapper class.
+class Module
+  # Returns whether this is a Ruby wrapper for a Java class or interface.
   def java_class?
-    method_defined?(:java_class)
+    respond_to?(:java_class)
   end
 
-  # Returns the Ruby class for the given class, as follows:
-  # * If the given class is already a Ruby class, then return the class.
-  # * If the class argument is a Java class or a Java class name, then
-  #   the Ruby class is the JRuby wrapper for the Java class.
+  # Returns the Ruby module for the given argument, as follows:
+  # * If the argument is a primitive Java type, then return the corresponding
+  #   JRuby wrapper.
+  # * If the argument is a Ruby module, then return that module.
+  # * If the argument is an unwrapped Java class or interface,
+  #   then return the JRuby wrapper for the class string.
+  # * If the argument is a String, then return the JRuby wrapper for the
+  #   Java class designated by that String.
   #
-  # @param [Class, String] class_or_name the class or class name
-  # @return [Class] the corresponding Ruby class
-  def self.to_ruby(class_or_name)
-    case class_or_name
-      when Class then class_or_name
-      when String then eval to_ruby_name(class_or_name)
-      else to_ruby(class_or_name.name)
+  # @example
+  #   Java.to_ruby(Java::java.lang.Boolean) #=> Java::JavaLang::Boolean
+  #   Java.to_ruby(Java::boolean) #=> Java::JavaLang::Boolean
+  #   Java.to_ruby('boolean') #=> Java::JavaLang::Boolean
+  #
+  # @param [Module, String] mod the Ruby module or unwrapped Java class, interface or name
+  # @return [Module] the corresponding Ruby class
+  def self.to_ruby(mod)
+    if mod.respond_to?(:java_class) then
+      # A primitive Java type has an empty name and non-capitalized java_class name.
+      jname = mod.name.blank? ? mod.java_class.name : mod.name
+      if jname.blank? then
+        raise ArgumentError.new("Cannot convert the anonymous Java class #{mod} to a JRuby class")
+      end
+      if jname =~ /^[a-z]+$/ then
+        # The effective Java type is the Java wrapper class.
+        to_ruby('java.lang.' + jname.capitalize)
+      elsif Module === mod then
+        mod
+      else
+        to_ruby(jname)
+      end
+    elsif Module === mod then
+      mod
+    elsif String === mod then 
+      eval "Java::#{mod}"
+    else
+      raise ArgumentError.new("Cannot convert a #{mod.class} to a JRuby module")
     end
   end
 
@@ -242,7 +267,7 @@ class Class
   # If the hierarchy flag is set to +false+, then only this class's properties
   # will be introspected.
   def property_descriptors(hierarchy=true)
-    return Array::EMPTY_ARRAY  unless java_class?
+    return Array::EMPTY_ARRAY unless java_class?
     info = hierarchy ? Java::JavaBeans::Introspector.getBeanInfo(java_class) : Java::JavaBeans::Introspector.getBeanInfo(java_class, java_class.superclass)
     info.propertyDescriptors.select { |pd| pd.write_method and property_read_method(pd) }
   end
@@ -314,18 +339,6 @@ class Class
   private
   
   OBJ_INST_MTHDS = Object.instance_methods
-  
-  # @param [String] jname the fully-qualified Java class or interface name
-  # @return [String] the JRuby class or module name
-  # @example
-  #   Java.to_ruby_class_name('com.test.Sample') #=> Java::ComTest::Sample
-  def self.to_ruby_name(jname)
-    path = jname.split('.')
-    return "Java::#{jname}" if path.size == 1
-    cname = path[-1]
-    pkg = path[0...-1].map { |s| s.capitalize_first }.join
-    "Java::#{pkg}::#{cname}"
-  end
 end
 
 class Array

data/lib/jinx/importer.rb

@@ -25,6 +25,20 @@ module Jinx
       # introspected when they are referenced.
     end
     
+    # Returns whether the given Java class or interface is imported into this
+    # domain module. This method imports the class or interface on demand.
+    #
+    # @param [Module] the class to check
+    # @return [Boolean] whether the class or interface is imported into this
+    #   domain module
+    def contains?(klass)
+      # Import a domain class on demand by referencing the class base name in the context
+      # of this module. If the class name can be resolved, then also check that it
+      # was introspected. Primitive classes like String can be resolved, but are not
+      # introspected. Domain classes are introspected when the name is resolved.
+      (!!const_get(klass.name.demodulize) rescue false) and @introspected.include?(klass)
+    end
+    
     # Imports a Java class constant on demand. If the class does not already
     # include this module's mixin, then the mixin is included in the class.
     #
@@ -51,14 +65,16 @@ module Jinx
           nil
         end
       end
-      if klass.nil? then
+      if klass then
+        logger.debug { "Added #{klass} to the #{self} module." }
+      else
         # Not a Java class; print a log message and pass along the error.
         logger.debug { "#{sym} is not recognized as a #{self} Java class." }
         super
       end
       
       # Introspect the Java class meta-data, if necessary.
-      unless @introspected.include?(klass) then
+      unless introspected?(klass) then
         add_metadata(klass)
         # Print the class meta-data.
         logger.info(klass.pp_s)
@@ -103,23 +119,30 @@ module Jinx
       end
       # The introspected classes.
       @introspected = Set.new
+      # The name => file hash for file definitions that are not in the packages.
+      @unresolved_defs = {}
     end
     
-    # Sets the package names. The default package conforms to the JRuby convention for
-    # mapping a package name to a module name, e.g. the +MyApp::Domain+ default package
+    # If the given *names* argument is empty, then returns the package names.
+    # Otherwise, sets the package names. The default package conforms to the JRuby convention
+    # for mapping a package name to a module name, e.g. the +MyApp::Domain+ default package
     # is +myapp.domain+. Clients set the package if it differs from the default.
     #
     # @param [<String>] name the package names
     def packages(*names)
-      @packages = names
+      names.empty? ? @packages : @packages = names
     end
     
     # Alias for the common case of a single package.
     alias :package :packages
-    
+
+    # If the given *directories* argument is empty, then return the definition directories.
+    # Otherwise, set the definitions.
+    #
     # @param [<String>] directories the Ruby class definitions directories
+    # @return [<String>] the definition directories
     def definitions(*directories)
-      @definitions = directories
+      directories.empty? ? @definitions : @definitions = directories
     end
     
     def load_definitions
@@ -140,17 +163,26 @@ module Jinx
       srcs = sources(dir)
       # Introspect and load the classes in reverse class order, i.e. superclass before subclass.
       klasses = srcs.keys.transitive_closure { |k| [k.superclass] }.select { |k| srcs[k] }.reverse
-      # Introspect the classes if necessary.
-      klasses.each { |klass| add_metadata(klass) unless @introspected.include?(klass) }
+      # Introspect the classes as necessary.
+      klasses.each { |klass| add_metadata(klass) unless introspected?(klass) }
       # Load the classes.
       klasses.each do |klass|
         file = srcs[klass]
-        logger.debug { "Loading #{klass.qp} definition #{file}..." }
-        require file
-        logger.debug { "Loaded #{klass.qp} definition #{file}." }
+        load_definition(klass, file)
       end
       logger.debug { "Loaded the class definitions in #{dir}." }
     end
+    
+    def load_definition(klass, file)
+      logger.debug { "Loading the #{klass.qp} definition #{file}..." }
+      begin
+        require file
+      rescue Exception
+        logger.error("Could not load the #{klass} definition #{file} - " + $!)
+        raise
+      end
+      logger.debug { "Loaded the #{klass.qp} definition #{file}." }
+    end
 
     # @param [String] dir the source directory
     # @return [{Class => String}] the source class => file hash
@@ -161,7 +193,12 @@ module Jinx
       # Ignore files which do not resolve to a class.
       files.to_compact_hash do |file|
         name = File.basename(file, ".rb").camelize
-        resolve_class(name)
+        klass = resolve_class(name)
+        if klass.nil? then
+          logger.debug { "The class definition file #{file} does not correspond to a class in the standard #{qp} packages." }
+          @unresolved_defs[name] = file
+        end
+        klass
       end.invert
     end
     
@@ -196,46 +233,62 @@ module Jinx
       # into this method when the references are introspected below.
       @introspected << klass
       # Add the superclass meta-data if necessary.
-      if Class === klass then
-        sc = klass.superclass
-        unless @introspected.include?(sc) or sc == Java::java.lang.Object then
-          add_metadata(sc)
-        end
-      end
-      # Include this resource module into the class.
+      add_superclass_metadata(klass)
+      # Include this resource module into the class, unless this has already occurred.
       unless klass < self then
         m = self
         klass.class_eval { include m }
       end
+      # Import the class into this resource module, unless this has already occurred.
+      name = klass.name.demodulize
+      unless const_defined?(name) then
+        java_import(klass.java_class.name)
+      end
       # Add introspection capability to the class.
       md_mod = @metadata_module || Metadata
-      
       logger.debug { "Extending #{self}::#{klass.qp} with #{md_mod.name}..." }
       klass.extend(md_mod)
-      
-      # Introspect the Java properties.
-      introspect(klass)
-      klass.add_attribute_value_initializer if Class === klass
       # Set the class domain module.
       klass.domain_module = self
+      # Introspect the Java properties.
+      klass.introspect
+      # Add the {attribute => value} initializer.
+      klass.add_attribute_value_initializer if Class === klass
       # Add referenced domain class metadata as necessary.
-      mod = klass.parent_module
       klass.each_property do |prop|
         ref = prop.type
         if ref.nil? then raise MetadataError.new("#{self} #{prop} domain type is unknown.") end
-        unless @introspected.include?(ref) or ref.parent_module != mod then
-          logger.debug { "Introspecting #{qp} #{prop} reference #{ref.qp}..." }
+        if introspectible?(ref) then
+          logger.debug { "Introspecting the #{klass.qp} #{prop} reference type #{ref.qp}..." }
           add_metadata(ref)
         end
       end
+      # If the class has a definition file but does not resolve to a standard package, then
+      # load it now based on the demodulized class name match.
+      file = @unresolved_defs[name]
+      load_definition(klass, file) if file
+      
       logger.debug("#{self}::#{klass.qp} metadata added.")
     end
     
-    # Introspects the given class.
-    #
-    # @param [Class] the domain class to introspect
-    def introspect(klass)
-      klass.introspect
+    def add_superclass_metadata(klass)
+      if Class === klass then
+        sc = klass.superclass
+        add_metadata(sc) unless introspected?(sc) or sc == Java::java.lang.Object
+      end
+    end
+    
+    # @param [Class] the class to check
+    # @return [Boolean] whether the class is an introspected {Resource} class
+    def introspected?(klass)
+       klass < Resource and klass.introspected?
+    end
+                               
+    # @param [Class] klass the class to check                          
+    # @return [Boolean] whether the given class has a Java package among this module's
+    #  {#packages} and has not yet been introspected
+    def introspectible?(klass)
+      not introspected?(klass) and Class === klass and @packages.include?(klass.java_class.package.name)
     end
   end
 end