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 _______________________________________________ jbosstools-dev mailing list jbosstools-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/jbosstools-dev

On 03/06/2013 10:31 PM, Rob Cernich wrote: > Also, it's much easier to change from void to some type as nobody > is using the return value already. It's true that changing from void to some type maintains source compatability, the issue here is that it breaks binary compatability. So some tools compiled against jbt 4.0.0 but running in a 4.0.1 environment (after you changed void to SomeObject) will get exceptions in that the method is NOT FOUND. This will make our tools useless. > 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. Changing the return type at all is a binary api breakage. Plain and simple. Changing it from Object to OtherObject is a breakage. Changing it from void to SomeObject is a breakage. All of them are breakages. The only way would be to maintain the method signature at Object, but return whatever you want, leaving it up to clients to properly cast it. This is of course ugly, but it's better than binary incompatabilities.

> If you're using Object to provide flexibility for extended interfaces, I suggest parameterizing the type instead, I'm sure you're right, but if we had the foresight of coding for flexibility before, we wouldn't have the issue of people changing return types now ;) THe issue I'm bringing to light is people changing interfaces that were not coded in expectence of flexibility. In short, you can't. So don't. ;)

Unfortunately a lot of packages in JBT do not have ".internal" in the package name, and max has declared anything not in an ".internal" package is public api ;) I've tried telling him those packages were private, but he told me, nope! You didn't mark them, so they're not!

And of course I can't simply mark them private now, as that'd break api ;)

On 03/06/2013 11:43 PM, Rob Cernich wrote: > > ----- Original Message ----- >> On 03/06/2013 10:31 PM, Rob Cernich wrote: >>> Also, it's much easier to change from void to some type as nobody >>> is using the return value already. >> It's true that changing from void to some type maintains source >> compatability, the issue here is that it breaks binary compatability. >> So >> some tools compiled against jbt 4.0.0 but running in a 4.0.1 >> environment >> (after you changed void to SomeObject) will get exceptions in that >> the >> method is NOT FOUND. This will make our tools useless. >> >> > 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. >> >> Changing the return type at all is a binary api breakage. Plain and >> simple. Changing it from Object to OtherObject is a breakage. >> Changing >> it from void to SomeObject is a breakage. All of them are breakages. >> The >> only way would be to maintain the method signature at Object, but >> return >> whatever you want, leaving it up to clients to properly cast it. >> This >> is of course ugly, but it's better than binary incompatabilities. > How is it any different? I suppose it's OK if you're not using the returned value, but it's probably still going to cause an exception for anybody actually using the return value. At that point, what does it matter what type of exception it is? I think you need to take the "fail early" approach here and use proper types. > >> > If you're using Object to provide flexibility for extended >> interfaces, I suggest parameterizing the type instead, >> >> I'm sure you're right, but if we had the foresight of coding for >> flexibility before, we wouldn't have the issue of people changing >> return types now ;) THe issue I'm bringing to light is people >> changing interfaces that were not coded in expectence of >> flexibility. In short, you can't. So don't. ;) > If you're not thinking ahead, I don't think it matters. Maybe better say, if you're going to change something, make sure you have a good reason. If you have to change it, make sure you do it in a compatible way. There are many strategies that can be used to maintain compatibility (shoot, the refactor functionality in Eclipse actually allows you to keep the old methods, which delegate to the new). > > It is a good thing to highlight that you shouldn't be making interface changes willy nilly. Then again, I think a lot of times we get around this by not providing a public API. Heh, look at Dali. ;) > >> _______________________________________________ jbosstools-dev mailing list jbosstools-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/jbosstools-dev