javaclass 0.4.1 → 0.4.2

data/lib/generated/examples/find_referenced_modules.txt

@@ -0,0 +1,41 @@
+# Example usage of JavaClass::Classpath and JavaClass::Classpath::TrackingClasspath: 
+# Use the classes of one module and mark all their dependencies. Then find all modules 
+# which were not referenced. This list contains *potential* unused libraries (modules). 
+# Note that the libraries may still be used by reflection or internal from other libraries.
+# Author::          Peter Kofler
+# Copyright::       Copyright (c) 2009, Peter Kofler.
+# License::         {BSD License}[link:/files/license_txt.html]
+#
+# === Steps
+#  
+#  require 'javaclass/dsl/mixin'
+#  
+# 1) create a classpath of the main module(s) under test
+#  main_classpath = classpath("#{main_location};#{test_location}")
+#  puts "#{main_classpath.count} classes found in main classpath:"
+#  puts "  #{main_classpath.elements.join("\n  ")}"
+#  
+# 2) mix in JavaClass::Classpath::TrackingClasspath before creating any new classpaths
+#  require 'javaclass/classpath/tracking_classpath'
+#  
+# 3) create the (tracking) composite classpath of the given workspace
+#  cp = workspace(location)
+#  puts "#{cp.elements.size} classpaths found under the workspace #{location}"
+#  puts "  #{cp.elements.join("\n  ")}"
+#  puts "#{cp.count} classes found in classpaths"
+#  
+# 4) mark all their referenced types as accessed in the workspace
+#  puts 'mapping referenced classes... (can take several minutes)'
+#  cp.reset_access
+#  main_classpath.external_types.each { |clazz| cp.mark_accessed(clazz) }
+#  puts 'referenced classes mapped'
+#  
+# 5a) now find non accessed modules/libraries (i.e. classpath elements)
+#  unused = cp.elements.find_all { |clp| clp.jar? && clp.accessed == 0 }
+#  puts "\n#{unused.size} unused modules found:\n  #{unused.join("\n  ")}"
+#  
+# 5b) or print the list of classpath elements (e.g. JARs) with their access
+#  puts "\nlibrary (module path): number of accessed classes"
+#  puts cp.elements.map { |clp| [clp.to_s, clp.accessed] }.
+#                   sort { |a,b| a[1] <=> b[1] }.
+#                   map { |e| "  #{e[0]}: #{e[1]}" }

data/lib/generated/examples/find_unreferenced_classes.txt

