river-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Peter Firmstone <j...@zeus.net.au>
Subject Re: Jini Spec API changes - Advise needed
Date Wed, 28 Apr 2010 10:28:02 GMT
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.



> 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:jini@zeus.net.au] 
> Sent: Friday, April 23, 2010 10:13 PM
> To: river-dev@incubator.apache.org
> 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:jini@zeus.net.au] 
>> Sent: Thursday, April 22, 2010 6:31 PM
>> To: river-dev@incubator.apache.org
>> 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.

View raw message