diff --git a/build.gradle b/build.gradle index 0905dec369..11c9997e6e 100644 --- a/build.gradle +++ b/build.gradle @@ -237,7 +237,7 @@ configure(rootProject) { apply plugin: "groovy" apply plugin: "io.spring.nohttp" - apply from: "${gradleScriptDir}/jdiff.gradle" + apply plugin: 'org.springframework.build.api-diff' apply from: "${gradleScriptDir}/docs.gradle" nohttp { diff --git a/buildSrc/README.md b/buildSrc/README.md index 2cdbf94905..7c722a3627 100644 --- a/buildSrc/README.md +++ b/buildSrc/README.md @@ -29,4 +29,19 @@ configurations are preferred. The `org.springframework.build.test-sources` updates `testCompile` dependencies to include the test source sets of `project()` dependencies. This plugin is used in the Spring Framework build -to share test utilities and fixtures amongst modules. \ No newline at end of file +to share test utilities and fixtures amongst modules. + +## API Diff + +This plugin uses the [Gradle JApiCmp](https://github.com/melix/japicmp-gradle-plugin) plugin +to generate API Diff reports for each Spring Framework module. This plugin is applied once on the root +project and create tasks in each framework module. Unlike previous versions of this part of the build, +there is no need for checking out a specific tag. The plugin will fetch the JARs we want to compare the +current working version with. You can generate the reports for all modules or a single module: + +``` +./gradlew apiDiff -PbaselineVersion=5.1.0.RELEASE +./gradlew :spring-core:apiDiff -PbaselineVersion=5.1.0.RELEASE +``` + +The reports are located under `build/reports/api-diff/$OLDVERSION_to_$NEWVERSION/`. \ No newline at end of file diff --git a/buildSrc/build.gradle b/buildSrc/build.gradle index 51631d39c3..09a31a0123 100644 --- a/buildSrc/build.gradle +++ b/buildSrc/build.gradle @@ -4,10 +4,20 @@ plugins { repositories { mavenCentral() + gradlePluginPortal() +} + +dependencies { + implementation "me.champeau.gradle:japicmp-gradle-plugin:0.2.8" + } gradlePlugin { plugins { + apiDiffPlugin { + id = "org.springframework.build.api-diff" + implementationClass = "org.springframework.build.api.ApiDiffPlugin" + } compileConventionsPlugin { id = "org.springframework.build.compile" implementationClass = "org.springframework.build.compile.CompilerConventionsPlugin" diff --git a/buildSrc/src/main/java/org/springframework/build/api/ApiDiffPlugin.java b/buildSrc/src/main/java/org/springframework/build/api/ApiDiffPlugin.java new file mode 100644 index 0000000000..0f281235ac --- /dev/null +++ b/buildSrc/src/main/java/org/springframework/build/api/ApiDiffPlugin.java @@ -0,0 +1,115 @@ +/* + * Copyright 2002-2019 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.springframework.build.api; + +import java.io.File; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.Collections; +import java.util.List; + +import me.champeau.gradle.japicmp.JapicmpPlugin; +import me.champeau.gradle.japicmp.JapicmpTask; +import org.gradle.api.Plugin; +import org.gradle.api.Project; +import org.gradle.api.artifacts.Configuration; +import org.gradle.api.artifacts.Dependency; +import org.gradle.api.plugins.JavaBasePlugin; +import org.gradle.api.plugins.JavaPlugin; +import org.gradle.api.tasks.TaskProvider; +import org.gradle.jvm.tasks.Jar; + +/** + * {@link Plugin} that applies the {@code "japicmp-gradle-plugin"} + * and create tasks for all subprojects, diffing the public API one by one + * and creating the reports in {@code "build/reports/api-diff/$OLDVERSION_to_$NEWVERSION/"}. + *

{@code "./gradlew apiDiff -PbaselineVersion=5.1.0.RELEASE"} will output the + * reports for the API diff between the baseline version and the current one for all modules. + * You can limit the report to a single module with + * {@code "./gradlew :spring-core:apiDiff -PbaselineVersion=5.1.0.RELEASE"}. + * + * @author Brian Clozel + */ +public class ApiDiffPlugin implements Plugin { + + public static final String TASK_NAME = "apiDiff"; + + private static final String BASELINE_VERSION_PROPERTY = "baselineVersion"; + + private static final List PACKAGE_INCLUDES = Collections.singletonList("org.springframework.*"); + + @Override + public void apply(Project project) { + if (project.hasProperty(BASELINE_VERSION_PROPERTY) && project.equals(project.getRootProject())) { + project.getPluginManager().apply(JapicmpPlugin.class); + project.getPlugins().withType(JapicmpPlugin.class, + plugin -> applyApiDiffConventions(project)); + } + } + + private void applyApiDiffConventions(Project project) { + String baselineVersion = project.property(BASELINE_VERSION_PROPERTY).toString(); + project.subprojects(subProject -> createApiDiffTask(baselineVersion, subProject)); + } + + private void createApiDiffTask(String baselineVersion, Project project) { + if (isProjectEligible(project)) { + JapicmpTask apiDiff = project.getTasks().create(TASK_NAME, JapicmpTask.class); + apiDiff.setDescription("Generates an API diff report with japicmp"); + apiDiff.setGroup(JavaBasePlugin.DOCUMENTATION_GROUP); + + apiDiff.setOldClasspath(project.files(createBaselineConfiguration(baselineVersion, project))); + TaskProvider jar = project.getTasks().withType(Jar.class).named("jar"); + apiDiff.setNewArchives(project.getLayout().files(jar.get().getArchiveFile().get().getAsFile())); + apiDiff.setNewClasspath(getRuntimeClassPath(project)); + apiDiff.setPackageIncludes(PACKAGE_INCLUDES); + apiDiff.setOnlyModified(true); + apiDiff.setIgnoreMissingClasses(true); + // Ignore Kotlin metadata annotations since they contain + // illegal HTML characters and fail the report generation + apiDiff.setAnnotationExcludes(Collections.singletonList("@kotlin.Metadata")); + + apiDiff.setHtmlOutputFile(getOutputFile(baselineVersion, project)); + + apiDiff.dependsOn(project.getTasks().getByName("jar")); + } + } + + private boolean isProjectEligible(Project project) { + return project.getPlugins().hasPlugin(JavaPlugin.class) + && !project.getName().equals("spring-core-coroutines") + && !project.getName().equals("spring-framework-bom"); + } + + private Configuration createBaselineConfiguration(String baselineVersion, Project project) { + String baseline = String.join(":", + project.getGroup().toString(), project.getName(), baselineVersion); + Dependency baselineDependency = project.getDependencies().create(baseline + "@jar"); + return project.getRootProject().getConfigurations().detachedConfiguration(baselineDependency); + } + + private Configuration getRuntimeClassPath(Project project) { + return project.getConfigurations().getByName(JavaPlugin.RUNTIME_CLASSPATH_CONFIGURATION_NAME); + } + + private File getOutputFile(String baseLineVersion, Project project) { + Path outDir = Paths.get(project.getRootProject().getBuildDir().getAbsolutePath(), + "reports", "api-diff", + baseLineVersion + "_to_" + project.getRootProject().getVersion()); + return project.file(outDir.resolve(project.getName() + ".html").toString()); + } + +} \ No newline at end of file diff --git a/gradle/jdiff.gradle b/gradle/jdiff.gradle deleted file mode 100644 index da454e62ab..0000000000 --- a/gradle/jdiff.gradle +++ /dev/null @@ -1,76 +0,0 @@ -/** - * 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 required - * @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 currentVersion = rootProject.version - def currentVersionRoot = rootProject.rootDir - - def oldVersion = System.getProperty("OLD_VERSION") - def oldVersionRoot = System.getProperty("OLD_VERSION_ROOT") - - def outputDir = "${rootProject.buildDir}/reports/jdiff/${oldVersion}_to_${currentVersion}" - - doLast { - if (oldVersion == null) - throw new IllegalArgumentException( - "Set OLD_VERSION property to indicate older of the two versions being compared") - 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, - source: "1.8", - verbose: "off", - stats: "on", - docchanges: "off") { - 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 deleted file mode 100644 index fab48ede1c..0000000000 --- a/gradle/jdiff/LICENSE.txt +++ /dev/null @@ -1,506 +0,0 @@ - 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 deleted file mode 100644 index 2d8649e544..0000000000 --- a/gradle/jdiff/Null.java +++ /dev/null @@ -1,9 +0,0 @@ -/** - * 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 deleted file mode 100644 index 430f2bffec..0000000000 --- a/gradle/jdiff/README-SPRING.txt +++ /dev/null @@ -1,6 +0,0 @@ -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 deleted file mode 100644 index caa85c5302..0000000000 --- a/gradle/jdiff/README.txt +++ /dev/null @@ -1,59 +0,0 @@ - - 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: -https://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://javadiff.sourceforge.net/ - -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 https://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 -https://wwws.sun.com/software/xml/developers/diffmk/ diff --git a/gradle/jdiff/antjdiff.jar b/gradle/jdiff/antjdiff.jar deleted file mode 100644 index 063dbee960..0000000000 Binary files a/gradle/jdiff/antjdiff.jar and /dev/null differ diff --git a/gradle/jdiff/background.gif b/gradle/jdiff/background.gif deleted file mode 100644 index e6d2dda389..0000000000 Binary files a/gradle/jdiff/background.gif and /dev/null differ diff --git a/gradle/jdiff/black.gif b/gradle/jdiff/black.gif deleted file mode 100644 index 185d95b110..0000000000 Binary files a/gradle/jdiff/black.gif and /dev/null differ diff --git a/gradle/jdiff/jdiff.html b/gradle/jdiff/jdiff.html deleted file mode 100644 index d242fb8a49..0000000000 --- a/gradle/jdiff/jdiff.html +++ /dev/null @@ -1,1032 +0,0 @@ - - - - -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. "https://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. "https://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

- -
- -
- -
- -

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. - - - -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 deleted file mode 100644 index 5fc7ed0209..0000000000 Binary files a/gradle/jdiff/jdiff.jar and /dev/null differ diff --git a/gradle/jdiff/jdiff_logo.gif b/gradle/jdiff/jdiff_logo.gif deleted file mode 100644 index d098485d3a..0000000000 Binary files a/gradle/jdiff/jdiff_logo.gif and /dev/null differ diff --git a/gradle/jdiff/new.gif b/gradle/jdiff/new.gif deleted file mode 100644 index c0ef7a4744..0000000000 Binary files a/gradle/jdiff/new.gif and /dev/null differ diff --git a/gradle/jdiff/xerces.jar b/gradle/jdiff/xerces.jar deleted file mode 100644 index e75d486c8d..0000000000 Binary files a/gradle/jdiff/xerces.jar and /dev/null differ