@@ -0,0 +1,66 @@
+# Advanced example usage of JavaClass::Classpath::TrackingClasspath. Load all 
+# classes of an Eclipse workspace. Then mark all referenced classes. In the end 
+# report remaining classes as unreferenced. This lists *potential* unused classes. 
+# Note that the classes may still be used by reflection. Also this can be used to
+# find classes that have a certain number of references to them, e.g. only used once.
+# Author::          Peter Kofler
+# Copyright::       Copyright (c) 2009, Peter Kofler.
+# License::         {BSD License}[link:/files/license_txt.html]
+#
+# === Steps
+#  
+#  require 'javaclass/dsl/mixin'
+#  require 'javaclass/classpath/tracking_classpath'
+#  
+# speed up loading by skipping non source file classpaths
+#  Eclipse.skip_lib
+#  
+# 1) create the (tracking) composite classpath of the given workspace
+#  cp = workspace(location)
+#  puts "#{cp.elements.size} classpaths found under the workspace #{location}:"
+#  puts "  #{cp.elements.join("\n  ")}"
+#  
+# create a filter to limit all operations to the classes of two base packages
+#  filter = Proc.new { |clazz| clazz.same_or_subpackage_of?(package1) || 
+#                              clazz.same_or_subpackage_of?(package2) }
+#  
+# 2) load all classes in the given packages
+#  puts 'loading all *filtered* classes... (can take several minutes)'
+#  classes = cp.values(&filter)
+#  puts "#{classes.size} classes loaded from classpaths"
+#  
+# 3) mark all referenced types in the given packages as accessed
+#  cp.reset_access
+#  classes.map { |clazz| clazz.imported_types }.
+#          flatten.
+#          find_all(&filter).
+#          each { |classname| cp.mark_accessed(classname) }
+#  puts '*filtered* classes mapped'
+#  
+# 4) also mark all classes referenced from config files (e.g. hardcoded class names)
+#  hardcoded_classnames = scan_config_for_3rd_party_class_names(location).find_all(&filter)
+#  puts "#{hardcoded_classnames.size} classes references found in configs"
+#  hardcoded_classnames.each { |classname| cp.mark_accessed(classname) }
+#  puts 'hardcoded classes mapped'
+#  
+# 5) mark unit tests (all classes ending in Test) on the test projects (classpath elements ending in .test)
+#  test_projects = cp.elements.find_all { |cpe| cpe.to_s =~ /\.test\// }
+#  test_projects.each do |project|
+#    project.names { |classname| classname =~ /Test(?:Case|Suite|s)?\.class/ }.
+#            each { |classname| project.mark_accessed(classname) }
+#  end
+#  puts 'test classes mapped'
+#  
+# 6) find non accessed classes in specific packages and report them
+#  unused_classes = classes.find_all { |clazz| cp.accessed(clazz) == 0 }
+#  report = unused_classes.map { |clazz| "#{clazz.to_classname}" }
+#  puts "#{report.size} unused classes found:\n  #{report.join("\n  ")}"
+#  
+# 7) find only once accessed classes and report them
+#  once_used_classes = classes.find_all { |clazz| cp.accessed(clazz) == 1 }
+#  report = once_used_classes.map { |clazz| "#{clazz.to_classname}" }
+#  puts "#{report.size} once used classes found:\n  #{report.join("\n  ")}"
+#  
+#  twice_used_classes = classes.find_all { |clazz| cp.accessed(clazz) == 2 }
+#  report = twice_used_classes.map { |clazz| "#{clazz.to_classname}" }
+#  puts "#{report.size} twice used classes found:\n  #{report.join("\n  ")}"

data/lib/generated/examples/generate_class_lists.txt

@@ -0,0 +1,53 @@
+# Generate a JavaClass::ClassList, which contains all class 
+# names with version numbers when introduced. The list is created 
+# iterating all JDKs, opening the RT.jars and loading all classes.
+# Author::          Peter Kofler
+# Copyright::       Copyright (c) 2009, Peter Kofler.
+# License::         {BSD License}[link:/files/license_txt.html]
+#
+# === Usage
+#  
+#  require 'javaclass/classlist/jar_searcher'
+#  require 'javaclass/classpath/jar_classpath'
+#  require 'javaclass/classlist/list'
+#  
+# Struct to keep configuration what kind of JDK classes should be searched and added.
+#  JDK_CONFIG = Struct.new(:version, :label, :paths)
+#  
+# configuration for some JDKs
+#  JDKS = [ JDK_CONFIG.new(...), ... ]
+#  
+# 1) create a JavaClass::ClassList::JarSearcher
+#  JavaClass.unpack_jars!(:unpack)
+#  searcher = JavaClass::ClassList::JarSearcher.new
+#  searcher.skip_inner_classes = false
+#  searcher.skip_package_classes = true
+#  
+# 2) filter out unwanted classes, e.g. vendor classes
+#  searcher.filters = %w[sun/ sunw/ com/oracle/ com/sun/ netscape/ com/rsa/ 
+#           quicktime/ com/apple/mrj/macos/carbon/ org/jcp/xml/dsig/internal/
+#           oracle/jrockit/ jdk/internal/ jdk/nashorn/internal/
+#           jdk/dynalink/internal/ jdk/incubator/http.internal/ jdk/javadoc/internal/ jdk/tools/jlink/internal/ ]
+#  
+# 3) create a new JavaClass::ClassList::List to contain the classes
+#  list = JavaClass::ClassList::List.new
+#  
+#  
+# Work on all lists defined in +JDKS+, add to the list and write list files.
+#  JDKS.each do |conf|
+#    # 4) iterate JARs and compile a list
+#    conf.paths.each { |p| list = searcher.compile_list(conf.version, p, list) }
+#  
+#    # 5) save various kind of lists
+#    basename = "./ClassLists/jdk#{conf.label.gsub(/\./, '')}"
+#    # File.open("#{basename}_new_package_classes.txt", "w") { |f| f.print list.old_access_list.collect{|m| m.sub(/\s.*$/, '')} }
+#    # File.open("#{basename}_all_classes.txt", "w") { |f| f.print list.plain_class_list }
+#    File.open("#{basename}_all_packages.txt", "w") { |f| f.print list.to_s }
+#    File.open("#{basename}_all_public_classes.txt", "w") { |f| f.print list.plain_class_list { |c| c.public? }.join() }
+#    File.open("#{basename}_new_public_classes.txt", "w") { |f| f.print list.plain_class_list { |c| c.public? and c.version.first == conf.version }.join() }
+#  
+#    baseversion = conf.label.gsub(/\.|-.+$/, '')
+#    File.open("./fullClassList#{baseversion}.txt", "w") { |f| f.print list.full_class_list.join() }
+#  
+#    puts "processed #{conf.label}"
+#  end

