Skip to main content


Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
Home » Modeling » EMF "Technology" (Ecore Tools, EMFatic, etc)  » [documentation] why are diagrams not done with EMF?
[documentation] why are diagrams not done with EMF? [message #97246] Tue, 25 September 2007 06:56 Go to next message
Philipp W. Kutter is currently offline Philipp W. KutterFriend
Messages: 306
Registered: July 2009
Senior Member
Hi, everybody of EMFT.

I started to go through validation, ocl and other EMF documentation.

What strikes me is that the documentation gives UML diagrams of the
getters and setters, rather than the real conceptual models you get when
using EMF.

For instance, under "Overview of Constraints" there is a diagram, with
IModelConstraint having a getter "getDescriptor)()" and then there is
a <<use>> relation to IConstraintDescriptor.

By adding a few line of EMF tags to the corresponding interfaces,
extracting the EMF model from it, and then exporting it to UML,
we would get the same diagram, but with a reference "description" from
IModelConstraint to IConstraintDescriptor.


Why is this not done?

Are people not eating their own dog food?


I know the 100 arguments why not to do what I propose, most of them
around the topic "it does not make me faster while programming".

If someone provides me with the UML tool you use to make the screenshot,
I volonteer to annotate the corresponding classes and interfaces with
EMF tags. I do not think it is a lot of work, it is just a last step of
bootstrapping... and it would be the basis to motivate other non-EMF
projects to use EMF in documenting their code in the EMF way.

Would it not be a great step forward, if all the classes developed in
the various Eclipse projects are correctly tagged with EMF info, and if
the resulting diagrams would be a basis for documentation all EMF plugins?

Best, Philipp
Re: [documentation] why are diagrams not done with EMF? [message #97349 is a reply to message #97246] Tue, 25 September 2007 12:31 Go to previous messageGo to next message
Eclipse UserFriend
Originally posted by: merks.ca.ibm.com

Philipp,

OCL issues should use the OCl newsgroup and the query, validation, and
transaction components are now part of EMF rather than EMFT (they
graduated) so the EMF newsgroup is good for discussing those. Some of
the things you refer to are hand written code so I assume folks chose to
model them in the most obvious way, i.e., an EClass wrapper with
EOperations. One could certainly use an unchangeable EReference to
model the IModelConstraint's getDescriptor operation that, but then one
might expect to be able to call eGet on an instance of that, which might
well not be supported by the implementation classes...


Philipp W. Kutter wrote:
> Hi, everybody of EMFT.
>
> I started to go through validation, ocl and other EMF documentation.
>
> What strikes me is that the documentation gives UML diagrams of the
> getters and setters, rather than the real conceptual models you get when
> using EMF.
>
> For instance, under "Overview of Constraints" there is a diagram, with
> IModelConstraint having a getter "getDescriptor)()" and then there is
> a <<use>> relation to IConstraintDescriptor.
>
> By adding a few line of EMF tags to the corresponding interfaces,
> extracting the EMF model from it, and then exporting it to UML,
> we would get the same diagram, but with a reference "description" from
> IModelConstraint to IConstraintDescriptor.
>
>
> Why is this not done?
>
> Are people not eating their own dog food?
>
>
> I know the 100 arguments why not to do what I propose, most of them
> around the topic "it does not make me faster while programming".
>
> If someone provides me with the UML tool you use to make the screenshot,
> I volonteer to annotate the corresponding classes and interfaces with
> EMF tags. I do not think it is a lot of work, it is just a last step of
> bootstrapping... and it would be the basis to motivate other non-EMF
> projects to use EMF in documenting their code in the EMF way.
>
> Would it not be a great step forward, if all the classes developed in
> the various Eclipse projects are correctly tagged with EMF info, and if
> the resulting diagrams would be a basis for documentation all EMF
> plugins?
>
> Best, Philipp
>
>
Re: [documentation] why are diagrams not done with EMF? [message #97379 is a reply to message #97349] Tue, 25 September 2007 14:09 Go to previous messageGo to next message
Eclipse UserFriend
Originally posted by: cdamus.ca.ibm.com

Hi, Ed, Philipp,

The class diagrams that you see in these developer guides cover, for the
most part, code that was not modeled in Ecore and generated by EMF.

The diagrams were created using the "Java Modeling" feature of IBM
Rational's development tools (RAD/RSA) by dragging and dropping classes
from the Package Explorer onto class diagrams. Their purpose was to
provide at-a-glance overviews of the principal types in these APIs.

The presence of usage relationships instead of associations is a quirk of
RAD's support for Java interfaces. We couldn't easily draw associations
because RAD depends on having actual Java fields representing the ends, and
interfaces don't have these. It would be cool if it could interpret
bean-style operations as implicit properties.

The *.dnx files are checked in to the CVS repos, so if you're keen to
improve them, we will gladly review your contributions!

Thanks,

Christian


Ed Merks wrote:

> Philipp,
>
> OCL issues should use the OCl newsgroup and the query, validation, and
> transaction components are now part of EMF rather than EMFT (they
> graduated) so the EMF newsgroup is good for discussing those. Some of
> the things you refer to are hand written code so I assume folks chose to
> model them in the most obvious way, i.e., an EClass wrapper with
> EOperations. One could certainly use an unchangeable EReference to
> model the IModelConstraint's getDescriptor operation that, but then one
> might expect to be able to call eGet on an instance of that, which might
> well not be supported by the implementation classes...
>
>
> Philipp W. Kutter wrote:
>> Hi, everybody of EMFT.
>>
>> I started to go through validation, ocl and other EMF documentation.
>>
>> What strikes me is that the documentation gives UML diagrams of the
>> getters and setters, rather than the real conceptual models you get when
>> using EMF.
>>
>> For instance, under "Overview of Constraints" there is a diagram, with
>> IModelConstraint having a getter "getDescriptor)()" and then there is
>> a <<use>> relation to IConstraintDescriptor.
>>
>> By adding a few line of EMF tags to the corresponding interfaces,
>> extracting the EMF model from it, and then exporting it to UML,
>> we would get the same diagram, but with a reference "description" from
>> IModelConstraint to IConstraintDescriptor.
>>
>>
>> Why is this not done?

-----8<-----
Re: [documentation] why are diagrams not done with EMF? [message #97700 is a reply to message #97379] Wed, 26 September 2007 18:49 Go to previous messageGo to next message
Philipp W. Kutter is currently offline Philipp W. KutterFriend
Messages: 306
Registered: July 2009
Senior Member
Hi, Christian.
That's exactly my point: EMF is the perfect tool to interpret bean-style
operations as implicit properties.

Why is it not used in EMF related documentation?

What should be checked in in my opinion are the EMF tags of the
developed code.

Best, Philipp

Christian W. Damus wrote:
> Hi, Ed, Philipp,
>
> The class diagrams that you see in these developer guides cover, for the
> most part, code that was not modeled in Ecore and generated by EMF.
>
> The diagrams were created using the "Java Modeling" feature of IBM
> Rational's development tools (RAD/RSA) by dragging and dropping classes
> from the Package Explorer onto class diagrams. Their purpose was to
> provide at-a-glance overviews of the principal types in these APIs.
>
> The presence of usage relationships instead of associations is a quirk of
> RAD's support for Java interfaces. We couldn't easily draw associations
> because RAD depends on having actual Java fields representing the ends, and
> interfaces don't have these. It would be cool if it could interpret
> bean-style operations as implicit properties.
>
> The *.dnx files are checked in to the CVS repos, so if you're keen to
> improve them, we will gladly review your contributions!
>
> Thanks,
>
> Christian
>
>
> Ed Merks wrote:
>
>> Philipp,
>>
>> OCL issues should use the OCl newsgroup and the query, validation, and
>> transaction components are now part of EMF rather than EMFT (they
>> graduated) so the EMF newsgroup is good for discussing those. Some of
>> the things you refer to are hand written code so I assume folks chose to
>> model them in the most obvious way, i.e., an EClass wrapper with
>> EOperations. One could certainly use an unchangeable EReference to
>> model the IModelConstraint's getDescriptor operation that, but then one
>> might expect to be able to call eGet on an instance of that, which might
>> well not be supported by the implementation classes...
>>
>>
>> Philipp W. Kutter wrote:
>>> Hi, everybody of EMFT.
>>>
>>> I started to go through validation, ocl and other EMF documentation.
>>>
>>> What strikes me is that the documentation gives UML diagrams of the
>>> getters and setters, rather than the real conceptual models you get when
>>> using EMF.
>>>
>>> For instance, under "Overview of Constraints" there is a diagram, with
>>> IModelConstraint having a getter "getDescriptor)()" and then there is
>>> a <<use>> relation to IConstraintDescriptor.
>>>
>>> By adding a few line of EMF tags to the corresponding interfaces,
>>> extracting the EMF model from it, and then exporting it to UML,
>>> we would get the same diagram, but with a reference "description" from
>>> IModelConstraint to IConstraintDescriptor.
>>>
>>>
>>> Why is this not done?
>
> -----8<-----
Re: [documentation] why are diagrams not done with EMF? [message #97715 is a reply to message #97349] Wed, 26 September 2007 18:54 Go to previous messageGo to next message
Philipp W. Kutter is currently offline Philipp W. KutterFriend
Messages: 306
Registered: July 2009
Senior Member
Hi, Ed.
Thanks for the hint. I will try to use the right group in the future.

Regarding the other issue: if you set IModelConstraint with
interface=true, there will never by an instance, you can call eGet on.

And in the case of hand written code, one would anyhow not extend the
EObjectImpl. I am not proposing to use EMF features in hand written
code, but I propose to use it to generate the models, and I would only
generate code (with all EMF stuff turned off) to check that the EMF tags
are complete.

In our industry projects, this turned out to be at least as useful at
the runtime features of EMF. I think even POJOs should be documented
with the corresponding EMF tags.

Best, Philipp

Ed Merks wrote:
> Philipp,
>
> OCL issues should use the OCl newsgroup and the query, validation, and
> transaction components are now part of EMF rather than EMFT (they
> graduated) so the EMF newsgroup is good for discussing those. Some of
> the things you refer to are hand written code so I assume folks chose to
> model them in the most obvious way, i.e., an EClass wrapper with
> EOperations. One could certainly use an unchangeable EReference to
> model the IModelConstraint's getDescriptor operation that, but then one
> might expect to be able to call eGet on an instance of that, which might
> well not be supported by the implementation classes...
>
>
> Philipp W. Kutter wrote:
>> Hi, everybody of EMFT.
>>
>> I started to go through validation, ocl and other EMF documentation.
>>
>> What strikes me is that the documentation gives UML diagrams of the
>> getters and setters, rather than the real conceptual models you get when
>> using EMF.
>>
>> For instance, under "Overview of Constraints" there is a diagram, with
>> IModelConstraint having a getter "getDescriptor)()" and then there is
>> a <<use>> relation to IConstraintDescriptor.
>>
>> By adding a few line of EMF tags to the corresponding interfaces,
>> extracting the EMF model from it, and then exporting it to UML,
>> we would get the same diagram, but with a reference "description" from
>> IModelConstraint to IConstraintDescriptor.
>>
>>
>> Why is this not done?
>>
>> Are people not eating their own dog food?
>>
>>
>> I know the 100 arguments why not to do what I propose, most of them
>> around the topic "it does not make me faster while programming".
>>
>> If someone provides me with the UML tool you use to make the screenshot,
>> I volonteer to annotate the corresponding classes and interfaces with
>> EMF tags. I do not think it is a lot of work, it is just a last step of
>> bootstrapping... and it would be the basis to motivate other non-EMF
>> projects to use EMF in documenting their code in the EMF way.
>>
>> Would it not be a great step forward, if all the classes developed in
>> the various Eclipse projects are correctly tagged with EMF info, and if
>> the resulting diagrams would be a basis for documentation all EMF
>> plugins?
>>
>> Best, Philipp
>>
>>
Re: [documentation] why are diagrams not done with EMF? [message #97745 is a reply to message #97700] Wed, 26 September 2007 20:28 Go to previous messageGo to next message
Eclipse UserFriend
Originally posted by: cdamus.ca.ibm.com

Hi, Philipp,

I don't know what you mean by "EMF tags." Do you mean, that I should add
EMF's javadoc tags (@model etc.) to non-EMF code? That would give people
the impression that it is generated by EMF and maintained thus, and I
wouldn't want that.

RSA's Java visualization was a good tool for me as it allowed me to easily
create some class diagrams that look good and provide an at-a-glance
overview of the structure. Even better, it does not require that I
annotate my code with stuff it doesn't need.

Unfortunately, I never can make documentation a priority. Anything that the
community can contribute is most welcome.

Cheers,

Christian


Philipp W. Kutter wrote:

> Hi, Christian.
> That's exactly my point: EMF is the perfect tool to interpret bean-style
> operations as implicit properties.
>
> Why is it not used in EMF related documentation?
>
> What should be checked in in my opinion are the EMF tags of the
> developed code.
>
> Best, Philipp


<snip>
Re: [documentation] why are diagrams not done with EMF? [message #98241 is a reply to message #97745] Tue, 02 October 2007 05:35 Go to previous messageGo to next message
Philipp W. Kutter is currently offline Philipp W. KutterFriend
Messages: 306
Registered: July 2009
Senior Member
Hi, Christian.
> I don't know what you mean by "EMF tags." Do you mean, that I should add
> EMF's javadoc tags (@model etc.) to non-EMF code? That would give people
> the impression that it is generated by EMF and maintained thus, and I
> wouldn't want that.

With the right EMF options set, you can generate almost all
getter/setter kind of code, and the signatures of almost any method.
I would restrict adding EMF's javadoc tags to those places which should
appear in your documentations.

> RSA's Java visualization was a good tool for me as it allowed me to easily
> create some class diagrams that look good and provide an at-a-glance
> overview of the structure. Even better, it does not require that I
> annotate my code with stuff it doesn't need.

I'd like to share an experience I had at a big client of us. About two
years ago I started there to add EMF tags to non-EMF code, and to
regenerate this code with EMF. I filed some EMF bugs regarding project
specific settings of formating, e.t.c. and thanks to Ed's fast reply to
them, I managed to set the EMF options such, that we got exactly the
same code as before. I had to add a few annotations, for instance when
I needed as Set instead of List, and then changed the templates, as you did.

After I left, someone internally still maintains the EMF tags, and uses
this as a tool to control the development process, and to extract the
real class diagrams from their code.

But I understand your concern, that you do not want to have people
thinking that the code is EMF code if it is not inheriting from EObjectImpl.

By the way, what are the reasons to make any of your code non-EMF code?

Is it the absence of support for inner classes?

Best, Philipp
>
> Unfortunately, I never can make documentation a priority. Anything that the
> community can contribute is most welcome.
>
> Cheers,
>
> Christian
>
>
> Philipp W. Kutter wrote:
>
>> Hi, Christian.
>> That's exactly my point: EMF is the perfect tool to interpret bean-style
>> operations as implicit properties.
>>
>> Why is it not used in EMF related documentation?
>>
>> What should be checked in in my opinion are the EMF tags of the
>> developed code.
>>
>> Best, Philipp
>
>
> <snip>
Re: [documentation] why are diagrams not done with EMF? [message #98256 is a reply to message #98241] Tue, 02 October 2007 08:26 Go to previous messageGo to next message
Tomas Zijdemans is currently offline Tomas ZijdemansFriend
Messages: 90
Registered: July 2009
Member
Philipp W. Kutter wrote:
> for instance when I needed as Set instead of List

That would actually solve one of my problems... How did you do it?


Tomas
Re: [documentation] why are diagrams not done with EMF? [message #98285 is a reply to message #98256] Tue, 02 October 2007 11:44 Go to previous messageGo to next message
Eclipse UserFriend
Originally posted by: merks.ca.ibm.com

Tomas,

Note that BasicEList actually implements all the java.util.Set methods.
The only problem is that equals for Set and List are mutually exclusive
in their design, i.e., you can't implement both correctly with one
method. So if we ever implement
https://bugs.eclipse.org/bugs/show_bug.cgi?id=75931 we'd need to
implement some type of mechanism to support a Set view of the List (just
like we support a Map view of an EMap). The idea being that for any
feature for which upperBound > 0 and for which isOrdered is false and
isUnique is true, we'd use a Set.


Tomas Zijdemans wrote:
> Philipp W. Kutter wrote:
>> for instance when I needed as Set instead of List
>
> That would actually solve one of my problems... How did you do it?
>
>
> Tomas
Re: [documentation] why are diagrams not done with EMF? [message #98314 is a reply to message #98241] Tue, 02 October 2007 13:44 Go to previous messageGo to next message
Eclipse UserFriend
Originally posted by: cdamus.ca.ibm.com

Hi, Philipp,

See some comments in-line, below.

Cheers,

Christian


Philipp W. Kutter wrote:

-----8<-----

> I'd like to share an experience I had at a big client of us. About two
> years ago I started there to add EMF tags to non-EMF code, and to
> regenerate this code with EMF. I filed some EMF bugs regarding project
> specific settings of formating, e.t.c. and thanks to Ed's fast reply to
> them, I managed to set the EMF options such, that we got exactly the
> same code as before. I had to add a few annotations, for instance when
> I needed as Set instead of List, and then changed the templates, as you
> did.
>
> After I left, someone internally still maintains the EMF tags, and uses
> this as a tool to control the development process, and to extract the
> real class diagrams from their code.

That sounds much like the round-trip-engineering capabilities of many
development products, that put annotations into one's Javadoc comments (or
as real annotations, since J2SE 5.0). This is a novel use of EMF, for
sure. I wonder when EMF will support 5.0-style annotations, which would
certainly add to the tooling and run-time possibilities for managing
EMF-generated code ...


> But I understand your concern, that you do not want to have people
> thinking that the code is EMF code if it is not inheriting from
> EObjectImpl.
>
> By the way, what are the reasons to make any of your code non-EMF code?
>
> Is it the absence of support for inner classes?

And possibly such constructs as visibility, staticness, etc. Much of this
component isn't a data model, as such, but some of it is. In retrospect, a
good deal of it could have been modeled with EMF, but its history started
in an architecture that wasn't designed in the EMF mould and was later
contributed to Eclipse via the initial contribution of the GMF Run-time.

-----8<-----
Re: [documentation] why are diagrams not done with EMF? [message #103756 is a reply to message #98314] Mon, 26 November 2007 14:08 Go to previous message
Philipp W. Kutter is currently offline Philipp W. KutterFriend
Messages: 306
Registered: July 2009
Senior Member
Hi, Christian.
Sorry for the delayed answer.

Christian W. Damus wrote 20071002:
> Hi, Philipp,
>
> See some comments in-line, below.
>
> Cheers,
>
> Christian
>
>
> Philipp W. Kutter wrote:
>
> -----8<-----
>
>> I'd like to share an experience I had at a big client of us. About two
>> years ago I started there to add EMF tags to non-EMF code, and to
>> regenerate this code with EMF. I filed some EMF bugs regarding project
>> specific settings of formating, e.t.c. and thanks to Ed's fast reply to
>> them, I managed to set the EMF options such, that we got exactly the
>> same code as before. I had to add a few annotations, for instance when
>> I needed as Set instead of List, and then changed the templates, as you
>> did.
>>
>> After I left, someone internally still maintains the EMF tags, and uses
>> this as a tool to control the development process, and to extract the
>> real class diagrams from their code.
>
> That sounds much like the round-trip-engineering capabilities of many
> development products, that put annotations into one's Javadoc comments (or
> as real annotations, since J2SE 5.0). This is a novel use of EMF, for
> sure.

I am not sure whether Ed Merks would agree. Roundtrip between Java and
Ecore, and between Ecore and XSD are among it most valuable features.

I agree that most people on the newsgroup use EMF differently, but when
I reported problems doing this back in 2005, Ed fixed all related
problems, and at the end it worked perfectly.

It is as well a very good practice in order to get up to spead with
forward engineering.


> I wonder when EMF will support 5.0-style annotations, which would
> certainly add to the tooling and run-time possibilities for managing
> EMF-generated code ...

As far as I know, there was no switch announce.

>
>> But I understand your concern, that you do not want to have people
>> thinking that the code is EMF code if it is not inheriting from
>> EObjectImpl.
>>
>> By the way, what are the reasons to make any of your code non-EMF code?
>>
>> Is it the absence of support for inner classes?
>
> And possibly such constructs as visibility, staticness, etc.

Visibility of setters and getters can be controlled with an EMF
annotation. Thus you can make getters and setters invisible in the
interface.

The staticness is a topic not touched by EMF. The static fields have to
be excluded from the models, or done by tailoring your templates. We use
for instance annotations to define static fields. The objects refered by
this static fields must exist in EMF resources which are available in
the same plugin as the EMF models.

> Much of this
> component isn't a data model, as such, but some of it is. In retrospect, a
> good deal of it could have been modeled with EMF, but its history started
> in an architecture that wasn't designed in the EMF mould and was later
> contributed to Eclipse via the initial contribution of the GMF Run-time.

Why not adding the EMF tags to the code of the component? After all, its
risk free:
1) you add the EMF tags
2) you load the ECore from the code
3) you regenerate the code
4) differences on CVS must be zero, otherwise adapt the
genmodel/code-tags and return to 2)

If you cannot solve the problem, report it to the EMF list, and they
typically fix the problem.

This only works, if the formating options of all the components are
standardized, and all the code is formatted before it is committed.

Best, Philipp
Re: [documentation] why are diagrams not done with EMF? [message #609807 is a reply to message #97246] Tue, 25 September 2007 12:31 Go to previous message
Ed Merks is currently offline Ed MerksFriend
Messages: 31467
Registered: July 2009
Senior Member
Philipp,

OCL issues should use the OCl newsgroup and the query, validation, and
transaction components are now part of EMF rather than EMFT (they
graduated) so the EMF newsgroup is good for discussing those. Some of
the things you refer to are hand written code so I assume folks chose to
model them in the most obvious way, i.e., an EClass wrapper with
EOperations. One could certainly use an unchangeable EReference to
model the IModelConstraint's getDescriptor operation that, but then one
might expect to be able to call eGet on an instance of that, which might
well not be supported by the implementation classes...


Philipp W. Kutter wrote:
> Hi, everybody of EMFT.
>
> I started to go through validation, ocl and other EMF documentation.
>
> What strikes me is that the documentation gives UML diagrams of the
> getters and setters, rather than the real conceptual models you get when
> using EMF.
>
> For instance, under "Overview of Constraints" there is a diagram, with
> IModelConstraint having a getter "getDescriptor)()" and then there is
> a <<use>> relation to IConstraintDescriptor.
>
> By adding a few line of EMF tags to the corresponding interfaces,
> extracting the EMF model from it, and then exporting it to UML,
> we would get the same diagram, but with a reference "description" from
> IModelConstraint to IConstraintDescriptor.
>
>
> Why is this not done?
>
> Are people not eating their own dog food?
>
>
> I know the 100 arguments why not to do what I propose, most of them
> around the topic "it does not make me faster while programming".
>
> If someone provides me with the UML tool you use to make the screenshot,
> I volonteer to annotate the corresponding classes and interfaces with
> EMF tags. I do not think it is a lot of work, it is just a last step of
> bootstrapping... and it would be the basis to motivate other non-EMF
> projects to use EMF in documenting their code in the EMF way.
>
> Would it not be a great step forward, if all the classes developed in
> the various Eclipse projects are correctly tagged with EMF info, and if
> the resulting diagrams would be a basis for documentation all EMF
> plugins?
>
> Best, Philipp
>
>


Ed Merks
Professional Support: https://www.macromodeling.com/
Re: [documentation] why are diagrams not done with EMF? [message #609809 is a reply to message #97349] Tue, 25 September 2007 14:09 Go to previous message
Eclipse UserFriend
Originally posted by: cdamus.ca.ibm.com

Hi, Ed, Philipp,

The class diagrams that you see in these developer guides cover, for the
most part, code that was not modeled in Ecore and generated by EMF.

The diagrams were created using the "Java Modeling" feature of IBM
Rational's development tools (RAD/RSA) by dragging and dropping classes
from the Package Explorer onto class diagrams. Their purpose was to
provide at-a-glance overviews of the principal types in these APIs.

The presence of usage relationships instead of associations is a quirk of
RAD's support for Java interfaces. We couldn't easily draw associations
because RAD depends on having actual Java fields representing the ends, and
interfaces don't have these. It would be cool if it could interpret
bean-style operations as implicit properties.

The *.dnx files are checked in to the CVS repos, so if you're keen to
improve them, we will gladly review your contributions!

Thanks,

Christian


Ed Merks wrote:

> Philipp,
>
> OCL issues should use the OCl newsgroup and the query, validation, and
> transaction components are now part of EMF rather than EMFT (they
> graduated) so the EMF newsgroup is good for discussing those. Some of
> the things you refer to are hand written code so I assume folks chose to
> model them in the most obvious way, i.e., an EClass wrapper with
> EOperations. One could certainly use an unchangeable EReference to
> model the IModelConstraint's getDescriptor operation that, but then one
> might expect to be able to call eGet on an instance of that, which might
> well not be supported by the implementation classes...
>
>
> Philipp W. Kutter wrote:
>> Hi, everybody of EMFT.
>>
>> I started to go through validation, ocl and other EMF documentation.
>>
>> What strikes me is that the documentation gives UML diagrams of the
>> getters and setters, rather than the real conceptual models you get when
>> using EMF.
>>
>> For instance, under "Overview of Constraints" there is a diagram, with
>> IModelConstraint having a getter "getDescriptor)()" and then there is
>> a <<use>> relation to IConstraintDescriptor.
>>
>> By adding a few line of EMF tags to the corresponding interfaces,
>> extracting the EMF model from it, and then exporting it to UML,
>> we would get the same diagram, but with a reference "description" from
>> IModelConstraint to IConstraintDescriptor.
>>
>>
>> Why is this not done?

-----8<-----
Re: [documentation] why are diagrams not done with EMF? [message #609831 is a reply to message #97379] Wed, 26 September 2007 18:49 Go to previous message
Philipp W. Kutter is currently offline Philipp W. KutterFriend
Messages: 306
Registered: July 2009
Senior Member
Hi, Christian.
That's exactly my point: EMF is the perfect tool to interpret bean-style
operations as implicit properties.

Why is it not used in EMF related documentation?

What should be checked in in my opinion are the EMF tags of the
developed code.

Best, Philipp

Christian W. Damus wrote:
> Hi, Ed, Philipp,
>
> The class diagrams that you see in these developer guides cover, for the
> most part, code that was not modeled in Ecore and generated by EMF.
>
> The diagrams were created using the "Java Modeling" feature of IBM
> Rational's development tools (RAD/RSA) by dragging and dropping classes
> from the Package Explorer onto class diagrams. Their purpose was to
> provide at-a-glance overviews of the principal types in these APIs.
>
> The presence of usage relationships instead of associations is a quirk of
> RAD's support for Java interfaces. We couldn't easily draw associations
> because RAD depends on having actual Java fields representing the ends, and
> interfaces don't have these. It would be cool if it could interpret
> bean-style operations as implicit properties.
>
> The *.dnx files are checked in to the CVS repos, so if you're keen to
> improve them, we will gladly review your contributions!
>
> Thanks,
>
> Christian
>
>
> Ed Merks wrote:
>
>> Philipp,
>>
>> OCL issues should use the OCl newsgroup and the query, validation, and
>> transaction components are now part of EMF rather than EMFT (they
>> graduated) so the EMF newsgroup is good for discussing those. Some of
>> the things you refer to are hand written code so I assume folks chose to
>> model them in the most obvious way, i.e., an EClass wrapper with
>> EOperations. One could certainly use an unchangeable EReference to
>> model the IModelConstraint's getDescriptor operation that, but then one
>> might expect to be able to call eGet on an instance of that, which might
>> well not be supported by the implementation classes...
>>
>>
>> Philipp W. Kutter wrote:
>>> Hi, everybody of EMFT.
>>>
>>> I started to go through validation, ocl and other EMF documentation.
>>>
>>> What strikes me is that the documentation gives UML diagrams of the
>>> getters and setters, rather than the real conceptual models you get when
>>> using EMF.
>>>
>>> For instance, under "Overview of Constraints" there is a diagram, with
>>> IModelConstraint having a getter "getDescriptor)()" and then there is
>>> a <<use>> relation to IConstraintDescriptor.
>>>
>>> By adding a few line of EMF tags to the corresponding interfaces,
>>> extracting the EMF model from it, and then exporting it to UML,
>>> we would get the same diagram, but with a reference "description" from
>>> IModelConstraint to IConstraintDescriptor.
>>>
>>>
>>> Why is this not done?
>
> -----8<-----
Re: [documentation] why are diagrams not done with EMF? [message #609832 is a reply to message #97349] Wed, 26 September 2007 18:54 Go to previous message
Philipp W. Kutter is currently offline Philipp W. KutterFriend
Messages: 306
Registered: July 2009
Senior Member
Hi, Ed.
Thanks for the hint. I will try to use the right group in the future.

Regarding the other issue: if you set IModelConstraint with
interface=true, there will never by an instance, you can call eGet on.

And in the case of hand written code, one would anyhow not extend the
EObjectImpl. I am not proposing to use EMF features in hand written
code, but I propose to use it to generate the models, and I would only
generate code (with all EMF stuff turned off) to check that the EMF tags
are complete.

In our industry projects, this turned out to be at least as useful at
the runtime features of EMF. I think even POJOs should be documented
with the corresponding EMF tags.

Best, Philipp

Ed Merks wrote:
> Philipp,
>
> OCL issues should use the OCl newsgroup and the query, validation, and
> transaction components are now part of EMF rather than EMFT (they
> graduated) so the EMF newsgroup is good for discussing those. Some of
> the things you refer to are hand written code so I assume folks chose to
> model them in the most obvious way, i.e., an EClass wrapper with
> EOperations. One could certainly use an unchangeable EReference to
> model the IModelConstraint's getDescriptor operation that, but then one
> might expect to be able to call eGet on an instance of that, which might
> well not be supported by the implementation classes...
>
>
> Philipp W. Kutter wrote:
>> Hi, everybody of EMFT.
>>
>> I started to go through validation, ocl and other EMF documentation.
>>
>> What strikes me is that the documentation gives UML diagrams of the
>> getters and setters, rather than the real conceptual models you get when
>> using EMF.
>>
>> For instance, under "Overview of Constraints" there is a diagram, with
>> IModelConstraint having a getter "getDescriptor)()" and then there is
>> a <<use>> relation to IConstraintDescriptor.
>>
>> By adding a few line of EMF tags to the corresponding interfaces,
>> extracting the EMF model from it, and then exporting it to UML,
>> we would get the same diagram, but with a reference "description" from
>> IModelConstraint to IConstraintDescriptor.
>>
>>
>> Why is this not done?
>>
>> Are people not eating their own dog food?
>>
>>
>> I know the 100 arguments why not to do what I propose, most of them
>> around the topic "it does not make me faster while programming".
>>
>> If someone provides me with the UML tool you use to make the screenshot,
>> I volonteer to annotate the corresponding classes and interfaces with
>> EMF tags. I do not think it is a lot of work, it is just a last step of
>> bootstrapping... and it would be the basis to motivate other non-EMF
>> projects to use EMF in documenting their code in the EMF way.
>>
>> Would it not be a great step forward, if all the classes developed in
>> the various Eclipse projects are correctly tagged with EMF info, and if
>> the resulting diagrams would be a basis for documentation all EMF
>> plugins?
>>
>> Best, Philipp
>>
>>
Re: [documentation] why are diagrams not done with EMF? [message #609834 is a reply to message #97700] Wed, 26 September 2007 20:28 Go to previous message
Eclipse UserFriend
Originally posted by: cdamus.ca.ibm.com

Hi, Philipp,

I don't know what you mean by "EMF tags." Do you mean, that I should add
EMF's javadoc tags (@model etc.) to non-EMF code? That would give people
the impression that it is generated by EMF and maintained thus, and I
wouldn't want that.

RSA's Java visualization was a good tool for me as it allowed me to easily
create some class diagrams that look good and provide an at-a-glance
overview of the structure. Even better, it does not require that I
annotate my code with stuff it doesn't need.

Unfortunately, I never can make documentation a priority. Anything that the
community can contribute is most welcome.

Cheers,

Christian


Philipp W. Kutter wrote:

> Hi, Christian.
> That's exactly my point: EMF is the perfect tool to interpret bean-style
> operations as implicit properties.
>
> Why is it not used in EMF related documentation?
>
> What should be checked in in my opinion are the EMF tags of the
> developed code.
>
> Best, Philipp


<snip>
Re: [documentation] why are diagrams not done with EMF? [message #609867 is a reply to message #97745] Tue, 02 October 2007 05:35 Go to previous message
Philipp W. Kutter is currently offline Philipp W. KutterFriend
Messages: 306
Registered: July 2009
Senior Member
Hi, Christian.
> I don't know what you mean by "EMF tags." Do you mean, that I should add
> EMF's javadoc tags (@model etc.) to non-EMF code? That would give people
> the impression that it is generated by EMF and maintained thus, and I
> wouldn't want that.

With the right EMF options set, you can generate almost all
getter/setter kind of code, and the signatures of almost any method.
I would restrict adding EMF's javadoc tags to those places which should
appear in your documentations.

> RSA's Java visualization was a good tool for me as it allowed me to easily
> create some class diagrams that look good and provide an at-a-glance
> overview of the structure. Even better, it does not require that I
> annotate my code with stuff it doesn't need.

I'd like to share an experience I had at a big client of us. About two
years ago I started there to add EMF tags to non-EMF code, and to
regenerate this code with EMF. I filed some EMF bugs regarding project
specific settings of formating, e.t.c. and thanks to Ed's fast reply to
them, I managed to set the EMF options such, that we got exactly the
same code as before. I had to add a few annotations, for instance when
I needed as Set instead of List, and then changed the templates, as you did.

After I left, someone internally still maintains the EMF tags, and uses
this as a tool to control the development process, and to extract the
real class diagrams from their code.

But I understand your concern, that you do not want to have people
thinking that the code is EMF code if it is not inheriting from EObjectImpl.

By the way, what are the reasons to make any of your code non-EMF code?

Is it the absence of support for inner classes?

Best, Philipp
>
> Unfortunately, I never can make documentation a priority. Anything that the
> community can contribute is most welcome.
>
> Cheers,
>
> Christian
>
>
> Philipp W. Kutter wrote:
>
>> Hi, Christian.
>> That's exactly my point: EMF is the perfect tool to interpret bean-style
>> operations as implicit properties.
>>
>> Why is it not used in EMF related documentation?
>>
>> What should be checked in in my opinion are the EMF tags of the
>> developed code.
>>
>> Best, Philipp
>
>
> <snip>
Re: [documentation] why are diagrams not done with EMF? [message #609868 is a reply to message #98241] Tue, 02 October 2007 08:26 Go to previous message
Tomas Zijdemans is currently offline Tomas ZijdemansFriend
Messages: 90
Registered: July 2009
Member
Philipp W. Kutter wrote:
> for instance when I needed as Set instead of List

That would actually solve one of my problems... How did you do it?


Tomas
Re: [documentation] why are diagrams not done with EMF? [message #609870 is a reply to message #98256] Tue, 02 October 2007 11:44 Go to previous message
Ed Merks is currently offline Ed MerksFriend
Messages: 31467
Registered: July 2009
Senior Member
Tomas,

Note that BasicEList actually implements all the java.util.Set methods.
The only problem is that equals for Set and List are mutually exclusive
in their design, i.e., you can't implement both correctly with one
method. So if we ever implement
https://bugs.eclipse.org/bugs/show_bug.cgi?id=75931 we'd need to
implement some type of mechanism to support a Set view of the List (just
like we support a Map view of an EMap). The idea being that for any
feature for which upperBound > 0 and for which isOrdered is false and
isUnique is true, we'd use a Set.


Tomas Zijdemans wrote:
> Philipp W. Kutter wrote:
>> for instance when I needed as Set instead of List
>
> That would actually solve one of my problems... How did you do it?
>
>
> Tomas


Ed Merks
Professional Support: https://www.macromodeling.com/
Re: [documentation] why are diagrams not done with EMF? [message #609872 is a reply to message #98241] Tue, 02 October 2007 13:44 Go to previous message
Eclipse UserFriend
Originally posted by: cdamus.ca.ibm.com

Hi, Philipp,

See some comments in-line, below.

Cheers,

Christian


Philipp W. Kutter wrote:

-----8<-----

> I'd like to share an experience I had at a big client of us. About two
> years ago I started there to add EMF tags to non-EMF code, and to
> regenerate this code with EMF. I filed some EMF bugs regarding project
> specific settings of formating, e.t.c. and thanks to Ed's fast reply to
> them, I managed to set the EMF options such, that we got exactly the
> same code as before. I had to add a few annotations, for instance when
> I needed as Set instead of List, and then changed the templates, as you
> did.
>
> After I left, someone internally still maintains the EMF tags, and uses
> this as a tool to control the development process, and to extract the
> real class diagrams from their code.

That sounds much like the round-trip-engineering capabilities of many
development products, that put annotations into one's Javadoc comments (or
as real annotations, since J2SE 5.0). This is a novel use of EMF, for
sure. I wonder when EMF will support 5.0-style annotations, which would
certainly add to the tooling and run-time possibilities for managing
EMF-generated code ...


> But I understand your concern, that you do not want to have people
> thinking that the code is EMF code if it is not inheriting from
> EObjectImpl.
>
> By the way, what are the reasons to make any of your code non-EMF code?
>
> Is it the absence of support for inner classes?

And possibly such constructs as visibility, staticness, etc. Much of this
component isn't a data model, as such, but some of it is. In retrospect, a
good deal of it could have been modeled with EMF, but its history started
in an architecture that wasn't designed in the EMF mould and was later
contributed to Eclipse via the initial contribution of the GMF Run-time.

-----8<-----
Re: [documentation] why are diagrams not done with EMF? [message #612672 is a reply to message #98314] Mon, 26 November 2007 14:08 Go to previous message
Philipp W. Kutter is currently offline Philipp W. KutterFriend
Messages: 306
Registered: July 2009
Senior Member
Hi, Christian.
Sorry for the delayed answer.

Christian W. Damus wrote 20071002:
> Hi, Philipp,
>
> See some comments in-line, below.
>
> Cheers,
>
> Christian
>
>
> Philipp W. Kutter wrote:
>
> -----8<-----
>
>> I'd like to share an experience I had at a big client of us. About two
>> years ago I started there to add EMF tags to non-EMF code, and to
>> regenerate this code with EMF. I filed some EMF bugs regarding project
>> specific settings of formating, e.t.c. and thanks to Ed's fast reply to
>> them, I managed to set the EMF options such, that we got exactly the
>> same code as before. I had to add a few annotations, for instance when
>> I needed as Set instead of List, and then changed the templates, as you
>> did.
>>
>> After I left, someone internally still maintains the EMF tags, and uses
>> this as a tool to control the development process, and to extract the
>> real class diagrams from their code.
>
> That sounds much like the round-trip-engineering capabilities of many
> development products, that put annotations into one's Javadoc comments (or
> as real annotations, since J2SE 5.0). This is a novel use of EMF, for
> sure.

I am not sure whether Ed Merks would agree. Roundtrip between Java and
Ecore, and between Ecore and XSD are among it most valuable features.

I agree that most people on the newsgroup use EMF differently, but when
I reported problems doing this back in 2005, Ed fixed all related
problems, and at the end it worked perfectly.

It is as well a very good practice in order to get up to spead with
forward engineering.


> I wonder when EMF will support 5.0-style annotations, which would
> certainly add to the tooling and run-time possibilities for managing
> EMF-generated code ...

As far as I know, there was no switch announce.

>
>> But I understand your concern, that you do not want to have people
>> thinking that the code is EMF code if it is not inheriting from
>> EObjectImpl.
>>
>> By the way, what are the reasons to make any of your code non-EMF code?
>>
>> Is it the absence of support for inner classes?
>
> And possibly such constructs as visibility, staticness, etc.

Visibility of setters and getters can be controlled with an EMF
annotation. Thus you can make getters and setters invisible in the
interface.

The staticness is a topic not touched by EMF. The static fields have to
be excluded from the models, or done by tailoring your templates. We use
for instance annotations to define static fields. The objects refered by
this static fields must exist in EMF resources which are available in
the same plugin as the EMF models.

> Much of this
> component isn't a data model, as such, but some of it is. In retrospect, a
> good deal of it could have been modeled with EMF, but its history started
> in an architecture that wasn't designed in the EMF mould and was later
> contributed to Eclipse via the initial contribution of the GMF Run-time.

Why not adding the EMF tags to the code of the component? After all, its
risk free:
1) you add the EMF tags
2) you load the ECore from the code
3) you regenerate the code
4) differences on CVS must be zero, otherwise adapt the
genmodel/code-tags and return to 2)

If you cannot solve the problem, report it to the EMF list, and they
typically fix the problem.

This only works, if the formating options of all the components are
standardized, and all the code is formatted before it is committed.

Best, Philipp
Previous Topic:[CDO 0.8.0] StoreAccessor could return less or more element than the reference Chunk ask for.
Next Topic:problem with DB2 schema creation with abstration
Goto Forum:
  


Current Time: Sat Sep 19 15:33:17 GMT 2020

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

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

Back to the top