Vladimir,
- Am I right that source/binary compatibility implies that
package-private implementation also matches? If it does then how does
it fit to clean-room?
- Do we really need to be source/binary compatible? Do you think that
existing compatibility guideline
http://incubator.apache.org/harmony/subcomponents/classlibrary/compat.html
is not enough?
Sorry if it was discussed before and I missed it.
--
Anton Avtamonov,
Intel Middleware Products Division
On 5/6/06, Vladimir Ivanov <[EMAIL PROTECTED]> wrote:
Recently I thought about guaranteeing binary and source compatibility
between HARMONY API and other compatible J2SE API implementations, what is
our goal and how to check it, automation. Let me share my thoughts - for us
to understand clearly what we want and how to test it.
Here is the summary:
· For 1.4 J2SE API implementation - JAPI tool, being applied in both
ways (RI vs. HARMONY and HARMONY vs. RI), tests 2-way binary compatibility
between two J2SE API implementations and only one small update to check the
inheritance class hierarchy should be added to tests 2-way source
compatibility.
· For 1.5 – JAPI tests 2-way binary compatibility. For checking 2-way
source compatibility JAPI lacks some 1.5 language specific checks in
addition to checking inheritance class hierarchy. We need some add-ons for
JAPI.
Details:
First, definitions…
Binary compatibility – if class A can be linked with a set of classes B and
a set of classes C than sets B and C are binary compatible (from the A's
point of view). For Java it is defined in the JLS chapter 13.
Source compatibility – if a source of class A can be compiled with a set of
classes B and a set of classes C (by conformant compiler) than sets B and C
are source compatible.
1-way binary/source compatibility – any arbitrary class A, linked/compiled
with a set of classes B, can be linked/compiled with a set of classes C.
2-way binary/source compatibility – any arbitrary class A, linked/compiled
with a set of classes B, can be linked/compiled with a set of classes C AND
vice versa – any arbitrary class A, linked/compiled with a set of classes C,
can be linked/compiled with a set of classes B.
Some observations
Observation #1: I think, in general, binary compatibility is a weaker
requirement then source compatibility and is completely covered by source
compatibility.
Observation #2: I think, talking about 1.4, checking of 2-way binary
compatibility + throws clause + inheritance hierarchy will guarantee 2-way
source compatibility. I did not find any contra examples.
Observation #3: In 1.5, however, checking of 2-way binary compatibility+
throws clause + inheritance hierarchy does not guarantee 2-way source
compatibility. Why? - generics, enums, annotations.
Example for generics:
class A<T> {
public void m(T p) {
}
}
class A {
public void m(Object p) {
}
}
class MyClass {
public static void main() {
new A<String>().m("abc");
}
}
Both "A"s are 2-way binary compatible, but, MyClass can not be compiled with
non-parameterized A.
What is our (Harmony) goal?
In terms of these definitions, ideally, I suppose we want that Harmony is
2-way source compatible with the conformant J2SE API implementation (RI API)
to make sure that any application compiled with RI API can be compiled with
Harmony and vice versa (as well as linked, that is guaranteed by the
"Observation #1").
* Automation: what does JAPI check? (http://www.kaffe.org/~stuart/japi/)
Being run in two ways (for example, RI vs Harmony and Harmony vs RI) JAPI
checks 2-way binary compatibility for both 1.4 and 1.5 language-written
APIs.
It compares method, class signatures in two sets of API binaries and, being
run in two ways, checks the following:
---------------------------------------------------
Checks | JAPI
---------------------------------------------------
Classes: modifiers (access+abstract) | +
Classes: add/remove super classes | +/+
Classes: add/remove super interfaces | +/+
Classes: order of super class hierarchy | -
Fields: modifiers (access+final) | +
Fields: change value for constant | +
Fields: change static/transient | +/-
Fields: add/remove | +/+
Methods: modifiers(access+abstract+final) | +
Methods: change static/throws clause | +/+
Methods: add/remove | +/+
Constructors: modifiers(access) | +
Constructors: add/remove | +/+
Interfaces: modifiers | +
Interfaces: add fields/methods | +/+
Interfaces: remove fields/methods | +/+
---------------------------------------------------
So, talking about 1.4, two runs of JAPI - Harmony vs RI and RI vs Harmony
and small JAPI update (check that it is illegal to re-order class
inheritance, actually, it is checked, but indirectly) will check 2-way
source compatibility (any deviation in the classes will be checked, except
for transient).
What about 1.5? – so far, seems like to check 2-way source compatibility
JAPI lacks:
Checks | JAPI
----------------------
generic | -
annotation | -
enum | -
What else?
Conclusion:
· For 1.4 J2SE API implementation - JAPI tool, being applied in both
ways (RI vs. HY and HY vs. RI), tests 2-way binary compatibility between 2
J2SE API implementations and only one small update to check inheritance
class hierarchy should be added to test 2-way source compatibility.
· For 1.5 – JAPI tests 2-way binary compatibility. For checking 2-way
source compatibility JAPI lacks some 1.5 language specific checks. We need
some add-ons for JAPI.
Questions:
1. Can we think of other cases when JAPI does not guarantee 2-way source
compatibility, talking about 1.5 language?
2. What more checks should be added to JAPI to guarantee 2-way source
compatibility for 1.5?
3. Does somebody know other tools that can check 2-way source
compatibility for 1.5 to compare with JAPI?
Thanks,
Vladimir Ivanov
---------------------------------------------------------------------
Terms of use : http://incubator.apache.org/harmony/mailing.html
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
