jartools 0.0.0

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in jartools.gemspec
+gemspec

data/README.md

@@ -0,0 +1,66 @@
+jartools
+========
+
+`jartools` is a command-line utility for examining java archives (JARs
+and WARs).  It is a complement to (not a replacement for) the standard
+`jar` utility.
+
+It is designed to use streams in the standard unix style so it can be
+composed with other stream-processing tools (e.g., `grep`, `xargs`).
+
+Installing `jartools`
+---------------------
+
+`jartools` is distributed as a rubygem.  Install it like so:
+
+    $ gem install jartools
+
+Depending on how your ruby is installed, you may need root privileges
+to do this.
+
+It's been tested on Ruby 1.8.7, JRuby 1.5.6, and Ruby 1.9.2.
+
+Using `jartools`
+----------------
+
+To see what tools are included in the version you have installed, you
+can do this:
+
+    $ jartools help
+
+To get details on a particular tool, use, e.g.:
+
+    $ jartools help packages
+
+This online help tells you what arguments may be passed to each command.
+
+Tools included
+--------------
+
+### packages
+
+Lists all the packages present in a JAR.
+
+### manifest
+
+Prints the JAR's manifest (if any) to standard out.
+
+### diff
+
+Does a diff of two JARs or WARs, including file content diffs and
+recursive diffs of contained JARs.
+
+Project links
+-------------
+
+* [Continuous integration](https://ctms-ci.nubic.northwestern.edu/hudson/job/jartools/)
+* [Issue tracking](http://github.com/rsutphin/jartools/issues)
+
+Non-issue questions can be sent to rhett@detailedbalance.net.
+
+About
+-----
+
+`jartools` is copyright 2010 Rhett Sutphin.  It was built at [NUBIC][].
+
+[NUBIC]: http://www.nucats.northwestern.edu/centers/nubic

data/Rakefile

@@ -0,0 +1,18 @@
+require 'bundler'
+require 'rspec/core/rake_task'
+require 'ci/reporter/rake/rspec'
+
+Bundler::GemHelper.install_tasks
+
+desc "Run all specs"
+RSpec::Core::RakeTask.new('spec') do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+  t.verbose = true
+end
+
+namespace :ci do
+  ENV["CI_REPORTS"] = "reports/spec-xml"
+
+  desc "Run specs for CI"
+  task :spec => ['ci:setup:rspec', 'rake:spec']
+end

data/bin/jartools

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+require 'jartools'
+
+begin
+  JarTools::CLI.start
+rescue Interrupt => e
+  $stderr.puts "Interrupted"
+  exit 1
+end

data/lib/jartools.rb

@@ -0,0 +1,5 @@
+module JarTools
+  autoload :CLI,     'jartools/cli'
+  autoload :Diff,    'jartools/diff'
+  autoload :VERSION, 'jartools/version'
+end

data/lib/jartools/cli.rb

@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+require 'jartools'
+require 'thor'
+
+require 'zip/zipfilesystem'
+
+module JarTools
+  class CLI < Thor
+    desc "packages JARFILE", "Print the java packages found in the JAR to standard out"
+    long_desc <<-DESC
+      Prints all the java packages found in the specified JAR to standard out, one per line.
+      "Packages" are defined as unique paths in the JAR which contain at least one class.
+    DESC
+    def packages(jarfile)
+      entry_names = []
+      Zip::ZipFile.foreach(jarfile) { |entry|
+        entry_names << entry.name
+      }
+
+      entry_names.select { |e| e =~ /\.class$/ }.
+        collect { |e| e.sub(/\/[^\/]+$/, '').gsub('/', '.') }.
+        uniq.sort.each { |pkg| say pkg }
+    end
+
+    desc "manifest JARFILE", "Print the manifest found in the JAR to standard out"
+    long_desc <<-DESC
+      Prints the META-INF/MANIFEST.MF if one is found in the JAR.  To ease examination,
+      lines are unwrapped.  Use --raw to get the original manifest with wrapped lines.
+    DESC
+    method_option :raw, :type => :boolean,
+      :desc => "Print the manifest exactly as it appears in the JAR."
+    def manifest(jarfile)
+      content = Zip::ZipFile.open(jarfile) { |zip|
+        zip.file.read("META-INF/MANIFEST.MF") if zip.file.exists?("META-INF/MANIFEST.MF")
+      }
+      return unless content
+      if options.raw
+        say content
+      else
+        say content.gsub("\r\n", "\n").gsub("\r", "\n").split("\n").inject([]) { |result, raw_line|
+          if raw_line =~ /^\s/
+            result[-1] += raw_line.slice(1, raw_line.size)
+          else
+            result << raw_line
+          end
+          result
+        }.join("\n")
+      end
+    end
+
+    desc "diff JARFILE1 JARFILE2", "Recursively find differences in two JARs or WARs"
+    def diff(jar1, jar2)
+      Diff.diff(jar1, jar2)
+    end
+  end
+end

data/lib/jartools/diff.rb

@@ -0,0 +1,237 @@
+require 'jartools'
+
+require 'diff/lcs'
+require 'diff/lcs/hunk'
+require 'digest/sha1'
+
+require 'tempfile'
+require 'zip/zip'
+
+module JarTools
+  module Diff
+    def self.diff(jar1, jar2)
+      self.compare(ActualFile.new(jar1), ActualFile.new(jar2), [])
+    end
+
+    private
+
+    ##
+    # @param [ActualFile,ExtractedFile] jar1
+    # @param [ActualFile,ExtractedFile] jar2
+    # @param [Array<String>] container_files
+    def self.compare(jar1, jar2, container_files = [], roots = [])
+      # skip check if the files are identical
+      return if jar1.sha1 == jar2.sha1
+      roots = [jar1, jar2] if roots.empty?
+
+      entries1 = EntryIterator.new(jar1, container_files)
+      entries2 = EntryIterator.new(jar2, container_files)
+
+      until entries1.exhausted? && entries2.exhausted?
+        if entries2.exhausted? || (!entries1.exhausted? && entries1.current < entries2.current)
+          puts missing_file_message(entries1.current.display_name, roots.first, roots.last)
+          entries1.advance
+        elsif entries1.exhausted? || entries1.current > entries2.current
+          puts missing_file_message(entries2.current.display_name, roots.last, roots.first)
+          entries2.advance
+        else
+          # at this point, the entry names are identical so we can
+          # examine just one
+          if entries1.current.archive?
+            self.compare(entries1.current.extract, entries2.current.extract,
+              container_files + [entries1.current.path], roots)
+          elsif entries1.current.extract.sha1 != entries2.current.extract.sha1
+            if entries1.current.binary? || entries2.current.binary?
+              puts mismatched_binary_file_message(entries1.current.display_name)
+            else
+              puts mismatched_text_file_message(entries1.current.display_name,
+                entries1.current.extract, entries2.current.extract)
+            end
+          else
+            # identical in both
+          end
+
+          entries1.advance
+          entries2.advance
+        end
+      end
+    end
+
+    def self.missing_file_message(display_name, is_in, is_not_in)
+      "#{display_name} is in #{is_in.readable_filename} but not in #{is_not_in.readable_filename}"
+    end
+
+    def self.mismatched_binary_file_message(display_name)
+      "#{display_name} differs"
+    end
+
+    def self.mismatched_text_file_message(display_name, one, two)
+      diff = TextDiff.new(one.contents, two.contents)
+      "#{display_name} text differs:\n#{diff.text_description}\n"
+    end
+
+    class EntryIterator
+      attr_accessor :index
+
+      def initialize(jarfile, container_files)
+        @jarfile = jarfile
+        @entries = read_directory
+        @container_files = container_files
+        @index = 0
+        @current_entry_cache = nil
+      end
+
+      def current
+        unless exhausted?
+          @current_entry_cache ||=
+            AnalyzableEntry.new(@jarfile, @entries[index], @container_files)
+        end
+      end
+
+      def exhausted?
+        index >= @entries.size
+      end
+
+      def advance
+        @index += 1
+        @current_entry_cache = nil
+      end
+
+      private
+
+      def read_directory
+        entries = []
+        Zip::ZipFile.foreach(@jarfile.readable_filename) do |ze|
+          entries << ze.name
+        end
+        entries.sort
+      end
+
+      class AnalyzableEntry
+        include Comparable
+
+        attr_reader :path
+
+        def initialize(jarfile, path, container_files)
+          @jarfile = jarfile
+          @path = path
+          @container_files = container_files
+        end
+
+        def display_name
+          (@container_files + [path]).join(" | ")
+        end
+
+        def extract
+          @extract ||= Zip::ZipFile.open(@jarfile.readable_filename) do |z|
+            ExtractedFile.new(z.get_entry(path))
+          end
+        end
+
+        def archive?
+          path =~ /(zip|jar|war)$/
+        end
+
+        # This logic is odd, but it's what grep does, apparently
+        def binary?
+          extract.contents.match("\000")
+        end
+
+        def <=>(other)
+          path <=> other.path
+        end
+      end
+    end
+
+    class UniformFile
+      def contents
+        @contents ||= if RUBY_VERSION =~ /1.8/
+                        File.read(readable_filename)
+                      else
+                        File.read(readable_filename, :encoding => 'binary')
+                      end
+      end
+
+      def sha1
+        @sha1 ||= Digest::SHA1.hexdigest(contents)
+      end
+    end
+
+    class ExtractedFile < UniformFile
+      attr_reader :entry_path
+
+      def initialize(zip_entry)
+        @entry_path = zip_entry.name
+        @temp_file = Tempfile.new(File.basename(@entry_path))
+        File.open(@temp_file.path, 'w') do |f|
+          zip_entry.get_input_stream do |ze|
+            f.write ze.read
+          end
+        end
+      end
+
+      def readable_filename
+        @temp_file.path
+      end
+    end
+
+    class ActualFile < UniformFile
+      attr_reader :entry_path, :readable_filename
+
+      def initialize(filename)
+        @entry_path = @readable_filename = filename
+      end
+    end
+
+    class TextDiff
+      def initialize(a, b)
+        @s1 = a
+        @s2 = b
+      end
+
+      def different?
+        @s1 != @s2
+      end
+
+      def text_description
+        printable_diff if different?
+      end
+
+      private
+
+      # Adapted from Diff::LCS::Ldiff by way of Rspec::Expectations::Differ
+      def printable_diff
+        data_old = @s1.split(/\n/).map! { |e| e.chomp }
+        data_new = @s2.split(/\n/).map! { |e| e.chomp }
+        output = ""
+        diffs = ::Diff::LCS.diff(data_old, data_new)
+        return output if diffs.empty?
+        oldhunk = hunk = nil
+        file_length_difference = 0
+        diffs.each do |piece|
+          begin
+            hunk = ::Diff::LCS::Hunk.new(
+              data_old, data_new, piece, 3, file_length_difference
+            )
+            file_length_difference = hunk.file_length_difference
+            next unless oldhunk
+            # Hunks may overlap, which is why we need to be careful when our
+            # diff includes lines of context. Otherwise, we might print
+            # redundant lines.
+            if hunk.overlaps?(oldhunk)
+              hunk.unshift(oldhunk)
+            else
+              output << oldhunk.diff(:unified)
+            end
+          ensure
+            oldhunk = hunk
+            output << "\n"
+          end
+        end
+        #Handle the last remaining hunk
+        output << oldhunk.diff(:unified) << "\n"
+        output.lstrip
+      end
+    end
+  end
+end

data/lib/jartools/version.rb

@@ -0,0 +1,3 @@
+module JarTools
+  VERSION = "0.0.0"
+end

data/spec/jartools/cli_spec.rb

@@ -0,0 +1,70 @@
+require File.expand_path("../../spec_helper", __FILE__)
+
+describe JarTools::CLI do
+  def cli_lines(*args)
+    capture_stdout do
+      JarTools::CLI.start(args)
+    end.gsub("\r\n", "\n").split(/\n/)
+  end
+
+  describe "#packages" do
+    before do
+      @result = cli_lines("packages", sample_jar("slf4j-api-1.6.0.jar"))
+    end
+
+    %w(org.slf4j org.slf4j.spi org.slf4j.helpers).each do |expected_pkg|
+      it "lists all the packages, including #{expected_pkg}" do
+        @result.should include(expected_pkg)
+      end
+    end
+
+    it "does not list things which are not packages" do
+      @result.should_not include "META-INF"
+    end
+  end
+
+  describe "#manifest" do
+    describe "by default" do
+      before do
+        @result = cli_lines("manifest", sample_jar("slf4j-api-1.6.0.jar"))
+      end
+
+      it "prints the whole manifest" do
+        @result.should have(16).lines
+      end
+
+      it "unwraps hard-wrapped lines" do
+        @result.find { |l| l =~ /^Export-Package/ }.should ==
+          "Export-Package: org.slf4j;version=1.6.0, org.slf4j.spi;version=1.6.0, org.slf4j.helpers;version=1.6.0"
+      end
+    end
+
+    describe "--raw" do
+      before do
+        @result = cli_lines("manifest", sample_jar("slf4j-api-1.6.0.jar"), "--raw")
+      end
+
+      it "prints the raw manifest" do
+        @result.should have(17).lines
+      end
+
+      it "leaves wrapped lines alone" do
+        @result.find { |l| l =~ /^Export-Package/ }.should ==
+          "Export-Package: org.slf4j;version=1.6.0, org.slf4j.spi;version=1.6.0, "
+      end
+    end
+
+    describe "on a JAR without a manifest" do
+      it "prints nothing" do
+        cli_lines("manifest", sample_jar("empty.jar")).should == []
+      end
+    end
+  end
+
+  describe "#diff" do
+    it "prints nothing for the same jar" do
+      cli_lines("diff", sample_jar("slf4j-api-1.6.0.jar"), sample_jar("slf4j-api-1.6.0.jar")).
+        should == []
+    end
+  end
+end

data/spec/jartools/diff_spec.rb

@@ -0,0 +1,133 @@
+require File.expand_path("../../spec_helper", __FILE__)
+
+describe JarTools::Diff do
+  it "reports no differences for the same JAR" do
+    same = sample_jar('slf4j-api-1.6.0.jar')
+    capture_stdout { JarTools::Diff.diff(same, same) }.should == ""
+  end
+
+  describe "with a text file difference" do
+    before do
+      tmpdir("sub")
+      tmpfile("A.txt", "Description\nFirst Letter")
+      tmpfile("sub/B.txt", "Description\nSecond letter")
+      jar1 = tmpjar("one.jar", "A.txt", "sub/B.txt")
+      tmpfile("sub/B.txt", "Description\n2nd letter")
+      jar2 = tmpjar("two.jar", "A.txt", "sub/B.txt")
+
+      @actual = capture_stdout { JarTools::Diff.diff(jar1, jar2) }
+    end
+
+    it "should note the difference in its text description" do
+      @actual.should == <<-EXPECTED
+sub/B.txt text differs:
+@@ -1,3 +1,3 @@
+ Description
+-Second letter
++2nd letter
+
+EXPECTED
+    end
+  end
+
+  describe "with a classfile difference" do
+    before do
+      tmpfile("A.java", "public class A { }");
+      cd(tmpdir) { system("javac A.java") }
+      jar1 = tmpjar("one.jar", "A.class")
+
+      tmpfile("A.java", %q(public class A { public static final String N = "A"; }))
+      cd(tmpdir) { system("javac A.java") }
+      jar2 = tmpjar("two.jar", "A.class")
+
+      @actual = capture_stdout { JarTools::Diff.diff(jar1, jar2) }
+    end
+
+    it "should not include a detailed diff" do
+      @actual.should == <<-EXPECTED
+A.class differs
+EXPECTED
+    end
+  end
+
+  describe "with files present in one jar but not the other" do
+    before do
+      tmpdir("sub")
+      tmpfile("A.txt", "Description\nFirst Letter")
+      tmpfile("sub/B.txt", "Description\nSecond letter")
+      tmpfile("sub/C.txt", "Description\Third letter")
+      jar1 = tmpjar("one.jar", "sub/B.txt", "sub/C.txt")
+      jar2 = tmpjar("two.jar", "sub/C.txt", "A.txt")
+
+      cd(tmpdir) do
+        @actual = capture_stdout { JarTools::Diff.diff("one.jar", "two.jar") }
+      end
+    end
+
+    it "should have an appropriate text description" do
+      @actual.should == <<-EXPECTED
+A.txt is in two.jar but not in one.jar
+sub/B.txt is in one.jar but not in two.jar
+EXPECTED
+    end
+  end
+
+  describe "with a nested JAR difference" do
+    before do
+      tmpfile("same.txt", "No changes in here")
+      tmpfile("altered.txt", "V1")
+      tmpjar("nested.jar", "altered.txt")
+      jar1 = tmpjar("main1.jar", "nested.jar", "same.txt")
+
+      tmpfile("altered.txt", "V2")
+      tmpfile("extra.txt", "Not in that other one")
+      tmpjar("nested.jar", "altered.txt", "extra.txt")
+      jar2 = tmpjar("main2.jar", "nested.jar", "same.txt")
+
+      cd(tmpdir) do
+        @actual = capture_stdout { JarTools::Diff.diff("main1.jar", "main2.jar") }
+      end
+    end
+
+    it "should output the details of the difference" do
+      @actual.should == <<-EXPECTED
+nested.jar | altered.txt text differs:
+@@ -1,2 +1,2 @@
+-V1
++V2
+
+nested.jar | extra.txt is in main2.jar but not in main1.jar
+EXPECTED
+    end
+  end
+
+  module JarTools::Diff
+    describe TextDiff do
+      describe "#different?" do
+        it "is true for different values" do
+          TextDiff.new("A", "B").should be_different
+        end
+
+        it "is false for identical values" do
+          TextDiff.new("C", "C").should_not be_different
+        end
+      end
+
+      describe "#text_description" do
+        it "is nil for no differences" do
+          TextDiff.new("ABC", "ABC").text_description.should be_nil
+        end
+
+        it "gives diff-style output for differences" do
+          TextDiff.new("A\nb\nC", "A\nB\nC").text_description.should == <<-EXPECTED
+@@ -1,4 +1,4 @@
+ A
+-b
++B
+ C
+          EXPECTED
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,70 @@
+require 'bundler'
+Bundler.setup
+
+require 'rspec'
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+
+require 'jartools'
+require 'fileutils'
+
+RSpec.configure do |config|
+  config.include FileUtils
+
+  config.after do
+    if @tmpdir
+      rm_r @tmpdir
+    end
+  end
+
+  ##
+  # Returns the path to a JAR from the samples directory
+  def sample_jar(name)
+    File.join(File.expand_path("../samples", __FILE__), name)
+  end
+
+  ##
+  # Captures everything printed to stdout during the block
+  # and returns it as a string.
+  def capture_stdout
+    old_stdout, $stdout = $stdout, StringIO.new
+    begin
+      yield
+      $stdout.string
+    ensure
+      $stdout = old_stdout
+    end
+  end
+
+  def tmpdir(sub=nil)
+    @tmpdir ||= begin
+                  dirname = File.expand_path("../tmp", __FILE__)
+                  mkdir_p dirname
+                  dirname
+                end
+    if sub
+      full = File.join(@tmpdir, sub)
+      mkdir_p full
+      full
+    else
+      @tmpdir
+    end
+  end
+
+  def tmpfile(basename, contents=nil)
+    full_path = File.join(tmpdir, basename)
+    File.open(full_path, 'w') do |f|
+      f.write(contents) if contents
+    end
+    full_path
+  end
+
+  def tmpjar(basename, *files)
+    full_path = File.join(tmpdir, basename)
+    cd tmpdir do
+      cmd = "jar Mcf '#{full_path}' '#{files.join("' '")}'"
+      `#{cmd}`
+    end
+    full_path
+  end
+end

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification 
+name: jartools
+version: !ruby/object:Gem::Version 
+  hash: 31
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 0
+  version: 0.0.0
+platform: ruby
+authors: 
+- Rhett Sutphin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-04 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thor
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 39
+        segments: 
+        - 0
+        - 14
+        - 0
+        version: 0.14.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rubyzip
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 51
+        segments: 
+        - 0
+        - 9
+        - 4
+        version: 0.9.4
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 2
+        - 3
+        version: "2.3"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: ci_reporter
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 1
+        - 6
+        version: "1.6"
+  type: :development
+  version_requirements: *id004
+description: |-
+  jartools provides a busybox of command-line tools
+                       for examining the contents and metadata of java archive files (JARs and WARs).
+email: 
+- rhett@detailedbalance.net
+executables: 
+- jartools
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/jartools/cli.rb
+- lib/jartools/diff.rb
+- lib/jartools/version.rb
+- lib/jartools.rb
+- spec/jartools/cli_spec.rb
+- spec/jartools/diff_spec.rb
+- spec/samples/empty.jar
+- spec/samples/slf4j-api-1.6.0.jar
+- spec/spec_helper.rb
+- bin/jartools
+- README.md
+- Rakefile
+- Gemfile
+has_rdoc: true
+homepage: http://github.com/rsutphin/jartools
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A set of command line tools for looking through java archives (JARs and WARs)
+test_files: 
+- spec/jartools/cli_spec.rb
+- spec/jartools/diff_spec.rb
+- spec/samples/empty.jar
+- spec/samples/slf4j-api-1.6.0.jar
+- spec/spec_helper.rb