Skip to main content


Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
Home » Modeling » EMF » EMF + API Tools
EMF + API Tools [message #423331] Sun, 28 September 2008 20:46 Go to next message
Eclipse UserFriend
Originally posted by: cdamus.zeligsoft.com

Hi,

I have recently begun using the PDE's very cool API Tools in the Eclipse
OCL project. I am quite satisfied with the API tooling, but it raised a
problem that worries me, in the binary compatibility of EMF-generated
models.

The package meta-data interface has hordes of static int constants
identifying feature IDs. Users of a model API commonly use these in
switch statements in Adapters and related listener mechanisms. The API
tooling pointed out a binary-incompatible change when I re-generated
after adding a new attribute to one of the base classes in my model.

The problem is, that virtually all of the feature-ID constants in my
model changed because the feature-count of a base class was incremented,
and all of these feature IDs are based on the count of inherited
features. The reason why this is a binary compatibility issue is that
the Java compiler in-lined all of these constants into users' Adapter
code when they compiled against the previous OCL version.

What can I do to have the generator just assign new IDs in a
binary-compatible way?

Thanks,

Christian
Re: EMF + API Tools [message #423332 is a reply to message #423331] Sun, 28 September 2008 22:58 Go to previous messageGo to next message
Ed Merks is currently offline Ed MerksFriend
Messages: 30804
Registered: July 2009
Senior Member
Christian,

Comments below.


Christian W. Damus wrote:
> Hi,
>
> I have recently begun using the PDE's very cool API Tools in the
> Eclipse OCL project. I am quite satisfied with the API tooling, but
> it raised a problem that worries me, in the binary compatibility of
> EMF-generated models.
>
> The package meta-data interface has hordes of static int constants
> identifying feature IDs. Users of a model API commonly use these in
> switch statements in Adapters and related listener mechanisms. The
> API tooling pointed out a binary-incompatible change when I
> re-generated after adding a new attribute to one of the base classes
> in my model.
Indeed, that's the "cost" of using a highly efficient switch mechanism...
>
> The problem is, that virtually all of the feature-ID constants in my
> model changed because the feature-count of a base class was
> incremented, and all of these feature IDs are based on the count of
> inherited features.
Certainly all derived feature IDs will change when the base has a
feature added.
> The reason why this is a binary compatibility issue is that the Java
> compiler in-lined all of these constants into users' Adapter code when
> they compiled against the previous OCL version.
Indded.
>
> What can I do to have the generator just assign new IDs in a
> binary-compatible way?
Nothing. The IDs are by designed offsets into the list of all
features. In the models we have "Binary Compatible Reflective Methods"
but we've done nothing for the switches on an adapter. After more than
6 years with this situation, no one has even expressed a concern about
the item provider issue. Go figure... :-P
>
> Thanks,
>
> Christian
Re: EMF + API Tools [message #423334 is a reply to message #423332] Mon, 29 September 2008 01:47 Go to previous messageGo to next message
Eclipse UserFriend
Originally posted by: cdamus.zeligsoft.com

Hi, Ed,

So, you're saying that the feature IDs are an internal implementation
detail and should not be published in the package interface. Certainly,
it is an error for client code to reference the feature ID constants.
Is this widely known?

Luckily, the API tooling gives us the means to impose that restriction,
using the @noreference tag in the doc comments. I can apply that to my
OCL models as they change (currently, changes contributed to the
concrete-syntax model are throwing up red flags).

In the mean-time, perhaps EMF can help by any one of:

- optionally not publishing the feature IDs in the package interface
- optionally including an @noreference tag in the doc comment
for every feature ID. I should be able to do this for myself
with a dynamic template, for now
- adding the @noreference tag to the getFeatureID() method of the
Notifier class, so that clients will be discourage from a common
cause of referencing these constants

The problem with relying on the API tooling, of course, is that it
depends on a client using it and on having the API metadata available
(which generally isn't in an OCL build that one might have the target
environment). Even this change in the contract is, technically, a
breaking API change. However, that contract has already been broken in
every release ...

Cheers,

Christian


Ed Merks wrote:
> Christian,
>
> Comments below.
>
>
> Christian W. Damus wrote:
>> Hi,
>>
>> I have recently begun using the PDE's very cool API Tools in the
>> Eclipse OCL project. I am quite satisfied with the API tooling, but
>> it raised a problem that worries me, in the binary compatibility of
>> EMF-generated models.
>>
>> The package meta-data interface has hordes of static int constants
>> identifying feature IDs. Users of a model API commonly use these in
>> switch statements in Adapters and related listener mechanisms. The
>> API tooling pointed out a binary-incompatible change when I
>> re-generated after adding a new attribute to one of the base classes
>> in my model.
> Indeed, that's the "cost" of using a highly efficient switch mechanism...
>>
>> The problem is, that virtually all of the feature-ID constants in my
>> model changed because the feature-count of a base class was
>> incremented, and all of these feature IDs are based on the count of
>> inherited features.
> Certainly all derived feature IDs will change when the base has a
> feature added.
>> The reason why this is a binary compatibility issue is that the Java
>> compiler in-lined all of these constants into users' Adapter code when
>> they compiled against the previous OCL version.
> Indded.
>>
>> What can I do to have the generator just assign new IDs in a
>> binary-compatible way?
> Nothing. The IDs are by designed offsets into the list of all
> features. In the models we have "Binary Compatible Reflective Methods"
> but we've done nothing for the switches on an adapter. After more than
> 6 years with this situation, no one has even expressed a concern about
> the item provider issue. Go figure... :-P
>>
>> Thanks,
>>
>> Christian
Re: EMF + API Tools [message #423350 is a reply to message #423334] Mon, 29 September 2008 12:03 Go to previous messageGo to next message
Ed Merks is currently offline Ed MerksFriend
Messages: 30804
Registered: July 2009
Senior Member
Christian,

Comments below.

Christian W. Damus wrote:
> Hi, Ed,
>
> So, you're saying that the feature IDs are an internal implementation
> detail and should not be published in the package interface.
I didn't hear me say that! :-P
> Certainly, it is an error for client code to reference the feature
> ID constants.
No, it's not. It all comes down to expectations. If you look at the
generated code for the binary compatible reflective methods you'll see
that such constants can be safely used even if their values change in a
binary incompatible way.
> Is this widely known?
Don't you find it telling that this has not been raised as an issue in
the last 7 years? Binary compatibility is one of those holy grails that
no one questions and yet mostly folks build new versions of the software
and recompile... It's very easy after all to put a tight version range
bound to address an issue like this. You remember some of your reasons
for tight version range bounds on your Ecore dependencies? :-P
>
> Luckily, the API tooling gives us the means to impose that
> restriction, using the @noreference tag in the doc comments. I can
> apply that to my OCL models as they change (currently, changes
> contributed to the concrete-syntax model are throwing up red flags).
Or you could just not change your model. Or add things only to leaf
classes... Just a like joke. :-P
>
> In the mean-time, perhaps EMF can help by any one of:
>
> - optionally not publishing the feature IDs in the package interface
Where to publish them then? They're needed in downstream derived
models. And even if we move them, the problem associated with them
doesn't change, it just moves...
> - optionally including an @noreference tag in the doc comment
> for every feature ID. I should be able to do this for myself
> with a dynamic template, for now
We could have such an option.
> - adding the @noreference tag to the getFeatureID() method of the
> Notifier class, so that clients will be discourage from a common
> cause of referencing these constants
It's not this method that has a problem. It could very well be compared
to dynamic computed feature IDs.
>
> The problem with relying on the API tooling, of course, is that it
> depends on a client using it and on having the API metadata available
> (which generally isn't in an OCL build that one might have the target
> environment). Even this change in the contract is, technically, a
> breaking API change. However, that contract has already been broken
> in every release ...
Again, doesn't this tell you something?

The only other generated place the constants are used is in the item
providers, where we could do something similar to what we did for the
reflective methods or we could compare against feature instances instead
(optionally of course).
>
> Cheers,
>
> Christian
>
>
> Ed Merks wrote:
>> Christian,
>>
>> Comments below.
>>
>>
>> Christian W. Damus wrote:
>>> Hi,
>>>
>>> I have recently begun using the PDE's very cool API Tools in the
>>> Eclipse OCL project. I am quite satisfied with the API tooling, but
>>> it raised a problem that worries me, in the binary compatibility of
>>> EMF-generated models.
>>>
>>> The package meta-data interface has hordes of static int constants
>>> identifying feature IDs. Users of a model API commonly use these in
>>> switch statements in Adapters and related listener mechanisms. The
>>> API tooling pointed out a binary-incompatible change when I
>>> re-generated after adding a new attribute to one of the base classes
>>> in my model.
>> Indeed, that's the "cost" of using a highly efficient switch
>> mechanism...
>>>
>>> The problem is, that virtually all of the feature-ID constants in my
>>> model changed because the feature-count of a base class was
>>> incremented, and all of these feature IDs are based on the count of
>>> inherited features.
>> Certainly all derived feature IDs will change when the base has a
>> feature added.
>>> The reason why this is a binary compatibility issue is that the Java
>>> compiler in-lined all of these constants into users' Adapter code
>>> when they compiled against the previous OCL version.
>> Indded.
>>>
>>> What can I do to have the generator just assign new IDs in a
>>> binary-compatible way?
>> Nothing. The IDs are by designed offsets into the list of all
>> features. In the models we have "Binary Compatible Reflective
>> Methods" but we've done nothing for the switches on an adapter.
>> After more than 6 years with this situation, no one has even
>> expressed a concern about the item provider issue. Go figure... :-P
>>>
>>> Thanks,
>>>
>>> Christian
Re: EMF + API Tools [message #423371 is a reply to message #423350] Mon, 29 September 2008 14:52 Go to previous messageGo to next message
Eclipse UserFriend
Originally posted by: cdamus.zeligsoft.com

Hi, Ed,

More replies in-line, below.

Thanks,

Christian


Ed Merks wrote:
> Christian,
>
> Comments below.
>
> Christian W. Damus wrote:
>> Hi, Ed,
>>
>> So, you're saying that the feature IDs are an internal implementation
>> detail and should not be published in the package interface.
> I didn't hear me say that! :-P

Oh, but I did. :-D You said that the IDs are offsets into the lists of
features. That's an implementation choice, and is the only reason why
they have to change when new features are added.


>> Certainly, it is an error for client code to reference the feature
>> ID constants.
> No, it's not. It all comes down to expectations. If you look at the
> generated code for the binary compatible reflective methods you'll see
> that such constants can be safely used even if their values change in a
> binary incompatible way.

Yes, but that's a code pattern generated by EMF to work around its own
binary-incompatible changes. According to Eclipse's development
practices vis-a-vis API, this needs to be flagged to clients as an
exception to the rules of API evolution.


>> Is this widely known?
> Don't you find it telling that this has not been raised as an issue in
> the last 7 years? Binary compatibility is one of those holy grails that

Folks have been lucky, I guess, that they haven't tried to upgrade the
plug-in that deploys an EMF-generated model while continuing to use a
plug-in that was compiled against an older version. I have seen code
that uses the feature IDs in switch statements, and which would
definitely break in an upgrade scenario.

Binary compatibility isn't a holy grail. It's quite practically
realizable. Especially with tools like the PDE available to help :-)


> no one questions and yet mostly folks build new versions of the software
> and recompile... It's very easy after all to put a tight version range
> bound to address an issue like this. You remember some of your reasons
> for tight version range bounds on your Ecore dependencies? :-P

I did that because I knowingly implemented the discouraged practice of
extending Ecore. I wouldn't have, otherwise. A reasonable defence
mechanism for clients would be to treat the feature IDs as internal API
and use these narrow dependency ranges, yes.


>> Luckily, the API tooling gives us the means to impose that
>> restriction, using the @noreference tag in the doc comments. I can
>> apply that to my OCL models as they change (currently, changes
>> contributed to the concrete-syntax model are throwing up red flags).
> Or you could just not change your model. Or add things only to leaf
> classes... Just a like joke. :-P

Heh heh ... good one. :-)


>> In the mean-time, perhaps EMF can help by any one of:
>>
>> - optionally not publishing the feature IDs in the package interface
> Where to publish them then? They're needed in downstream derived
> models. And even if we move them, the problem associated with them
> doesn't change, it just moves...

Publish them on the package implementation class. Clients are already
discouraged from using it, so it's a natural home.


>> - optionally including an @noreference tag in the doc comment
>> for every feature ID. I should be able to do this for myself
>> with a dynamic template, for now
> We could have such an option.

Oo! I would be happy to work on such an enhancement, if you're
interested. A GenModel option for API Tools support could add several
useful annotations:

- @noreference on the feature IDs
- @noimplement on all of the generated interfaces. Otherwise, API
Tools rightly flags additions of any new features (i.e., their
accessor methods) as incompatible changes
- @noreference on the *Impl classes, to formalize this convention
- @since tags on new API elements, being smart to determine the new
plug-in version number

There may be more, of course. I'm gradually discovering all of the API
flags that crop up when re-generating a model with new content.


>> - adding the @noreference tag to the getFeatureID() method of the
>> Notifier class, so that clients will be discourage from a common
>> cause of referencing these constants
> It's not this method that has a problem. It could very well be compared
> to dynamic computed feature IDs.

Right, not a good idea.


>> The problem with relying on the API tooling, of course, is that it
>> depends on a client using it and on having the API metadata available
>> (which generally isn't in an OCL build that one might have the target
>> environment). Even this change in the contract is, technically, a
>> breaking API change. However, that contract has already been broken
>> in every release ...
> Again, doesn't this tell you something?

That some of us have, for years, been missing an obvious problem that
PDE's API Tools have shone a big spotlight on. :-D


> The only other generated place the constants are used is in the item
> providers, where we could do something similar to what we did for the
> reflective methods or we could compare against feature instances instead
> (optionally of course).

The item providers aren't a problem, though, are they? Because they are
regenerated and, hence, recompiled and redeployed together with the
model API.

>>
>> Cheers,
>>
>> Christian
>>
>>
>> Ed Merks wrote:
>>> Christian,
>>>
>>> Comments below.
>>>
>>>
>>> Christian W. Damus wrote:
>>>> Hi,
>>>>
>>>> I have recently begun using the PDE's very cool API Tools in the
>>>> Eclipse OCL project. I am quite satisfied with the API tooling, but
>>>> it raised a problem that worries me, in the binary compatibility of
>>>> EMF-generated models.
>>>>
>>>> The package meta-data interface has hordes of static int constants
>>>> identifying feature IDs. Users of a model API commonly use these in
>>>> switch statements in Adapters and related listener mechanisms. The
>>>> API tooling pointed out a binary-incompatible change when I
>>>> re-generated after adding a new attribute to one of the base classes
>>>> in my model.
>>> Indeed, that's the "cost" of using a highly efficient switch
>>> mechanism...
>>>>
>>>> The problem is, that virtually all of the feature-ID constants in my
>>>> model changed because the feature-count of a base class was
>>>> incremented, and all of these feature IDs are based on the count of
>>>> inherited features.
>>> Certainly all derived feature IDs will change when the base has a
>>> feature added.
>>>> The reason why this is a binary compatibility issue is that the Java
>>>> compiler in-lined all of these constants into users' Adapter code
>>>> when they compiled against the previous OCL version.
>>> Indded.
>>>>
>>>> What can I do to have the generator just assign new IDs in a
>>>> binary-compatible way?
>>> Nothing. The IDs are by designed offsets into the list of all
>>> features. In the models we have "Binary Compatible Reflective
>>> Methods" but we've done nothing for the switches on an adapter.
>>> After more than 6 years with this situation, no one has even
>>> expressed a concern about the item provider issue. Go figure... :-P
>>>>
>>>> Thanks,
>>>>
>>>> Christian
Re: EMF + API Tools [message #423374 is a reply to message #423371] Mon, 29 September 2008 15:43 Go to previous messageGo to next message
Ed Merks is currently offline Ed MerksFriend
Messages: 30804
Registered: July 2009
Senior Member
This is a multi-part message in MIME format.
--------------090703000802080307080302
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Christian,

Comments below.


Christian W. Damus wrote:
> Hi, Ed,
>
> More replies in-line, below.
>
> Thanks,
>
> Christian
>
>
> Ed Merks wrote:
>> Christian,
>>
>> Comments below.
>>
>> Christian W. Damus wrote:
>>> Hi, Ed,
>>>
>>> So, you're saying that the feature IDs are an internal
>>> implementation detail and should not be published in the package
>>> interface.
>> I didn't hear me say that! :-P
>
> Oh, but I did. :-D You said that the IDs are offsets into the lists
> of features. That's an implementation choice,
I'd call it a design choice.
> and is the only reason why they have to change when new features are
> added.
They are designed to change...
>
>
>>> Certainly, it is an error for client code to reference the feature
>>> ID constants.
>> No, it's not. It all comes down to expectations. If you look at the
>> generated code for the binary compatible reflective methods you'll
>> see that such constants can be safely used even if their values
>> change in a binary incompatible way.
>
> Yes, but that's a code pattern generated by EMF to work around its own
> binary-incompatible changes.
It's a design that performs well.
> According to Eclipse's development practices vis-a-vis API, this
> needs to be flagged to clients as an exception to the rules of API
> evolution.
Contributions will be considered. :-P
>
>
>>> Is this widely known?
>> Don't you find it telling that this has not been raised as an issue
>> in the last 7 years? Binary compatibility is one of those holy
>> grails that
>
> Folks have been lucky, I guess, that they haven't tried to upgrade the
> plug-in that deploys an EMF-generated model while continuing to use a
> plug-in that was compiled against an older version. I have seen code
> that uses the feature IDs in switch statements, and which would
> definitely break in an upgrade scenario.
100% lucky so far...
>
> Binary compatibility isn't a holy grail. It's quite practically
> realizable. Especially with tools like the PDE available to help :-)
It's an ideal. I didn't say it's not achievable.
>
>
>> no one questions and yet mostly folks build new versions of the
>> software and recompile... It's very easy after all to put a tight
>> version range bound to address an issue like this. You remember some
>> of your reasons for tight version range bounds on your Ecore
>> dependencies? :-P
>
> I did that because I knowingly implemented the discouraged practice of
> extending Ecore. I wouldn't have, otherwise. A reasonable defence
> mechanism for clients would be to treat the feature IDs as internal
> API and use these narrow dependency ranges, yes.
Yep.
>
>
>>> Luckily, the API tooling gives us the means to impose that
>>> restriction, using the @noreference tag in the doc comments. I can
>>> apply that to my OCL models as they change (currently, changes
>>> contributed to the concrete-syntax model are throwing up red flags).
>> Or you could just not change your model. Or add things only to leaf
>> classes... Just a like joke. :-P
>
> Heh heh ... good one. :-)
>
>
>>> In the mean-time, perhaps EMF can help by any one of:
>>>
>>> - optionally not publishing the feature IDs in the package interface
>> Where to publish them then? They're needed in downstream derived
>> models. And even if we move them, the problem associated with them
>> doesn't change, it just moves...
>
> Publish them on the package implementation class.
Again, it just moves them.
> Clients are already discouraged from using it, so it's a natural home.
But clients with derived models need them.
>
>
>>> - optionally including an @noreference tag in the doc comment
>>> for every feature ID. I should be able to do this for myself
>>> with a dynamic template, for now
>> We could have such an option.
>
> Oo! I would be happy to work on such an enhancement, if you're
> interested. A GenModel option for API Tools support could add several
> useful annotations:
>
> - @noreference on the feature IDs
> - @noimplement on all of the generated interfaces. Otherwise, API
> Tools rightly flags additions of any new features (i.e., their
> accessor methods) as incompatible changes
> - @noreference on the *Impl classes, to formalize this convention
> - @since tags on new API elements, being smart to determine the new
> plug-in version number
>
> There may be more, of course. I'm gradually discovering all of the
> API flags that crop up when re-generating a model with new content.
This sounds cool. Sounds like a lot of work!
>
>
>>> - adding the @noreference tag to the getFeatureID() method of the
>>> Notifier class, so that clients will be discourage from a common
>>> cause of referencing these constants
>> It's not this method that has a problem. It could very well be
>> compared to dynamic computed feature IDs.
>
> Right, not a good idea.
>
>
>>> The problem with relying on the API tooling, of course, is that it
>>> depends on a client using it and on having the API metadata
>>> available (which generally isn't in an OCL build that one might have
>>> the target environment). Even this change in the contract is,
>>> technically, a breaking API change. However, that contract has
>>> already been broken in every release ...
>> Again, doesn't this tell you something?
>
> That some of us have, for years, been missing an obvious problem that
> PDE's API Tools have shone a big spotlight on. :-D
Yes, and also that potential problems often are *not *manifested as real
problems.
>
>
>> The only other generated place the constants are used is in the item
>> providers, where we could do something similar to what we did for the
>> reflective methods or we could compare against feature instances
>> instead (optionally of course).
>
> The item providers aren't a problem, though, are they? Because they
> are regenerated and, hence, recompiled and redeployed together with
> the model API.
Not if only the base class from a different model is changed. The
problem is the same as with the reflective accessors...
>
>>>
>>> Cheers,
>>>
>>> Christian
>>>
>>>
>>> Ed Merks wrote:
>>>> Christian,
>>>>
>>>> Comments below.
>>>>
>>>>
>>>> Christian W. Damus wrote:
>>>>> Hi,
>>>>>
>>>>> I have recently begun using the PDE's very cool API Tools in the
>>>>> Eclipse OCL project. I am quite satisfied with the API tooling,
>>>>> but it raised a problem that worries me, in the binary
>>>>> compatibility of EMF-generated models.
>>>>>
>>>>> The package meta-data interface has hordes of static int constants
>>>>> identifying feature IDs. Users of a model API commonly use these
>>>>> in switch statements in Adapters and related listener mechanisms.
>>>>> The API tooling pointed out a binary-incompatible change when I
>>>>> re-generated after adding a new attribute to one of the base
>>>>> classes in my model.
>>>> Indeed, that's the "cost" of using a highly efficient switch
>>>> mechanism...
>>>>>
>>>>> The problem is, that virtually all of the feature-ID constants in
>>>>> my model changed because the feature-count of a base class was
>>>>> incremented, and all of these feature IDs are based on the count
>>>>> of inherited features.
>>>> Certainly all derived feature IDs will change when the base has a
>>>> feature added.
>>>>> The reason why this is a binary compatibility issue is that the
>>>>> Java compiler in-lined all of these constants into users' Adapter
>>>>> code when they compiled against the previous OCL version.
>>>> Indded.
>>>>>
>>>>> What can I do to have the generator just assign new IDs in a
>>>>> binary-compatible way?
>>>> Nothing. The IDs are by designed offsets into the list of all
>>>> features. In the models we have "Binary Compatible Reflective
>>>> Methods" but we've done nothing for the switches on an adapter.
>>>> After more than 6 years with this situation, no one has even
>>>> expressed a concern about the item provider issue. Go figure... :-P
>>>>>
>>>>> Thanks,
>>>>>
>>>>> Christian

--------------090703000802080307080302
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type">
</head>
<body bgcolor="#ffffff" text="#000000">
Christian,<br>
<br>
Comments below.<br>
<br>
<br>
Christian W. Damus wrote:
<blockquote cite="mid:gbqq3c$kht$1@build.eclipse.org" type="cite">Hi,
Ed,
<br>
<br>
More replies in-line, below.
<br>
<br>
Thanks,
<br>
<br>
Christian
<br>
<br>
<br>
Ed Merks wrote:
<br>
<blockquote type="cite">Christian,
<br>
<br>
Comments below.
<br>
<br>
Christian W. Damus wrote:
<br>
<blockquote type="cite">Hi, Ed,
<br>
<br>
So, you're saying that the feature IDs are an internal implementation
detail and should not be published in the package interface.
<br>
</blockquote>
I didn't hear me say that! :-P
<br>
</blockquote>
<br>
Oh, but I did.&nbsp; :-D&nbsp; You said that the IDs are offsets into the lists
of features.&nbsp; That's an implementation choice, </blockquote>
I'd call it a design choice.<br>
<blockquote cite="mid:gbqq3c$kht$1@build.eclipse.org" type="cite">and
is the only reason why they have to change when new features are added.
<br>
</blockquote>
They are designed to change...<br>
<blockquote cite="mid:gbqq3c$kht$1@build.eclipse.org" type="cite"><br>
<br>
<blockquote type="cite">
<blockquote type="cite">&nbsp; Certainly, it is an error for client code
to reference the feature ID constants.
<br>
</blockquote>
No, it's not.&nbsp; It all comes down to expectations.&nbsp; If you look at the
generated code for the binary compatible reflective methods you'll see
that such constants can be safely used even if their values change in a
binary incompatible way.
<br>
</blockquote>
<br>
Yes, but that's a code pattern generated by EMF to work around its own
binary-incompatible changes.</blockquote>
It's a design that performs well.<br>
<blockquote cite="mid:gbqq3c$kht$1@build.eclipse.org" type="cite">&nbsp;
According to Eclipse's development practices vis-a-vis API, this needs
to be flagged to clients as an exception to the rules of API evolution.
<br>
</blockquote>
Contributions will be considered. :-P<br>
<blockquote cite="mid:gbqq3c$kht$1@build.eclipse.org" type="cite"><br>
<br>
<blockquote type="cite">
<blockquote type="cite">Is this widely known?
<br>
</blockquote>
Don't you find it telling that this has not been raised as an issue in
the last 7 years?&nbsp; Binary compatibility is one of those holy grails
that </blockquote>
<br>
Folks have been lucky, I guess, that they haven't tried to upgrade the
plug-in that deploys an EMF-generated model while continuing to use a
plug-in that was compiled against an older version.&nbsp; I have seen code
that uses the feature IDs in switch statements, and which would
definitely break in an upgrade scenario.
<br>
</blockquote>
100% lucky so far...<br>
<blockquote cite="mid:gbqq3c$kht$1@build.eclipse.org" type="cite"><br>
Binary compatibility isn't a holy grail.&nbsp; It's quite practically
realizable.&nbsp; Especially with tools like the PDE available to help&nbsp; :-)
<br>
</blockquote>
It's an ideal.&nbsp; I didn't say it's not achievable.&nbsp; <br>
<blockquote cite="mid:gbqq3c$kht$1@build.eclipse.org" type="cite"><br>
<br>
<blockquote type="cite">no one questions and yet mostly folks build
new versions of the software and recompile...&nbsp; It's very easy after all
to put a tight version range bound to address an issue like this.&nbsp; You
remember some of your reasons for tight version range bounds on your
Ecore dependencies? :-P
<br>
</blockquote>
<br>
I did that because I knowingly implemented the discouraged practice of
extending Ecore.&nbsp; I wouldn't have, otherwise.&nbsp; A reasonable defence
mechanism for clients would be to treat the feature IDs as internal API
and use these narrow dependency ranges, yes.
<br>
</blockquote>
Yep.<br>
<blockquote cite="mid:gbqq3c$kht$1@build.eclipse.org" type="cite"><br>
<br>
<blockquote type="cite">
<blockquote type="cite">Luckily, the API tooling gives us the means
to impose that restriction, using the @noreference tag in the doc
comments.&nbsp; I can apply that to my OCL models as they change (currently,
changes contributed to the concrete-syntax model are throwing up red
flags).
<br>
</blockquote>
Or you could just not change your model.&nbsp; Or add things only to leaf
classes...&nbsp; Just a like joke. :-P
<br>
</blockquote>
<br>
Heh heh ... good one.&nbsp; :-)
<br>
<br>
<br>
<blockquote type="cite">
<blockquote type="cite">In the mean-time, perhaps EMF can help by
any one of:
<br>
<br>
&nbsp; - optionally not publishing the feature IDs in the package interface
<br>
</blockquote>
Where to publish them then?&nbsp; They're needed in downstream derived
models.&nbsp; And even if we move them, the problem associated with them
doesn't change, it just moves...
<br>
</blockquote>
<br>
Publish them on the package implementation class. <br>
</blockquote>
Again, it just moves them.<br>
<blockquote cite="mid:gbqq3c$kht$1@build.eclipse.org" type="cite">
Clients are already discouraged from using it, so it's a natural home.
<br>
</blockquote>
But clients with derived models need them.<br>
<blockquote cite="mid:gbqq3c$kht$1@build.eclipse.org" type="cite"><br>
<br>
<blockquote type="cite">
<blockquote type="cite">&nbsp; - optionally including an @noreference
tag in the doc comment
<br>
&nbsp;&nbsp;&nbsp; for every feature ID.&nbsp; I should be able to do this for myself
<br>
&nbsp;&nbsp;&nbsp; with a dynamic template, for now
<br>
</blockquote>
We could have such an option.
<br>
</blockquote>
<br>
Oo!&nbsp; I would be happy to work on such an enhancement, if you're
interested.&nbsp; A GenModel option for API Tools support could add several
useful annotations:
<br>
<br>
&nbsp; - @noreference on the feature IDs
<br>
&nbsp; - @noimplement on all of the generated interfaces.&nbsp; Otherwise, API
<br>
&nbsp;&nbsp;&nbsp; Tools rightly flags additions of any new features (i.e., their
<br>
&nbsp;&nbsp;&nbsp; accessor methods) as incompatible changes
<br>
&nbsp; - @noreference on the *Impl classes, to formalize this convention
<br>
&nbsp; - @since tags on new API elements, being smart to determine the new
<br>
&nbsp;&nbsp;&nbsp; plug-in version number
<br>
<br>
There may be more, of course.&nbsp; I'm gradually discovering all of the API
flags that crop up when re-generating a model with new content.
<br>
</blockquote>
This sounds cool.&nbsp; Sounds like a lot of work!<br>
<blockquote cite="mid:gbqq3c$kht$1@build.eclipse.org" type="cite"><br>
<br>
<blockquote type="cite">
<blockquote type="cite">&nbsp; - adding the @noreference tag to the
getFeatureID() method of the
<br>
&nbsp;&nbsp;&nbsp; Notifier class, so that clients will be discourage from a common
<br>
&nbsp;&nbsp;&nbsp; cause of referencing these constants
<br>
</blockquote>
It's not this method that has a problem.&nbsp; It could very well be
compared to dynamic computed feature IDs.
<br>
</blockquote>
<br>
Right, not a good idea.
<br>
<br>
<br>
<blockquote type="cite">
<blockquote type="cite">The problem with relying on the API
tooling, of course, is that it depends on a client using it and on
having the API metadata available (which generally isn't in an OCL
build that one might have the target environment).&nbsp; Even this change in
the contract is, technically, a breaking API change.&nbsp; However, that
contract has already been broken in every release ...
<br>
</blockquote>
Again, doesn't this tell you something?
<br>
</blockquote>
<br>
That some of us have, for years, been missing an obvious problem that
PDE's API Tools have shone a big spotlight on.&nbsp; :-D
<br>
</blockquote>
Yes, and also that potential problems often are <b>not </b>manifested
as real problems.<br>
<blockquote cite="mid:gbqq3c$kht$1@build.eclipse.org" type="cite"><br>
<br>
<blockquote type="cite">The only other generated place the constants
are used is in the item providers, where we could do something similar
to what we did for the reflective methods or we could compare against
feature instances instead (optionally of course).
<br>
</blockquote>
<br>
The item providers aren't a problem, though, are they?&nbsp; Because they
are regenerated and, hence, recompiled and redeployed together with the
model API.
<br>
</blockquote>
Not if only the base class from a different model is changed.&nbsp; The
problem is the same as with the reflective accessors...<br>
<blockquote cite="mid:gbqq3c$kht$1@build.eclipse.org" type="cite"><br>
<blockquote type="cite">
<blockquote type="cite"><br>
Cheers,
<br>
<br>
Christian
<br>
<br>
<br>
Ed Merks wrote:
<br>
<blockquote type="cite">Christian,
<br>
<br>
Comments below.
<br>
<br>
<br>
Christian W. Damus wrote:
<br>
<blockquote type="cite">Hi,
<br>
<br>
I have recently begun using the PDE's very cool API Tools in the
Eclipse OCL project.&nbsp; I am quite satisfied with the API tooling, but it
raised a problem that worries me, in the binary compatibility of
EMF-generated models.
<br>
<br>
The package meta-data interface has hordes of static int constants
identifying feature IDs.&nbsp; Users of a model API commonly use these in
switch statements in Adapters and related listener mechanisms.&nbsp; The API
tooling pointed out a binary-incompatible change when I re-generated
after adding a new attribute to one of the base classes in my model.
<br>
</blockquote>
Indeed, that's the "cost" of using a highly efficient switch
mechanism...
<br>
<blockquote type="cite"><br>
The problem is, that virtually all of the feature-ID constants in my
model changed because the feature-count of a base class was
incremented, and all of these feature IDs are based on the count of
inherited features.
<br>
</blockquote>
Certainly all derived feature IDs will change when the base has a
feature added.
<br>
<blockquote type="cite">The reason why this is a binary
compatibility issue is that the Java compiler in-lined all of these
constants into users' Adapter code when they compiled against the
previous OCL version.
<br>
</blockquote>
Indded.
<br>
<blockquote type="cite"><br>
What can I do to have the generator just assign new IDs in a
binary-compatible way?
<br>
</blockquote>
Nothing.&nbsp; The IDs are by designed offsets into the list of all
features.&nbsp; In the models we have "Binary Compatible Reflective Methods"
but we've done nothing for the switches on an adapter.&nbsp; After more than
6 years with this situation, no one has even expressed a concern about
the item provider issue.&nbsp; Go figure... :-P
<br>
<blockquote type="cite"><br>
Thanks,
<br>
<br>
Christian
<br>
</blockquote>
</blockquote>
</blockquote>
</blockquote>
</blockquote>
</body>
</html>

