View source for Eclipse Code Generation for HL7 Applications

=Premise=
*Between 1997 and 2003, HL7 committed to 
**Basing V3 standards on information models based on UML (as it evolved)
**producing "processable" representations of its V3 standards to facilitate implementation
**adopting XML as its first implementation technology
**developing a tooling interchange format (MIF) that expresses the UML models and their profiled extensions in a robust, validatable XML schema  
* As a consequence, we have both the tools and the challenge to simplify tooling for both standards development and implementation by taking advantage of these characteristics.
*This presentation explores the synergies between the artifacts that HL7 develops and the Capabilities of the Eclipse Modeling Framework (EMF)  
=Backgrounf=
=="Glossary" Stuff==
Classes, instances, elements, objects, attributes, properties, models, meta-models: These are terms that are important to – object modeling (UML), meta-models and meta-data (all), object-oriented programming (Java), information modeling (HL7), structured data (XML and HL7) – but whose meaning is too often taken for granted, and whose relationships are, at times misunderstood. 

The following sections will attempt to provide "brief" definitions of these and to establish their relationships in the context of HL7 tooling.
===Bibliography===
#EMF: Eclipse Modeling Framework (2nd Edition), Dave Steinberg [et. al.], ISBN 0-321-33188-5; ©2009, Pearson Education, Inc.
#Java 2 for Dummies (2nd Edition), Barry Burd, ISBN 0-7645-6858-2; © 2004 Wiley Publishing, Inc.
#HL7 Version 3 Standard: Core Principles and Properties of Version 3 Models, Release 1, HL7, © 2012  HL7 International

==Definitions (sorta)==
'''class, instance, object''' (from Burd [2]) - A class is the idea behind a certain kind of thing.  An object is a concrete instance of a class.

An '''EMF model''' is essentially the Class Diagram subset of UML; that is, a simple model of the classes, or data, of the application (from Steinberg [1])

A '''metamodel''' is simply the model of a model, and if [the] model [being modeled] is itself a metamodel, then the metamodel is in fact a meta-metamodel. (from Steinberg [1])

A '''derived model''' is one for which the content is drawn from a set of "foundation standards"  (RIM, data types, vocabulary) according to a set of derivation rules defined in the HL7 methodology. (from HL7 [3])
:'''Note:''' A derived model is the same kind of model as the model from which its derived.  A model from which others are derived is not a metamodel for the derivations.
==HL7 "Products" & Tools==
Primary standards are information models (class models) that define message instances (collection of objects for communication).

Foundation standards are base models from which primary standards are derived. 

Implementation tools are based on HL7 models to create and communicate instances

Standards development tools use the base models as source data to create primary standards defined according to the HL7 metamodel for information models.
==Metamodels==
The UML metamodel is the core product of the OMG's UML standardization efforts.

XMI is the primary serialized representation of UML-conformant models.  XMI permits extension of these representations using "profiles" that contain additional "tagged" properties for each of the UML element types, but XMI does not permit extension by adding new, distinct  elements (such as code systems or value sets.)

The HL7 metamodel starts with the UML metamodel and adds significant extensions, in the form of primary elements to represent new concepts, such as terminologies, terminology constraints and data type properties, that are not present in UML.

The complete HL7 metamodel is defined in the HL7 Model Interchange Format (MIF) - a combination of XML schema and schematron rules. MIF-conformant XML files provides the primary serialized representation of HL7-conformant models.
==Eclipse & EMF Project==
“Eclipse is an open source software project, the purpose of which is to provide a highly integrated tool platform.” (from Steinberg [1])

Eclipse is HL7's preferred tooling base, and also the adopted base of Open Health Tools – OHT.

EMF – “The Eclipse Modeling Project is the focal point for the evolution and promotion of model-based development technologies at Eclipse. At its core is EMF, … which provides the basic framework for modeling. Other modeling sub-projects build on top of the EMF core …” (from Steinberg [1])
=EMF Basics=
==EMF Model Relationships==
[[Image:EMFModelRelationships.gif|thumb|right|320px|Relationships between EMF Models from Steinberg [1]]]
*EMF provides full translation for all directions
*XML “model” is XML schema
*UML model source is either “Rose” model or “Eclipse UML2” model
*Java model is class interfaces
*EMF model is “Ecore”
*:“Ecore is a small and simplified subset of full UML” (from Steinberg [1] )

