Guidelines on how to derive XML schemas from FuGE-based UML2 models
Applicable also as formal validation of FuGE-based UML2 models
Authors
- Created by Josef Spidlen, January 24, 2007
- Based on initial investigation by Settimo Szliske and Andy Jones as well as on several AndroMDA and Maven discussion fora
- Update by Olga Tchuvatkina, May 17, 2007
- Update by Josef Spidlen, June 4, 2007 , based on comments by Allyson Lister and Andy Jones
Requirements
Java 1.5 (JDK 5.0) or newer required; Java SE Development Kit recommended
Maven2 (tested with Maven 2.0.4)
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.
Step by Step
- Directly applicable on MS Windows based platforms; modifications required for other platforms. *
Replace jspidlen by your login/profile name in all the paths below. It is highly recommended to use the suggested values.
1. Install Java
You 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.4-bin.zip file)
Unzip the file to the directory you wish to install Maven2; (e.g., C:\apps\maven-2.0.4)
Create an empty folder: C:\Documents and Settings\jspidlen\.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.4
M2_REPO
C:\Documents and Settings\jspidlen\.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. Install AndroMDA Application plugin
Next we will download and install the AndroMDA Application plugin into your Maven repository. This plugin allows creation of Java starter applications that use AndroMDA. This is the only AndroMDA artifact that we will install explicitly. All other artifacts, such as AndroMDA cartridges, will be automatically downloaded by the Maven scripts generated by the plugin. Install the plugin by following the steps below.
Download the the AndroMDA plugin installer: http://team.andromda.org/maven2/org/andromda/maven/plugins/andromdapp-maven-plugin/3.2/andromdapp-maven-plugin-install-3.2.zip
Unzip the contents of the installer into your Maven repository at C:\Documents and Settings\your user name\.m2\repository .
Verify that the following directory was created: C:\Documents and Settings\your user name\.m2\repository\org\andromda\maven\plugins\andromda-maven-plugin
Create a temporary directory, e.g. C:\andromda-temp .
- Create a file called pom.xml in this directory with the following content.
<project> <modelVersion>4.0.0</modelVersion> <groupId>samples.test</groupId> <artifactId>test</artifactId> <version>1.0</version> <packaging>jar</packaging> <name>test</name> <build> <defaultGoal>compile</defaultGoal> <plugins> <plugin> <groupId>org.andromda.maven.plugins</groupId> <artifactId>andromdapp-maven-plugin</artifactId> <version>3.2</version> </plugin> </plugins> </build> <repositories> <repository> <id>andromda</id> <name>AndroMDA Repository</name> <url>http://team.andromda.org/maven2</url> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>andromda</id> <name>AndroMDA Repository</name> <url>http://team.andromda.org/maven2</url> </pluginRepository> </pluginRepositories> </project> Open a Command Prompt in the directory where you created this pom.xml and run the command mvn without any arguments. Make sure the command completes successfully by displaying the BUILD SUCCESSFUL message.
- You can now delete the temporary directory you created
6. Create Conversion Project (Maven2 Application)
From the command line, create the C:\apps\FugeFlow directory and change to there.
Run mvn org.andromda.maven.plugins:andromdapp-maven-plugin:3.2:generate
- Answer the questions as follows:
Question
Answer
Comment
Please choose the type of application to generate.
j2ee
Please enter the location in which your new application will be created.
C:/apps/FugeFlow
Note the “/” instead of “\”.
Please enter your first and last name.
Josef Spidlen
Enter your name
Which kind of modeling tool will you use?
uml2
Important
Please enter the name of your J2EE project.
FugeFlow
Please enter an id for your J2EE project.
fugeflow
Please enter a version for your project.
0.1
or other
Please enter the root package name for your J2EE project .
org.flowcyt.fugeflow
Would you like an EAR or standalone WAR?
ear
ear is JBoss; war is Tomcat
Please enter the type of transactional/persistence cartridge to use.
spring
We may try others later?
Please enter the database backend for the persistence layer.
mysql
We may try others later?
Will your project need workflow engine capabilities?
no
Please enter the hibernate version number.
3
Will your project have a web user interface?
yes
Would you like your web user interface to use JSF or Struts?
struts
Would you like to be able to expose your services as web services?
no
You should get the BUILD SUCCESSFUL message.
7. Create XML Schema Cartridge Template
Create manually the following directory: C:\apps\FuGEFlow\fugeflow\mda\src\cartridge\custom\templates\xmlschema
Save the following XmlSchema.vsl file into the directory specified above.
We will customize this template in the future. Alternatively, you may use the Milestone 3 UML2 Release cartridge file downloaded from FuGE (rename to XmlSchema.vsl).
The default VSL template file creates a single XML schema (XSD file) mixing core FuGE with custom extensions. In order to keep these separate: First, generate the FuGE core XML schema separate; use non-extended FuGE model for this process. Note the name (path) of the created XSD file (e.g., name it as FuGE-v1-Nov-candidate.xsd). Also, note the FuGE namespace (e.g., http://fuge.sourceforge.net/). You can also obtain FuGE xml schema from FuGE developers instead of generating it yourself.
Second, create a custom template (XmlSchema.vsl file) that would import FuGE core XML schema (instead of including it into a single XML schema file). Also, place your extension into a separate XML namespace. For example, for flow cytometry, you can change the target namespace as targetNamespace="http://flowcyt.sf.net/fugeflow/v0.1/", add the fcm namespace as xmlns:fcm="http://flowcyt.sf.net/fugeflow/v0.1/" and import FuGE XML schema as <import namespace="http://fuge.sourceforge.net/" schemaLocation="../../FuGE-v1-Nov-candidate.xsd" />. Mentioned changes are demonstrated in the following XmlSchema.vsl file.
- Third, modifications are also required in the AndroMDA configuration file (i.e., switching on/off what part of the model gets into the XML schema). See tips attached to step 10 for further details.
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; the Community Edition it may be downloaded and used for free.
FuGE Milestone 3 UML2 Release compliant model is needed to start the modeling. Either the example model directly from FuGE or a flow cytometry model from this Wiki may be used. FuGE must be extended according their guidelines, i.e., proper use of stereotypes, named relations, multiplicities, etc.
- All the references from the model shall be set to andromda-3.2-SNAPSHOT profiles for UML2, i.e., files
andromda-profile-3.2-SNAPSHOT.xml.zip,
andromda-profile-datatype-3.2-SNAPSHOT.xml.zip,
andromda-profile-meta-3.2-SNAPSHOT.xml.zip,
andromda-profile-persistence-3.2-SNAPSHOT.xml.zip,
andromda-profile-presentation-3.2-SNAPSHOT.xml.zip,
andromda-profile-process-3.2-SNAPSHOT.xml.zip,
andromda-profile-service-3.2-SNAPSHOT.xml.zip,
andromda-profile-webservice-3.2-SNAPSHOT.xml.zip, and
andromda-profile-xml-3.2-SNAPSHOT.xml.zip.
Flowcyt subversion, from the
FuGE example archive file, or find the relevant zip files at
Add Maven2 repository into MagicDraw path variable. In MagicDraw go to Options, Environment, Path Variables and add:
Name
Value
Comment
maven2.repository
C:\Documents and Settings\jspidlen\.m2\repository
Maven2 Repository.
Export the extended model as EMF UML2 (v1.x) XMI and store the export in C:\apps\FuGEFlow\fugeflow\mda\src\main\uml . The export creates several files in the uml directory.
9. Update the Project Description File
Edit the following file: C:\apps\FuGEFlow\fugeflow\mda\pom.xml
- Add the following dependency:
<dependency> <groupId>org.andromda.cartridges</groupId> <artifactId>andromda-xmlschema-cartridge</artifactId> <version>${andromda.version}</version> </dependency> And include the following project properties: (FuGEFlow is the name of your MagicDraw project. FuGEFlow.uml2 should be located in C:\apps\FuGEFlow\fugeflow\mda\src\main\uml)
<properties> ... <model.uri>file:${project.build.sourceDirectory}/FuGEFlow.uml2</model.uri> <andromda.version>3.2-SNAPSHOT</andromda.version> ... </properties>
Replace FuGEFlow.uml2 with actual name of uml2 model. If you use FuGE Milestone 3 UML2 Release, the correct name is FuGE-M3-profile.uml2
10. Update the AndroMDA Configuration File
Edit the following file: C:\apps\FuGEFlow\fugeflow\mda\src\main\config\andromda.xml
- Update the model description: (XML fragment included with its content)
FlowCytometry is the name of the top level package with the UML2 model. <repositories> <repository name="emf-uml2"> <models> <model type="emf-uml2"> <uri>${model.uri}</uri> <moduleSearchLocations> <location patterns="**/*.uml2">${project.build.sourceDirectory}/md11test/emf/</location> <location patterns="*.uml2">${project.build.sourceDirectory}/</location> </moduleSearchLocations> <modelPackages processAll="true"> <modelPackage process="true">FuGE::**</modelPackage> <modelPackage process="true">FlowCytometry::**</modelPackage> </modelPackages> </model> </models> </repository> </repositories>
If you use original FuGE model (not extended) keep only FuGE::** model package (remove <modelPackage process="true">FlowCytometry::**</modelPackage> from the list of model packages)
If you have separate XML schemas for FuGE core model and for your extension (see tips attached to step 7), you may want to use the false settings for the processAll and for the processing of the FuGE package: <modelPackages processAll="false"> <modelPackage process="false">FuGE::**</modelPackage> <modelPackage process="true">FlowCytometry::**</modelPackage> </modelPackages>Delete (comment out) namespaces spring , hibernate , java , and bpm4struts (i.e., all but the default one).
Add namespace xmlschema as follows:
<namespace name="xmlschema"> <properties> <property name="overwrite">true</property> <property name="languageMappingsUri">file:${conf.dir}/mappings/XMLSchemaMappings.xml</property> <property name="mergeLocation">${pom.basedir}/src/cartridge/custom</property> <property name="wrapperMappingsUri">JavaWrapper</property> <property name="schema">${web.generated.dir}</property> <property name="namespace">fugeflow.flowcyt.org</property> </properties> </namespace>Alternatively, review the AndroMDA Configuration File that worked for me.
11. Specify XML Schema Data Type Mappings
Save the following XmlSchemaMappings.xml file as C:\apps\FuGEFlow\fugeflow\mda\src\main\config\mappings\XmlSchemaMappings.xml
12. Download All Required Components
From your command line: change to C:\apps\FuGEFlow\fugeflow\mda .
Run mvn .
Alternativelly, run mvn andromda:run -Dfilter=xmlschema (the XML schema only).
You may use the –e switch for details about potential problems/errors. This step should generate an empty XSD schema at C:\apps\FuGEFlow\fugeflow\web\target\src\xmlSchema.xsd . (The XSD file should basically contain the XML header only.)
- This step is used to download all required modules and plugins; not to generate the schema itself.
13. Fix Facade Mappings
Extract the metafacades.xml file from andromda-xmlschema-cartridge-3.2-SNAPSHOT.jar , i.e., change to
C:\Documents and Settings\jspidlen\.m2\repository\org\andromda\cartridges\andromda-xmlschema-cartridge\3.2-SNAPSHOT and run
jar xf andromda-xmlschema-cartridge-3.2-SNAPSHOT.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> Store the updated metafacades.xml file in the andromda-xmlschema-cartridge-3.2-SNAPSHOT.jar , i.e., change to
C:\Documents and Settings\jspidlen\.m2\repository\org\andromda\cartridges\andromda-xmlschema-cartridge\3.2-SNAPSHOT and run
jar uf andromda-xmlschema-cartridge-3.2-SNAPSHOT.jar META-INF/andromda/metafacades.xml
Fix based on AndroMDA forum.
14. Generate the XML Schema
From your command line: change to C:\apps\FuGEFlow\fugeflow\mda .
Run mvn -o .
Alternativelly, run mvn -o andromda:run -Dfilter=xmlschema (the XML schema only).
The -o switch sets the offline mode, which prevents new versions of plugins being downloaded, i.e., the "update" performed in previous step does not get overwritten.
You may use the –e switch for details about potential problems/errors. This step should generate the resulting XML Schema at C:\apps\FuGEFlow\fugeflow\web\target\src\xmlSchema.xsd .
15. The UML Model Validation
- The UML model gets validated automatically while generating the XML schema; you should see an output log similar to this:
C:\apps\FuGEFlow\fugeflow\mda>mvn andromda:run -Dfilter=xmlschema -e -o + Error stacktraces are turned on. [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] ---------------------------------------------------------------------------- [INFO] Building FuGEFlow MDA [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: 4.406[s] - INFO [AndroMDA] loading model --> 'file:C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/fugeflow.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/fugeflow.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/org.andromda.profile.xml.profile.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/org.andromda.profile.persistence.profile.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/UML_Standard_Profile.profile.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/UML_Standard_Profile.MagicDraw_Profile.profile.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/ProfilesAndConstraints.profile.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/org.andromda.profile.common.profile.uml2' INFO [AndroMDA] referenced model --> 'jar:file:/C:/Documents and Settings/jspidlen/.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/jspidlen/.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:/apps/FuGEFlow/fugeflow/mda/src/main/uml/UML_Standard_Profile.MagicDraw_Profile.DSL_Customization.profile.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/org.andromda.profile.service.profile.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/UML_Standard_Profile.UML_Standard_Profile.profile.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/UML_Standard_Profile.Validation_Profile.profile.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/org.andromda.profile.presentation.profile.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/org.andromda.profile.profile.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/org.andromda.profile.meta.profile.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/org.andromda.profile.webservice.profile.uml2' INFO [AndroMDA] referenced model --> 'file:/C:/apps/FuGEFlow/fugeflow/mda/src/main/uml/org.andromda.profile.process.profile.uml2' INFO [AndroMDA] referenced model --> 'jar:file:/C:/Documents and Settings/jspidlen/.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/jspidlen/.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/jspidlen/.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.063[s] - INFO [AndroMDA] - validating model - INFO [AndroMDA] - validation complete: 11.72[s] - INFO [AndroMDA:xmlschema] Output: 'file:/C:/apps/FuGEFlow/fugeflow/mda/../web/target/src/xmlSchema.xsd' INFO [AndroMDA] completed model processing --> TIME: 18.955[s], RESOURCES WRITTEN: 1 [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ [INFO] Total time: 28 seconds [INFO] Finished at: Tue Jan 23 15:59:06 PST 2007 [INFO] Final Memory: 24M/44M [INFO] ------------------------------------------------------------------------