--------------090703000802080307080302--
Re: EMF + API Tools [message #423380 is a reply to message #423374] Mon, 29 September 2008 16:27 Go to previous messageGo to next message
Thomas Schindl is currently offline Thomas SchindlFriend
Messages: 6516
Registered: July 2009
Senior Member
I know this sounds strange but how much does this inlining bring if you
don't declare them as literals?

E.g. Databinding uses the following trick.

-------8<-------
public static int POLICY_NEVER = notInlined(1);

private static int notInlined(int i) {
return i;
}
-------8<-------


Tom

Ed Merks schrieb:
> Christian,
>
> Comments below.
>
>
> Christian W. Damus wrote:
>> Hi, Ed,
>>
>> More replies in-line, below.
>>
>> Thanks,
>>
>> Christian
>>
>>
>> Ed Merks wrote:
>>> Christian,
>>>
>>> Comments below.
>>>
>>> Christian W. Damus wrote:
>>>> Hi, Ed,
>>>>
>>>> So, you're saying that the feature IDs are an internal
>>>> implementation detail and should not be published in the package
>>>> interface.
>>> I didn't hear me say that! :-P
>>
>> Oh, but I did. :-D You said that the IDs are offsets into the lists
>> of features. That's an implementation choice,
> I'd call it a design choice.
>> and is the only reason why they have to change when new features are
>> added.
> They are designed to change...
>>
>>
>>>> Certainly, it is an error for client code to reference the feature
>>>> ID constants.
>>> No, it's not. It all comes down to expectations. If you look at the
>>> generated code for the binary compatible reflective methods you'll
>>> see that such constants can be safely used even if their values
>>> change in a binary incompatible way.
>>
>> Yes, but that's a code pattern generated by EMF to work around its own
>> binary-incompatible changes.
> It's a design that performs well.
>> According to Eclipse's development practices vis-a-vis API, this
>> needs to be flagged to clients as an exception to the rules of API
>> evolution.
> Contributions will be considered. :-P
>>
>>
>>>> Is this widely known?
>>> Don't you find it telling that this has not been raised as an issue
>>> in the last 7 years? Binary compatibility is one of those holy
>>> grails that
>>
>> Folks have been lucky, I guess, that they haven't tried to upgrade the
>> plug-in that deploys an EMF-generated model while continuing to use a
>> plug-in that was compiled against an older version. I have seen code
>> that uses the feature IDs in switch statements, and which would
>> definitely break in an upgrade scenario.
> 100% lucky so far...
>>
>> Binary compatibility isn't a holy grail. It's quite practically
>> realizable. Especially with tools like the PDE available to help :-)
> It's an ideal. I didn't say it's not achievable.
>>
>>
>>> no one questions and yet mostly folks build new versions of the
>>> software and recompile... It's very easy after all to put a tight
>>> version range bound to address an issue like this. You remember some
>>> of your reasons for tight version range bounds on your Ecore
>>> dependencies? :-P
>>
>> I did that because I knowingly implemented the discouraged practice of
>> extending Ecore. I wouldn't have, otherwise. A reasonable defence
>> mechanism for clients would be to treat the feature IDs as internal
>> API and use these narrow dependency ranges, yes.
> Yep.
>>
>>
>>>> Luckily, the API tooling gives us the means to impose that
>>>> restriction, using the @noreference tag in the doc comments. I can
>>>> apply that to my OCL models as they change (currently, changes
>>>> contributed to the concrete-syntax model are throwing up red flags).
>>> Or you could just not change your model. Or add things only to leaf
>>> classes... Just a like joke. :-P
>>
>> Heh heh ... good one. :-)
>>
>>
>>>> In the mean-time, perhaps EMF can help by any one of:
>>>>
>>>> - optionally not publishing the feature IDs in the package interface
>>> Where to publish them then? They're needed in downstream derived
>>> models. And even if we move them, the problem associated with them
>>> doesn't change, it just moves...
>>
>> Publish them on the package implementation class.
> Again, it just moves them.
>> Clients are already discouraged from using it, so it's a natural home.
> But clients with derived models need them.
>>
>>
>>>> - optionally including an @noreference tag in the doc comment
>>>> for every feature ID. I should be able to do this for myself
>>>> with a dynamic template, for now
>>> We could have such an option.
>>
>> Oo! I would be happy to work on such an enhancement, if you're
>> interested. A GenModel option for API Tools support could add several
>> useful annotations:
>>
>> - @noreference on the feature IDs
>> - @noimplement on all of the generated interfaces. Otherwise, API
>> Tools rightly flags additions of any new features (i.e., their
>> accessor methods) as incompatible changes
>> - @noreference on the *Impl classes, to formalize this convention
>> - @since tags on new API elements, being smart to determine the new
>> plug-in version number
>>
>> There may be more, of course. I'm gradually discovering all of the
>> API flags that crop up when re-generating a model with new content.
> This sounds cool. Sounds like a lot of work!
>>
>>
>>>> - adding the @noreference tag to the getFeatureID() method of the
>>>> Notifier class, so that clients will be discourage from a common
>>>> cause of referencing these constants
>>> It's not this method that has a problem. It could very well be
>>> compared to dynamic computed feature IDs.
>>
>> Right, not a good idea.
>>
>>
>>>> The problem with relying on the API tooling, of course, is that it
>>>> depends on a client using it and on having the API metadata
>>>> available (which generally isn't in an OCL build that one might have
>>>> the target environment). Even this change in the contract is,
>>>> technically, a breaking API change. However, that contract has
>>>> already been broken in every release ...
>>> Again, doesn't this tell you something?
>>
>> That some of us have, for years, been missing an obvious problem that
>> PDE's API Tools have shone a big spotlight on. :-D
> Yes, and also that potential problems often are *not *manifested as real
> problems.
>>
>>
>>> The only other generated place the constants are used is in the item
>>> providers, where we could do something similar to what we did for the
>>> reflective methods or we could compare against feature instances
>>> instead (optionally of course).
>>
>> The item providers aren't a problem, though, are they? Because they
>> are regenerated and, hence, recompiled and redeployed together with
>> the model API.
> Not if only the base class from a different model is changed. The
> problem is the same as with the reflective accessors...
>>
>>>>
>>>> Cheers,
>>>>
>>>> Christian
>>>>
>>>>
>>>> Ed Merks wrote:
>>>>> Christian,
>>>>>
>>>>> Comments below.
>>>>>
>>>>>
>>>>> Christian W. Damus wrote:
>>>>>> Hi,
>>>>>>
>>>>>> I have recently begun using the PDE's very cool API Tools in the
>>>>>> Eclipse OCL project. I am quite satisfied with the API tooling,
>>>>>> but it raised a problem that worries me, in the binary
>>>>>> compatibility of EMF-generated models.
>>>>>>
>>>>>> The package meta-data interface has hordes of static int constants
>>>>>> identifying feature IDs. Users of a model API commonly use these
>>>>>> in switch statements in Adapters and related listener mechanisms.
>>>>>> The API tooling pointed out a binary-incompatible change when I
>>>>>> re-generated after adding a new attribute to one of the base
>>>>>> classes in my model.
>>>>> Indeed, that's the "cost" of using a highly efficient switch
>>>>> mechanism...
>>>>>>
>>>>>> The problem is, that virtually all of the feature-ID constants in
>>>>>> my model changed because the feature-count of a base class was
>>>>>> incremented, and all of these feature IDs are based on the count
>>>>>> of inherited features.
>>>>> Certainly all derived feature IDs will change when the base has a
>>>>> feature added.
>>>>>> The reason why this is a binary compatibility issue is that the
>>>>>> Java compiler in-lined all of these constants into users' Adapter
>>>>>> code when they compiled against the previous OCL version.
>>>>> Indded.
>>>>>>
>>>>>> What can I do to have the generator just assign new IDs in a
>>>>>> binary-compatible way?
>>>>> Nothing. The IDs are by designed offsets into the list of all
>>>>> features. In the models we have "Binary Compatible Reflective
>>>>> Methods" but we've done nothing for the switches on an adapter.
>>>>> After more than 6 years with this situation, no one has even
>>>>> expressed a concern about the item provider issue. Go figure... :-P
>>>>>>
>>>>>> Thanks,
>>>>>>
>>>>>> Christian