data/lib/generated/examples/show_jar_api.txt

@@ -0,0 +1,64 @@
+# Generate a JavaClass::ClassList, which contains all class of a given
+# JAR in the local Maven repository. Use JavaClass::Classpath::MavenArtefact
+# to identify and (possibly download) the JAR under question.
+# Author::          Peter Kofler
+# Copyright::       Copyright (c) 2009, Peter Kofler.
+# License::         {BSD License}[link:/files/license_txt.html]
+#
+# === Usage
+#  
+#  require 'javaclass/classlist/jar_searcher'
+#  require 'javaclass/classpath/maven_artefact'
+#  require 'javaclass/classlist/list'
+#  
+# Define configuration for some Maven artefacts
+#  JARS = [ JavaClass::Classpath::MavenArtefact.new('commons-lang', 'commons-lang', '2.6'),, ... ]
+#  
+# For all artefacts listed in +JARS+, load classes and write list files.
+#  JARS.each do |artefact|
+#  
+# 1) create a new JavaClass::ClassList::List to contain the classes of this JAR
+#    list = JavaClass::ClassList::List.new
+#  
+# 2) create a JavaClass::ClassList::JarSearcher
+#    searcher = JavaClass::ClassList::JarSearcher.new
+#    searcher.skip_package_classes = true
+#  
+# 3) create the classpath of the artefact's JAR
+#    artefact.download_if_needed
+#    classpath = artefact.classpath
+#  
+# 4) scan the JAR and add classes to the list
+#    searcher.add_list_from_classpath(artefact.version, classpath, list)
+#  
+# 5) save the list to a file named "Commons Lang 2.6.txt" (after the artefact)
+#    File.open("#{artefact.title} #{artefact.version}.txt", "w") do |f|
+#      # print title
+#      f.print "*** #{artefact.title}\n"
+#  
+#      list.packages.each { |pkg|
+#        f.print "\n"
+#        # print package name
+#        f.print "* #{pkg.name}\n"
+#      
+#        # print class names
+#        pkg.classes.each { |c| f.print "   #{c.name}\n" }
+#      }
+#    end
+#  
+#    puts "processed #{artefact.name}"
+#  end
+#  
+# 6) the generated file looks like
+#  *** Commons Lang
+#
+#  * org.apache.commons.lang
+#     ArrayUtils
+#     BitField
+#     ...
+#
+#  * org.apache.commons.lang.builder
+#     CompareToBuilder
+#     EqualsBuilder
+#     HashCodeBuilder
+#     ...

