Debian Codegraph @

animal-sniffer-enforcer-rule/src/site/apt/usage.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 Usage
26 -----
27 Stephen Connolly
28 ------
29 2009-11-04
30 ------
31
32 Usage
33
34 The enforcer rule offers a rule for checking projects against the signatures of an API.
35
36 * Basic Usage
37
38 ** Checking a project against an API signature
39
40 In order to check your project against an API signature, you must add the enforcer rule as a dependency to
41 the maven-enforcer-plugin and then configure the maven-enforcer-plugin to run the rule:
42
43 ---
44 <project>
45 ...
46 <build>
47 ...
48 <plugins>
49 ...
50 <plugin>
51 <artifactId>maven-enforcer-plugin</artifactId>
52 <version>1.0-beta-1</version>
53 ...
54 <dependencies>
55 ...
56 <dependency>
57 <groupId>${project.groupId}</groupId>
58 <artifactId>${project.artifactId}</artifactId>
59 <version>${project.version}</version>
60 </dependency>
61 ...
62 </dependencies>
63 ...
64 <executions>
65 ....
66 <execution>
67 <id>check-signatures</id>
68 <phase>test</phase>
69 <goals>
70 <goal>enforce</goal>
71 </goals>
72 <configuration>
73 <rules>
74 <checkSignatureRule implementation="org.codehaus.mojo.animal_sniffer.enforcer.CheckSignatureRule">
75 ...
76 <signature>
77 <groupId>org.codehaus.mojo.signature</groupId>
78 <artifactId>java15</artifactId>
79 <version>1.0</version>
80 </signature>
81 ...
82 </checkSignatureRule>
83 </rules>
84 </configuration>
85 </execution>
86 ...
87 </executions>
88 ...
89 </plugin>
90 ...
91 </plugins>
92 ...
93 </build>
94 ...
95 </project>
96 ---
97
98 The example above configures the signature for JRE 1.5. For a list of other ready-made signatures, please visit the
99 {{{http://mojo.codehaus.org/signatures/}Animal Scents subproject}}.
100
101 Once you have configured your project with details of the signature to check, maven-enforcer will be able to
102 throw a build error if your any of your classes reference a class, a method, or a field which is not in either
103 the signature or your project's dependencies.
104
105 <Note:> if you want to check against
106 multiple separate APIs (e.g. check against the Tomcat, JBoss, and Jetty servlet containers,
107 or check against multiple java versions) then you will probably want to keep the signature
108 configuration inside each of your multiple executions otherwise your project will be
109 checked against the union of all the signatures specified, which is probably not what you
110 wanted.
111
112 {{{./examples/checking-signatures.html} Some more detailed examples of the <<<checkSignatureRule>>> rule}}.