--
B e s t S o l u t i o n . at
------------------------------------------------------------ --------
Tom Schindl JFace-Committer
------------------------------------------------------------ --------
Re: EMF + API Tools [message #423381 is a reply to message #423380] Mon, 29 September 2008 16:32 Go to previous messageGo to next message
Ed Merks is currently offline Ed MerksFriend
Messages: 30804
Registered: July 2009
Senior Member
This is a multi-part message in MIME format.
--------------080405040507040203060300
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Tom,

Comments below.

Tom Schindl wrote:
> I know this sounds strange but how much does this inlining bring if you
> don't declare them as literals?
>
> E.g. Databinding uses the following trick.
>
> -------8<-------
> public static int POLICY_NEVER = notInlined(1);
>
The values are used in a switch, which requires a compile time
constant. The intent is to provide constant time dispatch on features...
> private static int notInlined(int i) {
> return i;
> }
> -------8<-------
>
>
> Tom
>
> Ed Merks schrieb:
>
>> Christian,
>>
>> Comments below.
>>
>>
>> Christian W. Damus wrote:
>>
>>> Hi, Ed,
>>>
>>> More replies in-line, below.
>>>
>>> Thanks,
>>>
>>> Christian
>>>
>>>
>>> Ed Merks wrote:
>>>
>>>> Christian,
>>>>
>>>> Comments below.
>>>>
>>>> Christian W. Damus wrote:
>>>>
>>>>> Hi, Ed,
>>>>>
>>>>> So, you're saying that the feature IDs are an internal
>>>>> implementation detail and should not be published in the package
>>>>> interface.
>>>>>
>>>> I didn't hear me say that! :-P
>>>>
>>> Oh, but I did. :-D You said that the IDs are offsets into the lists
>>> of features. That's an implementation choice,
>>>
>> I'd call it a design choice.
>>
>>> and is the only reason why they have to change when new features are
>>> added.
>>>
>> They are designed to change...
>>
>>>
>>>>> Certainly, it is an error for client code to reference the feature
>>>>> ID constants.
>>>>>
>>>> No, it's not. It all comes down to expectations. If you look at the
>>>> generated code for the binary compatible reflective methods you'll
>>>> see that such constants can be safely used even if their values
>>>> change in a binary incompatible way.
>>>>
>>> Yes, but that's a code pattern generated by EMF to work around its own
>>> binary-incompatible changes.
>>>
>> It's a design that performs well.
>>
>>> According to Eclipse's development practices vis-a-vis API, this
>>> needs to be flagged to clients as an exception to the rules of API
>>> evolution.
>>>
>> Contributions will be considered. :-P
>>
>>>
>>>>> Is this widely known?
>>>>>
>>>> Don't you find it telling that this has not been raised as an issue
>>>> in the last 7 years? Binary compatibility is one of those holy
>>>> grails that
>>>>
>>> Folks have been lucky, I guess, that they haven't tried to upgrade the
>>> plug-in that deploys an EMF-generated model while continuing to use a
>>> plug-in that was compiled against an older version. I have seen code
>>> that uses the feature IDs in switch statements, and which would
>>> definitely break in an upgrade scenario.
>>>
>> 100% lucky so far...
>>
>>> Binary compatibility isn't a holy grail. It's quite practically
>>> realizable. Especially with tools like the PDE available to help :-)
>>>
>> It's an ideal. I didn't say it's not achievable.
>>
>>>
>>>> no one questions and yet mostly folks build new versions of the
>>>> software and recompile... It's very easy after all to put a tight
>>>> version range bound to address an issue like this. You remember some
>>>> of your reasons for tight version range bounds on your Ecore
>>>> dependencies? :-P
>>>>
>>> I did that because I knowingly implemented the discouraged practice of
>>> extending Ecore. I wouldn't have, otherwise. A reasonable defence
>>> mechanism for clients would be to treat the feature IDs as internal
>>> API and use these narrow dependency ranges, yes.
>>>
>> Yep.
>>
>>>
>>>>> Luckily, the API tooling gives us the means to impose that
>>>>> restriction, using the @noreference tag in the doc comments. I can
>>>>> apply that to my OCL models as they change (currently, changes
>>>>> contributed to the concrete-syntax model are throwing up red flags).
>>>>>
>>>> Or you could just not change your model. Or add things only to leaf
>>>> classes... Just a like joke. :-P
>>>>
>>> Heh heh ... good one. :-)
>>>
>>>
>>>
>>>>> In the mean-time, perhaps EMF can help by any one of:
>>>>>
>>>>> - optionally not publishing the feature IDs in the package interface
>>>>>
>>>> Where to publish them then? They're needed in downstream derived
>>>> models. And even if we move them, the problem associated with them
>>>> doesn't change, it just moves...
>>>>
>>> Publish them on the package implementation class.
>>>
>> Again, it just moves them.
>>
>>> Clients are already discouraged from using it, so it's a natural home.
>>>
>> But clients with derived models need them.
>>
>>>
>>>>> - optionally including an @noreference tag in the doc comment
>>>>> for every feature ID. I should be able to do this for myself
>>>>> with a dynamic template, for now
>>>>>
>>>> We could have such an option.
>>>>
>>> Oo! I would be happy to work on such an enhancement, if you're
>>> interested. A GenModel option for API Tools support could add several
>>> useful annotations:
>>>
>>> - @noreference on the feature IDs
>>> - @noimplement on all of the generated interfaces. Otherwise, API
>>> Tools rightly flags additions of any new features (i.e., their
>>> accessor methods) as incompatible changes
>>> - @noreference on the *Impl classes, to formalize this convention
>>> - @since tags on new API elements, being smart to determine the new
>>> plug-in version number
>>>
>>> There may be more, of course. I'm gradually discovering all of the
>>> API flags that crop up when re-generating a model with new content.
>>>
>> This sounds cool. Sounds like a lot of work!
>>
>>>
>>>>> - adding the @noreference tag to the getFeatureID() method of the
>>>>> Notifier class, so that clients will be discourage from a common
>>>>> cause of referencing these constants
>>>>>
>>>> It's not this method that has a problem. It could very well be
>>>> compared to dynamic computed feature IDs.
>>>>
>>> Right, not a good idea.
>>>
>>>
>>>
>>>>> The problem with relying on the API tooling, of course, is that it
>>>>> depends on a client using it and on having the API metadata
>>>>> available (which generally isn't in an OCL build that one might have
>>>>> the target environment). Even this change in the contract is,
>>>>> technically, a breaking API change. However, that contract has
>>>>> already been broken in every release ...
>>>>>
>>>> Again, doesn't this tell you something?
>>>>
>>> That some of us have, for years, been missing an obvious problem that
>>> PDE's API Tools have shone a big spotlight on. :-D
>>>
>> Yes, and also that potential problems often are *not *manifested as real
>> problems.
>>
>>>
>>>> The only other generated place the constants are used is in the item
>>>> providers, where we could do something similar to what we did for the
>>>> reflective methods or we could compare against feature instances
>>>> instead (optionally of course).
>>>>
>>> The item providers aren't a problem, though, are they? Because they
>>> are regenerated and, hence, recompiled and redeployed together with
>>> the model API.
>>>
>> Not if only the base class from a different model is changed. The
>> problem is the same as with the reflective accessors...
>>
>>>>> Cheers,
>>>>>
>>>>> Christian
>>>>>
>>>>>
>>>>> Ed Merks wrote:
>>>>>
>>>>>> Christian,
>>>>>>
>>>>>> Comments below.
>>>>>>
>>>>>>
>>>>>> Christian W. Damus wrote:
>>>>>>
>>>>>>> Hi,
>>>>>>>
>>>>>>> I have recently begun using the PDE's very cool API Tools in the
>>>>>>> Eclipse OCL project. I am quite satisfied with the API tooling,
>>>>>>> but it raised a problem that worries me, in the binary
>>>>>>> compatibility of EMF-generated models.
>>>>>>>
>>>>>>> The package meta-data interface has hordes of static int constants
>>>>>>> identifying feature IDs. Users of a model API commonly use these
>>>>>>> in switch statements in Adapters and related listener mechanisms.
>>>>>>> The API tooling pointed out a binary-incompatible change when I
>>>>>>> re-generated after adding a new attribute to one of the base
>>>>>>> classes in my model.
>>>>>>>
>>>>>> Indeed, that's the "cost" of using a highly efficient switch
>>>>>> mechanism...
>>>>>>
>>>>>>> The problem is, that virtually all of the feature-ID constants in
>>>>>>> my model changed because the feature-count of a base class was
>>>>>>> incremented, and all of these feature IDs are based on the count
>>>>>>> of inherited features.
>>>>>>>
>>>>>> Certainly all derived feature IDs will change when the base has a
>>>>>> feature added.
>>>>>>
>>>>>>> The reason why this is a binary compatibility issue is that the
>>>>>>> Java compiler in-lined all of these constants into users' Adapter
>>>>>>> code when they compiled against the previous OCL version.
>>>>>>>
>>>>>> Indded.
>>>>>>
>>>>>>> What can I do to have the generator just assign new IDs in a
>>>>>>> binary-compatible way?
>>>>>>>
>>>>>> Nothing. The IDs are by designed offsets into the list of all
>>>>>> features. In the models we have "Binary Compatible Reflective
>>>>>> Methods" but we've done nothing for the switches on an adapter.
>>>>>> After more than 6 years with this situation, no one has even
>>>>>> expressed a concern about the item provider issue. Go figure... :-P
>>>>>>
>>>>>>> Thanks,
>>>>>>>
>>>>>>> Christian
>>>>>>>
>
>
>

