Christopher Dolan wrote:
In general (I have not looked at Peter's recent changes yet) I vote for
simple binary compatibility by adding @Deprecated to old methods and
adding new methods with the altered signatures. Instead of rearranging
method arguments, I favor changing the method name, or creating a whole
new class/interface and deprecating the old one if the changes are
extensive.
I'm tending to agree with you.
When two methods or constructors are similar, it's the caller that is
ambiguous due to null parameters, which means code that currently
compiles doesn't when new similar methods or constructors are added,
unless null parameters are cast to their intended type. I guess if
someone was going to the effort to compile, it wouldn't be much to add
some casts, and makes the replacement very obvious.
But where that's impossible (like the refactoring to reduce
java.rmi dependencies) I'm not sure what to propose. The most important
thing to me is that I any River 2.2.x code I write will be able talk to
my Jini 2.1 code.
I figured there would be significant pressure to maintain backward
compatibility, so far I think I'm succeeding. I think this is the reason
why Gregg's improvements to Reggie and ServiceRegistrar never made it
into River. However I think I can give Gregg what he needs, without
breaking backward compatibility.
Commit to follow.
Cheers,
Peter.
I don't like the sound of the ASM post-processing technique you propose.
It sounds fragile and it will make debugging harder since the source
won't match the bytecode. But I'll keep an open mind if others have had
positive experience with such an approach.
Sorry to be negative.
Chris
-----Original Message-----
From: Peter Firmstone [mailto:[email protected]]
Sent: Friday, April 23, 2010 10:13 PM
To: [email protected]
Subject: Re: Jini Spec API changes - Advise needed
Thanks Chris,
I'll look into what's needed to make it an ant build option.
On the subject of API changes, there is one particular bugbear I have
when it comes to maintaining Binary compatibility:
* You can't change a method signature's parameters, not even to a
superclass - any type change breaks binary compatibility (
exceptions aren't part of method signatures), which is annoying,
since changing a method to a superclass doesn't break compile time
compatibility and only requires a simple recompile for application
upgrades.
However maintaining Binary compatibility requires maintaining the
original method and adding a new method, often with the parameters moved
around to avoid compile time method signature ambiguity, existing
applications now require, not only a full recompile, but editing of all
occurrences of the old method signature in source code, which is far
less likely to happen.
*So I pose these questions:
*
* What sort of Compatibility do you want to maintain?
* Is compile time enough or do you want binary as well?
* Or do you want to have your cake and eat it too?
*Possible Solutions:*
* We could create a tool that utilises ASM to rewrite method
signatures of existing binary's to be compatible.
* Or is there some kind of annotation that we could use to have ASM
add the old method signature to Apache River after compilation?
Then we don't have to change existing application binaries, a
simple recompile means new binaries for existing applications now
link to the new methods. If anyone has any ideas for such an
annotation, or if someone has done this before, please advise.
(This would only work for classes, not interfaces).
Breaking Binary compatibility doesn't break Serialization
compatibility. However it does bring with it issues for distributed
computing, such as ensuring the local JVM has the right binary version,
that is compatible locally, in the correct ClassLoader, but for now,
I'll save that issue for another thread.
In River, we have three compatibility concerns:
1. JVM local Binary Compatibility.
2. Compile time Source Compatibility.
3. Distributed Serialization Compatibility.
It would be preferable to maintain binary and source level compatibility
with the Jini spec, in order to prevent forklift upgrade requirements
for existing installations, however if someone can show there is a
significant reason not to then I'll consider that too.
Note I'm only referring to the net.jini.* namespace.
Best Regards,
Peter Firmstone.
Christopher Dolan wrote:
I recommend http://www.jdiff.org/
Here's an example of use:
% javadoc -doclet jdiff.JDiff -docletpath 'jdiff.jar;xerces.jar'
-apiname testng5.7 -sourcepath '..\testng-5.7\testng-5.7\src\main'
org.testng
% javadoc -doclet jdiff.JDiff -docletpath 'jdiff.jar;xerces.jar'
-apiname testng5.8 -sourcepath '..\testng-5.8\testng-5.8\src\main'
org.testng
% javadoc -doclet jdiff.JDiff -docletpath 'jdiff.jar;xerces.jar'
-oldapi
testng5.7 -newapi testng5.8 org.testng
% open changes.html
Chris
-----Original Message-----
From: Peter Firmstone [mailto:[email protected]]
Sent: Thursday, April 22, 2010 6:31 PM
To: [email protected]
Subject: Jini Spec API changes - Advise needed
I've created several new classes / interfaces, currently these reside
in
the net.jini name space, I need community advise on which of these
belong in Jini's API and good places for those that don't.
The changes will be committed shortly, after my qa tests results.
It'd be neat if we could set up some sort of javadoc diff to monitor
changes, does anyone have experience with it?
Regards,
Peter.