data/lib/generated/examples/simple_usage.txt

@@ -0,0 +1,38 @@
+# Example of basic usage of JavaClass to load and inspect class files.
+# Author::          Peter Kofler
+# Copyright::       Copyright (c) 2009, Peter Kofler.       
+# License::         {BSD License}[link:/files/license_txt.html]
+#
+# === Usage
+#  
+# 1) require the basic module
+#  require 'javaclass'
+#  
+# 2a) load a class directly from the file system
+#  clazz = JavaClass.load_fs('./test/data/access_flags/AccessFlagsTestPublic.class')
+#  
+# 2b) or get a class from the system classpath which needs _JAVA_HOME_ to be set
+#  cp = JavaClass.environment_classpath
+#  puts cp.includes?('java/lang/String.class') # => 1 (true)
+#  
+# 2c) or look up the class from some JavaClass::Classpath by its Java qualified name
+#  cp = JavaClass.classpath('./test/data/access_flags')
+#  puts cp.includes?('AccessFlagsTestPublic')  # => 1 (true)
+#  clazz = JavaClass.load_cp('AccessFlagsTestPublic', cp)
+#  
+# 3) then retrieve low level information about the class
+#  puts clazz.version                          # => "50.0"
+#  puts clazz.constant_pool.items[1]           # => "packagename/AccessFlagsTestPublic"
+#  puts clazz.access_flags.public?             # => true
+#  puts clazz.access_flags.final?              # => false
+#  puts clazz.this_class                       # => "packagename/AccessFlagsTestPublic"
+#  puts clazz.super_class                      # => "java/lang/Object"
+#  puts clazz.super_class.to_classname         # => "java.lang.Object"
+#  puts clazz.references.referenced_methods[0] # => "java/lang/Object.<init>:()V"
+#  puts clazz.interfaces                       # => []
+#  
+# Returned class names are not just Strings, but JavaClass::JavaQualifiedName
+#  puts clazz.this_class.to_java_file          # => "packagename/AccessFlagsTestPublic.java"
+#  puts clazz.this_class.full_name             # => "packagename.AccessFlagsTestPublic"
+#  puts clazz.this_class.package               # => "packagename"
+#  puts clazz.this_class.simple_name           # => "AccessFlagsTestPublic"

data/lib/javaclass/classfile/access_flag_constants.rb

@@ -5,19 +5,46 @@ module JavaClass
     # Author::   Peter Kofler
     module AccessFlagsConstants
 
+      # field
+      # ACC_PUBLIC = 0x0001
+      ACC_PRIVATE = 0x0002
+      ACC_PROTECTED = 0x0004
+      # TODO How were Java 1.0's "private protected" fields? set up? (see old JVM spec)
+      ACC_STATIC = 0x0008
+      # ACC_FINAL = 0x0010
+      ACC_VOLATILE = 0x0040
+      ACC_TRANSIENT = 0x0080
+      # ACC_SYNTHETIC = 0x1000
+      # ACC_ENUM = 0x4000
+
+      # method
+      # ACC_PUBLIC = 0x0001
+      # ACC_PRIVATE = 0x0002
+      # ACC_PROTECTED = 0x0004
+      # ACC_STATIC = 0x0008
+      # ACC_FINAL = 0x0010
+      ACC_SYNCHRONIZED = 0x0020 
+      ACC_ACC_BRIDGE = 0x0040
+      ACC_VARARGS = 0x0080
+      ACC_NATIVE = 0x0100
+      # ACC_ABSTRACT = 0x0400
+      ACC_STRICT = 0x0800
+      # ACC_SYNTHETIC = 0x1000
+      
+      # class
       ACC_PUBLIC = 0x0001
       ACC_FINAL = 0x0010
       ACC_SUPER = 0x0020 # old invokespecial instruction semantics
       ACC_INTERFACE = 0x0200
       ACC_ABSTRACT = 0x0400
