Animal Sniffer

Animal Sniffer provides tools to assist verifying that classes compiled with a newer JDK/API are compatible with an older JDK/API.

Introduction

What happens if you compile a program written with a version of an API that is different from the version you are targetting? Well the answer depends on a number of things.

  • Firstly we will assume that the API has an evolution contract, i.e., if a class or method or field is present in version v1, it will also be present in version v2 providing v1 is less than or equal to v2. A good example of this is the Java Runtime Library (a.k.a the JRE)
  • If you are compiling with a newer version of the API, you should not get any compiler errors.
  • If you are compiling with an older version of the API, and you have only used those features in the older version of the API, you should not get any compiler errors.
  • If you are compiling with an older version of the API, and you have used some features only available in the newer version, you will get a compiler error.

If you are developing a project which must support running on JDK version 1.4, but your development system does not have a JDK version 1.4 available, it can be quite easy to accidentally use methods or classes that are only available in the newer version of the JDK. For example, if you are developing a plugin for Maven 2.0.x on a newer Macintosh.

Animal sniffer can check the classes and method signatures that your compiled code uses and verify that you have use only those classes and signatures available in the API you are targetting.

Why the name?

Sun gives each of the JDK versions codenames. Most of these codenames are animal names. Animal-sniffer was concieved as a utility to see what "animal" your code can run on.

What does animal-sniffer provide?

The following tools are provided by animal sniffer:

  • A command line tool to dump the class file version number. This helps you track down the offending jar file when you see UnsupportedClassVersionError.
  • A set of ANT tasks for verifying that your classes comply with an API signature as well as tasks for creating API signatures from a JDK, or a collection or jar and class files, or a collection of other API signature files, or combination of these elements.
  • A rule for use in the maven-enforcer-plugin for verifying that your classes comply with an API signature .
  • A maven plugin for verifying that your classes comply with an API signature as well as for creating API signatures from a JDK, or the current module's classes, or the current module's dependencies, or a collection of other API signature files, or combination of these elements.