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. 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 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. > >
