1Copyright (C) 1996-2004, International Business Machines Corporation and
2others. All Rights Reserved.
3
4-------------------------------------------
5Using the GatherAPIData and ReportAPI tools
6-------------------------------------------
7
8These two tools are used together to generate reports about changes in
9supported API between versions of ICU4J.
10
11
12GatherAPIData
13
14GatherAPIData uses javadoc to process the ICU4J source files and
15generate a file listing information about the public API, including
16the ICU4J status (draft, stable, deprecated, obsolete). It excludes
17private API, API marked @internal. The file is written as text, so it
18is human-readable, but it is a bit verbose. To save space, the file
19can be zip'd or gzip'd (using flags passed to the tool), which will
20reduce the size by about a factor of 10.
21
22GatherAPIData requires javadoc and is currently based on sun jdk
231.4.2. JavaDoc is internal (I believe) so you need a reference jvm
24from Sun to compile the tool, but it can be run against any 1.4 JDK
25(at least, those from Sun). Instructions in the source file show how
26it can be invoked.
27
28GatherAPIData should be passed all the packages that need reporting.
29Currently, public api is only in the lang, math, text, and util
30subpackages of com.ibm.icu.
31
32
33ReportAPI
34
35ReportAPI takes two api files generated by GatherAPIData and reports
36on removals, changes, and additions to the API. It does this by
37comparing the API information in the two API files. When new classes
38are added, only the class is listed, not its entire API, and similarly
39when a class is deleted. When APIs with the same name and signature
40are changed (visibility, status, inheritance) these changes are listed
41by showing the old and new versions of the API.
42
43ReportAPI is not particularly smart, and in particular, does not know
44about inherited API. So for example, moving public API from a class
45to a base class is reported as a deletion of API from the original
46class, even though the effective API on the original class is
47unchanged by this.
48
49ReportAPI also does not know about Java class files, so for example it
50cannot be used to compare com.ibm.icu.lang.UCharacter against
51java.lang.Character. This might be provided in a later release.
52
53For these reasons, in general it is best to compare two successive
54versions of ICU4J against each other, rather than radically different
55versions. A large number of changes can show up, many of which might
56fall into these 'innocuous' categories.
57
58ReportAPI can generate either plain text or html reports. Since it
59only requires the data files and does not rely on JavaDoc, it is more
60straightforward to invoke.
61
62ReportAPI uses the file extension to determine how to uncompress the
63api data files. It expects '.zip' for files that have been compressed
64using zip, and '.gz' for files that have been compressed using gzip.
65The GatherAPIData utility automatically appends these extensions when
66compression is used.
67
68API Data Files
69
70API Data files for ICU4J 2.8 and 3.0 are in this directory. The
71intent is to store data files for each release version of ICU4J, to
72facilitate comparison using the ReportAPI tool. Of course, they can
73always be regenerated using the GenerateAPI and the sources of a
74particular ICU4J release.
75
76The format of the API data file is straightforward. The first line of
77the file is the header, successive lines are the api information.
78Each line consists of a number of tokens, each followed by a
79semi-colon (incuding the last token on the line).
80
81The header line contains the version number, the 'name' of the version
82of ICU4J represented by the file, and a 'base directory' field
83(currently not fully implemented).
84
85The following lines contain data generated by the APIInfo class, one
86line per class or method. The tokens are status, visibility, static,
87final, synchronized, abstract, type, package, containing class, name,
88and 'signature' (which varies by the type of object). For classes,
89the 'signature' is the immediate inheritance of the class. For
90fields, the 'signature' is the type of the field. For methods, the
91'signature' is the function signature. All fields are always present.
92
93For more information, please see APIInfo.java.
94
95-------
96