javaclass 0.0.3 → 0.0.4

data/lib/javaclass/classfile/references.rb

@@ -1,43 +1,45 @@
 require 'javaclass/classfile/constant_pool'
 
 module JavaClass
-  module ClassFile 
-    
+  module ClassFile
+
     # Container class for list of all classes, methods and fields referenced by this class.
     # This information is derived from the constant pool, no analysis.
     # Author::   Peter Kofler
     class References
-      
-      # Create a references container with the constant _pool_ and skip references to index _classidx_ which is the host class itself.  
+
+      # Create a references container with the constant _pool_ and skip references to index _classidx_ which is the host class itself.
       def initialize(pool, classidx)
         @constant_pool = pool
         @class_idx = classidx
       end
-      
-      # Return the constants referring to fields (Constants::ConstantField). 
-      # If _includeown_ is +true+ then fields of this class are returned also. 
+
+      # Return the constants referring to fields (Constants::ConstantField).
+      # If _includeown_ is +true+ then fields of this class are returned also.
       def referenced_fields(includeown=false)
-        @constant_pool.find(ConstantPool::FIELD_TAG).find_all do |field| 
+        @constant_pool.find(ConstantPool::FIELD_TAG).find_all do |field|
           includeown || field.class_index != @class_idx
         end
       end
-      
-      # Return the constants referring to methods (Constants::ConstantMethod) in classes or interfaces. 
-      # If _includeown_ is +true+ then methods of this class are returned also. 
+
+      # Return the constants referring to methods (Constants::ConstantMethod) in classes or interfaces.
+      # If _includeown_ is +true+ then methods of this class are returned also.
       def referenced_methods(includeown=false)
-        @constant_pool.find(ConstantPool::METHOD_TAG, ConstantPool::INTERFACE_METHOD_TAG).find_all do |method| 
-          includeown || method.class_index != @class_idx 
+        @constant_pool.find(ConstantPool::METHOD_TAG, ConstantPool::INTERFACE_METHOD_TAG).find_all do |method|
+          includeown || method.class_index != @class_idx
         end
       end
-      
-      # Return the list of all constants containing class names of all used classes.
+
+      # Return the list of all constant pool constantss containing class names of all used classes.
+      # Returns a list of ConstantClass. 
       def used_classes
-        @constant_pool.find(ConstantPool::CLASS_TAG).find_all do |cl| 
-          cl.class_name != @constant_pool[@class_idx].to_s 
+        my_class_name = @constant_pool[@class_idx].class_name
+        @constant_pool.find(ConstantPool::CLASS_TAG).find_all do |cl|
+          cl.class_name != my_class_name 
         end
       end
-      
+
     end
-    
+
   end
 end

data/lib/javaclass/classlist/class_entry.rb

@@ -1,20 +1,19 @@
 require 'javaclass/java_name'
 
 module JavaClass
-  module ClassList # :nodoc:
-    
-    # An entry in the list. A ClassEntry belongs to a PackageEntry and has a list ov versions it exists in.
+  module ClassList
+
+    # An entry in the list. A ClassEntry belongs to a PackageEntry and has a list of versions it exists in.
     # Author::          Peter Kofler
     class ClassEntry
-      
+
       # Return the short (simple) name of this class.
       attr_reader :name
       attr_reader :full_name
       # Return the list of versions this class exists.
       attr_reader :version
-      
-      # Create a new entry. _parent_ must provide a +version+ field to compare against. _vers_ is the 
-      # base version of this class. 
+
+      # Create a new entry. _parent_ must provide a +version+ field to compare against. _vers_ is the base version of this class.
       def initialize(parent, full_name, is_public, vers)
         @parent = parent
         @full_name = full_name.to_javaname.to_classname
@@ -22,68 +21,68 @@ module JavaClass
         @is_public = is_public
         @version = [vers]
       end
-      
+
       def public?
         @is_public
       end
-      
+
       # Update the _version_ this class also exists in.
       def update(version, is_public=@is_public)
         raise "update class #{@name} is older than its last version: latest version=#{@version.last}, new version=#{version}" if version <= @version.last
         # check for holes in versions
         if version > @version.last+1
-          warn "#{@full_name} last in version #{@version.last}, not in #{@version.last+1}, but again in #{version}"        
+          warn "#{@full_name} last in version #{@version.last}, not in #{@version.last+1}, but again in #{version}"
         end
