You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
97 lines
4.2 KiB
97 lines
4.2 KiB
© 2016 and later: Unicode, Inc. and others. License & terms of use: http://www.unicode.org/copyright.html
|
|
Copyright (C) 1996-2004, International Business Machines Corporation and
|
|
others. All Rights Reserved.
|
|
|
|
-------------------------------------------
|
|
Using the GatherAPIData and ReportAPI tools
|
|
-------------------------------------------
|
|
|
|
These two tools are used together to generate reports about changes in
|
|
supported API between versions of ICU4J.
|
|
|
|
|
|
GatherAPIData
|
|
|
|
GatherAPIData uses javadoc to process the ICU4J source files and
|
|
generate a file listing information about the public API, including
|
|
the ICU4J status (draft, stable, deprecated, obsolete). It excludes
|
|
private API, API marked @internal. The file is written as text, so it
|
|
is human-readable, but it is a bit verbose. To save space, the file
|
|
can be zip'd or gzip'd (using flags passed to the tool), which will
|
|
reduce the size by about a factor of 10.
|
|
|
|
GatherAPIData requires javadoc and is currently based on sun jdk
|
|
1.4.2. JavaDoc is internal (I believe) so you need a reference jvm
|
|
from Sun to compile the tool, but it can be run against any 1.4 JDK
|
|
(at least, those from Sun). Instructions in the source file show how
|
|
it can be invoked.
|
|
|
|
GatherAPIData should be passed all the packages that need reporting.
|
|
Currently, public api is only in the lang, math, text, and util
|
|
subpackages of com.ibm.icu.
|
|
|
|
|
|
ReportAPI
|
|
|
|
ReportAPI takes two api files generated by GatherAPIData and reports
|
|
on removals, changes, and additions to the API. It does this by
|
|
comparing the API information in the two API files. When new classes
|
|
are added, only the class is listed, not its entire API, and similarly
|
|
when a class is deleted. When APIs with the same name and signature
|
|
are changed (visibility, status, inheritance) these changes are listed
|
|
by showing the old and new versions of the API.
|
|
|
|
ReportAPI is not particularly smart, and in particular, does not know
|
|
about inherited API. So for example, moving public API from a class
|
|
to a base class is reported as a deletion of API from the original
|
|
class, even though the effective API on the original class is
|
|
unchanged by this.
|
|
|
|
ReportAPI also does not know about Java class files, so for example it
|
|
cannot be used to compare com.ibm.icu.lang.UCharacter against
|
|
java.lang.Character. This might be provided in a later release.
|
|
|
|
For these reasons, in general it is best to compare two successive
|
|
versions of ICU4J against each other, rather than radically different
|
|
versions. A large number of changes can show up, many of which might
|
|
fall into these 'innocuous' categories.
|
|
|
|
ReportAPI can generate either plain text or html reports. Since it
|
|
only requires the data files and does not rely on JavaDoc, it is more
|
|
straightforward to invoke.
|
|
|
|
ReportAPI uses the file extension to determine how to uncompress the
|
|
api data files. It expects '.zip' for files that have been compressed
|
|
using zip, and '.gz' for files that have been compressed using gzip.
|
|
The GatherAPIData utility automatically appends these extensions when
|
|
compression is used.
|
|
|
|
API Data Files
|
|
|
|
API Data files for ICU4J 2.8 and 3.0 are in this directory. The
|
|
intent is to store data files for each release version of ICU4J, to
|
|
facilitate comparison using the ReportAPI tool. Of course, they can
|
|
always be regenerated using the GenerateAPI and the sources of a
|
|
particular ICU4J release.
|
|
|
|
The format of the API data file is straightforward. The first line of
|
|
the file is the header, successive lines are the api information.
|
|
Each line consists of a number of tokens, each followed by a
|
|
semi-colon (incuding the last token on the line).
|
|
|
|
The header line contains the version number, the 'name' of the version
|
|
of ICU4J represented by the file, and a 'base directory' field
|
|
(currently not fully implemented).
|
|
|
|
The following lines contain data generated by the APIInfo class, one
|
|
line per class or method. The tokens are status, visibility, static,
|
|
final, synchronized, abstract, type, package, containing class, name,
|
|
and 'signature' (which varies by the type of object). For classes,
|
|
the 'signature' is the immediate inheritance of the class. For
|
|
fields, the 'signature' is the type of the field. For methods, the
|
|
'signature' is the function signature. All fields are always present.
|
|
|
|
For more information, please see APIInfo.java.
|
|
|
|
-------
|