[jbosstools-dev] Migrating API

[Max Rydahl Andersen]

>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!

Let's be clear - jboss tools "core" (I'm putting core here since thats
a misnomer for this exact reason ;) never was built for the intention that
everything in it is for public consumption.

But since the JBTIS integration split certain modules now has the
change of breaking things badly (it actually happened in 5.0.x) - that is runtimedetection and server.

Those we have to be extra extra careful about.

And as discussed before, anyone doing new additions put things in
.internal or simply don't export it to clients in manifest.mf

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

On the topic of change return values of methods, then that in any API
is almost always a bad way of fixing an api concern in a micro release.

It's not only changing the API at both source and binary level
thus this kind of change simply only can be done in a api breaking
release (ie. 4.0->4.1) its also changing the behavior (before it just
did something, now it also return a value that might need cleaning up etc.) 

/max

>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 at lists.jboss.org
>https://lists.jboss.org/mailman/listinfo/jbosstools-dev