Guidelines on how to derive XML schemas from FuGE-based UML2 models

Authors

Created by Olga Tchuvatkina and Josef Spidlen based on initial investigation by Settimo Szliske and Andy Jones and comments by Allyson Lister.

Requirements

Java 1.5 (JDK 5.0) or newer required; Java SE Development Kit recommended
Maven2 (tested with Maven 2.0.6 and 2.0.8)
AndroMDA 3.2
FuGE v1 Final Release
MagicDraw 11.5 (or newer), Community Edition (or higher) required to prepare the UML2 model that will be converted to XSD; it is not needed for the conversion process itself. We recommend MagicDraw 15

Notes

Directly applicable on MS Windows based platforms; modifications required for other platforms.
Can be used as formal validation of FuGE-based UML2 models
You have to perform all 13 steps of the guide only once to set up the environment.
- If that's your first FuGE extension project, start from Step 1
- If you already followed the guide once and want to create a second extension project, start from Step 8
- If you want to update model of existing FuGE extension project, go to Step 12

Replace following values in the guide with your own (they are highlighted in bold throughout the text):

YourUserName	Your login/profile name (e.g. `jspidlen`)
ProjectName	Name of the project (e.g. `FuGEFlow`)
projectname	Name of the project in lower case (e.g. `fugeflow`)
Project.Description	Project description (e.g. `“Flowcytometry extension of FuGE”`)
UMLProjectName	Name of your uml model (e.g. `FuGEFlow_v1_0`)
ModelRoot	Name of the root folder in your uml model. May be the same as ProjectName or different (e.g. `FuGEFlow or FCM`)
modelroot	Name of the uml root folder in lower case (e.g. `fugeflow or fcm`)
domain.projectname	Root package for your project (e.g. `org.flowcyt.fugeflow`), do not confuse with ModelRoot
project.web.site	Namespace of your model (e.g. `http://flowcyt.sourceforge.net/fugeflow/`)

Step by Step

1. Install Java

Your current Java version can be checked by entering java -version on your command line.
Update Java if your version is earlier than 1.5; Java SE Development Kit (JDK) is recommended; JDK includes the required Java Runtime Environment (JRE).

2. Install Maven2

Download Maven2; (e.g., the maven-2.0.8-bin.zip file)
Unzip the file to the directory you wish to install Maven2; (e.g., C:\apps\maven-2.0.8)
Create an empty folder: C:\Documents and Settings\YourUserName\.m2\repository

3. Set Up Environment Variables

Open up the system properties (e.g., "Start --> Settings --> Control Panel --> System" or "Windows Key + Pause"), select the "Advanced" tab, and the "Environment Variables" button.

Create / update the following variables:

