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.