-        @version << version 
-        
+        @version << version
+
         if !is_public && @is_public
           warn "#{@full_name} changed from public to package in version #{version}"
           @is_public = is_public
           @version = [version] # skip older versions
         elsif is_public && ! @is_public
-          info "#{@full_name} changed from package to public in version #{version}"
+          puts "#{@full_name} changed from package to public in version #{version}"
           @is_public = is_public
           @version = [version] # skip older versions
         end
       end
-      
+
       # Sorts by simple +name+ inside the package.
       def <=>(other)
         @name.casecmp other.name
       end
-      
+
       def to_s
         @full_name
       end
-      
-      # Return a string containing the full qualified name together with first and last version
-      # of this class. Ignore package versions, but obey _minversion_ and _maxversion_ .
+
+      # Return a string containing the full qualified name together with first and last version of this class. Ignore package versions, but
+      # obey _minversion_ and _maxversion_ .
       # Print all versions, first to last, but skip <code>first<=minversion</code> and <code>last>=maxversion</code>.
       def to_full_qualified_s(minversion, maxversion)
         format_version(@full_name, minversion, maxversion)
       end
-      
+
       # Return a string containing the simple name and the version, if it is different from the package version.
       def to_package_shortcut_s
         vp = @parent.version
         format_version("   #{@name}", vp.first, vp.last)
       end
-      
+
       private
-      
+
       def format_version(start, minversion, maxversion)
         # this class has a set of versions where it exists
         # the parent has a set of versions where it exists, contains class versions
         is_newer = @version.first > minversion
         is_outdated = @version.last < maxversion
