Experimental generation of code and documentation from UML

--- Update July 2015: Note that updated openEHR specifications are now available at https://github.com/openEHR/specifications-RM/tree/master/computable/UML, https://github.com/openEHR/specifications-AM/tree/master/computable/UML and browsable links like via http://openehr.org/releases/trunk/UML/ ---

This page is in alpha stage. If it comes closer to beta it will be noted on the openEHR developer mailing list...

EMF is a (meta)modeling framework in Eclipse. UML version 1+ or 2+ are some of the possible meta models. The openEHR RM and AM specifications are available as UML (Magic Draw) and also (partly) as XML Schemas. This wikipage is a intended for people that arw interested in getting the openEHR specification models as input into the EMF framework and then to generate artifacts such as code and documentation as output from the EMF framework.

Experiment description 

An initial experiment was conducted running Eclipse 3.3 on Windows XP.

1. Get a machine readable version of the openEHR model specifications in UML/XMI-format
   • Alternative A: Until the link on the UML Models main page http://www.openehr.org/releases/1.0.1/architecture/computable/UML/uml.htmlto a (non-existing) zip (http://www.openehr.org/releases/architecture/computable/UML/MagicDraw/openehr.xml.zip) is fixed you'll need to get the MagicDraw-optimized version from the SVN repository at http://www.openehr.org/svn/specification/TRUNK/architecture/computable/UML/MagicDraw/openehr.xml.zip The UML Models main page above states that "An XMI 1.0 file output from the tool is also available" but no details are given where to find it, so you'll need to either install Magic Draw and export such a file or trust that the converted file attached to this wiki page is correct (coming soon...)
     • The current openEHR computable UML model was converted from UML 1.x to 2.x upon import in community version 15.1 of MagicDraw (on startup enable "expert" mode in order to see all menu items used for export later). The errors & warnings generated on import mostly concerned a (possibly unintentionally left behind) function "isRoot" that anyway seems to have been removed from the openEHR specification. The layout of some diagrams was manually modified a bit but the underlying class model was hopefully left intact.
     • The MagicDraw project was exported as EMF UML2 (v2.x) XMI.The errors & warnings generated on export are listed here.
       ...
       The option to export "Rich XMI" was turned on and the file suffix was manually changed from xml to uml in order to fit Eclipe EMF import better. The resulting file openehr1_0_1-rich-xmi.uml is attached to this page <-- not possible to import
   • Alternative B: Generate UML "backwards" from the openEHR XML Schemas found and described at http://www.openehr.org/releases/1.0.1/its/XML-schema/index.html(or download latest from TRUNK in the SVN repository http://www.openehr.org/svn/specification/TRUNK/ITS/XML-schema/) This XSD->UML transformation can be done for example using the Eclipse plugin hyperModel from http://www.xmlmodeling.com/ (The latest version of hyperModel requires Eclipse 3.4) Since the XSD models do not contain the full openEHR models you'll then need to manually edit the models.
   • Alternative C: Enter the models manually...
   • Alternative D: Reverse-engineer a Java openEHR implementation using e.g. Topcased as described in the presentation at http://gforge.enseeiht.fr/docman/view.php/7/279/TPC_2.1_Java_Reverse_tutorial.pdf from the discussion thread  http://lists.gforge.enseeiht.fr/pipermail/topcased-users/2008-October/002507.html
2. Open the UML file in an EMF-enabled Eclipse setup.
3. Inspect and edit the model if needed. If errors or differences in semantics compared to the PDF-specifications are found, then supply feedback to openEHR (TODO: Add link to JIRA-enry for "computable" spec?) Any EMF-based editing plugin for Eclipse should work. The errors and TODO-items found are listed at the end of this page.
   • In the first test Topcased was used
     • Eclipse update site: http://topcased-mm.gforge.enseeiht.fr/release/update-site3.3/ (As of this writing there seems to be a dependency problem, uncheck the unsatisfied admin component to get the installation going)
     • Topcased cookbok: http://gforge.enseeiht.fr/docman/view.php/7/2224/TOPCASED_cookbook_1.2_gb.pdf
   • TODO: Add alternative editors...
4. Use, modify or create new (usually template driven) output mechanisms to create code and documentation. There are several ways to go from EMF to Code (see discussion)
   • JET is built in, this and other approaches are described on http://www.eclipse.org/modeling/m2t (m2t=model to text)
   • For this initial test Acceleo, http://www.acceleo.org/, was used.

Suggested automated (or semiautomated) outputs to develop:

• Java UPPER_CASE and/or CamelCase class implementation stubs possibly extended by...
  • Annotations for DBC frameworks (rules should be extracted from XMI file)
  • Annotations for serializing frameworks for XML and JSON (and possibly DADL if somebody feels a pressing need for it )
  • Conversion code between mutable and immutable versions of java implementations
• JSON Schemas for AM and RM
• Python stubs
• C# stubs
• Ruby stubs
• Class documentation segments in FM (FrameMaker) format or something that FM can import as long as the specs are written using that tool instead of an open source alternative.
• Model documentation in other formats (HTML, PDF etc)
• ...

Errors and TODO-items

V 1.0.1 Alpha 0.02

DONE: (Please not that these "Alpha 0.02" changes  are not uploaded to this site yet)

• rm.composition.content.entry.INSTRUCTION: Removed double generalization/inheritance to ENTRY
• rm.composition.content.entry. EVALUATION: Removed double generalization/inheritance to ENTRY
• rm.data_types.time_specification.DV_TIME_SPECIFICATION: Made it abstract
• rm.data_structures.representation.ITEM: Added generalization/inheritance to LOCATABLE

TODO:

• Convert several classes to abstract in "quantity"-package
• upper/lower etc on INTERVAL in "quantity"-package
• Check how generics should be modeled in a good way. See also: http://www.eclipse.org/modeling/mdt/uml2/docs/articles/Defining_Generics_with_UML_Templates/article.html and possibly http://wiki.eclipse.org/MDT-UML2
• ERROR: PARTY_PROXY is missing the important attribute external_ref
• ERROR: MERGED_VERSION should be removed from UML, it has been dropped in at least openEHR release 1.0.1 and 1.0.2
• Look for more errors...

QUESITONS

• DV_TIME_SPECIFICATION: Should the children of this class really repeat the method definitions instead of inheriting? Is that because the methods probably will need to be implemented differently and only share signatures?

Additions to prepare audience for V 1.0.1++ (Upcoming versions)

• Add comment: PARTICIPATION will probably inhertit from LOCATABLE...