`M2_HOME`	`C:\apps\maven-2.0.8`
`M2_REPO`	`C:\Documents and Settings\`YourUserName`\.m2\repository`
`MAVEN_OPTS`	`-XX:MaxPermSize=128m -Xmx512m`
`JAVA_HOME`	location of your JDK, e.g., `C:\Program Files\Java\jdk1.5.0_05`
`PATH`	add the following at the end of the PATH variable value: `;%JAVA_HOME%\bin;%M2_HOME%\bin`

4. Test Maven2

Run mvn --version from your command line to verify that Maven2 is correctly installed.
In a temporary directory run mvn archetype:create -DgroupId=testapp -DartifactId=testapp from your command line. Check the BUILD SUCCESSFUL massage and delete the created testapp folder.

5. Create Conversion Project (Maven2 Application)

Create the C:\Projects\ProjectName\andromda directory
Download andromda_empty_project.zip and extract content to the directory specified above
After extraction your C:\Projects\ProjectName\andromda directory should contain maven project file called pom.xml and src directory with configuration files
You can remove andromda_empty_project.zip file

6. Download All Required Components

From your command line change to C:\Projects\ProjectName\andromda.
Run mvn dependency:go-offline .

All required libraries will be downloaded to maven repository automatically. This process may take a couple of minutes. When all dependencies are resolved, you should see log similar to this:

...
[INFO] Resolved: andromda-ocl-translation-core-3.2.jar
[INFO] Resolved: andromda-ocl-validation-library-3.2.jar
[INFO] Resolved: andromda-metafacades-uml-3.2.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL 
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 44 seconds
[INFO] Finished at: Thu Feb 28 11:11:34 EST 2008
[INFO] Final Memory: 9M/17M
[INFO] ------------------------------------------------------------------------

$/!\$ Successful download is required for further steps. To make sure you have downloaded necessary libraries, navigate to C:\Documents and Settings\YourUserName\.m2\repository\org\andromda and check that directory contains several sub-directories including cartridges (required for Step 7) and profiles (required for Step 8)

7. Fix Facade Mappings

Next, we have to fix bug in one of the AndroMDA libraries. More information about the bug can be found at AndroMDA forum. Without this fix, the generated XSDs will be empty, containing only the top-level namespace information.
Change to C:\Documents and Settings\YourUserName\.m2\repository\org\andromda\cartridges\andromda-xmlschema-cartridge\3.2\

You can either download correct andromda-xmlschema-cartridge-3.2.jar or edit it yourself. To download follow the link andromda-xmlschema-cartridge-3.2.jar (part of FuGE XSD STK distribution) and replace file in directory specified above. If for some reason file is not available, follow steps below:

Run jar xf andromda-xmlschema-cartridge-3.2.jar META-INF/andromda/metafacades.xml

Update the metafacades.xml file as follows:

<?xml version="1.0" encoding="ISO-8859-1" ?>

<metafacades>

  <metafacade class="org.andromda.cartridges.xmlschema.metafacades.XSDEnumerationTypeLogicImpl">
      <mapping>
          <stereotype>XML_SCHEMA_TYPE</stereotype>
          <stereotype>ENUMERATION</stereotype>
      </mapping>
  </metafacade>
  
  <!-- *** This part is replaced by the two following metafacade elements. ***
  <metafacade class="org.andromda.cartridges.xmlschema.metafacades.XSDComplexTypeLogicImpl">
      <mapping>
          <stereotype>XML_SCHEMA_TYPE</stereotype>
      </mapping>
  </metafacade>
  -->
  
  <metafacade class="org.andromda.cartridges.xmlschema.metafacades.XSDComplexTypeLogicImpl"> 
    <mapping class="org.omg.uml.foundation.core.UmlClass$Impl"> 
      <stereotype>XML_SCHEMA_TYPE</stereotype> 
    </mapping> 
  </metafacade> 
  <metafacade class="org.andromda.cartridges.xmlschema.metafacades.XSDComplexTypeLogicImpl"> 
    <mapping class="org.eclipse.uml2.impl.ClassImpl"> 
      <stereotype>XML_SCHEMA_TYPE</stereotype> 
    </mapping> 
  </metafacade>
  
  <metafacade class="org.andromda.cartridges.xmlschema.metafacades.XSDAttributeLogicImpl">
      <mapping>
          <property name="ownerSchemaType"/>
      </mapping>
  </metafacade>
  <metafacade class="org.andromda.cartridges.xmlschema.metafacades.XSDAssociationEndLogicImpl">
      <mapping>
          <property name="ownerSchemaType"/>
      </mapping>
  </metafacade>

</metafacades>

Run jar uf andromda-xmlschema-cartridge-3.2.jar META-INF/andromda/metafacades.xml

8. Preparing a FuGE-based UML2 Model for Conversion

MagicDraw 11.5 (or newer) Community Edition (or higher) is required to prepare the UML2 model. We recommend version 15.0. Community Edition may be downloaded and used for free – follow instruction on MagicDraw web site.
Create directory C:\Projects\ProjectName\model for your UML project
Download NewFuGEExtension.mdzip file from the FuGE site into the directory specified above
Download FuGE-v1-profile.mdzip file from the FuGE site into the same folder
Rename NewFuGEExtension.mdzip file to UMLProjectName.mdzip
Open renamed file with MagicDraw
You’ll be prompted to define maven2.repository variable. Set its value to C:\Documents and Settings\YourUserName\.m2\repository.
If you were not prompted, open menu "Options --> Environment --> Path Variables" and set value there.
Once project is opened, rename package NewFuGEExtension to ModelRoot
Save the project

9. Update the Project Description File

Edit the following file: C:\Projects\ProjectName\andromda\pom.xml

Replace domain.projectname, projectname, ProjectName and Project.Description with your project values:

<groupId>domain.projectname</groupId>
<artifactId>projectname-andromda</artifactId>
<version>0.1</version>
<packaging>pom</packaging>
<description>Project.Description</description>

Scroll to the end of the file and replace UMLProjectName with the name of your uml model:

<properties>
  <model.uri>file:${project.build.sourceDirectory}/UMLProjectName.uml2</model.uri>
  <andromda.version>3.2</andromda.version>
  ...
</properties>

10. Update the AndroMDA Configuration File

Edit the following file: C:\Projects\ProjectName\andromda\src\main\config\andromda.xml

To generate a separate extension schema that imports core FuGE (default), replace ModelRoot with the name of the root folder in your model:

  <repositories>
    <repository name="emf-uml2">
      <models>
        <model type="emf-uml2">
          ...
          <modelPackages processAll="false">
            <modelPackage process="false">FuGE::**</modelPackage>
            <modelPackage process="true">ModelRoot::**</modelPackage>
          </modelPackages>
        </model>
      </models>
    </repository>
  </repositories>

To generate a single XML schema that includes both core FuGE and custom extensions, replace ModelRoot with the name of the root folder in your model and update processAll and process values as follows:

  <repositories>
    <repository name="emf-uml2">
      <models>
        <model type="emf-uml2">
          ...
          <modelPackages processAll="true">
            <modelPackage process="true">FuGE::**</modelPackage>
            <modelPackage process="true">ModelRoot::**</modelPackage>
          </modelPackages>
        </model>
      </models>
    </repository>
  </repositories>

Scroll to the end of the file. Replace project.web.site with URL address of your project:

  <namespace name="xmlschema">
    <properties>
      ...
      <property name="namespace">project.web.site</property>
    </properties>
  </namespace>

11. Create XML Schema Cartridge Template

Open C:\Projects\ProjectName\andromda\src\cartridge\custom\templates\xmlschema directory
To generate a separate extension schema that imports core FuGE (default):
- Download XmlSchema_V1-extensions.vsl from FuGE site into the directory specified above
- Rename file to XmlSchema.vsl and open it for edit
- Replacemodelroot (on line 16) with the name of the root folder in your model in lower case:
```
<xsd:schema 
    targetNamespace="$namespace"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:fuge="http://fuge.sourceforge.net/fuge/1.0"
    xmlns:modelroot="$namespace"
    elementFormDefault="qualified">
    
