Debian Codegraph @

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