Japitools

Java API compatibility testing tools

Very Old News

  • 11 November 2004: Released japitools-0.9.5. This release has several significant changes and fixes:
    • A much-requested feature: the ability to ignore differences when reporting compatibility with an early API release, if those differences are required for compatibility with a later release. See the description of the -i flag below for more information. This new code has been running nightly for a while producing the results linked above, without any known problems. It reveals that the free implementations are much closer to full coverage of 1.0 and 1.1 than was previously apparent - in fact already perfect for 1.0 and in Classpath's case only one method away from 1.1.
      Thanks to Michael Koch for the key insight that enabled this feature to finally be written, four years after I first said it was needed.
    • A new bytecode reading implementation from Jeroen Frijters to replace Jode. This vastly reduces the amount of code because it only reads and understands the bits of metadata we actually need, where Jode was part of a larger system that needed more information. This code also fixes a "Miranda Methods" bug in the Jode implementation.
    • Also from Jeroen: methods in final classes are now treated as final even if they weren't explicitly marked as such.
    • Correct access modifiers on inner classes. Jeroen caught this one and the fix was a joint effort.
    • japicompat will warn if using a japi file from an older release that contains known bugs. That covers all versions except for this one, in fact. Use the -w flag to disable this warning
    • Better support for launching japiotext and japiohtml on Windows systems (some issues may remain, however).
    • The serialize and serialcompat tools have been removed (they are now a module in the Mauve project).
  • 30 September 2004: Released japitools-0.9.4. This is a bugfix release that addresses two issues:
    • Constant field values were frequently missed.
    • Exceptions were sometimes misreported (found and fixed by Tom Tromey).
    Needless to say, the world has changed a bit since I suggested that 0.9.3 was a release candidate for 1.0. Now that Java 5 has been released, it would be unacceptable to make a 1.0 release without support for generics and the other new language features. Still, 0.9.4 is definitely more stable than any previous "stable" release - this is the version you should be using.
  • 19 February 2003: Released japitools-0.9.3. This is a 'release candidate' for 1.0. There are a few minor fixes over 0.9.2 including:
    • Workaround a bug that caused Japize to abort when run against Classpath.
    • Implement toString-independent comparisons of floats and doubles, as described below.
    • Fix a problem that caused deprecation errors to be reported only on classes and interfaces, not members.
    • Fix an erroneous '}' that appeared in comparisons of constant fields. Also fix some other potential problems if particular characters appeared in constant fields.
  • 4 December 2002: Released an EXPERIMENTAL, BETA QUALITY japitools-0.9.2. This release is more complete than 0.9.1 and includes some fixes over version 0.9 that make it worth using even if you're not interested in the flashy output. On the other hand, it's still less tested than 0.9 was, so be warned. Improvements over 0.9.1 include:
    • Fix for a problem that caused inner classes to be incorrectly treated as non-static.
    • Deprecation support (undeprecating an API is flagged as a (minor) error).
    • Preparation for toString-independent comparisons of floats and doubles. Since toString on these types seems to be all but impossible to code to the spec (even Sun don't achieve it), this allows japi files to be somewhat independent of the VM producing them. Note that this is not yet implemented in japicompat, but the necessary information is in the japi file so the nightly results will be able to take advantage immediately.
    • The date of japi file creation is now included in the japi file and presented in the output
    • Numerous fixes to the HTML output including better organization of errors, browser compatibility fixes, and a color-legend.
    • Parallel enhancements to the text output.
    • Use -h to get HTML output, no more piping to japiohtml manually. You can still get raw output by specifying -j. Use -o to specify an output filename if you don't want to use shell redirection.
    • Other miscellaneous fixes.
  • 21 November 2002: Released an EXPERIMENTAL, ALPHA QUALITY japitools-0.9.1. Japitools-0.9 is still the recommended version if you plan to do anything important with the results. This release includes some nice new features but also has some significant issues:
    • The documentation below has not been updated to cover this release. Since 0.9 is still the stable version, I need to split out the webpage with separate docs for each version. I haven't done that yet. The only information about the differences in usage is this list.
    • japicompat no longer gives you anything terribly comprehensible if you save its stdout directly. Instead, you must pipe the output to one of the new tools japiotext or japiohtml. In a future version this will be made optional, with a pipe through japiotext as the default, but currently it's compulsory. You can save the results as a ".japio" file if you want to run both japiotext and japiohtml over the same output.
    • Speaking of which, the japiohtml tool gives nice HTML output. This is what's been generating the nightly classpath comparisons. The output will be further cleaned up in future versions.
    • Using japiotext to get text output still doesn't provide everything the old text output did. Neither does the HTML output.
    • The bits of Jode source code that I'm using are included directly and get compiled into japitools.jar, so jode-1.1.1.jar is no longer bundled. I stripped out some of the "magic" of the Jode build system to use just .java files instead of .java.in. I also applied a theoretical fix to Jode's problem with JDK1.4, but this is entirely untested. If you test it, and produce a jdk14.japi.gz, please send it to me.
  • 13 November 2002: Started a nightly script comparing classpath to various JDK versions using new experimental (and unreleased because it's still very crufty) HTML output. The results can be seen here: vs JDK1.1, vs JDK1.2, and vs JDK1.3.
  • 5 November 2002: Released japitools-0.9, and dared to announce it on a few mailing lists that I thought might be interested. This release only has minor changes and cleanups over 0.8.7:
    • Japifix was missing a case in the exception-pruning algorithm (thanks to Brian Jones for catching this).
    • Fixes to serialize from Brian Jones, including addition of the line that actually runs it, which I somehow missed last time.
    • Print a warning from japize about the importance of using the right filename, if "as" isn't used (thanks to Dalibor Topic for pointing out that this isn't obvious). Updated the docs, too.
    • Cleaner separation of japicompat output between stdout and stderr, to make it easier to redirect what you actually want. Recommended usage is now to redirect stdout only, and use the "-q" option if running non-interactively.
    This release is currently considered stable and suitable for widespread use. Barring the discovery of major problems, the next few releases will be potentially unstable new-feature releases leading up to an eventual 1.0.
  • 24 September 2002: Released japitools-0.8.7, which is a "release candidate" for a hopefully stable and widely-announced 0.9. Quite a bit new in this release:
    • Japize (and japifix) will now ignore any subclasses of Error and RuntimeException thrown, because they're redundant. Exceptions will also be skipped if they are subclasses of another exception thrown by the same method, eg FileNotFoundException won't be included if the method also throws IOException.
    • Added Ant build system (optional) provided by Brian Jones.
    • Added new tools serialize and serialcompat for testing serialization compatibility, again thanks to Brian Jones.
    • japipkgs has evolved into japilist, which can list classes and members, and filter results by package and class, as well as just listing packages. Thanks again to Brian for the "japiclasses" script that inspired this tool.
    • japifix can now detect mis-sorted files without the explicit -s flag, by re-starting as soon as a mis-sort is detected. To make this possible, the ability to operate on stdin has been dropped.
    • Fixed a corner-case mis-sorting bug in japize that appeared if java.lang.something was included but java.lang itself was not.
    • japicompat flushes stdout when it's done, making the output appear in a nice order if stdout and stderr are redirected to the same place.
    • Added windows batch file for running japize on windows systems, thanks (yet again :) ) to Brian Jones.
    • Added the japi file format specification for the benefit of anyone writing code to interoperate with japitools.
  • 18 September 2002: Released japitools-0.8.6, fixing an ordering problem related to inner classes (serve me right for having a machine that can only handle japizing JDK1.1, which has no inner classes). This release also includes some cruft-removal, including the unreliable "reflect" option and japicompat-old, and makes zipped output the default. I added Jode to the tarball itself and restructured a bit so that japize can find its own libraries, so you no longer need to set CLASSPATH (or download Jode separately).
  • 10 September 2002: Released japitools-0.8.5. This fixes numerous problems in the files produced by japize, bringing it finally back to parity with release 0.8 or so. Japicompat will now abort on mis-ordered files, so that errors like this will be caught quicker next time. Japi2new got a facelift and is now called japifix. Much more testing, leading me to conclude that japicompat is now more trustworthy than japicompat-old.
  • 31 July 2002: Released a brown-paper-bag japitools-0.8.4 with a fix for a hang-at-end-of-file bug that showed up whenever the 'orig' file contains packages or classes at the end of the file that aren't in the 'new' file. Oooops!
  • 31 July 2002: Released japitools-0.8.3 with a rewritten japicompat that uses a much faster and more scalable algorithm. Of course, being a total rewrite, there's a risk of regressions, so the old japicompat is still available as japicompat-old (and, in fact, includes a fix or two over the 0.8.2 version). The other casualty of the rewrite is that although some summary information is better, some is also worse. I hope to resurrect the bits of what was lost that make sense. Also updated the docs below so that they match the state of reality since 0.8.1.
  • 9 July 2002: Released japitools-0.8.2 with a fix for a NullPointer. There's more work in progress on my laptop that isn't included in this release because it's not ready yet, but hopefully soon there'll be a first pass at the optimized algorithm for japicompat.
  • 28 June 2002: Released japitools-0.8.1. Noted that this obsoletes some of the documentation on the website. Removed a bunch of old results files that aren't correct any more. The docs will have to be updated later - no time now.
  • 19 March 2002: Updated the website so that the documentation matches the actual current code. Since it's been almost 2 years since I wrote this, I can't be 100% sure that this documentation is all correct, but it's certainly better than it was before!
  • 28 June 2000: Finally bundled japitools up into a jarball which I'm calling version 0.8 (which is a good indicator of how close to "complete" I feel it is). It now requires the jode.bytecode package if you want to get good results, although you can still use the old buggy reflection version. See below for details.
  • 18 June 2000: At the suggestion of Edouard G. Parmelan, added support for checking SerialVersionUIDs. Since this will generally produce lots of errors and make it harder to identify more important API compatibility errors, it needs to be explicitly turned on in japicompat by passing the -v flag.
  • 16 June 2000: Godmar fixed the remaining Kaffe bug, so I've removed the hackaround. I still need to leave part of it in due to a subtlety in the way superinterfaces are defined by the JLS. japicompat now removes duplicates, cutting the number of Kaffe errors to 142, and checks everything in the JLS plus my four additions. Reflection is incapable of telling me if a field is a primitive constant, buggrit, so I have to move to using something like gnu.bytecode.
  • 15 June 2000: Japize is now, finally, well commented. Godmar Back kindly fixed one of the Kaffe bugs which will mean that some hackarounds can be removed Real Soon (once another related bug gets fixed). I've been hacking japicompat to allow duplicates to be removed; you can find the code here [long-dead link]. It doesn't actually do the removal yet, but the architecture is in. This will replace japicompat once I'm convinced it's as robust; early signs look good. It's also commented! Certify me on Advogato - or don't, but it really is me! I need to figure how I'm going to version japitools - right now, all the links here are to my working copies...