~~ The MIT License ~~ ~~ Copyright (c) 2009 codehaus.org. ~~ ~~ Permission is hereby granted, free of charge, to any person obtaining a copy ~~ of this software and associated documentation files (the "Software"), to deal ~~ in the Software without restriction, including without limitation the rights ~~ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell ~~ copies of the Software, and to permit persons to whom the Software is ~~ furnished to do so, subject to the following conditions: ~~ ~~ The above copyright notice and this permission notice shall be included in ~~ all copies or substantial portions of the Software. ~~ ~~ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR ~~ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, ~~ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE ~~ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER ~~ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, ~~ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN ~~ THE SOFTWARE. ~~ ----- Generating signatures of the Java Runtime ----- Stephen Connolly ------ 2010-03-10 ------ Generating signatures of the Java Runtime * Basic To generate signatures of any API, you simple construct a project with the appropriate dependencies exposed by the API and then add an execution of the <<>> goal to your project. In the case of the Java Runtime, this is a project with no dependencies, e.g. --- 4.0.0 ____ ____ ____ pom ${project.groupId} ${project.artifactId} ${project.version} ___id of execution___ package build --- Then you just build this project with the appropriate Java Runtime, and it will generate the signatures of that Java Runtime. The observant reader may have spotted that it may not always be possible to run Maven with the Java Runtime that you want to generate the signatures of. In these cases you have a number of solutions: * Use Maven Toolchains support and the <<>> parameter to define what toolchain you require. This will use automatic boot classpath detection, which does not work for Java 1.1 or earlier and may not work on some exotic Java Runtimes. An example of using the <<>> parameter is: --- ... ... ... ${project.groupId} ${project.artifactId} ${project.version} ... ... [1.6.0,1.6.1) sun ... ... ... ... ... --- * Use the <<>> parameter to specify the Java Home that you want to generate the signatures of. This will use automatic boot classpath detection, which does not work for Java 1.1 or earlier and may not work on some exotic Java Runtimes. An example of using the <<>> parameter is: --- ... ... ... ${project.groupId} ${project.artifactId} ${project.version} ... ... C:\Program Files\Java\jdk_1.6.0_14 ... ... ... ... ... --- * Use the <<>> parameter to specify the exact classpath to generate the signatures of. This is the only way to specify the Java Runtime when automatic boot classpath detection fails. An example of this technique is: --- ... ... ... ${project.groupId} ${project.artifactId} ${project.version} ... ... C:\Program Files\Java\jdk_1.6.0_14\jre\lib\rt.jar C:\Program Files\Java\jdk_1.6.0_14\jre\lib\jsse.jar ... ... ... ... ... --- [] * Generating "pure" signatures The above examples generate signatures of the entire classpath of the JRE. That will include all the implementation classes which are not part of the public contract of the JRE. For example sun.misc.BASE64Encoder is part of Sun's JRE runtime libraries, but is not part of the JRE specification and if you run on a JRE produced by a different vendor, it is highly likely that that class will not be available to your program. In order to ensure that the Java signatures you generate only include those classes which are officially published by the JRE, you will need to tune your signatures. ** Inclusion based tuning One technique is to only include those classes which you know are part of the JRE public specification. For example: --- ... ... ... ${project.groupId} ${project.artifactId} ${project.version} ... ... [1.4.0,1.5.0) java.* javax.* org.omg.* org.w3c.dom.* ... ... ... ... ... ... --- This requires that you known exactly what classes are part of the JRE specification. ** Exclusion based tuning The other technique is to specify which classes are not to be included. Note that a combination of the two can also be used. For example: --- ... ... ... ${project.groupId} ${project.artifactId} ${project.version} ... ... [1.4.0,1.5.0) com.sun.* sun.* ... ... ... ... ... ... --- * When the version of Java you require is not available By default, if the version of Java that you require is not available, the animal-sniffer plugin will fail the build. If you are generating multiple signatures, this may not be exactly what you want. For example you may be generating signatures for JREs on Windows, Linux and MacOS from the same project. This would require building the same project at least three times and setting the <<>> option to <<>> for example --- ... ... ... ${project.groupId} ${project.artifactId} ${project.version} ... ... true ... ... windows ... ... windows [1.4.0,1.5.0) windows ... ... linux ... ... linux [1.4.0,1.5.0) linux ... ... ... ... ... --- * Automatic boot classpath detection Animal sniffer uses a helper module to try and determine the boot classpath of the Java Home that has been specified. This can be done in one of two ways: * Indirectly via a toolchain reference using the <<>> configuration option * Directly using the <<>> option [] The {{{../../animal-sniffer/java-boot-classpath-detector/}helper module}} should work for most common versions of Java providing they are at least Java 1.2. If the default helper module does not work for the version of Java that you need to generate signatures of, you can replace the helper module with your own module. The replacement module must meet the following specification: * Must be an executable JAR file * If the Java boot classpath cannot be detected, it must return with exit code 1. * If the Java boot classpath has been detected, it must print the boot class path to <<>> as a single line with each element of the boot classpath separated from the next using <<>> and return with exit code 0. [] When invoking the helper module, animal-sniffer will: * Clear the CLASSPATH environment variable in the forked execution environment. * Clear the JAVA_HOME environment variable in the forked execution environment. * Invoke the <<>> command in the <<>> or <<>> that has been configured with the options <<<-jar>>> and the full path to the Java boot classpath detector module specified in the configuration of the animal-sniffer plugin. Note: this module JAR file will be located in the Maven local repository. [] A replacement module must be added to the <<>> section of and the groupId and artifactId must be configured using the <<>> and <<>> configuration options. For example, if your custom boot classpath detector is com.mycompany:detect-boot-classpath:1.2.0:jar then you could configure animal-sniffer to use this with the following: --- ... ... ... ${project.groupId} ${project.artifactId} ${project.version} ... ... com.mycompany detect-boot-classpath ... ... ... com.mycompany detect-boot-classpath 1.2.0 ... ... ... ... ... ---