Debian Codegraph @

animal-sniffer-maven-plugin/src/site/apt/examples/generating-other-api-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 other APIs
26 -----
27 Stephen Connolly
28 ------
29 2010-03-10
30 ------
31
32 Generating signatures of other APIs
33
34 * Basic
35
36 To generate signatures of any API, you simply 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, e.g.
39
40 ---
41 <project>
42 <modelVersion>4.0.0</modelVersion>
43 <groupId>____</groupId>
44 <artifactId>____</artifactId>
45 <version>____</version>
46 <dependencies>
47 ...
48 </dependencies>
49 <build>
50 <plugins>
51 <plugin>
52 <groupId>${project.groupId}</groupId>
53 <artifactId>${project.artifactId}</artifactId>
54 <version>${project.version}</version>
55 <executions>
56 <execution>
57 <id>___id of execution___</id>
58 <phase>package</phase>
59 <goals>
60 <goal>build</goal>
61 </goals>
62 </execution>
63 </executions>
64 </plugin>
65 </plugins>
66 </build>
67 </project>
68 ---
69
70 * Controlling the Java Runtime signatures in your API signature
71
72 By default, the signatures of the Java Runtime that you use to build with will
73 be included in the signatures of the API. Since the Java Runtime forms
74 part of any Java API (as your API extends <<<java.lang.Object>>>) in general
75 the Java Runtime signatures should form part of your API's signatures.
76
77 If you want different Java Runtime signatures used, you can either use the
78 techniques described in {{{./generating-java-signatures.html}Generating
79 signatures of the Java Runtime}} to control what Java Runtime to include or
80 you can base your API off an existing Java Runtime signature. For example:
81
82 ---
83 <project>
84 ...
85 <build>
86 ...
87 <plugins>
88 ...
89 <plugin>
90 <groupId>${project.groupId}</groupId>
91 <artifactId>${project.artifactId}</artifactId>
92 <version>${project.version}</version>
93 ...
94 <configuration>
95 ...
96 <includeSignatures>
97 <includeSignature>
98 <groupId>org.codehaus.mojo.animal_sniffer</groupId>
99 <artifactId>java</artifactId>
100 <version>1.0</version>
101 <classifier>java-1.4-generic</classifier>
102 </includeSignature>
103 </includeSignatures>
104 <includeJavaHome>false</includeJavaHome>
105 ...
106 </configuration>
107 ...
108 </plugin>
109 ...
110 </plugins>
111 ...
112 </build>
113 ...
114 </project>
115 ---
116
117 <<Note:>> You can include multiple signatures, and the signatures you include do
118 not have to include a Java Runtime (but ultimately if you are checking against
119 a signature which does not include the Java Runtime, your check will always fail).
120
121 * Excluding dependencies from signatures
122
123 Sometimes you may not want to include your module dependencies in the signature.
124 For example, your module might define the public API but depend on the private
125 implementations of that API. In that case you would use either the
126 <<<includeDependencies>>> to define the subset of module dependencies to include or
127 <<<excludeDependencies>>> to define the subset of module dependencies to exclude (or
128 a combination of the two. Note: includes are processed before excludes). For example,
129 to include all artifacts with groupId <<<com.mycompany>>> and the servlet-api version 2.5
130 you would use something like:
131
132 ---
133 <project>
134 ...
135 <build>
136 ...
137 <plugins>
138 ...
139 <plugin>
140 <groupId>${project.groupId}</groupId>
141 <artifactId>${project.artifactId}</artifactId>
142 <version>${project.version}</version>
143 ...
144 <configuration>
145 ...
146 <includeDependencies>
147 <includeDependency>com.mycompany:*</includeDependency>
148 <includeDependency>javax.servlet:servlet-api:2.5:jar</includeDependency>
149 </includeDependencies>
150 ...
151 </configuration>
152 ...
153 </plugin>
154 ...
155 </plugins>
156 ...
157 </build>
158 ...
159 </project>
160 ---
161
162 * Excluding module classes from signatures
163
164 In some cases you may not want to include your module classes in the generated
165 signature. To exclude module classes from the generated signature set the
166 <<<includeModuleClasses>>> to <<<false>>> for example:
167
168 ---
169 <project>
170 ...
171 <build>
172 ...
173 <plugins>
174 ...
175 <plugin>
176 <groupId>${project.groupId}</groupId>
177 <artifactId>${project.artifactId}</artifactId>
178 <version>${project.version}</version>
179 ...
180 <configuration>
181 ...
182 <includeModuleClasses>false</includeModuleClasses>
183 ...
184 </configuration>
185 ...
186 </plugin>
187 ...
188 </plugins>
189 ...
190 </build>
191 ...
192 </project>
193 ---
194
195 * Tuning exactly which classes are part of the signatures
196
197 The above examples generate signatures of all the classes in scope. In some
198 situations you may want to only include specific classes from the dependencies
199 or your module. This can be achieved using the <<<includeClasses>>> and
200 <<<excludeClasses>>> configuration options.
201
202 ** Inclusion based tuning
203
204 One technique is to only include those classes which you want to be part of the
205 API signature. For example:
206
207 ---
208 <project>
209 ...
210 <build>
211 ...
212 <plugins>
213 ...
214 <plugin>
215 <groupId>${project.groupId}</groupId>
216 <artifactId>${project.artifactId}</artifactId>
217 <version>${project.version}</version>
218 ...
219 <configuration>
220 ...
221 <includeClasses>
222 <includeClass>com.mycompany.myapi.*</includeClass>
223 <includeClass>com.mycompany.mydatamodel.ApiConfig</includeClass>
224 <!-- etc -->
225 ...
226 </includeClasses>
227 ...
228 </configuration>
229 ...
230 </plugin>
231 ...
232 </plugins>
233 ...
234 </build>
235 ...
236 </project>
237 ---
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 <excludeClasses>
259 <excludeClass>com.mycompany.impl.*</excludeClass>
260 <!-- etc -->
261 ...
262 </excludeClasses>
263 ...
264 </configuration>
265 ...
266 </plugin>
267 ...
268 </plugins>
269 ...
270 </build>
271 ...
272 </project>
273 ---
274