Bug 251963

Comment 1 Tom Morris 2008-10-28 13:21:56 EDT

Since JSR-040 Java Metadata Interface (JMI) was never updated for current versions of MOF/UML, I don't think there really is an API "standard" per se, is there?

I agree however that it would be very useful to be able to distinguish operations which are implied by (and generated from) the spec from those which were added separately.

(Of course it would be great of the OMG were to create a standard API mapping)

Comment 2 Christian Damus 2013-08-06 11:59:03 EDT

The URL referenced in comment #0 is obsolete.  I have linked the discussion thread that appears to have spun off this bug in the URL field.

Comment 3 Christian Damus 2013-10-07 17:42:37 EDT

I have pushed a solution on a new branch bugs/251963.  This comprises three commits, as described below.

Commit a8b19acfd70af7663c5f7c784f495652ce108da4:

Updates the UML2EcoreConverter to look for the "capabilities" annotation created by package merge to add statements in the Javadoc comments about the source packages from which API elements were merged.  For each merged package, the converter iterates all API elements (classifiers, properties, operations) merged from it and adds their GenModel doc annotations a statement indicating the package from which it was merged.  There is no new converter option governing this:  the option to generate the capabilities annotation is already in the Package Merge dialog, so it seems appropriate just to process it if it is present.  Moreover, the transformation (because it generates doc-annotation content) is not reversible; Ecore has no analogue of package merge and run-time behaviour is not affected, so it doesn't seem useful to record merge traceability in the Ecore model.

Commit 7ad06359aa672f7852914d883b402240ec7d509a:

This commit increments the existing PackageMerger generation of the "capabilities" annotation to add a detail on the sub-annotation for each merged package to record the package's URI, if any.  This helps the Javadoc generated in the API to more precisely identify packages (e.g., 'UML' is the name of both the OMG-standard package and the Eclipse-custom package that merges it).

Commit 600887c73b8424b994b2c3702cd7f787cbd4a7a8:

This commit merges the UML metamodel to generate the capabilities annotation and re-generates the Java API interfaces to add the traceability statements.  Note that, as the capabilities annotation is not actually used at run-time, we could actually retain only the updates to the generated API interfaces and discard the changes to the source models.

Comment 4 Kenn Hussey 2013-10-08 22:00:19 EDT

Thanks Christian! Here's my feedback:

- I would suggest method names like isCapabilityAnnotation(...) and processCapabilityAnnotations(...), for consistency

- isCapabilityTraceAnnotation(...) appears to be performing (a lot of) redundant checks, given that it's only called from a context where you already know that it's a nested annotation on a package

- given the decreasing relevance of package merge (and that I suspect API consumers could care less how the API was produced), I would hesitate to include "Merged from ..." at the beginning of all the new comments; better to say "From ..." (my preference) or "Defined in ..."

- all of the modified interface source files will need their copyright dates to be updated, a contributor entry added, and (potentially) obsolete CVS comment line removed

Comment 5 Christian Damus 2013-10-08 22:20:50 EDT

(In reply to Kenn Hussey from comment #4)
> Thanks Christian! Here's my feedback:

Thanks, Kenn.

> - I would suggest method names like isCapabilityAnnotation(...) and
> processCapabilityAnnotations(...), for consistency

Sure.  I do find the term "capability" to be rather odd, though.  Is that the language of the UML spec?


> - isCapabilityTraceAnnotation(...) appears to be performing (a lot of)
> redundant checks, given that it's only called from a context where you
> already know that it's a nested annotation on a package
> 
> - given the decreasing relevance of package merge (and that I suspect API
> consumers could care less how the API was produced), I would hesitate to
> include "Merged from ..." at the beginning of all the new comments; better
> to say "From ..." (my preference) or "Defined in ..."

"From" is good.


> - all of the modified interface source files will need their copyright dates
> to be updated, a contributor entry added, and (potentially) obsolete CVS
> comment line removed

Hmm.  Do you have a script that can do this for the 257 affected files?  I'll see whether Eclipse's regexp find-and-replace function is up to the task ...

Comment 6 Kenn Hussey 2013-10-08 22:30:52 EDT

(In reply to comment #5)
> Sure.  I do find the term "capability" to be rather odd, though.  Is that the
> language of the UML spec?

It's not a formal part of the language in the specification, but package merge was originally designed as a mechanism for merging capabilities from multiple package "increments"... 

> Hmm.  Do you have a script that can do this for the 257 affected files?

Sadly, I don't. :(

Comment 7 Christian Damus 2013-10-09 00:19:37 EDT

I have pushed two new commits to branch bugs/251963.

Commit ad37e95 addresses the comments on the UMLUtil code.

Commit 2434653 re-generates the model API with the updated "From package ..." statements in the doc comments and updates all 255 source files' header comments.  Yes! I applied a sequence of regexp replacements in Eclipse to:

* add missing 2013 range for single-year copyrights (e.g., LiteralReal introduced in 2006)
* update non-2013 range uppers to 2013
* add "CEA" copyright holder in the first line where it was missing
* add myself as a contributor with the bug number where I was missing

Because, of course, all 255 model interfaces and enums have "From package ..." statements.

All unit tests pass.

Comment 8 Kenn Hussey 2013-10-09 13:33:24 EDT

The changes have been merged and pushed to the 'master' branch in git.

Comment 9 Kenn Hussey 2013-10-14 11:43:18 EDT

The changes are available in an integration build for 4.2.0.