-      ACC_SYNTHETIC = 0x1000 # TODO Check what the synthetic flag means
+      ACC_SYNTHETIC = 0x1000 # may vary between different compilers
       ACC_ANNOTATION = 0x2000
       ACC_ENUM = 0x4000
-      # TODO How were Java 1.0's "private protected" fields? set up? (see old JVM spec)
-
-      # Bitmask for unknown/not supported flags.
-      ACC_OTHER = 0xffff ^ ACC_PUBLIC ^ ACC_FINAL ^ ACC_SUPER ^ ACC_INTERFACE ^ ACC_ABSTRACT ^ ACC_SYNTHETIC ^ ACC_ENUM ^ ACC_ANNOTATION
+      ACC_MODULE = 0x8000
 
+      ACC_IMPLICIT = 0x8000 # e.g. default constructor
+      ACC_MANDATED = 0x8000 # formal parameter implicit declared
+      
     end
 
   end

data/lib/javaclass/classfile/access_flags.rb

@@ -1,19 +1,18 @@
-require 'javaclass/string_ux'
 require 'javaclass/classfile/access_flag_constants'
 require 'javaclass/classfile/class_format_error'
 
 module JavaClass
   module ClassFile
 
-    # The access flags of a class or interface.
+    # The general JVM access flags.
     # Author::   Peter Kofler
     class AccessFlags
       include AccessFlagsConstants
 
       attr_reader :flags
       
-      def initialize(data, pos)
-        @flags = data.u2(pos)
+      def initialize(flags)
+        @flags = flags
         correct_flags
         assert_flags
       end
@@ -27,44 +26,64 @@ module JavaClass
       private :correct_flags
       
       def assert_flags
-        raise ClassFormatError, "inconsistent flags #{@flags} (abstract and final)" if abstract? && final?
-        raise ClassFormatError, "inconsistent flags #{@flags} (interface not abstract)" if interface? && !abstract?
-        raise ClassFormatError, "inconsistent flags #{@flags} (interface is final)" if interface? && final?
-        raise ClassFormatError, "inconsistent flags #{@flags} (annotation not interface)" if annotation? && !interface?
-        raise ClassFormatError, "inconsistent flags #{@flags} (other value #{@flags & ACC_OTHER})" if (@flags & ACC_OTHER) != 0
+        raise ClassFormatError, "inconsistent flags #{flags} (abstract and final)" if abstract? && final?
+        raise ClassFormatError, "inconsistent flags #{flags} (interface not abstract)" if interface? && !abstract?
+        raise ClassFormatError, "inconsistent flags #{flags} (interface is final)" if interface? && final?
+        raise ClassFormatError, "inconsistent flags #{flags} (annotation not interface)" if annotation? && !interface?
       end
       private :assert_flags
 
+      # Return +true+ if the bit _flag_ is set.
+      def is?(flag)
+        (@flags & flag) != 0
+      end
+      
       # Return +true+ if the class is public.
       def public?
-        (@flags & ACC_PUBLIC) != 0
+        is? ACC_PUBLIC
       end
       alias accessible? public?
 
-      def final?
-        (@flags & ACC_FINAL) != 0
+      def private?
+        is? ACC_PRIVATE
       end
 
+      def protected?
+        is? ACC_PROTECTED
+      end
+      
+      def static?
+        is? ACC_STATIC
+      end
+      
+      def final?
+        is? ACC_FINAL
+      end
+     
       def abstract?
-        (@flags & ACC_ABSTRACT) != 0
+        is? ACC_ABSTRACT
+      end
+      
+      def synthetic?
+        is? ACC_SYNTHETIC
       end
 
       def interface?
-        (@flags & ACC_INTERFACE) != 0
+        is? ACC_INTERFACE
       end
 
       def enum?