*Steinberg [1] on persistence of objects created with EMF:
:“... EMF includes a default XMI serializer that can be used to persist objects generically from any model, not just Ecore. Even better, if your model is defined using an XML Schema, EMF allows you to persist your objects as an XML instance document conforming to that schema.”

==Generation and Customization==
*As the EMF model is created, a “generator model” (genmodel)  is also created to hold information that affects only code, not content, such as labels, Java styles, code location, etc.
*The genmodel may be changed and will remain in “synch” with changes to the EMF model.
*Code is generated from the genmodel (which also links to the EMF model) . 
*Code may be customized, and customizations will be retained upon regeneration.
*“Dynamic” EMF allows addition of “structural elements” that are not in the base model. Examples:
**Add a “collector” element in a vocabulary model to contain all Concept Domains, even though the source and output simply include them as a sequence of elements below the model;
**Flatten selected elements (in the display) where they provide no new information, such as “containedClass” in a static model;
*Generation features include (non-exhaustive list):
**Base classes for each model element;
**Factories for creation and importation of classes:
**De-serialization (read) and serialization (write) of objects
**Resource (like label and icon) management;
**Rich “notification” structure of changes that enables “un-do” and “re-do” operations. 
*Generation also produces a basic “Editor” that permits either ''de novo'' creation of a new instance, or ability to edit a defined model. The editor can be extended as desired.

