diff --git a/build.gradle b/build.gradle index a54ec76fb2d..8d02ac6ffeb 100644 --- a/build.gradle +++ b/build.gradle @@ -659,6 +659,7 @@ configure(rootProject) { description = 'Spring Framework' apply plugin: 'docbook-reference' + apply from: "${gradleScriptDir}/jdiff.gradle" reference { sourceDir = file('src/reference/docbook') diff --git a/gradle.properties b/gradle.properties index eaa290f4b67..e062080ad35 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1 +1,2 @@ version=3.2.0.BUILD-SNAPSHOT +previousVersion=3.2.0.RC1 diff --git a/gradle/jdiff.gradle b/gradle/jdiff.gradle new file mode 100644 index 00000000000..fbce6e9e9b7 --- /dev/null +++ b/gradle/jdiff.gradle @@ -0,0 +1,74 @@ +/** + * Generate a JDiff report between the current version and an older version. + * + * Usage: + * gradle jdiff [-D OLD_VERSION=3.1.3.RELEASE] -D OLD_VERSION_ROOT=/path/to/3.1.3.RELEASE + * + * View generated report at: + * build/reports/jdiff/changes.html + * + * @param OLD_VERSION optional, defaulting to value of `previousVersion` in gradle.properties + * @param OLD_VERSION_ROOT required, typically pointing to a separate git clone dir + */ +task jdiff { + description = 'Generates a JDiff report' + group = 'Documentation' + + def jdiffHome = "${rootProject.rootDir}/gradle/jdiff" + + ant.taskdef( + name: 'jdiff', + classname: 'jdiff.JDiffAntTask', + classpath: "${jdiffHome}/antjdiff.jar") + + def previousVersion = rootProject.previousVersion + + def currentVersion = rootProject.version + def currentVersionRoot = rootProject.rootDir + + def oldVersion = System.getProperty("OLD_VERSION") ?: previousVersion + def oldVersionRoot = System.getProperty("OLD_VERSION_ROOT") + + def outputDir = "${rootProject.buildDir}/reports/jdiff/${oldVersion}_to_${currentVersion}" + + doLast { + if (oldVersionRoot == null) + throw new IllegalArgumentException( + "Set OLD_VERSION_ROOT property to indicate the root directory for ${oldVersion}") + + oldVersionRoot = new File(oldVersionRoot) + + ant.property(name: 'JDIFF_HOME', value: jdiffHome) + ant.mkdir(dir: outputDir) + ant.jdiff( + destdir: outputDir, + verbose: 'off', + stats: 'on', + docchanges: 'on') { + old(name: "Spring Framework ${oldVersion}") { + oldVersionRoot.eachDirMatch( { + def candidate = new File(it) + candidate.name.matches("org.springframework.*") || + candidate.name.matches("spring-.*") }) { match -> + match.eachDirRecurse { subdir -> + if (subdir.path ==~ '.*/src/main/java$') { + dirset(dir: subdir.path, includes: 'org/**') + } + } + } + } + 'new'(name: "Spring Framework ${currentVersion}") { + currentVersionRoot.eachDirMatch( { + def candidate = new File(it) + candidate.name.matches("org.springframework.*") || + candidate.name.matches("spring-.*") }) { match -> + match.eachDirRecurse { subdir -> + if (subdir.path ==~ '.*/src/main/java$') { + dirset(dir: subdir.path, includes: 'org/**') + } + } + } + } + } + } +} diff --git a/gradle/jdiff/LICENSE.txt b/gradle/jdiff/LICENSE.txt new file mode 100644 index 00000000000..fab48ede1c4 --- /dev/null +++ b/gradle/jdiff/LICENSE.txt @@ -0,0 +1,506 @@ + GNU LESSER GENERAL PUBLIC LICENSE + Version 2.1, February 1999 + + Copyright (C) 1991, 1999 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +[This is the first released version of the Lesser GPL. It also counts + as the successor of the GNU Library Public License, version 2, hence + the version number 2.1.] + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +Licenses are intended to guarantee your freedom to share and change +free software--to make sure the software is free for all its users. + + This license, the Lesser General Public License, applies to some +specially designated software packages--typically libraries--of the +Free Software Foundation and other authors who decide to use it. You +can use it too, but we suggest you first think carefully about whether +this license or the ordinary General Public License is the better +strategy to use in any particular case, based on the explanations below. + + When we speak of free software, we are referring to freedom of use, +not price. Our General Public Licenses are designed to make sure that +you have the freedom to distribute copies of free software (and charge +for this service if you wish); that you receive source code or can get +it if you want it; that you can change the software and use pieces of +it in new free programs; and that you are informed that you can do +these things. + + To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for +you if you distribute copies of the library or if you modify it. + + For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link other code with the library, you must provide +complete object files to the recipients, so that they can relink them +with the library after making changes to the library and recompiling +it. And you must show them these terms so they know their rights. + + We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + + To protect each distributor, we want to make it very clear that +there is no warranty for the free library. Also, if the library is +modified by someone else and passed on, the recipients should know +that what they have is not the original version, so that the original +author's reputation will not be affected by problems that might be +introduced by others. + + Finally, software patents pose a constant threat to the existence of +any free program. We wish to make sure that a company cannot +effectively restrict the users of a free program by obtaining a +restrictive license from a patent holder. Therefore, we insist that +any patent license obtained for a version of the library must be +consistent with the full freedom of use specified in this license. + + Most GNU software, including some libraries, is covered by the +ordinary GNU General Public License. This license, the GNU Lesser +General Public License, applies to certain designated libraries, and +is quite different from the ordinary General Public License. We use +this license for certain libraries in order to permit linking those +libraries into non-free programs. + + When a program is linked with a library, whether statically or using +a shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the +entire combination fits its criteria of freedom. The Lesser General +Public License permits more lax criteria for linking other code with +the library. + + We call this license the "Lesser" General Public License because it +does Less to protect the user's freedom than the ordinary General +Public License. It also provides other free software developers Less +of an advantage over competing non-free programs. These disadvantages +are the reason we use the ordinary General Public License for many +libraries. However, the Lesser license provides advantages in certain +special circumstances. + + For example, on rare occasions, there may be a special need to +encourage the widest possible use of a certain library, so that it becomes +a de-facto standard. To achieve this, non-free programs must be +allowed to use the library. A more frequent case is that a free +library does the same job as widely used non-free libraries. In this +case, there is little to gain by limiting the free library to free +software only, so we use the Lesser General Public License. + + In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of +free software. For example, permission to use the GNU C Library in +non-free programs enables many more people to use the whole GNU +operating system, as well as its variant, the GNU/Linux operating +system. + + Although the Lesser General Public License is Less protective of the +users' freedom, it does ensure that the user of a program that is +linked with the Library has the freedom and the wherewithal to run +that program using a modified version of the Library. + + The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +"work based on the library" and a "work that uses the library". The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. + + GNU LESSER GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License Agreement applies to any software library or other +program which contains a notice placed by the copyright holder or +other authorized party saying it may be distributed under the terms of +this Lesser General Public License (also called "this License"). +Each licensee is addressed as "you". + + A "library" means a collection of software functions and/or data +prepared so as to be conveniently linked with application programs +(which use some of those functions and data) to form executables. + + The "Library", below, refers to any such software library or work +which has been distributed under these terms. A "work based on the +Library" means either the Library or any derivative work under +copyright law: that is to say, a work containing the Library or a +portion of it, either verbatim or with modifications and/or translated +straightforwardly into another language. (Hereinafter, translation is +included without limitation in the term "modification".) + + "Source code" for a work means the preferred form of the work for +making modifications to it. For a library, complete source code means +all the source code for all modules it contains, plus any associated +interface definition files, plus the scripts used to control compilation +and installation of the library. + + Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running a program using the Library is not restricted, and output from +such a program is covered only if its contents constitute a work based +on the Library (independent of the use of the Library in a tool for +writing it). Whether that is true depends on what the Library does +and what the program that uses the Library does. + + 1. You may copy and distribute verbatim copies of the Library's +complete source code as you receive it, in any medium, provided that +you conspicuously and appropriately publish on each copy an +appropriate copyright notice and disclaimer of warranty; keep intact +all the notices that refer to this License and to the absence of any +warranty; and distribute a copy of this License along with the +Library. + + You may charge a fee for the physical act of transferring a copy, +and you may at your option offer warranty protection in exchange for a +fee. + + 2. You may modify your copy or copies of the Library or any portion +of it, thus forming a work based on the Library, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) The modified work must itself be a software library. + + b) You must cause the files modified to carry prominent notices + stating that you changed the files and the date of any change. + + c) You must cause the whole of the work to be licensed at no + charge to all third parties under the terms of this License. + + d) If a facility in the modified Library refers to a function or a + table of data to be supplied by an application program that uses + the facility, other than as an argument passed when the facility + is invoked, then you must make a good faith effort to ensure that, + in the event an application does not supply such function or + table, the facility still operates, and performs whatever part of + its purpose remains meaningful. + + (For example, a function in a library to compute square roots has + a purpose that is entirely well-defined independent of the + application. Therefore, Subsection 2d requires that any + application-supplied function or table used by this function must + be optional: if the application does not supply it, the square + root function must still compute square roots.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Library, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Library, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote +it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Library. + +In addition, mere aggregation of another work not based on the Library +with the Library (or with a work based on the Library) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may opt to apply the terms of the ordinary GNU General Public +License instead of this License to a given copy of the Library. To do +this, you must alter all the notices that refer to this License, so +that they refer to the ordinary GNU General Public License, version 2, +instead of to this License. (If a newer version than version 2 of the +ordinary GNU General Public License has appeared, then you can specify +that version instead if you wish.) Do not make any other change in +these notices. + + Once this change is made in a given copy, it is irreversible for +that copy, so the ordinary GNU General Public License applies to all +subsequent copies and derivative works made from that copy. + + This option is useful when you wish to copy part of the code of +the Library into a program that is not a library. + + 4. You may copy and distribute the Library (or a portion or +derivative of it, under Section 2) in object code or executable form +under the terms of Sections 1 and 2 above provided that you accompany +it with the complete corresponding machine-readable source code, which +must be distributed under the terms of Sections 1 and 2 above on a +medium customarily used for software interchange. + + If distribution of object code is made by offering access to copy +from a designated place, then offering equivalent access to copy the +source code from the same place satisfies the requirement to +distribute the source code, even though third parties are not +compelled to copy the source along with the object code. + + 5. A program that contains no derivative of any portion of the +Library, but is designed to work with the Library by being compiled or +linked with it, is called a "work that uses the Library". Such a +work, in isolation, is not a derivative work of the Library, and +therefore falls outside the scope of this License. + + However, linking a "work that uses the Library" with the Library +creates an executable that is a derivative of the Library (because it +contains portions of the Library), rather than a "work that uses the +library". The executable is therefore covered by this License. +Section 6 states terms for distribution of such executables. + + When a "work that uses the Library" uses material from a header file +that is part of the Library, the object code for the work may be a +derivative work of the Library even though the source code is not. +Whether this is true is especially significant if the work can be +linked without the Library, or if the work is itself a library. The +threshold for this to be true is not precisely defined by law. + + If such an object file uses only numerical parameters, data +structure layouts and accessors, and small macros and small inline +functions (ten lines or less in length), then the use of the object +file is unrestricted, regardless of whether it is legally a derivative +work. (Executables containing this object code plus portions of the +Library will still fall under Section 6.) + + Otherwise, if the work is a derivative of the Library, you may +distribute the object code for the work under the terms of Section 6. +Any executables containing that work also fall under Section 6, +whether or not they are linked directly with the Library itself. + + 6. As an exception to the Sections above, you may also combine or +link a "work that uses the Library" with the Library to produce a +work containing portions of the Library, and distribute that work +under terms of your choice, provided that the terms permit +modification of the work for the customer's own use and reverse +engineering for debugging such modifications. + + You must give prominent notice with each copy of the work that the +Library is used in it and that the Library and its use are covered by +this License. You must supply a copy of this License. If the work +during execution displays copyright notices, you must include the +copyright notice for the Library among them, as well as a reference +directing the user to the copy of this License. Also, you must do one +of these things: + + a) Accompany the work with the complete corresponding + machine-readable source code for the Library including whatever + changes were used in the work (which must be distributed under + Sections 1 and 2 above); and, if the work is an executable linked + with the Library, with the complete machine-readable "work that + uses the Library", as object code and/or source code, so that the + user can modify the Library and then relink to produce a modified + executable containing the modified Library. (It is understood + that the user who changes the contents of definitions files in the + Library will not necessarily be able to recompile the application + to use the modified definitions.) + + b) Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (1) uses at run time a + copy of the library already present on the user's computer system, + rather than copying library functions into the executable, and (2) + will operate properly with a modified version of the library, if + the user installs one, as long as the modified version is + interface-compatible with the version that the work was made with. + + c) Accompany the work with a written offer, valid for at + least three years, to give the same user the materials + specified in Subsection 6a, above, for a charge no more + than the cost of performing this distribution. + + d) If distribution of the work is made by offering access to copy + from a designated place, offer equivalent access to copy the above + specified materials from the same place. + + e) Verify that the user has already received a copy of these + materials or that you have already sent this user a copy. + + For an executable, the required form of the "work that uses the +Library" must include any data and utility programs needed for +reproducing the executable from it. However, as a special exception, +the materials to be distributed need not include anything that is +normally distributed (in either source or binary form) with the major +components (compiler, kernel, and so on) of the operating system on +which the executable runs, unless that component itself accompanies +the executable. + + It may happen that this requirement contradicts the license +restrictions of other proprietary libraries that do not normally +accompany the operating system. Such a contradiction means you cannot +use both them and the Library together in an executable that you +distribute. + + 7. You may place library facilities that are a work based on the +Library side-by-side in a single library together with other library +facilities not covered by this License, and distribute such a combined +library, provided that the separate distribution of the work based on +the Library and of the other library facilities is otherwise +permitted, and provided that you do these two things: + + a) Accompany the combined library with a copy of the same work + based on the Library, uncombined with any other library + facilities. This must be distributed under the terms of the + Sections above. + + b) Give prominent notice with the combined library of the fact + that part of it is a work based on the Library, and explaining + where to find the accompanying uncombined form of the same work. + + 8. You may not copy, modify, sublicense, link with, or distribute +the Library except as expressly provided under this License. Any +attempt otherwise to copy, modify, sublicense, link with, or +distribute the Library is void, and will automatically terminate your +rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses +terminated so long as such parties remain in full compliance. + + 9. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Library or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Library (or any work based on the +Library), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Library or works based on it. + + 10. Each time you redistribute the Library (or any work based on the +Library), the recipient automatically receives a license from the +original licensor to copy, distribute, link with or modify the Library +subject to these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties with +this License. + + 11. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Library at all. For example, if a patent +license would not permit royalty-free redistribution of the Library by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Library. + +If any portion of this section is held invalid or unenforceable under any +particular circumstance, the balance of the section is intended to apply, +and the section as a whole is intended to apply in other circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 12. If the distribution and/or use of the Library is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Library under this License may add +an explicit geographical distribution limitation excluding those countries, +so that distribution is permitted only in or among countries not thus +excluded. In such case, this License incorporates the limitation as if +written in the body of this License. + + 13. The Free Software Foundation may publish revised and/or new +versions of the Lesser General Public License from time to time. +Such new versions will be similar in spirit to the present version, +but may differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Library +specifies a version number of this License which applies to it and +"any later version", you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Library does not specify a +license version number, you may choose any version ever published by +the Free Software Foundation. + + 14. If you wish to incorporate parts of the Library into other free +programs whose distribution conditions are incompatible with these, +write to the author to ask for permission. For software which is +copyrighted by the Free Software Foundation, write to the Free +Software Foundation; we sometimes make exceptions for this. Our +decision will be guided by the two goals of preserving the free status +of all derivatives of our free software and of promoting the sharing +and reuse of software generally. + + NO WARRANTY + + 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE +LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A +FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF +SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Libraries + + If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of the +ordinary General Public License). + + To apply these terms, attach the following notices to the library. It is +safest to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + +Also add information on how to contact you by electronic and paper mail. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the library, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the + library `Frob' (a library for tweaking knobs) written by James Random Hacker. + + , 1 April 1990 + Ty Coon, President of Vice + +That's all there is to it! + + + + diff --git a/gradle/jdiff/Null.java b/gradle/jdiff/Null.java new file mode 100644 index 00000000000..019b71895da --- /dev/null +++ b/gradle/jdiff/Null.java @@ -0,0 +1,9 @@ +/** + * This class is used only as a "null" argument for Javadoc when comparing + * two API files. Javadoc has to have a package, .java or .class file as an + * argument, even though JDiff doesn't use it. + */ +public class Null { + public Null() { + } +} diff --git a/gradle/jdiff/README-SPRING.txt b/gradle/jdiff/README-SPRING.txt new file mode 100644 index 00000000000..430f2bffec1 --- /dev/null +++ b/gradle/jdiff/README-SPRING.txt @@ -0,0 +1,6 @@ +This distribution of JDiff 1.1.1 is included in the Spring Framework build +because JDiff has a hard requirement on a JDIFF_HOME directory containing +jdiff.jar and xerces.jar as well as other presentation resources. + +The actual generation of JDiff reports is driven by the `jdiff` task declared +in build.gradle in the project root. diff --git a/gradle/jdiff/README.txt b/gradle/jdiff/README.txt new file mode 100644 index 00000000000..9f7529e2864 --- /dev/null +++ b/gradle/jdiff/README.txt @@ -0,0 +1,59 @@ + + JDiff Doclet + ------------ + + Matthew Doar + mdoar@pobox.com + + +The JDiff doclet is used to generate a report describing the +difference between two public Java APIs. + +The file jdiff.html contains the reference page for JDiff. The latest +version of JDiff can be downloaded at: +http://sourceforge.net/projects/javadiff + +To use the Ant task on your own project, see example.xml. More examples +of using JDiff to compare the public APIs of J2SE1.3 and J2SE1.4 can +be seen at http://www.jdiff.org + +For an example with the source distribution, run "ant" and +look at the HTML output in ./build/reports/example/changes.html +The page at ./build/reports/example/changes/com.acme.sp.SPImpl.html +shows what a typical page of changes looks like. + +System Requirements +------------------- + +JDiff has been tested with all releases of Java since J2SE1.2 but +releases of JDiff after 1.10.0 focus on JDK1.5. + +License +------- + +JDiff is licensed under the Lesser GNU General Public License (LGPL). +See the file LICENSE.txt. + +Acknowledgements +---------------- + +JDiff uses Stuart D. Gathman's Java translation of Gene Myers' O(ND) +difference algorithm. + +JDiff uses Xerces 1.4.2 from http://www.apache.org. + +JDiff also includes a script to use the classdoc application from +http://classdoc.sourceforge.net or http://www.jensgulden.de, by Jens +Gulden, (mail@jensgulden.de), to call a doclet such as jdiff on a .jar +file rather than on source. + +Many thanks to the reviewers at Sun and Vitria who gave feedback on early +versions of JDiff output, and also to the distillers of Laphroaig, and to +Arturo Fuente for his consistently fine cigars which helped inspire +much of this work. + + +Footnote: + +If you are looking for a generalized diff tool for XML, try diffmk from +http://wwws.sun.com/software/xml/developers/diffmk/ diff --git a/gradle/jdiff/antjdiff.jar b/gradle/jdiff/antjdiff.jar new file mode 100644 index 00000000000..063dbee9600 Binary files /dev/null and b/gradle/jdiff/antjdiff.jar differ diff --git a/gradle/jdiff/background.gif b/gradle/jdiff/background.gif new file mode 100644 index 00000000000..e6d2dda3897 Binary files /dev/null and b/gradle/jdiff/background.gif differ diff --git a/gradle/jdiff/black.gif b/gradle/jdiff/black.gif new file mode 100644 index 00000000000..185d95b110b Binary files /dev/null and b/gradle/jdiff/black.gif differ diff --git a/gradle/jdiff/jdiff.html b/gradle/jdiff/jdiff.html new file mode 100644 index 00000000000..5c46f967b9e --- /dev/null +++ b/gradle/jdiff/jdiff.html @@ -0,0 +1,1032 @@ + + + + +JDiff User Documentation + + + + + + + +
+JDiff Logo SourceForge Logo
+ + +
+

JDiff User Documentation


+
+ +
+JDiff is a Javadoc doclet which generates an +HTML report of all the packages, classes, constructors, methods, and +fields which have been removed, added or changed in any way, including +their documentation, when two APIs are compared. This is very useful +for describing exactly what has changed between two releases of a +product. Only the API (Application Programming Interface) of each +version is compared. It does not compare what the source code does +when executed. +
+ +
+

CONTENTS

+ +
+ + +

OVERVIEW

+ +
+The basic sequence of operations is to run JDiff on one set of source +files to create an XML file which represents the API for that version +of a product. Then JDiff is run again on another set of source files +to create an XML file which represents the API for the next version of +a product. Finally, JDiff compares the two APIs as represented in the +XML files and generates an HTML report which describes the differences +between the two APIs, together with comments describing the reasons +for the differences. This whole process can be executed as separate +Javadoc steps (either from Ant or the command line) or by simply using +the Ant JDiff task provided. +
+ +
+The results are written into a file called changes.html, +with more files in a subdirectory called changes. These +files can contain links to existing Javadoc documentation. A CSS +stylesheet is also generated in the file +stylesheet-jdiff.css, and this uses a background image in +background.gif. These are the only files which usually +need to be shipped with a product to include a report of what has +changed since the previous release. If the -stats +option was used, then the file black.gif should also be +shipped. +
+ +
+There is a working example of how to use JDiff in the examples +directory of the source distribution. +
+ +
+ + +

INSTALLATION

+ +
+Unpack the jdiff-1.1.1.zip file. This will produce a directory named +"jdiff-1.1.1" containing all that is necessary to use JDiff to produce +your own reports. See the file "example.xml" in that directory for an +example of how to use the Ant JDiff task. The file "jdiff.html" +contains more information about using JDiff. +
+ +
+If you are using the complete source distribution, then you should be +able to simply type "ant" at the top-level to produce a working +example report. +
+ +
+The Ant JDiff task needs Ant 1.6.1 to work correctly. Using Ant +1.5 will produce the error: +
+Error: two projects are needed, one <old> and one <new>
+
+
+ +
+No Windows registry entries are changed by JDiff. To remove JDiff, +simply delete the directory where it is was unpacked. +
+ +
+ +

SYNOPSIS

+ +
+The Ant JDiff task has the following parameters: +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
destdirThe location where the JDiff report will be generated. Defaults to a directory "jdiff_report" in the directory from where Ant was executed.No
statsGenerate an HTML page of statistical information about the + differences between the two APIs. Defaults to "off".No
docchangesEnables comparison of Javadoc documentation. Defaults to "off".No
verboseIncrease the logging vebosity of the task. Defaults to "off".No
+
+ +
+Parameters specified as nested elements +
+ +
+The old and new elements are used to describe the projects to be compared. +
+ +
+ + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
nameThe name of the project, e.g. "My Project Version 1". The name, with spaces replaced by underscores, is used as the name of the XML file in destdir, +which is generated by JDiff to represent the structure of the source files of this project.Yes
javadocThe location of a Javadoc report for this project. If this attribute is not used, then a Javadoc report for the project will be generated in a subdirectory named name in destdir.No
+ +
+ +
+Note: the old and new elements only have DirSet nested elements, not FileSet ones. +
+ +
+The complete list parameters that can be passed to the JDiff doclet, +either through the Ant Javadoc task or directly at the command line, +is as follows: +
+ +
+javadoc -doclet jdiff.JDiff -docletpath jdiff.jar
+ [-apiname <API name>]
+ [-apidir <optional directory where the API XML file is to be placed>]
+ [-oldapi <name of old API>]
+ [-oldapidir <optional directory where the old API XML file is located>]
+ [-newapi <name of new API>]
+ [-newapidir <optional directory where the new API XML file is located>]
+ [-sourcepath <source path>]
+ [-javadocnew <javadoc files location for the new API>]
+ [-javadocold <javadoc files location for the old API>]
+ [-baseURI <base>]
+ [-excludeclass <exclusion level>]
+ [-excludemember <exclusion level>]
+ [-nosuggest <suggestion level>]
+ [-firstsentence]
+ [-docchanges]
+ [-checkcomments]
+ [-packagesonly]
+ [-showallchanges]
+ [-retainnonprinting]
+ [-excludetag <exclude tag>]
+ [-stats]
+ [-windowtitle <text>]
+ [-doctitle <HTML text>]
+ [-version]
+ [-help]
+
+ +
+NOTE: Either -apiname, or both -oldapi and +-newapi must be used. All other arguments are optional. +
+ +
+The -d directory argument works just as with Javadoc, redirecting +the HTML output to the given directory. +
+ +

The arguments for the JDiff doclet are:

+
+
+ -apiname <API name>
+
+ Define the name which will be associated + with the specified API. If the name which is given here has space + characters, they will be + replaced by underscore characters. This name with no spaces is used as the name of the XML + file. It is also written into the XML file as an attribute of the top + element. + E.g. "SuperProduct 1.0" generates an XML file named + "SuperProduct_1.0.xml". + The XML file is always generated in the current directory, unless + overridden by the -apidir argument. +
+ +
+ -oldapi <name of old API>
+
+ The name of the old or previous version of an + API or product, e.g. "SuperProduct 1.0", which is to be one of the + APIs compared. + This name is the name which was given to -apiname when + the XML file was generated. +
+ +
+ -newapi <name of old API>
+
+ The name of the new or later version of an + API or product, e.g. "SuperProduct 2.0", which is to be one of the + APIs compared. + This name is the name which was given to -apiname when + the XML file was generated. +
+ +
+ -apidir <API directory>
+
+ Defines the directory where the API XML file is to be placed. Used in + conjunction with the -apiname argument. +
+ +
+ -oldapidir <old API directory>
+
+ Defines the directory where the XML file for the old API is located. + Used in conjunction with the -oldapi argument. Default is the current + directory. +
+ +
+ -newapidir <new API directory>
+
+ Defines the directory where the XML file for the new API is located. + Used in conjunction with the -newapi argument. Default is the current + directory. +
+ +
+ -sourcepath <source path>
+
+ Define the path to the set of Java source + files (the API) + to be scanned, e.g. examples/SuperProduct1.0. The + slashes in this argument should match the local architecture. +
+ +
+ -javadocnew <javadoc files location for the new API>
+
+ The location of existing Javadoc files + for the new API, e.g. "http://java.sun.com/j2se/1.5.0/docs/api/" for the + public documentation for J2SE1.5.0. The default value is "../", which implies + that the documentation directory generated by Javadoc is at the same level as + the "changes.html" file generated by JDiff. Slashes are always + forward in the argument, since this is an HTML link. The argument + should also always end in a forward slash. If a relative value is + given, it should be relative to files in the "changes" directory + generated by JDiff. +
+ +
+ -javadocold <javadoc files location for the old API>
+
The location of existing + Javadoc files for the old API, e.g. "http://java.sun.com/j2se/1.5.0/docs/API/" + for the public documentation for J2SE1.5.0. The default value is null, which + results in no links to Javadoc-generated documentation for the previous + release. Slashes are always forward in the argument, since this is an HTML + link. The argument should also always end in a forward slash. If a relative + value is given, it should be relative to files in the "changes" directory + generated by JDiff. +
+ +
+ + -baseURI <base>
+
+ Use \"base\" as the base location of the various DTDs used by + JDiff. For example, -baseURI "file:///C:/jdiff/lib" would cause + the XML parser to use the copies which are shipped in the + lib directory, if JDiff is installed in + C:\jdiff. Note that there are three forward slashes + after "file:". +
+ +
+ -excludeclass <exclusion level>
+
+ This can be set to "public", + "protected", "package", or "private". If it is set to "protected", only + classes which are public or protected will be shown. If it is set to + "public", then only public classes are shown. The default is + "protected". If this is changed, the Javadoc -private + argument must also be passed to Javadoc. +
+ +
+ -excludemember <exclusion level>
+
+ This can be set to "public", + "protected", "package", or "private". If it is set to "protected", only + members (constructors, methods and fields) which are public or protected will be shown. If it is set to + "public", then only public members are shown. The default is + "protected". + If this is changed, the Javadoc -private + argument must also be passed to Javadoc. +
+ +
+ -firstsentence
+
+ This argument causes JDiff to save only the first sentence of each + Javadoc comment as part of + the API. This is only necessary when the XML file representing the + API is being generated. See -docchanges for how to + note documentation changes as differences.
+
+ +
+ -docchanges
+
+ This argument enables comparison of Javadoc documentation. + By default, changes in the saved Javadoc documentation + are not noted as changes (or as removals and related + additions). See -firstsentence option for how to compare just + the first sentence in Javadoc documentation. +
+ +
+ -nosuggest <suggestion level>
+
+ This can be set to "all", "remove", "add", + or "change". The effect of setting this to "all" is to stop comments + for any changes at all being suggested. Any comments which are to + appear in the report must then be written by the user (see below). + If it is set to "change", then + comments will not be suggested for changes, but will be suggested for + removals and additions. The default is that comments are suggested for + all possible places. +
+ +
+ -checkcomments
+
+ If this argument is used, JDiff + will warn the user when the report is generated if there are comments + which do not end in a period, question mark or exclamation mark. +
+ +
+ -packagesonly
+
+ If this argument is used, JDiff + will not scan classes specified on the command line. This should + only need to be used with the "jdiffjar" script, when + comparing Jar files. + If this options is not used when comparing Jar files, duplicate + classes with no packages ("anonymous" classes) may be + wrongly reported by JDiff. +
+ +
+ -showallchanges
+
+ If this argument is used, JDiff will show changes in + native and synchronized modifiers. See here for why these are not shown by default. +
+ +
+ -retainnonprinting
+
+ Retain non-printable characters + in comments. By default, JDiff removes non-printable characters + from comments which it uses. + This should only really be necessary if the first line of a + comment has used explicit Unicode character escape sequences which + cannot be printed, or more importantly for JDiff, read in from XML. + If this option is used, JDiff may fail to read in an XML + file, and exit with an error message about "an invalid XML character (Unicode: + 0x....)" on a certain line in the file. Turning off this option does + make creating large XML files a little faster. +
+ +
+ -excludetag <exclude tag>
+
+ The argument passed in with this causes + JDiff to ignore program elements (packages, classes, constructors, + methods, fields) which contain the given exclude tag in their comment blocks, + e.g. " @exclude", " @docset Internal". The extra space in front of "@" is + to stop Javadoc from expanding the name into a file containing commands on + the compile line. White space is trimmed off before the string is used. + + Another solution to passing "@" as part of an argument is to pass @foo, + and then create a file named foo, containing + -excludetag @exclude. + +
+ +
+ -stats
+
+ Generate an HTML page of statistical information about the + differences between the two APIs. +
+ +
+ -windowtitle <text>
+
+ Specify the title used in the browser window for the report. + By default, this is + "API Differences Between <name of old API> and + <name of new API>". +
+ +
+ -doctitle <HTML text>
+
+ Specify the title used on the first page of the report. + By default, this is + "API Differences Between <name of old API> and + <name of new API>". +
+ +
+ -version
+
+ Display the version of JDiff. +
+ +
+ -help
+
+ Display the usage summary for JDiff. +
+
+ +
+ +

OUTPUT

+ +
+
    +
  • Interfaces appear in italics, just as in Javadoc documentation.
    • +
  • When a package or class appears in bold, it has been added in +the new version or API.
    • +
  • When a package or class appears struck through, it has been removed in +the new version or API.
    • +
  • When a constructor is added, two entries are added to the "All +Differences" index: one for the addition of a new constructor, and +one for the change of the class. The constructor entry has +"constructor" after it.
    • +
  • There are some complex changes which can occur between versions, for example, when two or more methods with the same name change simultaneously, or when a method or field is moved into or from a superclass. +In these cases, the change will be seen as a removal and an addition, rather than as a change. Unexpected removals or additions are often part of one of these type of changes.
    • +
  • With large packages, it is often necessary to change the memory parameters for +Javadoc, e.g. pass in -J-Xmx128m to Javadoc.
    • +
  • The api.xsd template describes the format of the XML +for the APIs, and the comments.xsd template describes the format +of the XML for the comments. The API template is independent of any +related work at Sun, but the intention is to adopt whatever becomes +the de facto standard in the future, whilst retaining backward +compatibility. To enable validation, set the boolean validateXML in +the file XMLToAPI.java and recompile.
    • +
  • Comments in the comments XML file do get reordered during +regeneration. This is harmless.
    • +
+
+ +
+ +

ADDING COMMENTS TO A REPORT

+ +
+Comments can be added to a report by using a text editor to add text +to the "user_comments_X_to_Y.xml" file, where "X" and "Y" are the +names of the two APIs being compared. This file is automatically regenerated +each time the report is generated. +If the -d directory argument is used, the user comments XML +file also appears, and is expected, in the named directory. + +

Comments which become unused are +moved to the end of the file and placed inside XML comments. +

+ +
The text which is added can be HTML text if necessary, but if the + HTML is incorrect, JDiff may fail to read the comments file and exit. Note that + the required HTML is in fact XHTML. Since this HTML is stored in an XML document, single tags without their closing ("slash") element are not permitted. + For example, most browsers permit HTML which looks like "<p>Here is some + text.", with no closing tag. XML requires that either a closing tag exists ("</p>"), + or that the single tag is closed, e.g. "<p/>Here is some text.". +HTML p, br and hr tags can be single, due to common usage. +
+ +
+To write comments for a particular removal, addition or change in the +JDiff-generated report, edit the comments XML file. Your changes will +be automatically incorporated into a new version of this file when the +report is next generated. Search the file for the identifier for the +particular removal, addition or change, using the package name, class +name and member name to find the identifier. Alternatively, look at +the HTML source of a report and note the identifier (an HTML named anchor) +near the intended place for the comment. +
+ +
+Adding links to comments can be accomplished in two ways: with the {@link} Javadoc tag, or by using HTML links directly. + +
    + +
  • +To link to a class, use the package and class name, e.g. {@link +packagename.classname}. +
    • + +
  • +To link to a specific method in a class' HTML page, use the package, +class name, a pound sign, and then the method and parameters, or () +e.g. {@link packagename.classname#methodname(params)}. +
    • + +
  • +To link to a specific constructor in a class' HTML page, use the package, +class name, a pound sign, and then the classname and parameters, or () +e.g. {@link packagename.classname#classname(params)}. +
    • + +
  • +To link to a specific field in a class' HTML page, use the package, +class name, a pound sign, and then the name of the field +e.g. {@link packagename.classname#fieldname}. +
    • + +
+ +Alternatively, you can use an explicit HTML +<a> element. e.g. +<a href="packagename.classname.html#methodname">link text<a>. +The specific HTML named anchor can be found by looking at the HTML +source of a report. +
+ +
+Sometimes you may want to have the same comment text appear in +multiple places in the report. You can do this by having multiple +<identifier> elements in a single <comment> element. This +grouping does not persist after the comments file is regenerated. +
+ +
+The first sentence from a comment in the source code for an element is +available in the comments XML file by using the @first tag. This tag +will be replaced (once) in the comments in the report by the first +sentence from the appropriate Javadoc comment. +
+ +

+ +

TROUBLESHOOTING

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PROBLEMPOSSIBLE SOLUTION
Error: two projects are needed, one
+<old> and one <new>
The Ant JDiff task needs Ant 1.6.1 to work correctly
You are not connected to the Internet, or are behind a firewallSee the documentation for how to use + the -baseURI + optionThis only applies to generating JDiff output, + not to viewing it.
No changes are seen in the report.By default, Javadoc and JDiff only show public + and protected classes and members.
No changes seen for package and private classes.Enable both the correct Javadoc visibility level + (-public, -protected, -package, -private) and the correct JDiff + visibility level (-excludeclass, -excludemember).
No comments were inserted for packages.You need to use the -sourcepath argument to + locate the source code files, so that + JDiff can deduce where the package.html file with + comments about the package may be. If no package.html + file exists or can be found, then no comments can be suggested + for packages. Of course, comments can still be + added by hand.
JDiff takes a long time to load XML, or throws + java.net.NoRouteToHostException: Operation timed out.The validation portion of loading the XML file + currently requires the ability to make an HTTP connection. Check + your network and try again, or see the -baseURI + option and the next suggestion.
From behind a firewall, + + JDiff fails to load one of the required XML DTD files.Use the following settings to tell the Java2 VM + that you are behind a firewall:
+ java -DproxySet=true -DproxyHost=PROXYSERVER -DproxyPort=PORT
+ where PROXYSERVER is the hostname or IP address of + your proxy server, and PORT is the port number of the + proxy server.

+ The other alternative is to use the local copies of the required + files by using the option -baseURI when generating the API XML + files. For example, -baseURI "file:///C:/jdiff/lib" would cause + the XML parser to use the copies which are shipped in the + lib directory, if JDiff is installed in + C:\jdiff. Note that there are three forward slashes + after "file:". + The -baseURI approach has the advantage that it + requires no connectivity to the Internet to be able to run JDiff. +
JDiff fails to handle assert in J2SE1.4Be sure to use the -source 1.4 argument to + Javadoc to handle assertions present in J2SE1.4 source code. +
Using an XML parser other than XercesSet the org.xml.sax.driver system property to + the name of the XML parser class which you wish to use. Setting a system + property is usually done by passing -Dname=value to the JVM. + To cause Javadoc to pass an argument to the underlying JVM, use + -J-Dname=value. To pass an argument to Javadoc from within + an ANT Javadoc task, use the additionalparam attribute, e.g. + additionalparam="-J-Dorg.xml.sax.driver=com.example.my.driver" +
Comparing Jar files results in duplicate class + changes being reported.Be sure to use the -packagesonly + option when using Jar files as the input to JDiff. You should not + need to use -packagesonly otherwise. +
Documentation difference page becomes all changes + part way through.This problem can occur if incorrect HTML is + written in the new documentation. JDiff shows this HTML on the + documentation difference page, and can cause entries later on in + the page to be displayed incorrectly. + +

One solution is to edit the documentation difference page by + hand, but the better solution is to fix the offending HTML in the + new source code. +

The background color of my HTML report is not correct.Check that the file background.gif from the lib is in the same directory as the changes.html file. +
The names of exceptions are too long in the HTML report.To use short names for exceptions, set the + showExceptionTypes boolean to false in + XMLToAPI.java file and recompile. +
+
+ +
+ +

ERRORS AND WARNING MESSAGES

+ +
+The warnings and error messages which can be generated by JDiff are as +follows: +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ERROR MESSAGEPOSSIBLE CAUSE
Error: unknown element type.The XML file contains an element tag which the + current version of JDiff cannot recognize. This may occur if an + older version of JDiff is used with XML files generated by a newer + version.
Error: IO Error while attempting to create X.Java was unable to open a file for writing. May + occur if the user does not have write permission for the current + directory.
Error: no identifier found in the comments XML file.The XML file for the comments for the report must + contain an identifier to indicate which report of differing APIs + these comments are written for.
Error: unknown program element type.Internal JDiff error.
Error: could not create the subdirectory X.Java was unable to create a directory. May + occur if the user does not have write or execute permission for the current + directory.
Error: file X does not exist for the [old|new] API.The XML files corresponding to the names given to + -oldapi and -newapi are not in the + current directory. This may be because the XML files have not yet been + generated, or were generated elsewhere.
+ It can also occur if the + XML file was generated with one API identifier, and is now being + read in with another identifier. Either use the same identifier, + or change the <api> name element value in the XML file to the new + API identifier.
Error: no API identifier found in the XML file X.The given XML file does not have an identifier in + it, probably due to manual modification.
Error: no packages found in the APIs.JDiff was unable to find any packages in the + arguments given to Javadoc.
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
WARNING MESSAGEPOSSIBLE CAUSE
Warning: illegal string found in text. Ignoring the comment.The suggested comments from Javadoc are stored in + XML files in a CDATA element, which permits every string except .
Warning: no difference between the APIs.There was no difference between the APIs. You are + probably comparing two identical XML files.
Warning: no classes found in the package X.A package without classes was encountered.
Warning: change from deprecated to undeprecated for class X.A class changed from being deprecated to being + undeprecated in the next release. This is usually either poor + software design or a misplaced @deprecated Javadoc tag.
Warning: change from deprecated to undeprecated + for a constructor in class X.A constructor changed from being deprecated to being + undeprecated in the next release. This is usually either poor + software design or a misplaced @deprecated Javadoc tag.
Warning: change from deprecated to undeprecated for method X.A method changed from being deprecated to being + undeprecated in the next release. This is usually either poor + software design or a misplaced @deprecated Javadoc tag.
Warning: text of comment does not end in a period.Generated when the -checkcomments is + used. The suggested comment does not end in a period, question mark or exclamation mark.
Warning: N identical ids in the existing comments file. Using the first instance.The comments file contains comment for multiple + places in the report, but N of the identifiers for the comment + are non-unique.
Warning: incorrectly formatted @link in text.JDiff was unable to parse the @link in the + suggested comment.
Warning: comment com.acme.sp is no longer used.The comment in the comments file intended for the + given element is no longer needed, since the element is no longer + part of the changes between the APIs. The comment will be moved to + the end of the comments file and preserved, but not used.
Warning: API identifier in the comments XML file differs from the name of the file.The comments file keeps track of which APIs it is + to be used for, and has detected a mismatch with the names of the + current APIs.
Warning: multiple @deprecated tags found in comments for X. Using the first one only.A comment with more than one @deprecated tag was + encountered in the source code. This is considered poor Javadoc style.
Warning: @ tag seen in comment.An @ tag other than @link has somehow made its + way into a suggested comment. This should not occur, but can be + remedied by editing the comments file to use a different comment.
Warning: duplicate class : X found. Using the first instance only.Multiple instances of the same fully qualified + class name were found in the API XML file. Most likely caused by + manual modification of the file after it was generated.
Warning: missing @since tagA class, constructor, method or field was added + in the later API but no @since tag was found in the Javadoc + comment. This information is logged into a file + missingSinces.txt in the same directory as + changes.html. This file is informational only. The + boolean to control this behaviour is in the source file + HTMLIndexes.java. +
Warning: API identifier in the XML file X differs from the name of the file Y.The name given to -apiname when the XML file + is generated is embedded in the XML file as a top-level attribute. This + warning suggests that the XML file has been modified by hand, but that + report generation should proceed using the new API identifier.
+
+ +
+ +

DIFFERENCE STATISTICS

+
+During the generation of a report, JDiff also reports a percentage +difference between the two APIs being compared, e.g. "Approximately +10% difference between the APIs". This statistic is calculated in the +following way: + +
 
+Percentage change = 100 * (added + removed + 2*changed)
+                    -----------------------------------
+                    sum of public elements in BOTH APIs
+
+ +So if there are 15 packages in the old API, and 2 of these are removed, +and 17 packages in the new API, 1 of which is newly added, and only 3 +of which have changed, then the simple percentage difference would be: + +
+100 * (1 + 2 + 2*3)/ (15 + 17) = 28%
+
+ +A change of 100% means that there are no packages in common between +the two APIs. A change of 0% indicates that nothing changed between +the two APIs. This formula is applied recursively in JDiff for classes +and their members. That is, the value for the number of packages +changed is not an integer, but instead is the value obtained by +applying the same formula to the all the classes in the changed +packages, and then to all the members of the changed classes. + This results in a lower, but more accurate, percentage difference. +The percentage difference value does not appear anywhere in the HTML +report files generated by JDiff. +The test suite for JDiff v1.0 had a difference value of approximately 63%. +A real-world value is the value for the differences between J2SE1.2 and +J2SE1.3, which is approximately 8%. +
+ +
+ +

LIMITATIONS

+
+
    +
  1. While Java is highly backward compatible, so that, for example, + the XML for a +J2SE1.2 application can be generated using JDiff with J2SE1.3, there +are a few cases where classes will appear in the XML of the API which are +not present in the source code. These classes appear to be inserted by + javac or javadoc. An example of this is the class +java.awt.Robot, which is inserted into the XML for +J2SE1.2 if javadoc in J2SE1.3 is used, but not does not appear in + the XML if javadoc in J2SE1.2 is used.
    +To avoid these (rare) cases, it is recommended that you use the same version +of the J2SE that the application was written for.
    2. +
  2. JDiff does not tell you how two Javadoc web pages differ in layout, though +it can tell you how the content has changed. +Nor does it +compare what the methods in an API do; if JDiff could tell you what had changed about the way two +versions of an API execute, the Halting +Problem would be solved, and our lives would be very different.
    3. +
  3. On a P3 450MHz machine, to scan all of the J2SE Java +and javax packages and generate XML takes about 2 minutes +per version. To generate a report from the XML files takes about 30s
    4. +
+
+ +
+ +

FURTHER READING

+ +
+ + +
+ +
+
+This software comes with absolutely NO WARRANTY. See the LGPL in the file LICENSE.txt for +details. +
+ +

+ +Copyright © 2001-2007 Matthew B. Doar
+ +

+ + + diff --git a/gradle/jdiff/jdiff.jar b/gradle/jdiff/jdiff.jar new file mode 100644 index 00000000000..5fc7ed0209d Binary files /dev/null and b/gradle/jdiff/jdiff.jar differ diff --git a/gradle/jdiff/jdiff_logo.gif b/gradle/jdiff/jdiff_logo.gif new file mode 100644 index 00000000000..d098485d3a4 Binary files /dev/null and b/gradle/jdiff/jdiff_logo.gif differ diff --git a/gradle/jdiff/new.gif b/gradle/jdiff/new.gif new file mode 100644 index 00000000000..c0ef7a4744c Binary files /dev/null and b/gradle/jdiff/new.gif differ diff --git a/gradle/jdiff/xerces.jar b/gradle/jdiff/xerces.jar new file mode 100644 index 00000000000..e75d486c8d9 Binary files /dev/null and b/gradle/jdiff/xerces.jar differ