What checks are necessary to ensure GWT source compatibility?

[Alex Pantaleev]

Hi folks,

I am a Summer of Code participant working on a source compatibility
tool for the GWT.

The tool is described at http://code.google.com/p/google-web-toolkit/wiki/GWT_GSoC
. Initial ideas, which I already implemented with reflection, include:

* Compares the "footprints" of two packages, identifying
differences, such as:
o Added or deleted methods/fields
o New/missing interfaces
o Visibility changes on members (such as from going from
public to protected)

The tool will produce XML output that can later be read by other
tools, or transformed to other formats with XSLTs. Also, reflection
was used for a quick-and-dirty solution that only produces some output
to test. The bulk of the tool will be based on ASTs.

Can you think of additional differences to be identified that will be
useful to GWT users? Do you think there are compatibility problems
that can only be detected by analyzing JSNI code? Is XML a good output
format?

Thanks,
Alex

[BobV]

On 6/15/07, Alex Pantaleev <zylg...@gmail.com> wrote:
> Can you think of additional differences to be identified that will be
> useful to GWT users? Do you think there are compatibility problems
> that can only be detected by analyzing JSNI code? Is XML a good output
> format?

@gwt.typeArgs and other annotations in the JavaDoc prefix that aren't
explicit JavaDoc commands.

If you want to build a dependency map of functions to invocation
targets and fields, you would definitely need to analyze JSNI. I'd
imagine that you could pull quite a bit of this out of the GWT
compiler.

XML can be a fine choice for the container. Just make sure to think
about schema design and don't use XML to reinvent property files :-)

--
Bob Vawter
Google Web Toolkit Team

[Alex Pantaleev]

Thank you for the suggestion. I am looking at the GWT compiler in
order to extract its AST functionality, but I don't want to do some
kind of unnecessary and sophisticated static analysis - extracting and
comparing differences is fine, at least as a first step. Also, I know
XML is overkill, but I had to cover myself in case something complex
and important pops up as a result of this discussion. If there are no
other suggestions for comparison, I might use a simpler output format.

I have to say I'm not very experienced with the GWT, and I know quite
a bit about analyzing Java code (doing a PhD on that). So even if
something seems obvious to a GWT person, I do not know the domain
well, and it probably won't be obvious to me. Group, please offer more
suggestions, even if they seem obvious to you.

Thanks,
Alex

On Jun 15, 7:30 pm, BobV <b...@google.com> wrote:

[Miguel Méndez]

Hi Alex,

Here are a few references that might be useful.

• http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs - Good discussion on API compatibility, mostly binary level
  
• http://clirr.sourceforge.net/ - API compatibility tool; might be good to look at its features
• http://sab39.netreach.com/Software/Japitools/42/ - Another API compatibility tool; again you might want to check out its features
• http://mail-archives.apache.org/mod_mbox/harmony-dev/200605.mbox/%3C7273946b0605052233i3f...@mail.gmail.com%3E

GWT uses javadoc annotations to control code generation.  So Bob, is right to point out that things like @ gwt.typeArgs could be a source of incompatibility.  This javadoc annotation pattern is replicated in several places like I18N and ImageBundles.

It would seem that the only JSNI references that you could validate are the ones that reference Java members proper.  I do not think that we have enough information to validate references to raw JS since the backing code could come from a script included via the module or the host page. 

I would also caution that JSNI references can side-step Java's visibility rules.  So, from JSNI I could access a private/protected /default member of another class (RPC uses this technique).  Or worse still create a JS closure which references a private Java member.

These are all things that you should be aware of so you can decide how or if these cases should be handled.

Cheers,

[Bruce Johnson]

Here are the two use cases I care about most:

1) Somebody commits an API change to "improve" an API but breaks source backwards compatibility.
2) Somebody commits a change and accidentally breaks backward compatibility.

In both cases, the compat checker tool (the thing we want to add to the GWT continuous build), would break the build, saying "Stop! You broke compatibility <here>. If you meant to do this, you need to add an entry to the known-breaking-changes whitelist file." Having to explicitly update a whitelist file when you break compatibility really brings the point home clearly: if you're breaking compatibility, you'd better be meaning to.

Note that these are all source-level compatability issues we're talking about, not binary compatibility issues. One advantage of compiling monolithically from source (that's what GWT does) is that it avoids several nitpicky problems of classfile compat (e.g. changing the value of a public constant that was inlined in other classfiles).

-- Bruce

[Miguel Méndez]

I agree that we only care about source compatibility and not binary compatibility.  I was attempting to provide some information to motivate a discussion of exactly what checks we need perform to ensure source compatibility.

--
Miguel