--------------080405040507040203060300
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type">
</head>
<body bgcolor="#ffffff" text="#000000">
Tom,<br>
<br>
Comments below.<br>
<br>
Tom Schindl wrote:
<blockquote cite="mid:gbqvm9$gd5$1@build.eclipse.org" type="cite">
<pre wrap="">I know this sounds strange but how much does this inlining bring if you
don't declare them as literals?

E.g. Databinding uses the following trick.

-------8&lt;-------
public static int POLICY_NEVER = notInlined(1);
</pre>
</blockquote>
The values are used in a switch, which requires a compile time
constant.&nbsp; The intent is to provide constant time dispatch on
features...<br>
<blockquote cite="mid:gbqvm9$gd5$1@build.eclipse.org" type="cite">
<pre wrap="">
private static int notInlined(int i) {
return i;
}
-------8&lt;-------


Tom

Ed Merks schrieb:
</pre>
<blockquote type="cite">
<pre wrap="">Christian,

Comments below.


Christian W. Damus wrote:
</pre>
<blockquote type="cite">
<pre wrap="">Hi, Ed,

More replies in-line, below.

Thanks,

Christian


Ed Merks wrote:
</pre>
<blockquote type="cite">
<pre wrap="">Christian,

Comments below.

Christian W. Damus wrote:
</pre>
<blockquote type="cite">
<pre wrap="">Hi, Ed,

