Debian Codegraph @

animal-sniffer-ant-tasks/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 signatures
26 -----
27 Stephen Connolly
28 ------
29 2009-11-05
30 ------
31
32 Checking signatures
33
34 * Basic example
35
36 In order to check your classes against an API signature, you use the <<<check-signature>>> task:
37
38 ---
39 <project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
40 ...
41 <typedef uri="antlib:org.codehaus.mojo.animal_sniffer">
42 <classpath path="lib/${pom.xml.project.artifactId}-${pom.xml.project.parent.version}.jar"/>
43 </typedef>
44 ...
45 </project>
46 ---
47
48 The path provided will be recursively searched for jar files and class files, all of which will be
49 checked against the supplied signature.
50
51 When you run the <<<check-signature>>> task as in the above example, the task will fail if your
52 classes reference any class, method or field that is not either:
53
54 * in the signatures; or
55
56 * on the path you provided
57
58 []
59
60 If you have compiled your classes against a classpath that you have already verified against the signature
61 of your target platform, you can speed up the checking process by giving the <<<check-signature>>> task
62 the classpathRef of your compile classpath. For example, if you are checking a web application against signatures for
63 the Java EE Servlet specification, you might reference the classpath of the WEB-INF/lib folder when
64 checking your WEB-INF/classes path. The following example illustrates how to achieve this:
65
66 ---
67 <project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
68 ...
69 <target ...>
70 ...
71 <as:check-signature signature=".../javaee-servlet.sig" classpathRef="webLibs">
72 <path path="build/web/WEB-INF/classes"/>
73 </as:check-signature>
74 ...
75 </target>
76 ...
77 </project>
78 ---
79
80 * Ignoring classes not in the signature
81
82 In certain situations you may want to reference classes which are missing from the signature you are
83 checking. This is usually the case where you are compiling with a newer JDK than the JDK you are
84 targetting <<and>> you are writing some code which safely makes use of the features in the newer
85 JDK when running on the newer JDK. For example, if you have code like:
86
87 ---
88 public final class MapFactory {
89
90 private MapFactory() {
91 new IllegalAccessError("This is a utility class");
92 }
93
94 public static Map newHashMap() {
95 try {
96 // we'd prefer the concurrent version
97 return new ConcurrentHashMap();
98 } catch (LinkageError e) {
99 // oh dear, looks like we're running on something
100 // earlier than JDK 1.5. This will be slower
101 // but still safe for concurrent access
102 return Collections.synchronizedMap(new HashMap());
103 }
104 }
105 }
106 ---
107
108 The above code will require JDK 1.5 or newer to compile, and can run on earlier JDKs (although
109 with degraded performance, and we are assuming you have set the -source and -target options
110 correctly for the earlier JDKs).
111
112 When you run animal-sniffer against the above class using the JDK 1.4 signatures, you will get
113 a build failure because <<<java.util.concurrent.ConcurrentHashMap>>> is not in the JDK 1.4
114 signature. If you are sure that where you have used <<<java.util.concurrent.ConcurrentHashMap>>>
115 you have correctly encapsulated it within <<<try { ... } catch (LinkageError e) { ... }>>>
116 blocks or their equivalent, you can tell animal-sniffer to ignore the class, e.g.
117
118 ---
119 <project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
120 ...
121 <target ...>
122 ...
123 <as:check-signature ...>
124 ...
125 <ignore className="java.util.concurrent.ConcurrentHashMap"/>
126 ...
127 </as:check-signature>
128 ...
129 </target>
130 ...
131 </project>
132 ---
133
134 We can specify multiple <ignore> classes, and we can also use wildcards to match multiple classes, for
135 example, to ignore <<<java.util.concurrent.ConcurrentHashMap>>>, <<<java.util.concurrent.ConcurrentMap>>>
136 and <<<javax.servlet.*>>> you would use a configuration like:
137
138 ---
139 <project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
140 ...
141 <target ...>
142 ...
143 <as:check-signature ...>
144 ...
145 <ignore className="java.util.concurrent.ConcurrentHashMap"/>
146 <ignore className="java.util.concurrent.ConcurrentMap"/>
147 <ignore className="javax.servlet.*"/>
148 ...
149 </as:check-signature>
150 ...
151 </target>
152 ...
153 </project>
154 ---
155
156 * When your minimum target JRE is 1.5 or newer
157
158 If you are targetting JRE 1.5 or newer (i.e. the lowest version of Java that your project will support is
159 a version that supports annotations) it is preferable to annotate your <<<LinkageError>>> safe methods rather
160 than using the <<<ignores>>> configuration element.
161
162 To annotate your methods, you need to either add <<<animal-sniffer-annotations>>> to your compile classpath or
163 create your own annotation and configure it.
164
165 Then whenever you safely reference a newer class, you just annotate the method with the configured annotation,
166 for example:
167
168 ---
169 public final class Someclass {
170
171 ...
172
173 @IgnoreJRERequirement
174 public void doSomething() {
175 try {
176 // try it the JDK 6 way
177 } catch (LinkageError e) {
178 // fall back to the JDK 5 way
179 }
180 }
181
182 ...
183 }
184 ---
185
186 Note: if you have compiled with the <<<org.jvnet:animal-sniffer-annotation:1.0>>> you do not have to change
187 anything by default as animal-sniffer automatically detects this annotation as well (even although it is in
188 a different package.
189
190 Let's assume you want to use your own annotation instead, <<com.foo.JavaGenerationDependent>>, you would use
191 a configuration like:
192
193 ---
194 <project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
195 ...
196 <target ...>
197 ...
198 <as:check-signature ...>
199 ...
200 <annotation className="com.foo.JavaGenerationDependent"/>
201 ...
202 </as:check-signature>
203 ...
204 </target>
205 ...
206 </project>
207 ---