```
To generate a single XML schema that includes both core FuGE and custom extensions:
- Download XmlSchema_FuGE_Version1.vsl from FuGE site into the directory specified above
- Rename file to XmlSchema.vsl
$/!\$ Make sure you now have cartridge file at exactly this location with exactly this name and extension: C:\Projects\ProjectName\andromda\src\cartridge\custom\templates\xmlschema\XmlSchema.vsl

12. Extend FUGE and export UML2 Model

Open C:\Projects\ProjectName\model\UMLProjectName.mdzip with MagicDraw
Create/update your model underneath ModelRoot package following Guidelines to extend FuGE. Proper use of stereotypes, named relations, multiplicities, etc. is required for sucessful schema generation.
Once you are ready to validate model/generate XSD, go to "File --> Export" and choose "EMF UML2 (v1.x) XMI" option ( $/!\$ not "EMF UML2 (v2.x) XMI"). Set export location to C:\Projects\ProjectName\andromda\src\main\uml directory.
After export is completed, make sure that C:\Projects\ProjectName\andromda\src\main\uml directory contains UMLProjectName.uml2 file among other files
$/!\$ Repeat export step each time you made a change to your model

13. Generate the XML Schema

Final step: XML schema is generated from your model export
From your command line change to C:\Projects\ProjectName\andromda.
Run mvn or mvn -o .

If build was successful, generated XML schema will be located at C:\Projects\ProjectName\andromda\target\xmlSchema.xsd.

The -o switch sets the offline mode, which prevents new versions of libraries being downloaded, in other words it guarantees that "fix" performed in step 7 does not get overwritten.

You may use the –e switch for details about potential problems/errors.

The UML model gets validated automatically while generating the XML schema; you should see an output log similar to this:

 C:\Projects\!ProjectName\andromda>mvn -o
[INFO]NOTE: Maven is executing in offline mode. Any artifacts not already in your local repository will be inaccessible.
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'andromda'.
[INFO] org.apache.maven.plugins: checking for updates from andromda
[INFO] org.codehaus.mojo: checking for updates from andromda
[INFO] ------------------------------------------------------------------------
[INFO] Building ProjectName AndroMDA
[INFO]    task-segment: [andromda:run]
[INFO] ------------------------------------------------------------------------
[INFO] [andromda:run]
INFO  [AndroMDA]
INFO  [AndroMDA] A n d r o M D A  -  3.2
INFO  [AndroMDA]
INFO  [AndroMDA] - discovering namespaces -
INFO  [AndroMDA] found namespace --> 'bpm4struts'
INFO  [AndroMDA]   +  registering component 'cartridge'
INFO  [AndroMDA]   +  registering component 'metafacades'
INFO  [AndroMDA]   +  registering component 'profile'
INFO  [AndroMDA] found namespace --> 'emf-uml2'
INFO  [AndroMDA]   +  registering component 'metafacades'
INFO  [AndroMDA]   +  registering component 'profile'
INFO  [AndroMDA]   +  registering component 'repository'
INFO  [AndroMDA] found namespace --> 'hibernate'
INFO  [AndroMDA]   +  registering component 'cartridge'
INFO  [AndroMDA]   +  registering component 'metafacades'
INFO  [AndroMDA]   +  registering component 'profile'
INFO  [AndroMDA] found namespace --> 'java'
INFO  [AndroMDA]   +  registering component 'cartridge'
INFO  [AndroMDA]   +  registering component 'profile'
INFO  [AndroMDA] found namespace --> 'netBeansMDR'
INFO  [AndroMDA]   +  registering component 'repository'
INFO  [AndroMDA] found namespace --> 'query'
INFO  [AndroMDA]   +  registering component 'translation-library'
INFO  [AndroMDA] found namespace --> 'spring'
INFO  [AndroMDA]   +  registering component 'cartridge'
INFO  [AndroMDA]   +  registering component 'metafacades'
INFO  [AndroMDA]   +  registering component 'profile'
INFO  [AndroMDA] found namespace --> 'uml-1.4'
INFO  [AndroMDA]   +  registering component 'metafacades'
INFO  [AndroMDA]   +  registering component 'profile'
INFO  [AndroMDA] found namespace --> 'validation'
INFO  [AndroMDA]   +  registering component 'translation-library'
INFO  [AndroMDA] found namespace --> 'xmlschema'
INFO  [AndroMDA]   +  registering component 'cartridge'
INFO  [AndroMDA]   +  registering component 'metafacades'
INFO  [AndroMDA]   +  registering component 'profile'
INFO  [AndroMDA] - core initialization complete: 6.312[s] -
INFO  [AndroMDA] loading model --> 'file:C:/Projects/!ProjectName/andromda/src/main/uml/UMLProjectName.uml2'
INFO  [AndroMDA] referenced model --> 'file:/C:/Projects/!ProjectName/andromda/src/main/uml/UMLProjectName.uml2'
INFO  [AndroMDA] referenced model --> 'file:/C:/Projects/!ProjectName/andromda/src/main/uml/org.andromda.profile.xml.profile.uml2'
INFO  [AndroMDA] referenced model --> 'file:/C:/Projects/!ProjectName/andromda/src/main/uml/org.andromda.profile.persistence.profile.uml2'
INFO  [AndroMDA] referenced model --> 'file:/C:/Projects/!ProjectName/andromda/src/main/uml/UML_Standard_Profile.MagicDraw_Profile.profile.uml2'
INFO  [AndroMDA] referenced model --> 'file:/C:/Projects/!ProjectName/andromda/src/main/uml/FuGE.ProfilesAndConstraints.profile.uml2'
INFO  [AndroMDA] referenced model --> 'file:/C:/Projects/!ProjectName/andromda/src/main/uml/org.andromda.profile.common.profile.uml2'
INFO  [AndroMDA] referenced model --> 'jar:file:/C:/Documents and Settings/!YourUserName/.m2/repository/org/andromda/repositories/andromda-repository-emf-uml2/3.2/andromda-repository-emf-uml2-3.2.jar!/META-INF/emf/modules/UML2PrimitiveTypes.library.uml2'
INFO  [AndroMDA] referenced model --> 'jar:file:/C:/Documents and Settings/!YourUserName/.m2/repository/org/andromda/repositories/andromda-repository-emf-uml2/3.2/andromda-repository-emf-uml2-3.2.jar!/META-INF/emf/modules/Basic.profile.uml2'
INFO  [AndroMDA] referenced model --> 'file:/C:/Projects/!ProjectName/andromda/src/main/uml/UML_Standard_Profile.MagicDraw_Profile.DSL_Customization.profile.uml2'
INFO  [AndroMDA] referenced model --> 'file:/C:/Projects/!ProjectName/andromda/src/main/uml/org.andromda.profile.service.profile.uml2'
INFO  [AndroMDA] referenced model --> 'file:/C:/Projects/!ProjectName/andromda/src/main/uml/UML_Standard_Profile.UML_Standard_Profile.profile.uml2'
INFO  [AndroMDA] referenced model --> 'file:/C:/Projects/!ProjectName/andromda/src/main/uml/org.andromda.profile.meta.profile.uml2'
INFO  [AndroMDA] referenced model --> 'file:/C:/Projects/!ProjectName/andromda/src/main/uml/org.andromda.profile.presentation.profile.uml2'
INFO  [AndroMDA] referenced model --> 'file:/C:/Projects/!ProjectName/andromda/src/main/uml/UML_Standard_Profile.Validation_Profile.profile.uml2'
INFO  [AndroMDA] referenced model --> 'file:/C:/Projects/!ProjectName/andromda/src/main/uml/org.andromda.profile.process.profile.uml2'
INFO  [AndroMDA] referenced model --> 'file:/C:/Projects/!ProjectName/andromda/src/main/uml/org.andromda.profile.webservice.profile.uml2'
INFO  [AndroMDA] referenced model --> 'jar:file:/C:/Documents and Settings/!YourUserName/.m2/repository/org/andromda/repositories/andromda-repository-emf-uml2/3.2/andromda-repository-emf-uml2-3.2.jar!/META-INF/emf/modules/UML2.metamodel.uml2'
INFO  [AndroMDA] referenced model --> 'jar:file:/C:/Documents and Settings/!YourUserName/.m2/repository/org/andromda/repositories/andromda-repository-emf-uml2/3.2/andromda-repository-emf-uml2-3.2.jar!/META-INF/emf/modules/Ecore.profile.uml2'
INFO  [AndroMDA] referenced model --> 'jar:file:/C:/Documents and Settings/!YourUserName/.m2/repository/org/andromda/repositories/andromda-repository-emf-uml2/3.2/andromda-repository-emf-uml2-3.2.jar!/META-INF/emf/modules/Complete.profile.uml2'
INFO  [AndroMDA] - loading complete: 3.906[s] -
INFO  [AndroMDA] - validating model -
INFO  [AndroMDA] - validation complete: 11.25[s] -
INFO  [AndroMDA:xmlschema] Output: 'file:/C:/Projects/!ProjectName/andromda/target/xmlSchema.xsd'
INFO  [AndroMDA] completed model processing --> TIME: 15.766[s], RESOURCES WRITTEN: 1
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 28 seconds
[INFO] Finished at: Mon Feb 11 11:11:47 EST 2008
[INFO] Final Memory: 21M/42M
[INFO] ------------------------------------------------------------------------