So, you're saying that the feature IDs are an internal
implementation detail and should not be published in the package
interface.
</pre>
</blockquote>
<pre wrap="">I didn't hear me say that! :-P
</pre>
</blockquote>
<pre wrap="">Oh, but I did. :-D You said that the IDs are offsets into the lists
of features. That's an implementation choice,
</pre>
</blockquote>
<pre wrap="">I'd call it a design choice.
</pre>
<blockquote type="cite">
<pre wrap="">and is the only reason why they have to change when new features are
added.
</pre>
</blockquote>
<pre wrap="">They are designed to change...
</pre>
<blockquote type="cite">
<pre wrap="">
</pre>
<blockquote type="cite">
<blockquote type="cite">
<pre wrap=""> Certainly, it is an error for client code to reference the feature
ID constants.
</pre>
</blockquote>
<pre wrap="">No, it's not. It all comes down to expectations. If you look at the
generated code for the binary compatible reflective methods you'll
see that such constants can be safely used even if their values
change in a binary incompatible way.
</pre>
</blockquote>
<pre wrap="">Yes, but that's a code pattern generated by EMF to work around its own
binary-incompatible changes.
</pre>
</blockquote>
<pre wrap="">It's a design that performs well.
</pre>
<blockquote type="cite">
<pre wrap=""> According to Eclipse's development practices vis-a-vis API, this
needs to be flagged to clients as an exception to the rules of API
evolution.
</pre>
</blockquote>
<pre wrap="">Contributions will be considered. :-P
</pre>
<blockquote type="cite">
<pre wrap="">
</pre>
<blockquote type="cite">
<blockquote type="cite">
<pre wrap="">Is this widely known?
</pre>
</blockquote>
<pre wrap="">Don't you find it telling that this has not been raised as an issue
in the last 7 years? Binary compatibility is one of those holy
grails that
</pre>
</blockquote>
<pre wrap="">Folks have been lucky, I guess, that they haven't tried to upgrade the
plug-in that deploys an EMF-generated model while continuing to use a
plug-in that was compiled against an older version. I have seen code
that uses the feature IDs in switch statements, and which would
definitely break in an upgrade scenario.
</pre>
</blockquote>
<pre wrap="">100% lucky so far...
</pre>
<blockquote type="cite">
<pre wrap="">Binary compatibility isn't a holy grail. It's quite practically
realizable. Especially with tools like the PDE available to help :-)
</pre>
</blockquote>
<pre wrap="">It's an ideal. I didn't say it's not achievable.
</pre>
<blockquote type="cite">
<pre wrap="">
</pre>
<blockquote type="cite">
<pre wrap="">no one questions and yet mostly folks build new versions of the
software and recompile... It's very easy after all to put a tight
version range bound to address an issue like this. You remember some
of your reasons for tight version range bounds on your Ecore
dependencies? :-P
</pre>
</blockquote>
<pre wrap="">I did that because I knowingly implemented the discouraged practice of
extending Ecore. I wouldn't have, otherwise. A reasonable defence
mechanism for clients would be to treat the feature IDs as internal
API and use these narrow dependency ranges, yes.
</pre>
</blockquote>
<pre wrap="">Yep.
</pre>
<blockquote type="cite">
<pre wrap="">
</pre>
<blockquote type="cite">
<blockquote type="cite">
<pre wrap="">Luckily, the API tooling gives us the means to impose that
restriction, using the @noreference tag in the doc comments. I can
apply that to my OCL models as they change (currently, changes
contributed to the concrete-syntax model are throwing up red flags).
</pre>
</blockquote>
<pre wrap="">Or you could just not change your model. Or add things only to leaf
classes... Just a like joke. :-P
</pre>
</blockquote>
<pre wrap="">Heh heh ... good one. :-)


