Debian Codegraph @

animal-sniffer-ant-tasks/src/site/apt/examples/generating-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
26 -----
27 Stephen Connolly
28 ------
29 2009-11-05
30 ------
31
32 Generating signatures
33
34 * Basic
35
36 To generate signatures of any API, you simple construct a invoke the <<<build-signatures>>> task
37 and provide the path(s) of all the classes / jar files which form the API. For example:
38
39 ---
40 <project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
41 ...
42 <target ...>
43 ...
44 <as:build-signatures destfile="dist/api.sig">
45 <path>
46 <fileset dir="classes"/>
47 <fileset dir="lib" includes="log4j.jar"/>
48 </path>
49 </as:build-signatures>
50 ...
51 </target>
52 ...
53 </project>
54 ---
55
56 * Generating "pure" signatures
57
58 The above examples generate signatures of the every class in the provided path.
59 There are some situations where you may not want to include all the classes on the
60 provided path, for example when generating the signature of the JRE, as
61 that includes all the implementation classes which are not part of the
62 public contract of the JRE. For example sun.misc.BASE64Encoder is part
63 of Sun's JRE runtime libraries, but is not part of the JRE specification
64 and if you run on a JRE produced by a different vendor, it is highly likely
65 that that class will not be available to your program.
66
67 In order to ensure that the Java signatures you generate only include those
68 classes which you want, you may need to tune your signatures.
69
70 ** Inclusion based tuning
71
72 One technique is to only include those classes which you know are part of the
73 JRE public specification. For example:
74
75 ---
76 <project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
77 ...
78 <target ...>
79 ...
80 <as:build-signatures ...>
81 ...
82 <includeClasses className="java.*"/>
83 <includeClasses className="javax.*"/>
84 <includeClasses className="org.omg.*"/>
85 <includeClasses className="org.w3c.dom.*"/>
86 <!-- etc -->
87 ...
88 </as:build-signatures>
89 ...
90 </target>
91 ...
92 </project>
93 ---
94
95 This requires that you known exactly what classes to include.
96
97 ** Exclusion based tuning
98
99 The other technique is to specify which classes are not to be included
100 (Note that a combination of the two can also be used.) For example:
101
102 ---
103 <project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
104 ...
105 <target ...>
106 ...
107 <as:build-signatures ...>
108 ...
109 <excludeClasses className="com.sun.*"/>
110 <excludeClasses className="sun.*"/>
111 <!-- etc -->
112 ...
113 </as:build-signatures>
114 ...
115 </target>
116 ...
117 </project>
118 ---
119
120 * Extending signatures
121
122 In some cases you may want to generate a signature which extends another signature, this is
123 achieved by adding the required signatures to the <<<build-signature>>> task. For example:
124
125 ---
126 <project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
127 ...
128 <target ...>
129 ...
130 <as:build-signatures ...>
131 ...
132 <signature src="javase-1.5.sig"/>
133 <signature src="servlet-2.4.sig"/>
134 <!-- etc -->
135 ...
136 </as:build-signatures>
137 ...
138 </target>
139 ...
140 </project>
141 ---
142
143 Note: The resulting signature will be the union of:
144
145 * any the provided signatures
146
147 * any classes or jar files you provide via <<<path>>> elements
148
149 []
150
151 In addition, prior to writing the final signatures out:
152
153 * (if any <<<includeClasses>>> are specified) only classes which match at least one
154 <<<includeClasses>>> rule will be written to the signature.
155
156 * (if any <<<excludeClasses>>> are specified) any classes which match at least one
157 <<<exlcudeClasses>>> rule will be excluded from the signature.
158
159 * if both <<<includeClasses>>> and <<<excludeClasses>>> rules are specified, the
160 <<<excludeClasses>>> rules over-rule the <<<includeClasses>>> rules.
161
162 []