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