</pre>
<blockquote type="cite">
<blockquote type="cite">
<pre wrap="">In the mean-time, perhaps EMF can help by any one of:

- optionally not publishing the feature IDs in the package interface
</pre>
</blockquote>
<pre wrap="">Where to publish them then? They're needed in downstream derived
models. And even if we move them, the problem associated with them
doesn't change, it just moves...
</pre>
</blockquote>
<pre wrap="">Publish them on the package implementation class.
</pre>
</blockquote>
<pre wrap="">Again, it just moves them.
</pre>
<blockquote type="cite">
<pre wrap="">Clients are already discouraged from using it, so it's a natural home.
</pre>
</blockquote>
<pre wrap="">But clients with derived models need them.
</pre>
<blockquote type="cite">
<pre wrap="">
</pre>
<blockquote type="cite">
<blockquote type="cite">
<pre wrap=""> - optionally including an @noreference tag in the doc comment
for every feature ID. I should be able to do this for myself
with a dynamic template, for now
</pre>
</blockquote>
<pre wrap="">We could have such an option.
</pre>
</blockquote>
<pre wrap="">Oo! I would be happy to work on such an enhancement, if you're
interested. A GenModel option for API Tools support could add several
useful annotations:

- @noreference on the feature IDs
- @noimplement on all of the generated interfaces. Otherwise, API
Tools rightly flags additions of any new features (i.e., their
accessor methods) as incompatible changes
- @noreference on the *Impl classes, to formalize this convention
- @since tags on new API elements, being smart to determine the new
plug-in version number

There may be more, of course. I'm gradually discovering all of the
API flags that crop up when re-generating a model with new content.
</pre>
</blockquote>
<pre wrap="">This sounds cool. Sounds like a lot of work!
</pre>
<blockquote type="cite">
<pre wrap="">
</pre>
<blockquote type="cite">
<blockquote type="cite">
<pre wrap=""> - adding the @noreference tag to the getFeatureID() method of the
Notifier class, so that clients will be discourage from a common
cause of referencing these constants
</pre>
</blockquote>
<pre wrap="">It's not this method that has a problem. It could very well be
compared to dynamic computed feature IDs.
</pre>
</blockquote>
<pre wrap="">Right, not a good idea.


</pre>
<blockquote type="cite">
<blockquote type="cite">
<pre wrap="">The problem with relying on the API tooling, of course, is that it
depends on a client using it and on having the API metadata
available (which generally isn't in an OCL build that one might have
the target environment). Even this change in the contract is,
technically, a breaking API change. However, that contract has
already been broken in every release ...
</pre>
</blockquote>
<pre wrap="">Again, doesn't this tell you something?
</pre>
</blockquote>
<pre wrap="">That some of us have, for years, been missing an obvious problem that
PDE's API Tools have shone a big spotlight on. :-D
</pre>
</blockquote>
<pre wrap="">Yes, and also that potential problems often are *not *manifested as real
problems.
</pre>
<blockquote type="cite">
<pre wrap="">
</pre>
<blockquote type="cite">
<pre wrap="">The only other generated place the constants are used is in the item
providers, where we could do something similar to what we did for the
reflective methods or we could compare against feature instances
instead (optionally of course).
</pre>
</blockquote>
<pre wrap="">The item providers aren't a problem, though, are they? Because they
are regenerated and, hence, recompiled and redeployed together with
the model API.
</pre>
</blockquote>
<pre wrap="">Not if only the base class from a different model is changed. The
problem is the same as with the reflective accessors...
</pre>
<blockquote type="cite">
<blockquote type="cite">
<blockquote type="cite">
<pre wrap="">Cheers,

