将返回类型从Integer更改为int，而不会破坏向后兼容性

Question

I'm doing QA on a certain Java 7 API, that is in public usage as Open Source. My Clirr report checks for backwards API compatibility. I got the following errors:

[ERROR] 7006: com.example.Foo: Return type of method 'public java.lang.Integer nameToUnicode(java.lang.String)' has been changed to int
[ERROR] 7006: com.example.Bar: Return type of method 'public byte getAnchorDelta()' has been changed to short

So this means that my developers changed the return type of Foo from Integer to int , and the return type of Bar was changed from byte to short . The method signatures stayed the same, so overloading is not an option.

1. Does this really break backwards compatibility? Or is Clirr giving me a false positive?
2. How can I unbreak backwards compatibility? Is this even possible without introducing new method names?

I have got a couple of other errors about return type changes (mostly some void s to float ), but they are in protected methods, so I am going to ignore them.

Answer 1

It clearly breaks backwards compatibility as your API's user may have had a code like:

if (nameToUnicode("...").equals(4)) { ... } // no such method
byte delta = getAnchorDelta(); // typecast required

Which won't compile from now on.

Considering that the new version of getAnchorData() returns a wider amount of values, you can't perform the transition without breaking backwards compatibility, as client's old code may not be suitable to accept all the possible values.

Also regarding your last statement:

I have got a couple of other errors about return type changes (mostly some voids to float), but they are in protected methods, so I am going to ignore them.

If these methods are in public non- final classes, then you break backwards compatibility by doing so as well.

Answer 2

Backward compatibility is definitely broken, as the expression stack is typed, on the result unboxing is done.

The second question is: whether a recompilation against the new API would suffice and deliver no errors.

Integer to int, though better style might now propagate style warnings on Integer usage in client software. Even when inferring types as in java 8 it should go well, except when immediately comparing with null:

if (nameToUnicode("ĉarma") == null)

And that is a very rare case.

With byte/short hands-on is needed. Also one might expect short values exceeding the byte range, or sign overflow for short values between 128 and 255. Only if the logic is unchanged, the values still in -128 .. 127 all is functionally well.

Though not compilable, sources must be adapted.

---

Providing backward compatibility:

For existing binary jars: keep the old functions, @Deprecated and javadoc comments for new usage. Throwing IllegalStateException when out-of-range for short to byte.

Answer 3

Apart from what user3707125 wrote another problem might be if someone extends your class and overrides your method. Consider following example:

public class BaseClass {
    public Integer getInt() {
        return 1;
    }
}

public class MyClass extends BaseClass {
    @Override
    public Integer getInt() {
        return null;
    }
}

If you changed return type in BaseClass to int then MyClass will have a compilation error. So this breaks backward compatability. The same is when you change byte to short.