==Core Requirements==
*Java run-time   (Author used version 1.6.0_30.)
*“Eclipse Modeling Tools” (link is to a complete download for Eclipse “Indigo”)
*Eclipse support for SVN (“Subversive”)
*HL7 Schemas for MIF and information models – obtain from Gforge and/or Normative Editions.
*XML editor to “flatten” schemas (reduce to a single file) . (Author used XmlSpy)
*Base familiarity with Eclipse Framework
*Prototype - In the SVN space for the '''Tooling Documentation''' project on Gforge is a “sand-box” for project start-ups.  You can browse the SVN at [http://gforge.hl7.org/gf/project/tool-proc-arch/scmsvn/?action=browse&path=%2Ftrunk%2Ftooling-sandbox%2F gforge.hl7.org/svn/tool-proc-arch/trunk/tooling-sandbox/mif-emf]. The URL for the svn repository is '''gforge.hl7.org/svn/tool-proc-arch/trunk/tooling-sandbox/mif-emf''' 
**Prototype contents include complete models, schemas, and generated content for both MIF 2.1.6 and 2.2.0; as well as more detailed documentation and useful x-path constructs.

=Steps for MIF to EMF Software and Instances=
==Schema Preparation==
In order to take best advantage of the EMF editors, the base schemas for the MIF and static models must be “prepared” as:
*Exclude xhtml (annotation markup) from the generation '''''by declaring MIF types Flow, Inline, Object and Img to be mixed and to extend xs:anyType'''''. 
*:This removes many classes and probably over half the objects from the application, but does not remove the correct annotations from either the source or the output files.  A separate WYSIWYG editor for managing this content has been tested and will be incorporated in this suite.
*Flatten the schemas to a single file, rather than multiple “included” schemas. XmlSpy supports this as: '''''open the “root” schema; select the “Schema” view (the default); and select “Menu…Schema Design…Flatten schema…”'''''  
*:Flattening produces error-free conversion to ecore, and enables x-path analysis of the combined schema to assist in making other changes before model conversion. 
*'''''Create a version-specific xml namespace''''' to allow simultaneous preparation of code conversion for several MIF versions. Example specific namespace is: "urn:hl7-org:v3/mif220“ instead of "urn:hl7-org:v3/mif2"  for MIF version 2.2.0
*In the combined schema file, find all types that are used to both type an element  and as an extension base for another type. 
*:'''''Use x-path in  “TypesUsedAsBothTypeAndExtensionBase.txt” and incorporate in “cleanUpFlattenedMif220.xsl” for final schema processing'''''
*::The transform will eliminate a “wierdness” in the generator that causes the editor to offer a drop-down containing both the correct type and all the specializations..
*In the combined schema file, find all types that are used to both type and element  and as a restriction base for another type. 
*:'''''Use x-path in  “TypesUsedAsBothTypeAndRestrictionBase.txt” and incorporate in “cleanUpFlattenedMif220.xsl” for final schema processing'''''
*::The transform will eliminate a “wierdness” in the generator that causes the editor to offer a drop-down containing both the correct type and all the specializations.
*In the combined schema file, find all simple enumerated types that are used to type optional attributes. 
*:'''''Use x-path in  “EnumeratedSimpleTypesUsedInOptionalAttributes.txt” and incorporate in “cleanUpFlattenedMif220.xsl” for final schema processing'''''
*::The transform will address a “wierdness” in the generator forces the appearance of all enumerated attributes, even if optional. Change will still provide the enumerated drop-down in the editor..
*'''''Update the “cleanUpFlattenedMif220.xsl” transform''''', including the assertion of the proper namespace URN, and '''''use the transform to convert the flattened schema to the “final” form''''' for model conversion.

==Ecore and Genmodel preparation==
*In '''Eclipse: Menu…File...New...Eclipse Modeling Framework ...EMF Project'''; then '''NEXT'''
*'''Add project name''' like org.hl7.mif220.all; '''check Use default location'''; then '''NEXT'''
*'''Select XML Schema'''; then '''NEXT'''
*'''Browse to final schema''' (flattened and updated); '''select "Load"'''; '''Accept generator model file name''' (the same name as schema file with extension ".genmodel“);
*'''Check "Create XML Schema to Ecore Map"'''; TAKE A BREAK;
*:[Your Eclipse will now GRIND for at least 20 minutes. This is the ONLY slow part of the business and it only occurs once per schema revision.]
*When the hour-glass disappears, click '''FINISH''' 

These steps have created  the .ecore model and .genmodel as well as the mapping between the schema and ecore model.

==Code Generation==
*The preceding steps created a new “project” in your workspace named like org.hl7.mif220.all, and this model holds a model sub-directory with the three generated models.
*Browse these, if desired.  
*To generate code:
**Open the .genmodel file in a window by double-clicking it;
**Select any element from that model;
**Right-click, and select “Generate All” 
**:This will generate “src” files for the base model, and also will create three new models named with extensions to the base of “.edit”, “.editor”, and “.test”.  Two of these will also have generated icons directories.
*The Eclipse automated build process will add a bin directory and  fill it with compiled content for all four projects.
*:It is recommended that you '''exclude the “bin” and “icons” directories from SVN version control''' as they can be readily re-built.

==Start the Basic Editor==
The “Hello World!” step of this process is:
#Select one of the four "projects" that have been generated; 
#FIRST TIME: 
#*Right-click and select "Run as...Run configurations..." 
#*Select "Eclipse Application...Eclipse Application"
#*In "Main" tab, click on "Location" (under "Workspace Data") and select a directory location to serve as the root for your "Run-time" project(s) work space.  
#*:(Default location is as a sibling to the EMF work space.)
#* When Location is set, click "Run"
#SECOND TIME (and later): 
#*Right-click and select "Run as...Eclipse Application“

Either path (2) or (3) will end up opening a new instance of Eclipse with the workspace set to the value selected in (2.c)

==Create a new set of objects==
*Create a run-time project for  instances by:
**Select Menu..File...New...Project...General...Project; then NEXT
**Enter a name like "AllMif220"; then FINISH
*Create a new instance by: 
**Select the project from above;
**Right-click and Select "Menu... File... New... Other...“
***In dialog, Select "Example EMF Model Creation Wizards...MIF220 Model"; then NEXT
***In dialog enter  a "File name:" for the new instance with an extension of ".mif220“, such as "new.mif220"; then NEXT
**Using the "Model Object" drop-down list, select the intended rootElement of the file, (which displays with an upper case name like "Package“); then FINISH
*Open a “Properties” view to edit the elements and/or right-click to add child or sibling elements.

==Open an Extant Instance file==
*Assure that the namespace of the intended source file matches the schema used for generation
*Name the files with the correct extension (*.mif220), and copy them into the directory of the run-time project
*In the Runtime Eclipse, press "F5" to refresh the content. The instances should appear for browsing and/or editing.
**Double-click on an instance to open it in an editor. 
*Browse/validate/edit/save.