Christian


Ed Merks wrote:
</pre>
<blockquote type="cite">
<pre wrap="">Christian,

Comments below.


Christian W. Damus wrote:
</pre>
<blockquote type="cite">
<pre wrap="">Hi,

I have recently begun using the PDE's very cool API Tools in the
Eclipse OCL project. I am quite satisfied with the API tooling,
but it raised a problem that worries me, in the binary
compatibility of EMF-generated models.

The package meta-data interface has hordes of static int constants
identifying feature IDs. Users of a model API commonly use these
in switch statements in Adapters and related listener mechanisms.
The API tooling pointed out a binary-incompatible change when I
re-generated after adding a new attribute to one of the base
classes in my model.
</pre>
</blockquote>
<pre wrap="">Indeed, that's the "cost" of using a highly efficient switch
mechanism...
</pre>
<blockquote type="cite">
<pre wrap="">The problem is, that virtually all of the feature-ID constants in
my model changed because the feature-count of a base class was
incremented, and all of these feature IDs are based on the count
of inherited features.
</pre>
</blockquote>
<pre wrap="">Certainly all derived feature IDs will change when the base has a
feature added.
</pre>
<blockquote type="cite">
<pre wrap="">The reason why this is a binary compatibility issue is that the
Java compiler in-lined all of these constants into users' Adapter
code when they compiled against the previous OCL version.
</pre>
</blockquote>
<pre wrap="">Indded.
</pre>
<blockquote type="cite">
<pre wrap="">What can I do to have the generator just assign new IDs in a
binary-compatible way?
</pre>
</blockquote>
<pre wrap="">Nothing. The IDs are by designed offsets into the list of all
features. In the models we have "Binary Compatible Reflective
Methods" but we've done nothing for the switches on an adapter.
After more than 6 years with this situation, no one has even
expressed a concern about the item provider issue. Go figure... :-P
</pre>
<blockquote type="cite">
<pre wrap="">Thanks,

Christian
</pre>
</blockquote>
</blockquote>
</blockquote>
</blockquote>
</blockquote>
</blockquote>
<pre wrap=""><!---->

</pre>
</blockquote>
</body>
</html>

