You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@uima.apache.org by Marshall Schor <ms...@schor.com> on 2009/07/23 23:17:15 UTC
generics cleanup - avoiding modifying public APIs?
When adding generic type info to UIMA core, if there is a method which
is declared to return a List, and we change it to return a
List<ofSomeType>, and the method is part of the UIMA public API - does
that "break" the public API? Or will code that is already written to
use it continue to work? I think the code would continue to work in
terms of the runtime (because of the "erasure" approach), but the
compiling may generate some new warnings for our users?
Is this OK or should we refrain from any changes which are the public
UIMA api's?
Same question applies, I think, to methods which take arguments to which
we might be adding generic typing info.
Thanks for any insight here :-) -Marshall
Re: generics cleanup - avoiding modifying public APIs?
Posted by Jörn Kottmann <ko...@gmail.com>.
Marshall Schor wrote:
> This is because it's binary compatible to go from --no generic info-- to
> some-generic-info, but it is not binary compatible to change the
> generic-info once it is there.
>
Thats true. I always changed everything or nothing.
At the places I did not change I tried to make sure that
we have the opportunity to change it later.
Jörn
Re: generics cleanup - avoiding modifying public APIs?
Posted by Marshall Schor <ms...@schor.com>.
Key idea: It's OK to add generic type info - doesn't break binary
compatibility.
But the page says, too, you only get one chance (release), to get it
right. In particular, if you change a type in an API signature from the
raw type "|List|" to "|List<?>|" or "|List<Object>|", you will be locked
into that decision
This is because it's binary compatible to go from --no generic info-- to
some-generic-info, but it is not binary compatible to change the
generic-info once it is there.
-Marshall
Jörn Kottmann wrote:
> Marshall Schor wrote:
>> Is this OK or should we refrain from any changes which are the public
>> UIMA api's?
>>
> Here is something about the topic from the eclipse wiki:
> http://wiki.eclipse.org/Evolving_Java-based_APIs_2
>
> The section about turning non-gernic types and methods
> into generic ones is very interesting.
>
> Jörn
>
>
Re: generics cleanup - avoiding modifying public APIs?
Posted by Jörn Kottmann <ko...@gmail.com>.
Marshall Schor wrote:
> Is this OK or should we refrain from any changes which are the public
> UIMA api's?
>
Here is something about the topic from the eclipse wiki:
http://wiki.eclipse.org/Evolving_Java-based_APIs_2
The section about turning non-gernic types and methods
into generic ones is very interesting.
Jörn
Re: generics cleanup - avoiding modifying public APIs?
Posted by Thilo Goetz <tw...@gmx.de>.
Jörn Kottmann wrote:
> Marshall Schor wrote:
>> When adding generic type info to UIMA core, if there is a method which
>> is declared to return a List, and we change it to return a
>> List<ofSomeType>, and the method is part of the UIMA public API - does
>> that "break" the public API? Or will code that is already written to
>> use it continue to work? I think the code would continue to work in
>> terms of the runtime (because of the "erasure" approach), but the
>> compiling may generate some new warnings for our users?
>>
> If a user wrote List<SomeOtherType> sample = .... then its likely
> that he will get a compile error when our code return List<ofSomeType>
> (but not a runtime error I think).
> Same is true for things which are passed to UIMA API methods, if a user
> already
> declared generic types its possible that it will break the code.
>
>> Is this OK or should we refrain from any changes which are the public
>> UIMA api's?
>>
> I think it is ok, because its unlikely that we break something.
Yes, let's keep going. It's a bit late to have second thoughts
about this, as Joern has already made quite a few changes to
public APIs.
>
> In the whole UIMA repo was only one case which broke existing code
> and that was the additionalParams map which was in one case passed
> as a Properties object which is Map<Object, Object> and not Map<String,
> Object>.
> Though for that reason it was not changed and is still a raw Map.
>
> Jörn
Re: generics cleanup - avoiding modifying public APIs?
Posted by Marshall Schor <ms...@schor.com>.
I reviewed this generics change - looks good to me. I committed a few
more conversions from iterators to the Java 5 style for loop, but
quickly got tired of doing that :-). Too bad there isn't an Eclipse
refactor to do this (or is there?).
-Marshall
Jörn Kottmann wrote:
>
> On Jul 24, 2009, at 10:42 PM, Marshall Schor wrote:
>
>>
>>
>> Jörn Kottmann wrote:
>>> Marshall Schor wrote:
>>>> Jörn Kottmann wrote:
>>>>
>>>>> Marshall Schor wrote:
>>>>>
>>>>>> When adding generic type info to UIMA core, if there is a method
>>>>>> which
>>>>>> is declared to return a List, and we change it to return a
>>>>>> List<ofSomeType>, and the method is part of the UIMA public API -
>>>>>> does
>>>>>> that "break" the public API? Or will code that is already
>>>>>> written to
>>>>>> use it continue to work? I think the code would continue to work in
>>>>>> terms of the runtime (because of the "erasure" approach), but the
>>>>>> compiling may generate some new warnings for our users?
>>>>>>
>>>>> If a user wrote List<SomeOtherType> sample = .... then its likely
>>>>> that he will get a compile error when our code return
>>>>> List<ofSomeType>
>>>>> (but not a runtime error I think).
>>>>> Same is true for things which are passed to UIMA API methods, if a
>>>>> user already
>>>>> declared generic types its possible that it will break the code.
>>>>>
>>>>>
>>>>>> Is this OK or should we refrain from any changes which are the
>>>>>> public
>>>>>> UIMA api's?
>>>>>>
>>>>> I think it is ok, because its unlikely that we break something.
>>>>>
>>>>> In the whole UIMA repo was only one case which broke existing code
>>>>> and that was the additionalParams map which was in one case passed
>>>>> as a Properties object which is Map<Object, Object> and not
>>>>> Map<String, Object>.
>>>>>
>>>> Does this mean you've already changed everything except for that?
>>>> When
>>>> I started doing things in the uimaj-core I saw a lot that needed
>>>> changing and started changing it. (and I was up to date, too).
>>>>
>>> First I went through the interfaces and changed these,
>>> because thats the place where it must be right. To make
>>> sure the changes are ok I attached a patch to the jira issue
>>> and ask for review on the mailing list and got a +1 from Thilo,
>>> no one else commented. I assumed that it was accepted because
>>> no one complained.
>>>
>>> To further test if the changes are really ok I changed the test classes
>>> and later the cas.impl package. That lead to a number of corrections
>>> in the interfaces. Yeah there are still around 2000 warnings in the
>>> uimaj-core.
>>>
>>> Should we start a new review of the interface changes ?
>> I think so. But first, let me revert my changes, where I just sort of
>> "jumped in" without realizing you had already done this work but not
>> committed it :-).
>
> I committed it. Its in trunk since a while now.
>
> Jörn
>
Re: generics cleanup - avoiding modifying public APIs?
Posted by Jörn Kottmann <ko...@gmail.com>.
On Jul 24, 2009, at 10:42 PM, Marshall Schor wrote:
>
>
> Jörn Kottmann wrote:
>> Marshall Schor wrote:
>>> Jörn Kottmann wrote:
>>>
>>>> Marshall Schor wrote:
>>>>
>>>>> When adding generic type info to UIMA core, if there is a method
>>>>> which
>>>>> is declared to return a List, and we change it to return a
>>>>> List<ofSomeType>, and the method is part of the UIMA public API
>>>>> - does
>>>>> that "break" the public API? Or will code that is already
>>>>> written to
>>>>> use it continue to work? I think the code would continue to
>>>>> work in
>>>>> terms of the runtime (because of the "erasure" approach), but the
>>>>> compiling may generate some new warnings for our users?
>>>>>
>>>> If a user wrote List<SomeOtherType> sample = .... then its likely
>>>> that he will get a compile error when our code return
>>>> List<ofSomeType>
>>>> (but not a runtime error I think).
>>>> Same is true for things which are passed to UIMA API methods, if a
>>>> user already
>>>> declared generic types its possible that it will break the code.
>>>>
>>>>
>>>>> Is this OK or should we refrain from any changes which are the
>>>>> public
>>>>> UIMA api's?
>>>>>
>>>> I think it is ok, because its unlikely that we break something.
>>>>
>>>> In the whole UIMA repo was only one case which broke existing code
>>>> and that was the additionalParams map which was in one case passed
>>>> as a Properties object which is Map<Object, Object> and not
>>>> Map<String, Object>.
>>>>
>>> Does this mean you've already changed everything except for that?
>>> When
>>> I started doing things in the uimaj-core I saw a lot that needed
>>> changing and started changing it. (and I was up to date, too).
>>>
>> First I went through the interfaces and changed these,
>> because thats the place where it must be right. To make
>> sure the changes are ok I attached a patch to the jira issue
>> and ask for review on the mailing list and got a +1 from Thilo,
>> no one else commented. I assumed that it was accepted because
>> no one complained.
>>
>> To further test if the changes are really ok I changed the test
>> classes
>> and later the cas.impl package. That lead to a number of corrections
>> in the interfaces. Yeah there are still around 2000 warnings in the
>> uimaj-core.
>>
>> Should we start a new review of the interface changes ?
> I think so. But first, let me revert my changes, where I just sort of
> "jumped in" without realizing you had already done this work but not
> committed it :-).
I committed it. Its in trunk since a while now.
Jörn
Re: generics cleanup - avoiding modifying public APIs?
Posted by Marshall Schor <ms...@schor.com>.
Marshall Schor wrote:
> Jörn Kottmann wrote:
>
>> Marshall Schor wrote:
>>
>>> Jörn Kottmann wrote:
>>>
>>>
>>>> Marshall Schor wrote:
>>>>
>>>>
>>>>> When adding generic type info to UIMA core, if there is a method which
>>>>> is declared to return a List, and we change it to return a
>>>>> List<ofSomeType>, and the method is part of the UIMA public API - does
>>>>> that "break" the public API? Or will code that is already written to
>>>>> use it continue to work? I think the code would continue to work in
>>>>> terms of the runtime (because of the "erasure" approach), but the
>>>>> compiling may generate some new warnings for our users?
>>>>>
>>>>>
>>>> If a user wrote List<SomeOtherType> sample = .... then its likely
>>>> that he will get a compile error when our code return List<ofSomeType>
>>>> (but not a runtime error I think).
>>>> Same is true for things which are passed to UIMA API methods, if a
>>>> user already
>>>> declared generic types its possible that it will break the code.
>>>>
>>>>
>>>>
>>>>> Is this OK or should we refrain from any changes which are the public
>>>>> UIMA api's?
>>>>>
>>>>>
>>>> I think it is ok, because its unlikely that we break something.
>>>>
>>>> In the whole UIMA repo was only one case which broke existing code
>>>> and that was the additionalParams map which was in one case passed
>>>> as a Properties object which is Map<Object, Object> and not
>>>> Map<String, Object>.
>>>>
>>>>
>>> Does this mean you've already changed everything except for that? When
>>> I started doing things in the uimaj-core I saw a lot that needed
>>> changing and started changing it. (and I was up to date, too).
>>>
>>>
>> First I went through the interfaces and changed these,
>> because thats the place where it must be right. To make
>> sure the changes are ok I attached a patch to the jira issue
>> and ask for review on the mailing list and got a +1 from Thilo,
>> no one else commented. I assumed that it was accepted because
>> no one complained.
>>
>> To further test if the changes are really ok I changed the test classes
>> and later the cas.impl package. That lead to a number of corrections
>> in the interfaces. Yeah there are still around 2000 warnings in the
>> uimaj-core.
>>
>> Should we start a new review of the interface changes ?
>>
> I think so. But first, let me revert my changes, where I just sort of
> "jumped in" without realizing you had already done this work but not
> committed it :-).
After looking at SVN, it seems that most of my changes never got to the
point of being committed (just changed in my workspace), and Jörn has
already started committing his changes here. So I'll instead be
reviewing things.
-Marshall
> I'll do that over the weekend (at least that's my
> intention :-) ). Your changes sound like they're probably more
> carefully thought out, too...
>
> -Marshall
>
>> Jörn
>>
>>
>>
>
>
>
Re: generics cleanup - avoiding modifying public APIs?
Posted by Marshall Schor <ms...@schor.com>.
Jörn Kottmann wrote:
> Marshall Schor wrote:
>> Jörn Kottmann wrote:
>>
>>> Marshall Schor wrote:
>>>
>>>> When adding generic type info to UIMA core, if there is a method which
>>>> is declared to return a List, and we change it to return a
>>>> List<ofSomeType>, and the method is part of the UIMA public API - does
>>>> that "break" the public API? Or will code that is already written to
>>>> use it continue to work? I think the code would continue to work in
>>>> terms of the runtime (because of the "erasure" approach), but the
>>>> compiling may generate some new warnings for our users?
>>>>
>>> If a user wrote List<SomeOtherType> sample = .... then its likely
>>> that he will get a compile error when our code return List<ofSomeType>
>>> (but not a runtime error I think).
>>> Same is true for things which are passed to UIMA API methods, if a
>>> user already
>>> declared generic types its possible that it will break the code.
>>>
>>>
>>>> Is this OK or should we refrain from any changes which are the public
>>>> UIMA api's?
>>>>
>>> I think it is ok, because its unlikely that we break something.
>>>
>>> In the whole UIMA repo was only one case which broke existing code
>>> and that was the additionalParams map which was in one case passed
>>> as a Properties object which is Map<Object, Object> and not
>>> Map<String, Object>.
>>>
>> Does this mean you've already changed everything except for that? When
>> I started doing things in the uimaj-core I saw a lot that needed
>> changing and started changing it. (and I was up to date, too).
>>
> First I went through the interfaces and changed these,
> because thats the place where it must be right. To make
> sure the changes are ok I attached a patch to the jira issue
> and ask for review on the mailing list and got a +1 from Thilo,
> no one else commented. I assumed that it was accepted because
> no one complained.
>
> To further test if the changes are really ok I changed the test classes
> and later the cas.impl package. That lead to a number of corrections
> in the interfaces. Yeah there are still around 2000 warnings in the
> uimaj-core.
>
> Should we start a new review of the interface changes ?
I think so. But first, let me revert my changes, where I just sort of
"jumped in" without realizing you had already done this work but not
committed it :-). I'll do that over the weekend (at least that's my
intention :-) ). Your changes sound like they're probably more
carefully thought out, too...
-Marshall
>
> Jörn
>
>
Re: generics cleanup - avoiding modifying public APIs?
Posted by Jörn Kottmann <ko...@gmail.com>.
Marshall Schor wrote:
> Jörn Kottmann wrote:
>
>> Marshall Schor wrote:
>>
>>> When adding generic type info to UIMA core, if there is a method which
>>> is declared to return a List, and we change it to return a
>>> List<ofSomeType>, and the method is part of the UIMA public API - does
>>> that "break" the public API? Or will code that is already written to
>>> use it continue to work? I think the code would continue to work in
>>> terms of the runtime (because of the "erasure" approach), but the
>>> compiling may generate some new warnings for our users?
>>>
>>>
>> If a user wrote List<SomeOtherType> sample = .... then its likely
>> that he will get a compile error when our code return List<ofSomeType>
>> (but not a runtime error I think).
>> Same is true for things which are passed to UIMA API methods, if a
>> user already
>> declared generic types its possible that it will break the code.
>>
>>
>>> Is this OK or should we refrain from any changes which are the public
>>> UIMA api's?
>>>
>>>
>> I think it is ok, because its unlikely that we break something.
>>
>> In the whole UIMA repo was only one case which broke existing code
>> and that was the additionalParams map which was in one case passed
>> as a Properties object which is Map<Object, Object> and not
>> Map<String, Object>.
>>
> Does this mean you've already changed everything except for that? When
> I started doing things in the uimaj-core I saw a lot that needed
> changing and started changing it. (and I was up to date, too).
>
First I went through the interfaces and changed these,
because thats the place where it must be right. To make
sure the changes are ok I attached a patch to the jira issue
and ask for review on the mailing list and got a +1 from Thilo,
no one else commented. I assumed that it was accepted because
no one complained.
To further test if the changes are really ok I changed the test classes
and later the cas.impl package. That lead to a number of corrections
in the interfaces. Yeah there are still around 2000 warnings in the
uimaj-core.
Should we start a new review of the interface changes ?
Jörn
Re: generics cleanup - avoiding modifying public APIs?
Posted by Marshall Schor <ms...@schor.com>.
Jörn Kottmann wrote:
> Marshall Schor wrote:
>> When adding generic type info to UIMA core, if there is a method which
>> is declared to return a List, and we change it to return a
>> List<ofSomeType>, and the method is part of the UIMA public API - does
>> that "break" the public API? Or will code that is already written to
>> use it continue to work? I think the code would continue to work in
>> terms of the runtime (because of the "erasure" approach), but the
>> compiling may generate some new warnings for our users?
>>
> If a user wrote List<SomeOtherType> sample = .... then its likely
> that he will get a compile error when our code return List<ofSomeType>
> (but not a runtime error I think).
> Same is true for things which are passed to UIMA API methods, if a
> user already
> declared generic types its possible that it will break the code.
>
>> Is this OK or should we refrain from any changes which are the public
>> UIMA api's?
>>
> I think it is ok, because its unlikely that we break something.
>
> In the whole UIMA repo was only one case which broke existing code
> and that was the additionalParams map which was in one case passed
> as a Properties object which is Map<Object, Object> and not
> Map<String, Object>.
Does this mean you've already changed everything except for that? When
I started doing things in the uimaj-core I saw a lot that needed
changing and started changing it. (and I was up to date, too).
Did I miss something? -Marshall
> Though for that reason it was not changed and is still a raw Map.
>
> Jörn
>
>
Re: generics cleanup - avoiding modifying public APIs?
Posted by Jörn Kottmann <ko...@gmail.com>.
Marshall Schor wrote:
> When adding generic type info to UIMA core, if there is a method which
> is declared to return a List, and we change it to return a
> List<ofSomeType>, and the method is part of the UIMA public API - does
> that "break" the public API? Or will code that is already written to
> use it continue to work? I think the code would continue to work in
> terms of the runtime (because of the "erasure" approach), but the
> compiling may generate some new warnings for our users?
>
If a user wrote List<SomeOtherType> sample = .... then its likely
that he will get a compile error when our code return List<ofSomeType>
(but not a runtime error I think).
Same is true for things which are passed to UIMA API methods, if a user
already
declared generic types its possible that it will break the code.
> Is this OK or should we refrain from any changes which are the public
> UIMA api's?
>
I think it is ok, because its unlikely that we break something.
In the whole UIMA repo was only one case which broke existing code
and that was the additionalParams map which was in one case passed
as a Properties object which is Map<Object, Object> and not Map<String,
Object>.
Though for that reason it was not changed and is still a raw Map.
Jörn