Author: [EMAIL PROTECTED]
Date: Tue Dec 9 12:58:53 2008
New Revision: 4284
Modified:
wiki/GwtJavaApiCompatibilityChecker.wiki
Log:
Edited wiki page through web user interface.
Modified: wiki/GwtJavaApiCompatibilityChecker.wiki
==============================================================================
--- wiki/GwtJavaApiCompatibilityChecker.wiki (original)
+++ wiki/GwtJavaApiCompatibilityChecker.wiki Tue Dec 9 12:58:53 2008
@@ -4,13 +4,13 @@
GWT Java API compatibility checker is a tool to check two versions of GWT
for API source compatibility. In particular, the tool can ensure that newer
releases of GWT are able to compile applications that previous versions
could compile. A user can also specify explicit API changes that must
be "white-listed," i.e., ignored by the tool. While we focus on GWT, this
tool works for any Java API.
= Background =
-A key advantage of GWT is that client applications (developed using GWT)
do not have to worry about supporting new browsers or newer versions of a
previously supported browser. GWT handles such issues. For example, when
IE8 will be released, client application developers will be able to easily
support IE8 by simply compiling their applications against a newer version
of GWT. In general, as GWT continues to improve both in the quality of the
JavaScript code it generates and the number of platforms it supports,
client application developers can tap into these improvements by simply
compiling the Java versions of their applications against the latest
version of GWT. For client application developers to be able to
successfully tap into these improvements, new GWT releases must
successfully compile applications that previous versions could compile. We
call this property API source compatibility.
+A key advantage of GWT is that client applications (developed using GWT)
do not have to worry about supporting new browsers or newer versions of a
previously supported browser. GWT handles such issues. For example, when
IE8 will be released, client application developers will be able to easily
support IE8 by simply compiling their applications against a newer version
of GWT. In general, as GWT continues to improve both in the quality of
the !JavaScript code it generates and the number of platforms it supports,
client application developers can tap into these improvements by simply
compiling the Java versions of their applications against the latest
version of GWT. For client application developers to be able to
successfully tap into these improvements, new GWT releases must
successfully compile applications that previous versions could compile. We
call this property API source compatibility.
As GWT's popularity increases, the challenge of maintaining GWT's API
source compatibility is going to increase due to two factors. First, the
GWT code is likely to become more complex over time as the number of
features and platforms it supports increases. Second, the number of
contributors to GWT is likely to increase as well. With increasing number
of contributors, the changes to the source code will increase in both
magnitude and number. Therefore it is desirable to automate the task of
checking API source compatibility.
-Other evolving APIs, most notably the Java language API, also face a
similar problem [1]. Almost all of these APIs aim for binary compatibility,
as specified in the Java language specification [2]. With binary
compatibility, the aim for a new API release is to ensure that the client
applications can use the class files of the new release in place of the
class files of the previous release. There is no recompilation involved.
Several tools exist for checking API binary compatibility [3, 4]. To the
best of our knowledge, no tool exists for checking API source compatibility.
+Other evolving APIs, most notably the Java language API, also face a
similar problem ![1]. Almost all of these APIs aim for binary
compatibility, as specified in the Java language specification ![2]. With
binary compatibility, the aim for a new API release is to ensure that the
client applications can use the class files of the new release in place of
the class files of the previous release. There is no recompilation
involved. Several tools exist for checking API binary compatibility [3, 4].
To the best of our knowledge, no tool exists for checking API source
compatibility.
Of course, there can be cases when breaking the API is necessary. To
handle these cases, the tool should support "white-lists." Specifying a
whitelist explicitly should force the developers to think twice before
breaking an API. The whitelist would also help client applications in
refactoring their code appropriately.
@@ -71,7 +71,8 @@
# Check compatibility: When ApiComptabilityChecker is provided a
configuration file with information about the two repositories, it checks
them for source compatibility and outputs the API difference. The API
difference is a list of API change messages, with each API change message
listed on a separate line. An API change message specifies two things: (i)
a java package, class, method, or field in the existing API, (ii) the
manner in which the API has changed. For example, an API change message
could be "java.net MISSING" indicating that the package java.net has been
removed. Each API change message is followed by an optional string
containing additional information about the API change.
-{{{ java ApiCompatibilityChecker configFile
+{{{
+java ApiCompatibilityChecker configFile
}}}
# Check compatibility with expected failures whitelisted: The tool can
handle a whitelist of API changes, specified in the "whitelist" section of
the config file. These changes are excluded from the output.
--~--~---------~--~----~------------~-------~--~----~
http://groups.google.com/group/Google-Web-Toolkit-Contributors
-~----------~----~----~----~------~----~------~--~---