--------------080405040507040203060300--
Re: EMF + API Tools [message #423383 is a reply to message #423380] Mon, 29 September 2008 16:39 Go to previous messageGo to next message
Eclipse UserFriend
Originally posted by: cdamus.zeligsoft.com

Hi, Tom,

The problem with this pattern is that the compiler won't allow
POLICY_NEVER in a switch statement, which requires a constant value.
It's in switches that these values are commonly used.

cW

Tom Schindl wrote:
> I know this sounds strange but how much does this inlining bring if you
> don't declare them as literals?
>
> E.g. Databinding uses the following trick.
>
> -------8<-------
> public static int POLICY_NEVER = notInlined(1);
>
> private static int notInlined(int i) {
> return i;
> }
> -------8<-------
>
>
> Tom
>
> Ed Merks schrieb:
>> Christian,
>>
>> Comments below.
>>
>>
>> Christian W. Damus wrote:
>>> Hi, Ed,
>>>
>>> More replies in-line, below.
>>>
>>> Thanks,
>>>
>>> Christian
>>>
>>>
>>> Ed Merks wrote:
>>>> Christian,
>>>>
>>>> Comments below.
>>>>
>>>> Christian W. Damus wrote:
>>>>> Hi, Ed,
>>>>>
>>>>> So, you're saying that the feature IDs are an internal
>>>>> implementation detail and should not be published in the package
>>>>> interface.
>>>> I didn't hear me say that! :-P
>>> Oh, but I did. :-D You said that the IDs are offsets into the lists
>>> of features. That's an implementation choice,
>> I'd call it a design choice.
>>> and is the only reason why they have to change when new features are
>>> added.
>> They are designed to change...
>>>
>>>>> Certainly, it is an error for client code to reference the feature
>>>>> ID constants.
>>>> No, it's not. It all comes down to expectations. If you look at the
>>>> generated code for the binary compatible reflective methods you'll
>>>> see that such constants can be safely used even if their values
>>>> change in a binary incompatible way.
>>> Yes, but that's a code pattern generated by EMF to work around its own
>>> binary-incompatible changes.
>> It's a design that performs well.
>>> According to Eclipse's development practices vis-a-vis API, this
>>> needs to be flagged to clients as an exception to the rules of API
>>> evolution.
>> Contributions will be considered. :-P
>>>
>>>>> Is this widely known?
>>>> Don't you find it telling that this has not been raised as an issue
>>>> in the last 7 years? Binary compatibility is one of those holy
>>>> grails that
>>> Folks have been lucky, I guess, that they haven't tried to upgrade the
>>> plug-in that deploys an EMF-generated model while continuing to use a
>>> plug-in that was compiled against an older version. I have seen code
>>> that uses the feature IDs in switch statements, and which would
>>> definitely break in an upgrade scenario.
>> 100% lucky so far...
>>> Binary compatibility isn't a holy grail. It's quite practically
>>> realizable. Especially with tools like the PDE available to help :-)
>> It's an ideal. I didn't say it's not achievable.
>>>
>>>> no one questions and yet mostly folks build new versions of the
>>>> software and recompile... It's very easy after all to put a tight
>>>> version range bound to address an issue like this. You remember some
>>>> of your reasons for tight version range bounds on your Ecore
>>>> dependencies? :-P
>>> I did that because I knowingly implemented the discouraged practice of
>>> extending Ecore. I wouldn't have, otherwise. A reasonable defence
>>> mechanism for clients would be to treat the feature IDs as internal
>>> API and use these narrow dependency ranges, yes.
>> Yep.
>>>
>>>>> Luckily, the API tooling gives us the means to impose that
>>>>> restriction, using the @noreference tag in the doc comments. I can
>>>>> apply that to my OCL models as they change (currently, changes
>>>>> contributed to the concrete-syntax model are throwing up red flags).
>>>> Or you could just not change your model. Or add things only to leaf
>>>> classes... Just a like joke. :-P
>>> Heh heh ... good one. :-)
>>>
>>>
>>>>> In the mean-time, perhaps EMF can help by any one of:
>>>>>
>>>>> - optionally not publishing the feature IDs in the package interface
>>>> Where to publish them then? They're needed in downstream derived
>>>> models. And even if we move them, the problem associated with them
>>>> doesn't change, it just moves...
>>> Publish them on the package implementation class.
>> Again, it just moves them.
>>> Clients are already discouraged from using it, so it's a natural home.
>> But clients with derived models need them.
>>>
>>>>> - optionally including an @noreference tag in the doc comment
>>>>> for every feature ID. I should be able to do this for myself
>>>>> with a dynamic template, for now
>>>> We could have such an option.
>>> Oo! I would be happy to work on such an enhancement, if you're
>>> interested. A GenModel option for API Tools support could add several
>>> useful annotations:
>>>
>>> - @noreference on the feature IDs
>>> - @noimplement on all of the generated interfaces. Otherwise, API
>>> Tools rightly flags additions of any new features (i.e., their
>>> accessor methods) as incompatible changes
>>> - @noreference on the *Impl classes, to formalize this convention
>>> - @since tags on new API elements, being smart to determine the new
>>> plug-in version number
>>>
>>> There may be more, of course. I'm gradually discovering all of the
>>> API flags that crop up when re-generating a model with new content.
>> This sounds cool. Sounds like a lot of work!
>>>
>>>>> - adding the @noreference tag to the getFeatureID() method of the
>>>>> Notifier class, so that clients will be discourage from a common
>>>>> cause of referencing these constants
>>>> It's not this method that has a problem. It could very well be
>>>> compared to dynamic computed feature IDs.
>>> Right, not a good idea.
>>>
>>>
>>>>> The problem with relying on the API tooling, of course, is that it
>>>>> depends on a client using it and on having the API metadata
>>>>> available (which generally isn't in an OCL build that one might have
>>>>> the target environment). Even this change in the contract is,
>>>>> technically, a breaking API change. However, that contract has
>>>>> already been broken in every release ...
>>>> Again, doesn't this tell you something?
>>> That some of us have, for years, been missing an obvious problem that
>>> PDE's API Tools have shone a big spotlight on. :-D
>> Yes, and also that potential problems often are *not *manifested as real
>> problems.
>>>
>>>> The only other generated place the constants are used is in the item
>>>> providers, where we could do something similar to what we did for the
>>>> reflective methods or we could compare against feature instances
>>>> instead (optionally of course).
>>> The item providers aren't a problem, though, are they? Because they
>>> are regenerated and, hence, recompiled and redeployed together with
>>> the model API.
>> Not if only the base class from a different model is changed. The
>> problem is the same as with the reflective accessors...
>>>>> Cheers,
>>>>>
>>>>> Christian
>>>>>
>>>>>
>>>>> Ed Merks wrote:
>>>>>> Christian,
>>>>>>
>>>>>> Comments below.
>>>>>>
>>>>>>
>>>>>> Christian W. Damus wrote:
>>>>>>> Hi,
>>>>>>>
>>>>>>> I have recently begun using the PDE's very cool API Tools in the
>>>>>>> Eclipse OCL project. I am quite satisfied with the API tooling,
>>>>>>> but it raised a problem that worries me, in the binary
>>>>>>> compatibility of EMF-generated models.
>>>>>>>
>>>>>>> The package meta-data interface has hordes of static int constants
>>>>>>> identifying feature IDs. Users of a model API commonly use these
>>>>>>> in switch statements in Adapters and related listener mechanisms.
>>>>>>> The API tooling pointed out a binary-incompatible change when I
>>>>>>> re-generated after adding a new attribute to one of the base
>>>>>>> classes in my model.
>>>>>> Indeed, that's the "cost" of using a highly efficient switch
>>>>>> mechanism...
>>>>>>> The problem is, that virtually all of the feature-ID constants in
>>>>>>> my model changed because the feature-count of a base class was
>>>>>>> incremented, and all of these feature IDs are based on the count
>>>>>>> of inherited features.
>>>>>> Certainly all derived feature IDs will change when the base has a
>>>>>> feature added.
>>>>>>> The reason why this is a binary compatibility issue is that the
>>>>>>> Java compiler in-lined all of these constants into users' Adapter
>>>>>>> code when they compiled against the previous OCL version.
>>>>>> Indded.
>>>>>>> What can I do to have the generator just assign new IDs in a
>>>>>>> binary-compatible way?
>>>>>> Nothing. The IDs are by designed offsets into the list of all
>>>>>> features. In the models we have "Binary Compatible Reflective
>>>>>> Methods" but we've done nothing for the switches on an adapter.
>>>>>> After more than 6 years with this situation, no one has even
>>>>>> expressed a concern about the item provider issue. Go figure... :-P
>>>>>>> Thanks,
>>>>>>>
>>>>>>> Christian
>
>
Re: EMF + API Tools [message #423384 is a reply to message #423374] Mon, 29 September 2008 16:46 Go to previous message
Eclipse UserFriend
Originally posted by: cdamus.zeligsoft.com

Hi, Ed,

Thanks for being patient with me. I know it's a game of probabilities
.... I'm on a bit of an API kick at the moment.

I'll scope out the effort of the generator enhancements for API tooling
integration before I decide whether I can commit to it. I'd really like
to see it happen, because it'll be a win/win for usability of both EMF
and the API Tools in the same context.

cW

Ed Merks wrote:
> Christian,
>
> Comments below.
>
>
> Christian W. Damus wrote:
>> Hi, Ed,
>>
>> More replies in-line, below.
>>
>> Thanks,
>>
>> Christian
>>
>>
>> Ed Merks wrote:
>>> Christian,
>>>
>>> Comments below.
>>>
>>> Christian W. Damus wrote:
>>>> Hi, Ed,
>>>>
>>>> So, you're saying that the feature IDs are an internal
>>>> implementation detail and should not be published in the package
>>>> interface.
>>> I didn't hear me say that! :-P
>>
>> Oh, but I did. :-D You said that the IDs are offsets into the lists
>> of features. That's an implementation choice,
> I'd call it a design choice.
>> and is the only reason why they have to change when new features are
>> added.
> They are designed to change...
>>
>>
>>>> Certainly, it is an error for client code to reference the feature
>>>> ID constants.
>>> No, it's not. It all comes down to expectations. If you look at the
>>> generated code for the binary compatible reflective methods you'll
>>> see that such constants can be safely used even if their values
>>> change in a binary incompatible way.
>>
>> Yes, but that's a code pattern generated by EMF to work around its own
>> binary-incompatible changes.
> It's a design that performs well.
>> According to Eclipse's development practices vis-a-vis API, this
>> needs to be flagged to clients as an exception to the rules of API
>> evolution.
> Contributions will be considered. :-P
>>
>>
>>>> Is this widely known?
>>> Don't you find it telling that this has not been raised as an issue
>>> in the last 7 years? Binary compatibility is one of those holy
>>> grails that
>>
>> Folks have been lucky, I guess, that they haven't tried to upgrade the
>> plug-in that deploys an EMF-generated model while continuing to use a
>> plug-in that was compiled against an older version. I have seen code
>> that uses the feature IDs in switch statements, and which would
>> definitely break in an upgrade scenario.
> 100% lucky so far...
>>
>> Binary compatibility isn't a holy grail. It's quite practically
>> realizable. Especially with tools like the PDE available to help :-)
> It's an ideal. I didn't say it's not achievable.
>>
>>
>>> no one questions and yet mostly folks build new versions of the
>>> software and recompile... It's very easy after all to put a tight
>>> version range bound to address an issue like this. You remember some
>>> of your reasons for tight version range bounds on your Ecore
>>> dependencies? :-P
>>
>> I did that because I knowingly implemented the discouraged practice of
>> extending Ecore. I wouldn't have, otherwise. A reasonable defence
>> mechanism for clients would be to treat the feature IDs as internal
>> API and use these narrow dependency ranges, yes.
> Yep.
>>
>>
>>>> Luckily, the API tooling gives us the means to impose that
>>>> restriction, using the @noreference tag in the doc comments. I can
>>>> apply that to my OCL models as they change (currently, changes
>>>> contributed to the concrete-syntax model are throwing up red flags).
>>> Or you could just not change your model. Or add things only to leaf
>>> classes... Just a like joke. :-P
>>
>> Heh heh ... good one. :-)
>>
>>
>>>> In the mean-time, perhaps EMF can help by any one of:
>>>>
>>>> - optionally not publishing the feature IDs in the package interface
>>> Where to publish them then? They're needed in downstream derived
>>> models. And even if we move them, the problem associated with them
>>> doesn't change, it just moves...
>>
>> Publish them on the package implementation class.
> Again, it just moves them.
>> Clients are already discouraged from using it, so it's a natural home.
> But clients with derived models need them.
>>
>>
>>>> - optionally including an @noreference tag in the doc comment
>>>> for every feature ID. I should be able to do this for myself
>>>> with a dynamic template, for now
>>> We could have such an option.
>>
>> Oo! I would be happy to work on such an enhancement, if you're
>> interested. A GenModel option for API Tools support could add several
>> useful annotations:
>>
>> - @noreference on the feature IDs
>> - @noimplement on all of the generated interfaces. Otherwise, API
>> Tools rightly flags additions of any new features (i.e., their
>> accessor methods) as incompatible changes
>> - @noreference on the *Impl classes, to formalize this convention
>> - @since tags on new API elements, being smart to determine the new
>> plug-in version number
>>
>> There may be more, of course. I'm gradually discovering all of the
>> API flags that crop up when re-generating a model with new content.
> This sounds cool. Sounds like a lot of work!
>>
>>
>>>> - adding the @noreference tag to the getFeatureID() method of the
>>>> Notifier class, so that clients will be discourage from a common
>>>> cause of referencing these constants
>>> It's not this method that has a problem. It could very well be
>>> compared to dynamic computed feature IDs.
>>
>> Right, not a good idea.
>>
>>
>>>> The problem with relying on the API tooling, of course, is that it
>>>> depends on a client using it and on having the API metadata
>>>> available (which generally isn't in an OCL build that one might have
>>>> the target environment). Even this change in the contract is,
>>>> technically, a breaking API change. However, that contract has
>>>> already been broken in every release ...
>>> Again, doesn't this tell you something?
>>
>> That some of us have, for years, been missing an obvious problem that
>> PDE's API Tools have shone a big spotlight on. :-D
> Yes, and also that potential problems often are *not *manifested as real
> problems.
>>
>>
>>> The only other generated place the constants are used is in the item
>>> providers, where we could do something similar to what we did for the
>>> reflective methods or we could compare against feature instances
>>> instead (optionally of course).
>>
>> The item providers aren't a problem, though, are they? Because they
>> are regenerated and, hence, recompiled and redeployed together with
>> the model API.
> Not if only the base class from a different model is changed. The
> problem is the same as with the reflective accessors...
>>
>>>>
>>>> Cheers,
>>>>
>>>> Christian
>>>>
>>>>
>>>> Ed Merks wrote:
>>>>> Christian,
>>>>>
>>>>> Comments below.
>>>>>
>>>>>
>>>>> Christian W. Damus wrote:
>>>>>> Hi,
>>>>>>
>>>>>> I have recently begun using the PDE's very cool API Tools in the
>>>>>> Eclipse OCL project. I am quite satisfied with the API tooling,
>>>>>> but it raised a problem that worries me, in the binary
>>>>>> compatibility of EMF-generated models.
>>>>>>
>>>>>> The package meta-data interface has hordes of static int constants
>>>>>> identifying feature IDs. Users of a model API commonly use these
>>>>>> in switch statements in Adapters and related listener mechanisms.
>>>>>> The API tooling pointed out a binary-incompatible change when I
>>>>>> re-generated after adding a new attribute to one of the base
>>>>>> classes in my model.
>>>>> Indeed, that's the "cost" of using a highly efficient switch
>>>>> mechanism...
>>>>>>
>>>>>> The problem is, that virtually all of the feature-ID constants in
>>>>>> my model changed because the feature-count of a base class was
>>>>>> incremented, and all of these feature IDs are based on the count
>>>>>> of inherited features.
>>>>> Certainly all derived feature IDs will change when the base has a
>>>>> feature added.
>>>>>> The reason why this is a binary compatibility issue is that the
>>>>>> Java compiler in-lined all of these constants into users' Adapter
>>>>>> code when they compiled against the previous OCL version.
>>>>> Indded.
>>>>>>
>>>>>> What can I do to have the generator just assign new IDs in a
>>>>>> binary-compatible way?
>>>>> Nothing. The IDs are by designed offsets into the list of all
>>>>> features. In the models we have "Binary Compatible Reflective
>>>>> Methods" but we've done nothing for the switches on an adapter.
>>>>> After more than 6 years with this situation, no one has even
>>>>> expressed a concern about the item provider issue. Go figure... :-P
>>>>>>
>>>>>> Thanks,
>>>>>>
>>>>>> Christian
Previous Topic:How can i poof an elis datat?
Next Topic:EMF and JET generating a new package.
Goto Forum:
  


Current Time: Mon Jan 20 06:49:33 GMT 2020

Powered by FUDForum. Page generated in 0.02494 seconds
.:: Contact :: Home ::.

Powered by: FUDforum 3.0.2.
Copyright ©2001-2010 FUDforum Bulletin Board Software

Back to the top