-        line = start + 
-          " [#{ is_newer || (!@is_public && @version.first>0) ? @version.first.to_s : ''}" +
-          "#{is_outdated ? '-' + @version.last.to_s : ''}" +
-          "#{!@is_public ? 'p' : '' }]" +
-          " - \n"
+        line = start +
+        " [#{ is_newer || (!@is_public && @version.first>0) ? @version.first.to_s : ''}" +
+        "#{is_outdated ? '-' + @version.last.to_s : ''}" +
+        "#{!@is_public ? 'p' : '' }]" +
+        " - \n"
         line.sub(/\[-0/, "[0-0").sub(/(\d)-\1/, "only \\1").sub(/ \[\]/, '')
       end
     end
-    
+
   end
 end

data/lib/javaclass/classlist/jar_searcher.rb

@@ -1,30 +1,40 @@
-require 'javaclass/classpath/composite_classpath'
+require 'javaclass/classpath/any_classpath'
 require 'javaclass/classfile/java_class_header'
 
 module JavaClass
-  module ClassList # :nodoc:
-    
-    # Search in zip or jar files for Java class files, check for package access or inner classes and
-    # call back a list of all these.
+
+  # The module ClassList is for separating namespaces. It contains the logic 
+  # to create a list of all classes of all JDK versions. The main logic is
+  # performed in ClassList::JarSearcher, which creates the ClassList::List. 
+  # It uses a 
+  # Classpath::CompositeClasspath to find all classes and ClassFile::JavaClassHeader 
+  # to read the class information from. The generated list contains packages 
+  # and these packages contain the names of classes, their accessibility 
+  # and the versions they were added (or removed) from JDK. ClassList is an 
+  # "application" using the JavaClass infrastructure. For a full example see
+  # {how to generate lists of JDK classes}[link:/files/lib/generated/examples/generate_class_lists_txt.html].
+  # Author::          Peter Kofler
+  module ClassList 
+
+    # Search in zip or JAR files for Java class files, check for package access or inner classes and call back a list of all these.
     # Author::          Peter Kofler
     class JarSearcher
-      
+
       attr_accessor :skip_inner_classes
       attr_accessor :skip_package_classes
-      
+
       # Create a new searcher.
       def initialize
         @skip_inner_classes = true
         @skip_package_classes = false
         @package_filters = []
       end
-      
-      # The given _filters_ will be dropped during searching.
-      # _filters_ contain the beginning of package paths, i.e. <code>com/sun/</code>.
+
+      # The given _filters_ will be dropped during searching. _filters_ contain the beginning of package paths, i.e. <code>com/sun/</code>.
       def filters=(filters)
         @package_filters = filters.collect{ |f| /^#{f}/ }
       end
-      
+
       # Return the list of classnames of this list of _classes_ .
       # Skips inner classes if +skip_inner_classes+ is true.
       # Skips classes that are in the filtered packages.
@@ -33,37 +43,36 @@ module JavaClass
           !(@skip_inner_classes && name =~ /\$/) && (@package_filters.find { |filter| name =~ filter } == nil)
         end
       end
-      
-      # Return true if the _classfile_ in the given _classpath_ is public. This is expensive because
-      # the jarfile is opened and the _classfile_ is extracted and read.
+
+      # Return true if the _classfile_ in the given _classpath_ is public. This is expensive because the JAR file is opened and the
+      # _classfile_ is extracted and read.
       def public?(classpath, classfile)
         begin
           header = ClassFile::JavaClassHeader.new(classpath.load_binary(classfile))
-        rescue
-          puts "error #{$1} for class #{classfile} on #{classpath.to_s}"
-          raise
+        rescue JavaClass::ClassFile::ClassFormatError => ex
+          ex.add_classname(classfile, classpath.to_s)
+          raise ex
         end
-        raise "invalid java class #{classfile}" unless header.magic.valid?
+        header.magic.check("invalid java class #{classfile}")
         header.access_flags.accessible?
       end
-      
-      # Compile the class list for the given _version_ of Java. This searches the _path_ for zips and jars
+
+      # Compile the class list for the given _version_ of Java. This searches the _path_ for zips and JARs
       # and adds them to the given _list_ of found classes. _version_ is a number >= 0, e.g. 2 for JDK 1.2.
       # _list_ must provide a <code>add_class(entry, is_public, version)</code> method.
       def compile_list(version, path, list)
-        cpe = JavaClass::Classpath::CompositeClasspath.new
-        cpe.find_jars(path)
+        cpe = Classpath::AnyClasspath.new(path)
         filter_classes(cpe.names).each do |entry|
           is_public = public?(cpe, entry)
           next if @skip_package_classes && !is_public
           list.add_class(entry, is_public, version) if list
           yield(entry, is_public, version) if block_given?
         end
-        
+
         list
       end
-      
+
     end
-    
+
   end
 end

data/lib/javaclass/classlist/list.rb

@@ -2,31 +2,31 @@ require 'javaclass/java_name'
 require 'javaclass/classlist/package_entry'
 
 module JavaClass
-  module ClassList # :nodoc:
-    
-    # Classes to form a list of JDK classes to find classes which have been added in new releases.
-    # The list of classes. It list contains packages.
+  module ClassList
+
+    # Classes to form a list of JDK classes to find classes which have been 
+    # added in new releases. This is the list containing packages (PackageEntry).
     # Author::          Peter Kofler
     class List
-      
+
       def initialize
-        @packages = {}
+        @packages = Hash.new # package_name (String) => PackageEntry
       end
-      
-      # Add a _fileentry_ to the list. The _fileentry_ is the file name of the class in the jar file. _version_ 
+
+      # Add a _fileentry_ to the list. The _fileentry_ is the file name of the class in the JAR file. _version_
       # is the version of the JDK scanned and is used if the class is new.
       def add_class(fileentry, is_public, version)
         class_name = fileentry.to_javaname.to_classname
         package_name = class_name.package
         @packages[package_name] = PackageEntry.new(package_name, version) unless @packages.has_key?(package_name)
-        @packages[package_name].add_class(class_name, is_public, version)
+        @packages[package_name].add_class(class_name.full_name, is_public, version)
       end
-      
+
       # Parse a _line_ from a <code>fullClassList</code> and fill the list again. _maxversion_ is the maximum
       # max version from the list, i.e. the highest possible value, so we can continue to use it.
       def parse_line(line, maxversion)
         class_name, versions = line.scan(/^([^\s]+)\s(?:\[(.*)\]\s)?-\s*$/)[0]
-        
+
         # no [], so we have it from always and it is public
         first_vers = 0
         last_vers = maxversion
@@ -35,7 +35,7 @@ module JavaClass
           # extract package access and drop it
           is_public = (versions !~ /p/)
           versions = versions.gsub(/p/, '')
-          
+
           # \d, \d-\d, only \d, -\d, oder leer
           if versions =~ /^(\d)$/
             first_vers = $1.to_i
@@ -51,54 +51,54 @@ module JavaClass
             raise "can't match version number #{versions} in line #{line.chomp}" unless versions == ''
           end
         end
-        
-        first_vers.upto(last_vers) do |v| 
-          add_class(class_name, is_public, v) 
+
+        first_vers.upto(last_vers) do |v|
+          add_class(class_name, is_public, v)
         end
       rescue
         raise "#{$!} in line #{line.chomp}: class_name=#{class_name}, versions=#{versions}, first_vers=#{first_vers}, last_vers=#{last_vers}, is_public=#{is_public}"
       end
-      
+
       def packages
         @packages.values.sort
       end
-      
+
       # Return the version list of all packages.
       def version
         packages.collect { |p| p.version }.flatten.uniq.sort
       end
-      
+
       # Return the first and last version of this list.
       def first_last_versions
         v = version
         [v.first, v.last]
       end
-      
+
       def to_s
         packages.collect { |p| p.to_s }.join("\n")
       end
-      
+
       # Return the number of classes in this list.
       def size
         @packages.values.inject(0) {|sum, p| sum + p.size }
       end
-      
+
       # The access list is the raw list of all package access classes for one version. It was used to differ
       # normal classes from hidden classes and was saved in <code>doc/AccessLists/*_p.txt</code>.
-      # This works only if JarSearcher was used with +skip_package_classes+ set to false (default).
-      # If there are more versions loaded, then only the last version is printed. So we get consecutive lists 
+      # This works only if JarSearcher was used with <i>skip_package_classes</i> set to false (default).
+      # If there are more versions loaded, then only the last version is printed. So we get consecutive lists
       # of new package access classes with every JDK version.
       def old_access_list
         v = first_last_versions
-        packages.collect { |pkg| 
+        packages.collect { |pkg|
           pkg.classes.find_all { |c| !c.public? && c.version == [v[1]]}.collect { |c| c.to_full_qualified_s(v[0], v[1]) }
         }.flatten.sort{|a,b| a.casecmp b }
       end
-      
-      # The class list is the raw list of all classes for one version without version or package access 
+
+      # The class list is the raw list of all classes for one version without version or package access
       # descriptors. It was used to find differences and was saved in <code>doc/ClassLists/*_classes.txt</code>.
       # This usually was done with JarSearcher set +skip_package_classes+ to false.
-      # If a block is given it is invoked with ClassEntry and should return if to add the class or not. 
+      # If a block is given it is invoked with ClassEntry and should return if to add the class or not.
       def plain_class_list
         packages.collect { |pkg|
           cls = pkg.classes
@@ -108,19 +108,19 @@ module JavaClass
           cls.collect { |c| c.full_name + "\n" }
         }.flatten.sort{|a,b| a.casecmp b }
       end
-      
+
       # Create a full class list with version numbers and different versions to compare.
       # This was the base for classlists and was saved in <code>doc/fullClassList1x.txt</code>.
       # This usually was done with JarSearcher set +skip_package_classes+ to false and
       # contained different classlists merged together.
       def full_class_list
         v = first_last_versions
-        packages.collect { |pkg| 
+        packages.collect { |pkg|
           pkg.classes.collect { |c| c.to_full_qualified_s(v[0], v[1]) }
         }.flatten.sort{|a,b| a.casecmp b }
       end
-      
+
     end
-    
+
   end
 end

data/lib/javaclass/classlist/package_entry.rb

@@ -1,34 +1,35 @@
 require 'javaclass/classlist/class_entry'
 
 module JavaClass
-  module ClassList # :nodoc:
-    
-    # A package in the List.
+  module ClassList
+
+    # A package in the List. A package contains ClassEntry.
     # Author::          Peter Kofler
     class PackageEntry # ZenTest FULL to find method <=>
-      
+
       attr_reader :name
       # Return the list of versions this package exists. This is the sum of all versions of all classes in the package.
       attr_reader :version
-      
+
       # Create a new package with name _name_ and first version _vers_ which is the version of the first class in the package.
       def initialize(name, vers=0)
         @name = name
         @version = [vers]
-        @classes = {}
+        @classes = Hash.new # class_name (most likely String) => ClassEntry
       end
-      
+
       def add_class(class_name, is_public, version)
         @version << version unless @version.include? version
         @version = @version.sort
-        
+
         unless @classes.has_key?(class_name)
           @classes[class_name] = ClassEntry.new(self, class_name, is_public, version)
+          # class_name does not need to be frozen because it's not read from the keys 
         else
           @classes[class_name].update(version, is_public)
         end
       end
-      
+
       # Sorting in packages is: <code>java.lang</code>, other <code>java.*</code>, <code>javax.*</code> and then others.
       def <=>(other)
         if @name =~ /^java\.lang$/ and other.name !~ /^java\.lang$/
@@ -47,41 +48,41 @@ module JavaClass
           @name <=> other.name
         end
       end
-      
+
       # Return the classes in this package.
       def classes
         @classes.values.sort
       end
-      
+
       # Return the number of classes in this package.
       def size
         @classes.size
       end
-      
+
       def to_s
         @name
       end
-      
-      # Special version of +to_s+ for package shortcut. A package needs _minversion_ and _maxversion_ to
-      # determine if the whole package was dropped. 
+
+      # Special version of +to_s+ for package shortcut. A package needs _minversion_ and _maxversion_ to determine if the whole package was
+      # dropped.
       def to_package_shortcut_s(minversion, maxversion)
-      "#{@name}#{format_version(minversion, maxversion)} - \n" + 
+        "#{@name}#{format_version(minversion, maxversion)} - \n" +
         classes.collect { |c| c.to_package_shortcut_s }.join
       end
-      
+
       private
-      
+
       def format_version(minversion, maxversion)
         is_newer = @version.first > minversion
         is_outdated = @version.last < maxversion
-        line = 
-          " [#{ is_newer  ? @version.first.to_s : ''}" +
-          "#{is_outdated ? '-' + @version.last.to_s : ''}" +
-          "]"
+        line =
+        " [#{ is_newer  ? @version.first.to_s : ''}" +
+        "#{is_outdated ? '-' + @version.last.to_s : ''}" +
+        "]"
         line.sub(/(\d)-\1/, "only \\1").sub(/ \[\]/, '')
       end
-      
+
     end
-    
+
   end
 end

data/lib/javaclass/classpath/any_classpath.rb

@@ -0,0 +1,48 @@
+require 'javaclass/classpath/composite_classpath'
+
+module JavaClass
+  module Classpath
+
+    # Classpath containing everything under a folder. This is for an unstructured 
+    # collection of JARs and class files.
+    # Author::   Peter Kofler
+    class AnyClasspath < CompositeClasspath
+
+      # Create a classpath with all classes found under this _folder_ wherever they are.
+      def initialize(folder)
+        super(File.join(folder, '*'))
+        find_jars(folder)
+        
+        # TODO Implement "find_classes_under(folder)" to find all class folders under this path. 
+        # Search for classes, open the first one, check its package, backtrack to its base folder, 
+        # add it to this classpath "add_file_name(sub_folders)", skip it in further analysis and continue.
+      end
+      
+      # Search the given _path_ recursively for zips or jars. Add all found jars to this classpath.
+      def find_jars(path)
+        if FileTest.file?(path) && path =~ /\.jar$|\.zip$/
+          add_file_name File.expand_path(path)
+          return
+        end
+        
+        current = Dir.getwd
+        begin
+          Dir.chdir File.expand_path(path)
+
+          Dir['*'].collect do |name|
+            if FileTest.directory?(name)
+              find_jars(name)
+            elsif name =~ /\.jar$|\.zip$/
+              add_file_name File.expand_path(name)
+            end
+          end
+
+        ensure
+          Dir.chdir current
+        end
+      end
+      
+    end
+
+  end
+end

data/lib/javaclass/classpath/class_not_found_error.rb

@@ -0,0 +1,20 @@
+module JavaClass
+  module Classpath
+
+    # An error in the classpath. The requested classfile could not be found.
+    # Author::   Peter Kofler
+    class ClassNotFoundError < IOError
+
+      attr_reader :classname
+      attr_reader :classpath
+
+      def initialize(classname, classpath=nil)
+        @classname = classname
+        @classpath = classpath
+        super("class #{@classname} not found in classpath #{@classpath}")
+      end
+      
+    end
+
+  end
+end

data/lib/javaclass/classpath/classpaths.txt

@@ -1,2 +1,2 @@
-* Java 1.1 Home classpath with lib/classes.zip
-* other classpath abstractions: - WARs and EARs contain JARs and a folder
+TODO other classpath abstractions: 
+* WARs and EARs contain JARs and a folder