[jbosstools-dev] Migrating API

[Rob Stryker]

Hey all:

I'd like to take this moment to remind everyone that changing interfaces 
is not allowed if the interface is public and non-internal. Interfaces 
cannot change at all and require very careful migration.  Other tasks 
which are not allowed include changing the return type of an API class 
in ANY fashion. I've also been guilty of this recently, and caused a 
breakage in the soa product, but recent patch submissions have done the 
same.

These rules are a lot more critical in LOW level modules, such as 
base/*, server/*, etc, and less so for projects like Central, which are 
at the top of the stack and have very few consumers. But, the rules 
still must be enforced regardless and we should always try to keep api 
stable.

Migrating public interfaces is a bit of a harder task, and anyone 
attempting to do it should probably ask for advice on how to maintain 
api compatability. For stable components like base/common, it must be 
done in the safest way possible. This usually involves creating a second 
interface which extends the first, and creating new methods to use the 
more specific interface.

In the future, when designing an API, if you think you might ever need 
any return value, even if you don't need one now, it is a good idea to 
return Object. While I don't think this is a beautiful solution, the 
fact is any subclass can return a more specific value. If you simply 
declare it as a 'void' return value, this can never be changed at all in 
any way.

Any questions on api migration, do not delay to ask the list :)

- Rob Stryker