Debian Codegraph @

animal-sniffer-maven-plugin/src/site/apt/examples/generating-java-signatures.apt.vm

raw
1 ~~ The MIT License
2 ~~
3 ~~ Copyright (c) 2009 codehaus.org.
4 ~~
5 ~~ Permission is hereby granted, free of charge, to any person obtaining a copy
6 ~~ of this software and associated documentation files (the "Software"), to deal
7 ~~ in the Software without restriction, including without limitation the rights
8 ~~ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 ~~ copies of the Software, and to permit persons to whom the Software is
10 ~~ furnished to do so, subject to the following conditions:
11 ~~
12 ~~ The above copyright notice and this permission notice shall be included in
13 ~~ all copies or substantial portions of the Software.
14 ~~
15 ~~ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 ~~ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 ~~ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 ~~ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 ~~ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 ~~ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21 ~~ THE SOFTWARE.
22 ~~
23
24 -----
25 Generating signatures of the Java Runtime
26 -----
27 Stephen Connolly
28 ------
29 2010-03-10
30 ------
31
32 Generating signatures of the Java Runtime
33
34 * Basic
35
36 To generate signatures of any API, you simple construct a project with the appropriate
37 dependencies exposed by the API and then add an execution of the <<<animal-sniffer:build>>>
38 goal to your project. In the case of the Java Runtime, this is a project with no
39 dependencies, e.g.
40
41 ---
42 <project>
43 <modelVersion>4.0.0</modelVersion>
44 <groupId>____</groupId>
45 <artifactId>____</artifactId>
46 <version>____</version>
47 <packaging>pom</packaging>
48 <build>
49 <plugins>
50 <plugin>
51 <groupId>${project.groupId}</groupId>
52 <artifactId>${project.artifactId}</artifactId>
53 <version>${project.version}</version>
54 <executions>
55 <execution>
56 <id>___id of execution___</id>
57 <phase>package</phase>
58 <goals>
59 <goal>build</goal>
60 </goals>
61 </execution>
62 </executions>
63 </plugin>
64 </plugins>
65 </build>
66 </project>
67 ---
68
69 Then you just build this project with the appropriate Java Runtime, and it will generate the signatures of that
70 Java Runtime.
71
72 The observant reader may have spotted that it may not always be possible to run Maven with the Java Runtime
73 that you want to generate the signatures of. In these cases you have a number of solutions:
74
75 * Use Maven Toolchains support and the <<<jdk>>> parameter to define what toolchain you require.
76 This will use automatic boot classpath detection, which does not work for Java 1.1 or earlier and
77 may not work on some exotic Java Runtimes.
78
79 An example of using the <<<jdk>>> parameter is:
80
81 ---
82 <project>
83 ...
84 <build>
85 ...
86 <plugins>
87 ...
88 <plugin>
89 <groupId>${project.groupId}</groupId>
90 <artifactId>${project.artifactId}</artifactId>
91 <version>${project.version}</version>
92 ...
93 <configuration>
94 ...
95 <jdk>
96 <version>[1.6.0,1.6.1)</version>
97 <vendor>sun</vendor>
98 </jdk>
99 ...
100 </configuration>
101 ...
102 </plugin>
103 ...
104 </plugins>
105 ...
106 </build>
107 ...
108 </project>
109 ---
110
111 * Use the <<<javaHome>>> parameter to specify the Java Home that you want to generate the signatures of.
112 This will use automatic boot classpath detection, which does not work for Java 1.1 or earlier and
113 may not work on some exotic Java Runtimes.
114
115 An example of using the <<<javaHome>>> parameter is:
116
117 ---
118 <project>
119 ...
120 <build>
121 ...
122 <plugins>
123 ...
124 <plugin>
125 <groupId>${project.groupId}</groupId>
126 <artifactId>${project.artifactId}</artifactId>
127 <version>${project.version}</version>
128 ...
129 <configuration>
130 ...
131 <javaHome>C:\Program Files\Java\jdk_1.6.0_14</javaHome>
132 ...
133 </configuration>
134 ...
135 </plugin>
136 ...
137 </plugins>
138 ...
139 </build>
140 ...
141 </project>
142 ---
143
144 * Use the <<<javaHomeClassPath>>> parameter to specify the exact classpath to generate the signatures of.
145 This is the only way to specify the Java Runtime when automatic boot classpath detection fails.
146
147 An example of this technique is:
148
149 ---
150 <project>
151 ...
152 <build>
153 ...
154 <plugins>
155 ...
156 <plugin>
157 <groupId>${project.groupId}</groupId>
158 <artifactId>${project.artifactId}</artifactId>
159 <version>${project.version}</version>
160 ...
161 <configuration>
162 ...
163 <javaHomeClassPath>
164 <javaHomeClassPath>C:\Program Files\Java\jdk_1.6.0_14\jre\lib\rt.jar</javaHomeClassPath>
165 <javaHomeClassPath>C:\Program Files\Java\jdk_1.6.0_14\jre\lib\jsse.jar</javaHomeClassPath>
166 </javaHomeClassPath>
167 ...
168 </configuration>
169 ...
170 </plugin>
171 ...
172 </plugins>
173 ...
174 </build>
175 ...
176 </project>
177 ---
178
179 []
180
181 * Generating "pure" signatures
182
183 The above examples generate signatures of the entire classpath of the JRE.
184 That will include all the implementation classes which are not part of the
185 public contract of the JRE. For example sun.misc.BASE64Encoder is part
186 of Sun's JRE runtime libraries, but is not part of the JRE specification
187 and if you run on a JRE produced by a different vendor, it is highly likely
188 that that class will not be available to your program.
189
190 In order to ensure that the Java signatures you generate only include those
191 classes which are officially published by the JRE, you will need to tune
192 your signatures.
193
194 ** Inclusion based tuning
195
196 One technique is to only include those classes which you know are part of the
197 JRE public specification. For example:
198
199 ---
200 <project>
201 ...
202 <build>
203 ...
204 <plugins>
205 ...
206 <plugin>
207 <groupId>${project.groupId}</groupId>
208 <artifactId>${project.artifactId}</artifactId>
209 <version>${project.version}</version>
210 ...
211 <configuration>
212 ...
213 <jdk>
214 <version>[1.4.0,1.5.0)</version>
215 </jdk>
216 <includeClasses>
217 <includeClass>java.*</includeClass>
218 <includeClass>javax.*</includeClass>
219 <includeClass>org.omg.*</includeClass>
220 <includeClass>org.w3c.dom.*</includeClass>
221 <!-- etc -->
222 ...
223 </includeClasses>
224 ...
225 </configuration>
226 ...
227 </plugin>
228 ...
229 </plugins>
230 ...
231 </build>
232 ...
233 </project>
234 ---
235
236 This requires that you known exactly what classes are part of the JRE
237 specification.
238
239 ** Exclusion based tuning
240
241 The other technique is to specify which classes are not to be included.
242 Note that a combination of the two can also be used. For example:
243
244 ---
245 <project>
246 ...
247 <build>
248 ...
249 <plugins>
250 ...
251 <plugin>
252 <groupId>${project.groupId}</groupId>
253 <artifactId>${project.artifactId}</artifactId>
254 <version>${project.version}</version>
255 ...
256 <configuration>
257 ...
258 <jdk>
259 <version>[1.4.0,1.5.0)</version>
260 </jdk>
261 <excludeClasses>
262 <excludeClass>com.sun.*</excludeClass>
263 <excludeClass>sun.*</excludeClass>
264 <!-- etc -->
265 ...
266 </excludeClasses>
267 ...
268 </configuration>
269 ...
270 </plugin>
271 ...
272 </plugins>
273 ...
274 </build>
275 ...
276 </project>
277 ---
278
279 * When the version of Java you require is not available
280
281 By default, if the version of Java that you require is not available,
282 the animal-sniffer plugin will fail the build. If you are generating
283 multiple signatures, this may not be exactly what you want. For example
284 you may be generating signatures for JREs on Windows, Linux and MacOS
285 from the same project. This would require building the same project
286 at least three times and setting the <<<skipIfNoJavaHome>>> option to
287 <<<true>>> for example
288
289 ---
290 <project>
291 ...
292 <build>
293 ...
294 <plugins>
295 ...
296 <plugin>
297 <groupId>${project.groupId}</groupId>
298 <artifactId>${project.artifactId}</artifactId>
299 <version>${project.version}</version>
300 ...
301 <configuration>
302 ...
303 <skipIfNoJavaHome>true</skipIfNoJavaHome>
304 ...
305 </configuration>
306 ...
307 <executions>
308 <execution>
309 <id>windows</id>
310 ...
311 <configuration>
312 ...
313 <classifier>windows</classifier>
314 <jdk>
315 <version>[1.4.0,1.5.0)</version>
316 <os>windows</os>
317 </jdk>
318 ...
319 </configuration>
320 ...
321 </execution>
322 <execution>
323 <id>linux
324 ...
325 <configuration>
326 ...
327 <classifier>linux</classifier>
328 <jdk>
329 <version>[1.4.0,1.5.0)</version>
330 <os>linux</os>
331 </jdk>
332 ...
333 </configuration>
334 ...
335 </execution>
336 </executions>
337 </plugin>
338 ...
339 </plugins>
340 ...
341 </build>
342 ...
343 </project>
344 ---
345
346 * Automatic boot classpath detection
347
348 Animal sniffer uses a helper module to try and determine the boot classpath
349 of the Java Home that has been specified. This can be done in one of two ways:
350
351 * Indirectly via a toolchain reference using the <<<jdk>>> configuration
352 option
353
354 * Directly using the <<<javaHome>>> option
355
356 []
357
358 The {{{../../animal-sniffer/java-boot-classpath-detector/}helper module}}
359 should work for most common versions of Java providing they are at least
360 Java 1.2.
361
362 If the default helper module does not work for the version of Java that
363 you need to generate signatures of, you can replace the helper module
364 with your own module. The replacement module must meet the following
365 specification:
366
367 * Must be an executable JAR file
368
369 * If the Java boot classpath cannot be detected, it must return with
370 exit code 1.
371
372 * If the Java boot classpath has been detected, it must print the boot
373 class path to <<<stdout>>> as a single line with each element of
374 the boot classpath separated from the next using <<<File.pathSeparator>>>
375 and return with exit code 0.
376
377 []
378
379 When invoking the helper module, animal-sniffer will:
380
381 * Clear the CLASSPATH environment variable in the forked execution environment.
382
383 * Clear the JAVA_HOME environment variable in the forked execution environment.
384
385 * Invoke the <<<java>>> command in the <<<javaHome>>> or <<<jdk>>> that
386 has been configured with the options <<<-jar>>> and the full path to
387 the Java boot classpath detector module specified in the configuration
388 of the animal-sniffer plugin. Note: this module JAR file will be located
389 in the Maven local repository.
390
391 []
392
393 A replacement module must be added to the <<<dependencies>>> section of
394 <the Animal Sniffer Plugin> and the groupId and artifactId must be configured
395 using the <<<jbcpdGroupId>>> and <<<jbcpdArtifactId>>> configuration options.
396 For example, if your custom boot classpath detector is
397 com.mycompany:detect-boot-classpath:1.2.0:jar then you could configure
398 animal-sniffer to use this with the following:
399
400 ---
401 <project>
402 ...
403 <build>
404 ...
405 <plugins>
406 ...
407 <plugin>
408 <groupId>${project.groupId}</groupId>
409 <artifactId>${project.artifactId}</artifactId>
410 <version>${project.version}</version>
411 ...
412 <configuration>
413 ...
414 <jbcpdGroupId>com.mycompany</jbcpdGroupId>
415 <jbcpdArtifactId>detect-boot-classpath</jbcpdArtifactId>
416 ...
417 </configuration>
418 ...
419 <dependencies>
420 ...
421 <dependency>
422 <groupId>com.mycompany</groupId>
423 <artifactId>detect-boot-classpath</artifactId>
424 <version>1.2.0</version>
425 </dependency>
426 ...
427 </dependencies>
428 ...
429 </plugin>
430 ...
431 </plugins>
432 ...
433 </build>
434 ...
435 </project>
436 ---
437