[jbosstools-dev] Migrating API

[Rob Cernich]

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

This is actually worse.  If the method is typed appropriately and that type changes you will get a compile error.  If the return type is Object and you change the type you will get a ClassCastException.  Which would you rather have?

Also, it's much easier to change from void to some type as nobody is using the return value already.

If you're using Object to provide flexibility for extended interfaces, I suggest parameterizing the type instead, as it allows extensions to specialize the type, while preserving compile time type checking.

> 
> Any questions on api migration, do not delay to ask the list :)
> 
> - Rob Stryker
> _______________________________________________
> jbosstools-dev mailing list
> jbosstools-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jbosstools-dev
>