Home | History | Annotate | only in /external/icu/icu4j/tools/build
Up to higher level directory
NameDateSize
.classpath21-Oct-2016376
.project21-Oct-2016376
.settings/21-Oct-2016
build-tools-build.launch21-Oct-20161.8K
build.properties21-Oct-2016355
build.xml21-Oct-20162.3K
icu4j48.api3.gz21-Oct-201643.2K
icu4j49.api3.gz21-Oct-201645.4K
icu4j50.api3.gz21-Oct-201645.9K
icu4j51.api3.gz21-Oct-201646.7K
icu4j52.api3.gz21-Oct-201648.9K
icu4j53.api3.gz21-Oct-201649.8K
icu4j54.api3.gz21-Oct-201652.6K
icu4j55.api3.gz21-Oct-201653K
icu4j56.api3.gz21-Oct-201653.4K
manifest.stub21-Oct-2016701
README.txt21-Oct-20164.1K
src/21-Oct-2016
src8/21-Oct-2016

README.txt

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