Debian Codegraph @

animal-sniffer-maven-plugin/src/site/apt/examples/checking-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 Checking a project against API signatures
26 -----
27 Stephen Connolly
28 ------
29 2010-03-10
30 ------
31
32 Checking a project against API signatures
33
34 * Basic example
35
36 In order to check your project against an API signature, you must configure your
37 <<<pom.xml>>> to reference the signature to check against:
38
39 ---
40 <project>
41 ...
42 <build>
43 ...
44 <plugins>
45 ...
46 <plugin>
47 <groupId>${project.groupId}</groupId>
48 <artifactId>${project.artifactId}</artifactId>
49 <version>${project.version}</version>
50 ...
51 <configuration>
52 ...
53 <signature>
54 <groupId>___group id of signature___</groupId>
55 <artifactId>___artifact id of signature___</artifactId>
56 <version>___version of signature___</version>
57 </signature>
58 ...
59 </configuration>
60 ...
61 </plugin>
62 ...
63 </plugins>
64 ...
65 </build>
66 ...
67 </project>
68 ---
69
70 Depending on how your tooling is configured, you may alternatively want to control the version
71 of the signatures from the <<<dependencies>>> or <<dependencyManagement>>> section of your project, e.g.
72
73 ---
74 <project>
75 ...
76 <dependencyManagement>
77 <dependencies>
78 ...
79 <dependency>
80 <groupId>___group id of signature___</groupId>
81 <artifactId>___artifact id of signature___</artifactId>
82 <version>___version of signature___</version>
83 <!-- the type is optional, safer to include it though -->
84 <type>signature</type>
85 <!-- if there are multiple matches, then a type of "signature" wins and "pom" trumps "jar" or none -->
86 </dependency>
87 ...
88 </dependencies>
89 </dependencyManagement>
90 ...
91 <build>
92 ...
93 <plugins>
94 ...
95 <plugin>
96 <groupId>${project.groupId}</groupId>
97 <artifactId>${project.artifactId}</artifactId>
98 <version>${project.version}</version>
99 ...
100 <configuration>
101 ...
102 <signature>
103 <groupId>___group id of signature___</groupId>
104 <artifactId>___artifact id of signature___</artifactId>
105 </signature>
106 ...
107 </configuration>
108 ...
109 </plugin>
110 ...
111 </plugins>
112 ...
113 </build>
114 ...
115 </project>
116 ---
117
118
119 Once you have configured your project with details of the signature to check, you have two ways to
120 check your classes against this signature:
121
122 * Invoke the <<<animal-sniffer:check>>> goal directly, e.g.
123
124 ---
125 mvn animal-sniffer:check
126 ---
127
128 * Make the checks part of your build process add an execution to your
129 configuration, e.g.
130
131 ---
132 <project>
133 ...
134 <build>
135 ...
136 <plugins>
137 ...
138 <plugin>
139 <groupId>${project.groupId}</groupId>
140 <artifactId>${project.artifactId}</artifactId>
141 <version>${project.version}</version>
142 <executions>
143 ...
144 <execution>
145 <id>___id of execution___</id>
146 ...
147 <phase>test</phase>
148 ...
149 <goals>
150 <goal>check</goal>
151 </goals>
152 ...
153 </execution>
154 ...
155 </executions>
156 </plugin>
157 ...
158 </plugins>
159 ...
160 </build>
161 ...
162 </project>
163 ---
164
165 []
166
167 In either case, if any of your classes reference a class, a method, or a field which is not in either
168 the signature or your project's dependencies then a build error will be thrown.
169
170 * Ignoring classes not in the signature
171
172 In certain situations you may want to reference classes which are missing from the signature you are
173 checking. This is usually the case where you are compiling with a newer JDK than the JDK you are
174 targetting <<and>> you are writing some code which safely makes use of the features in the newer
175 JDK when running on the newer JDK. For example, if you have code like:
176
177 ---
178 public final class MapFactory {
179
180 private MapFactory() {
181 new IllegalAccessError("This is a utility class");
182 }
183
184 public static Map newHashMap() {
185 try {
186 // we'd prefer the concurrent version
187 return new ConcurrentHashMap();
188 } catch (LinkageError e) {
189 // oh dear, looks like we're running on something
190 // earlier than JDK 1.5. This will be slower
191 // but still safe for concurrent access
192 return Collections.synchronizedMap(new HashMap());
193 }
194 }
195 }
196 ---
197
198 The above code will require JDK 1.5 or newer to compile, and can run on earlier JDKs (although
199 with degraded performance, and we are assuming you have set the -source and -target options
200 correctly for the earlier JDKs).
201
202 When you run animal-sniffer against the above class using the JDK 1.4 signatures, you will get
203 a build failure because <<<java.util.concurrent.ConcurrentHashMap>>> is not in the JDK 1.4
204 signature. If you are sure that where you have used <<<java.util.concurrent.ConcurrentHashMap>>>
205 you have correctly encapsulated it within <<<try { ... } catch (LinkageError e) { ... }>>>
206 blocks or their equivalent, you can tell animal-sniffer to ignore the class, e.g.
207
208 ---
209 <project>
210 ...
211 <build>
212 ...
213 <plugins>
214 ...
215 <plugin>
216 <groupId>${project.groupId}</groupId>
217 <artifactId>${project.artifactId}</artifactId>
218 <version>${project.version}</version>
219 ...
220 <configuration>
221 ...
222 <ignores>
223 ...
224 <ignore>java.util.concurrent.ConcurrentHashMap</ignore>
225 ...
226 </ignores>
227 ...
228 </configuration>
229 ...
230 </plugin>
231 ...
232 </plugins>
233 ...
234 </build>
235 ...
236 </project>
237 ---
238
239 We can specify multiple <ignore> classes, and we can also use wildcards to match multiple classes, for
240 example, to ignore <<<java.util.concurrent.ConcurrentHashMap>>>, <<<java.util.concurrent.ConcurrentMap>>>
241 and <<<javax.servlet.*>>> you would use a configuration like:
242
243 ---
244 <project>
245 ...
246 <build>
247 ...
248 <plugins>
249 ...
250 <plugin>
251 <groupId>${project.groupId}</groupId>
252 <artifactId>${project.artifactId}</artifactId>
253 <version>${project.version}</version>
254 ...
255 <configuration>
256 ...
257 <ignores>
258 <ignore>java.util.concurrent.ConcurrentHashMap</ignore>
259 <ignore>java.util.concurrent.ConcurrentMap</ignore>
260 <ignore>javax.servlet.*</ignore>
261 </ignores>
262 ...
263 </configuration>
264 ...
265 </plugin>
266 ...
267 </plugins>
268 ...
269 </build>
270 ...
271 </project>
272 ---
273
274 * When your minimum target JRE is 1.5 or newer
275
276 If you are targetting JRE 1.5 or newer (i.e. the lowest version of Java that your project will support is
277 a version that supports annotations) it is preferable to annotate your <<<LinkageError>>> safe methods rather
278 than using the <<<ignores>>> configuration element.
279
280 To annotate your methods, you need to either add <<<animal-sniffer-annotations>>> to your compile classpath or
281 create your own annotation and configure it. Technically optional is the correct way, but to work around some
282 incorrectly written Maven plugins, you may end up using scope provided.
283
284 ---
285 <project>
286 ...
287 <dependencies>
288 ...
289 <dependency>
290 <groupId>${project.parent.groupId}</groupId>
291 <artifactId>animal-sniffer-annotations</artifactId>
292 <version>${project.parent.version}</version>
293 <optional>true</optional>
294 <!-- if you are using badly written Maven plugins then blame them and add
295 <scope>provided</scope>
296 -->
297 </dependency>
298 ...
299 </dependencies>
300 ...
301 <build>
302 ...
303 <plugins>
304 ...
305 <plugin>
306 <artifactId>maven-compiler-plugin</artifactId>
307 ...
308 <configuration>
309 ...
310 <source>1.5</source>
311 <target>1.5</target>
312 ...
313 </configuration>
314 ...
315 </plugin>
316 ...
317 </plugins>
318 ...
319 </project>
320 ---
321
322 Then whenever you safely reference a newer class, you just annotate the method with the configured annotation,
323 for example:
324
325 ---
326 public final class Someclass {
327
328 ...
329
330 @IgnoreJRERequirement
331 public void doSomething() {
332 try {
333 // try it the JDK 6 way
334 } catch (LinkageError e) {
335 // fall back to the JDK 5 way
336 }
337 }
338
339 ...
340 }
341 ---
342
343 Note: if you have compiled with the <<<org.jvnet:animal-sniffer-annotation:1.0>>> you do not have to change
344 anything by default as animal-sniffer automatically detects this annotation as well (even although it is in
345 a different package.
346
347 Let's assume you want to use your own annotation instead, <<com.foo.JavaGenerationDependent>>, you would use
348 a configuration like:
349
350 ---
351 <project>
352 ...
353 <build>
354 ...
355 <plugins>
356 ...
357 <plugin>
358 <groupId>${project.groupId}</groupId>
359 <artifactId>${project.artifactId}</artifactId>
360 <version>${project.version}</version>
361 ...
362 <configuration>
363 ...
364 <annotations>
365 <annotation>com.foo.JavaGenerationDependent</annotation>
366 </annotations
367 ...
368 </configuration>
369 ...
370 </plugin>
371 ...
372 </plugins>
373 ...
374 </build>
375 ...
376 </project>
377 ---
378
379 * Referencing classes from dependencies
380
381 By default, animal-sniffer will automatically ignore any classes and methods defined in your dependencies.
382 This is usually what you want.
383
384 In certain rare situations, you may want to include your project dependencies by setting the <<<ignoreDependencies>>>
385 parameter to <<<false>>>.
386
387 For example, you might be compiling your project against the JavaEE 5 specification but want to check compatibility
388 against the J2EE 1.4 specification. You will have a signature corresponding to the exposed J2EE 1.4 api's.
389 If you check against this signature, because all of the JavaEE 1.5 API dependencies are ignored your project
390 will never fail even if it uses JavaEE 1.5 only methods. In this situation, you would want to turn off the
391 default behaviour, e.g.
392
393 ---
394 <project>
395 ...
396 <build>
397 ...
398 <plugins>
399 ...
400 <plugin>
401 <groupId>${project.groupId}</groupId>
402 <artifactId>${project.artifactId}</artifactId>
403 <version>${project.version}</version>
404 ...
405 <configuration>
406 ...
407 <ignoreDependencies>false</ignoreDependencies>
408 ...
409 </configuration>
410 ...
411 </plugin>
412 ...
413 </plugins>
414 ...
415 </build>
416 ...
417 </project>
418 ---