-        (@flags & ACC_ENUM) != 0
+        is? ACC_ENUM
       end
 
       def annotation?
-        (@flags & ACC_ANNOTATION) != 0
+        is? ACC_ANNOTATION
       end
 
-#      def inner?
-#        (@flags & ACC_INNER) != 0
-#      end
-
+      def module?
+        is? ACC_MODULE
+      end
+      
       # Return the hex word of the flag.
       def flags_hex
         format '%4.4X', @flags

data/lib/javaclass/classfile/attributes/attributes.rb

@@ -0,0 +1,134 @@
+module JavaClass
+  module ClassFile
+    module Attributes
+
+      # General container of the attributes.
+      # Author::   Peter Kofler
+      class Attributes
+
+        # Size of the whole attributes structure in bytes.
+        attr_reader :size
+
+        # Parse the attributes structure from the bytes _data_ beginning at position _start_.
+        def initialize(data, start, constant_pool)
+          creator = AttributesCreator.new(data, start, constant_pool)
+          creator.create!
+          @attributes = creator.attributes
+          @size = creator.size
+        end
+
+        # Find the attribute with the given _name_.
+        def with(name)
+          @attributes.find { |attr|  attr.name == name  }
+        end
+
+      end
+
+      class AttributesCreator # :nodoc:
+
+        attr_reader :attributes
+
+        def initialize(data, start, constant_pool)
+          @data = data
+          @start = start
+          @pos = start
+          @constant_pool = constant_pool
+        end
+
+        def size
+          @pos - @start
+        end
+
+        def create!
+          @attributes = []
+
+          count = @data.u2(@pos)
+          @pos += 2
+
+          (1..count).each do |i|
+            attribute_name_idx = @data.u2(@pos) 
+            @pos += 2
+            attribute_name = @constant_pool[attribute_name_idx].string
+
+            attribute_length = @data.u4(@pos)
+            @pos += 4
+            
+            if attribute_name == 'SourceFile'
+              @attributes << source_file(attribute_name)
+            elsif attribute_name == 'InnerClasses'
+              @attributes << inner_classes(attribute_name)
+            else # skip 
+              @pos += attribute_length 
+            end
+
+          end
+        end
+
+        def source_file(attribute_name)
+          sourcefile_idx = @data.u2(@pos)
+          @pos += 2
+          source_file = @constant_pool[sourcefile_idx].string
+          SourceFile.new(attribute_name, source_file)
+        end
+
+        def inner_classes(attribute_name)
+          number_of_classes = @data.u2(@pos)
+          @pos += 2
+          inner_classes = (1..number_of_classes).collect do |i|
+            inner_class_info_idx = @data.u2(@pos)
+            @pos += 2
+            
+            @pos += 4
+            inner_class_access_flags = @data.u2(@pos)
+            @pos += 2
+
+            inner_class_info = @constant_pool[inner_class_info_idx]
+
+            InnerClass.new(inner_class_info.class_name, AccessFlags.new(inner_class_access_flags))
+          end
+          InnerClasses.new(attribute_name, inner_classes)
+        end
+
+      end
+
+      # Base class of the attributes
+      # Author::   Peter Kofler
+      class Attribute
+        attr_reader :name
+
+        def initialize(name)
+          @name = name
+        end
+      end
+
+      class SourceFile < Attribute
+        attr_reader :source_file
+
+        def initialize(name, source_file)
+          super(name)
+          @source_file = source_file
+        end
+      end
+
+      class InnerClasses < Attribute
+        attr_reader :inner_classes
+
+        def initialize(name, inner_classes)
+          super(name)
+          @inner_classes = inner_classes
+        end
+      end
+
+      class InnerClass
+        attr_reader :class_name
+        attr_reader :access_flags
+
+        def initialize(name, access_flags)
+          @class_name = name
+          @access_flags = access_flags
+        end
+      end
+
+    end
+  end
+end