Create a package oaw4.demo.classic.uml.meta. This package will contain our metaclasses which realize the UML profile we want to use. As you can see from the model above we use the Stereotypes Entity, Key and DAO. For these Stereotypes we need metaclasses.

Metaclasses are derived from UML metaclasses. oAW4 provides implementation classes for UML metaclasses. For example an Entity is represented by classes, so the right metaclass to extend is Class, while Keys are a specialization from Attribute.

In the simplest case you will only have to create the classes Entity, Key and DAO and derive them from the base metaclasses Class and Attribute defined in package org.openarchitecture.meta.uml.classifier:

package oaw4.demo.classic.uml.meta;

public class Entity extends org.openarchitectureware.meta.uml.classifier.Class {
   // nothing to do in the simplest case
}

package oaw4.demo.classic.uml.meta;

public class Key extends org.openarchitectureware.meta.uml.classifier.Attribute {
}

package oaw4.demo.classic.uml.meta;

public class DAO extends org.openarchitectureware.meta.uml.classifier.Class {
}

By now the generator will not know that the stereotype <<Entity>> has to be mapped to the metaclass oaw4.demo.classic.uml.meta.Entity. By default these elements are mapped to their UML base classes, in case of Entity this is Class.

To map stereotypes to metaclasses a xml file has to be created, called the metamapping file.

Create the file metamappings.xml in your source folder:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE MetaMap SYSTEM "http://www.openarchitectureware.org/dtds/metamap.dtd">

<MetaMap>
   <Mapping>
      <Map>Entity</Map>
      <To>oaw4.demo.classic.uml.meta.Entity</To>
   </Mapping>
   <Mapping>
      <Map>DAO</Map>
      <To>oaw4.demo.classic.uml.meta.DAO</To>
   </Mapping>
   <Mapping>
      <Map>Key</Map>
      <To>oaw4.demo.classic.uml.meta.Key</To>
   </Mapping>
</MetaMap>

The next step is to create a workflow script. The workflow has to accomplish the following tasks:

For all these tasks pre-defined workflow-scripts and components can be included in the workflow. The following workflow script does all these tasks and should fit for the first steps. Later on you may need to customize the workflow script to integrate further components like model modifiers. Therefore the script itself is not bundled as a cartridge.

<?xml version="1.0" encoding="UTF-8"?>
<workflow>
   <property file="workflow.properties"/>

   <cartridge file="org/openarchitectureware/workflow/oawclassic/classicstart.oaw">
      <metaEnvironmentSlot value="me"/>
      <instantiatorEnvironmentSlot value="ie"/>
   </cartridge>

   <component class="org.openarchitectureware.core.frontends.xmi.workflow.XMIInstantiator">
      <instantiatorEnvironmentSlot value="ie"/>
      <modelFile value="${model.xmi}"/>
      <xmlMapFile value="${toolMappingFile}"/>
      <metaMapFile value="${metaMapFile}"/>
      <toolAdapterClassname value="${toolAdapterClassname}"/>
      <moduleFile value="${moduleFile}"/>
   </component>
    
   <cartridge file="org/openarchitectureware/workflow/oawclassic/classicinit.oaw">
      <metaEnvironmentSlot value="me"/>
   </cartridge>

   <component id="dirCleaner"
      class="org.openarchitectureware.workflow.common.DirectoryCleaner">
      <directories value="${srcGenPath}"/>
   </component>

   <component id="generator" class="org.openarchitectureware.xpand2.Generator">
      <metaModel class="org.openarchitectureware.type.impl.java.JavaMetaModel">
         <typeStrategy 
            class="org.openarchitectureware.type.impl.oawclassic.OAWClassicStrategy" 
            convertPropertiesToLowerCase="false"/>
      </metaModel>
      <expand value="Root::Root FOREACH me.getElements('Model')"/>
      <genPath value="${srcGenPath}/"/>
      <srcPath value="${srcGenPath}/"/>
      <beautifier class="org.openarchitectureware.xpand2.output.JavaBeautifier"/>
      <beautifier class="org.openarchitectureware.xpand2.output.XmlBeautifier"/>
      <fileEncoding value="ISO-8859-1"/>
   </component>

   <cartridge file="org/openarchitectureware/workflow/oawclassic/classicfinish.oaw">
      <instantiatorEnvironmentSlot value="ie"/>
      <dumpfile value="${dumpfile}"/>
   </cartridge>

</workflow>

The workflow includes a properties file in which the concrete configuration is stored. Create the file workflow.properties like this:

# Note: all paths must be found in the classpath! 
# the metamappings file
metaMapFile = metamappings.xml

# model.xmi: name of the XMI export
# toolMappingFile: tool mapping file to use
# toolAdapterClassname: tool adapter implementation
# moduleFile: profile files

# MagicDraw 10
model.xmi = AuthorBookExampleMD10.mdzip
toolMappingFile = magicdraw_xmi21_all.xml
toolAdapterClassname = 
   org.openarchitectureware.core.frontends.xmi.toolsupport.uml.magicdraw.MagicDrawAdapter21
moduleFile = 
   magicdraw/md10/UML_Standard_Profile.xml

#model.xmi = AuthorBookExampleMD11.mdzip
#toolMappingFile = magicdraw_xmi21_all.xml
#toolAdapterClassname = 
   org.openarchitectureware.core.frontends.xmi.toolsupport.uml.magicdraw.MagicDrawAdapter21
#moduleFile = magicdraw/md11/UML_Standard_Profile.xml

# path to create the generated output to 
srcGenPath = src-gen
# path where the dump file is created
dumpfile = bin/dump

toolAdapterClassname = 
   org.openarchitectureware.core.frontends.xmi.toolsupport.uml.poseidon.PoseidonAdapter
toolMappingFile = poseidon40_xmi12_all.xml

In the workflow the generator has been configured to start with the this definition:

<expand value="Root::Root FOREACH me.getElements('Model')"/>

This means that the generator will look for a template file Root.xpt in the classpath where a definition named Root is found for all elements that are selected by the expression me.getElements('Model'). In case of UML models there exists solely one element of type Model that will be selected.

Now create the file Root.xpt in the templates folder. Remember: We have configured our Eclipse project that the folder templates is a classpath folder. You will see that the new file is recognized as an oAW template file, as it has a template file icon:

For the beginning the template will be simple:

«IMPORT org::openarchitectureware::core::meta::core»

«DEFINE Root FOR Model»
«ENDDEFINE»

This template contains only an empty definition for Model elements. The namespace of the Model metaclass must be known for the generator, so we import the corresponding package. Otherwise we would have to fully qualify Model. As you could expect this template does not really do anything yet.

At this time your project structure should look like this:

For our example we want to use extensions to introduce some naming conventions for instance variables, parameters and the computation of the package and path for classes.

Now create a file NamingConventions.ext in the templates/java folder. In this extension we declare some functions that are helpful for name conversions ^[10]:

import org::openarchitectureware::meta::uml;
import org::openarchitectureware::meta::uml::classifier;

String asParameter (ModelElement elem) :
   "p"+elem.NameS.toFirstUpper();

String asSetter (ModelElement elem) :
   "set"+elem.NameS.toFirstUpper();

String asGetter (ModelElement elem) :
   "get"+elem.NameS.toFirstUpper();

String asInstanceVar (ModelElement elem) :
   elem.NameS.toFirstLower();

In extension files import statements for used types are necessary, too. The function declarations are single-lined and can use any expressions, calls of other extension functions included.

Open Attribute.xpt and make use of these functions. In template files the usage of extensions must be declared by the «EXTENSION» keyword. The modified template file will be this:

«IMPORT org::openarchitectureware::meta::uml::classifier»
«EXTENSION java::NamingConventions»

«DEFINE PropertyDeclaration FOR Attribute»
   private «Type.NameS» «asInstanceVar()»;
«ENDDEFINE»

«DEFINE Getter FOR Attribute»
   public «Type.NameS» «asGetter()» () {
      return this.«asInstanceVar()»;
   }
«ENDDEFINE»

«DEFINE Setter FOR Attribute»
public void «asSetter()» («Type.NameS» «asParameter()») {
	this.«asInstanceVar()» = «asParameter()»;
}
«ENDDEFINE»

Run the generator and open Author.java. The file looks almost the same, since the replacements for instance variables, getter and setter method names are equivalent. The only difference are the parameters for setter methods. They are now prefixed with the character p.

public void setId(String pId) {
   this.id = pId;
}

More complex computations are often easier and more understandable by means of the Java programming language. So the Xtend language allows to define functions by referencing a Java function. The methods that should be called must be declared public static.

In our example we miss the declaration of packages, and files are written in the root directory. We now want to declare some functions that help us to compute the full package name of classes, their corresponding path and the fully qualified name.

Create a new package oaw4.demo.classic.uml.extend and a class ClassUtil. In this class we define a function getPackageName() that computes the full package of a Class (remember that we operate on the metamodel's class named (org.openarchitectureware.meta.uml.classifier.)Class, not java.lang.Class).

package oaw4.demo.classic.uml.extend;

import org.openarchitectureware.meta.uml.classifier.Class;
import org.openarchitectureware.meta.uml.classifier.Package;

public class ClassUtil {
   public static String getPackageName (Class cls) {
      String result = "";
      for (Package pck=cls.Package(); pck!=null; pck=pck.SuperPackage()) {
         result = pck.NameS() + (result.length()>0 ? "."+result : "");
      }
      return result;
   }
}

We declare this function in NamingConventions.ext and two more functions that use it. Add these function declarations:

String packageName (Class cls) : 
   JAVA oaw4.demo.classic.uml.extend.ClassUtil
   .getPackageName(org.openarchitectureware.meta.uml.classifier.Class);

String packagePath (Class cls) : 
   packageName(cls).replaceAll("\\.", "/");

String fqn (Class cls) : 
   packageName(cls).length>0 ? packageName(cls)+"."+cls.NameS : cls.NameS;

The additional functions are used to compute the path to files based on a class and to get the full qualified name of a class. We want to make use of these functions to declare the package, compute the desired file path and to extend from the super class, if a class has one (in our example model this is not the case yet). If no super class exists, the Bean class should declare to implement the Serializable interface.

Open the JavaBean.xpt template file and modify it like follows:

«IMPORT org::openarchitectureware::meta::uml::classifier»
«IMPORT java»
«EXTENSION java::NamingConventions»

«DEFINE BeanClass FOR Class»
«FILE packagePath()+"/"+NameS+".java"»
package «packageName()»;
public class «Name»
   «IF hasSuperClass»extends «SuperClass.fqn()» «ENDIF»
   implements java.io.Serializable {

...

Once again run the generator and refresh your src-gen folder. Now the classes are generated in the expected directory structure:

The generated classes now contain the correct package statement:

package oaw4.demo.classic.uml.entity;

public class Author implements java.io.Serializable {
   ...

The extensions for functions used for associations are put into a seperate file. Create the file templates/java/Associations.ext with this content:

import org::openarchitectureware::meta::uml::classifier;
extension java::NamingConventions;

String fqn (AssociationEnd ae) : 
   !ae.isMultiple ? ae.Class.fqn() : "java.util.Collection<"+ae.Class.fqn()+">";

String iterator (AssociationEnd ae) : "java.util.Iterator<"+ae.Class.fqn()+">";

As you can see we will create Java 5 style collections for to-many associations. If you don't want to use generics you could easily replace or modify the extension file and all associations will change to your style.

We see in this extension file that other extensions can be referenced using the extension keyword. In this case we need the function fqn() that was defined for classes. For associations another function fqn() is defined, but now for AssociationEnds. For to-one associations the fully qualified name of the associated class is returned, for to-many references a generic collection for that class. In the template code classes and association ends will both use the fqn() function to print out the referenced type.

Now it is time to write the template for associations. Create the file Association.xpt. Now fill in the content, we will explain some statements right after.

«IMPORT org::openarchitectureware::meta::uml::classifier»
«EXTENSION java::NamingConventions»
«EXTENSION java::Associations»

«DEFINE ReferenceVariables FOR Class»
   «FOREACH AssociationEnd.Opposite.select(ae|ae.isNavigable) AS ae»
      private «ae.fqn()» «ae.asInstanceVar()»;
   «ENDFOREACH»	
«ENDDEFINE»

«DEFINE AccessorMethods FOR Class»
   «EXPAND ToOneAccessorMethods FOREACH 
      AssociationEnd.Opposite.select(ae|!ae.isMultiple && ae.isNavigable)»
   «EXPAND ToManyAccessorMethods FOREACH 
      AssociationEnd.Opposite.select(ae|ae.isMultiple && ae.isNavigable)»
«ENDDEFINE»

«DEFINE ToOneAccessorMethods FOR AssociationEnd»
   public void «asSetter()» («Class.fqn()» «asParameter()») {
      this.«asInstanceVar()» = «asParameter()»;
   }

   public «Class.fqn()» «asGetter()» () {
      return this.«asInstanceVar()»;
   }
«ENDDEFINE»

«DEFINE ToManyAccessorMethods FOR AssociationEnd»
   public void add«NameS.toFirstUpper()» («Class.fqn()» «asParameter()») {
      this.«asInstanceVar()».add(«asParameter()»);
   }

   public void remove«NameS.toFirstUpper()» («Class.fqn()» «asParameter()») {
      this.«asInstanceVar()».remove(«asParameter()»);
   }

   public «iterator()» «asGetter()» () {
      return this.«asInstanceVar()».iterator();
   }
«ENDDEFINE»

At first we see that this template uses both extensions, NamingConventions and Associations.

Next, a template ReferenceVariables is declared. The template makes use of a FOREACH loop of a different kind than we saw before. One more specific thing here is the statement

«FOREACH AssociationEnd.Opposite.select(ae|ae.isNavigable) ...

This returns all navigable opposite end of each association end a class has.

The body of the loop declares a reference variable for an association. For both alternatives (to-one and to-many) the function fqn() (the one defined for association ends) is called to determine the right type. In our example this should result in the following both declarations:

// to-one association (Copy.java)
private oaw4.demo.classic.uml.entity.Library owner;

// to-many association (Author.java)
private java.util.Collection<oaw4.demo.classic.uml.entity.Book> writtenBook;

Both types are now expressed by this statement – simple, isn't it?

private «ae.fqn()» «ae.asInstanceVar()»;

The next template definition is also interesting. The definition AccessorMethods FOR Class dispatches to the definitions ToOneAccessorMethods or ToManyAccessorMethods, depending on the cardinality of the association. To distinguish both types we make use of the select expression which is defined for expression. The statement

«EXPAND ToOneAccessorMethods FOREACH 
   AssociationEnd.Opposite.select(ae|!ae.isMultiple && ae.isNavigable)»

means that the definition ToOneAccessorMethods should be expanded for each opposite association end which is not to-many and navigable. So for unnavigable associations no accessor method will be created.

The definitions for the accessor methods have nothing new, so we do not explain them in detail now.

Now we want to use the new templates from the JavaBeans template so that the classes get instance variables for referenced classes and appropriate accessor methods. Modify the template file JavaBeans.xpt by adding these two statements to the class definition:

public class «Name» «IF hasSuperClass»extends «SuperClass.fqn()» «ENDIF»{
   «EXPAND Attribute::PropertyDeclaration FOREACH Attribute»
   «EXPAND Attribute::Getter FOREACH Attribute»
   «EXPAND Attribute::Setter FOREACH Attribute»
   «EXPAND Association::ReferenceVariables»
   «EXPAND Association::AccessorMethods»
}

Run the generator again. After successful generation open Book.java. This file should have the following contents:

package oaw4.demo.classic.uml.entity;

public class Book implements java.io.Serializable {
   private String isbn;
   private String title;
   private java.util.Collection<oaw4.demo.classic.uml.entity.Author> author;

   public String getIsbn () {
      return this.isbn;
   }

   public String getTitle () {
      return this.title;
   }

   public void setIsbn (String pIsbn) {
      this.isbn = pIsbn;
   }

   public void setTitle (String pTitle) {
      this.title = pTitle;
   }

   public void addAuthor (oaw4.demo.classic.uml.entity.Author pAuthor) {
      this.author.add(pAuthor);
   }

   public void removeAuthor (oaw4.demo.classic.uml.entity.Author pAuthor) {
      this.author.remove(pAuthor);
   }

   public java.util.Iterator<oaw4.demo.classic.uml.entity.Author> getAuthor () {
      return this.author.iterator();
   }
}

In this file we have a to-many association named author to entity Author. No code exists for the association to the Copy class, since this association is not navigable.

An example for to-one associations can be seen in the Copy class:

public class Copy implements java.io.Serializable {
   ...
   private oaw4.demo.classic.uml.entity.Library owner;
   ...
   public void setOwner (oaw4.demo.classic.uml.entity.Library pOwner) {
      this.owner = pOwner;
   }

   public oaw4.demo.classic.uml.entity.Library getOwner () {
      return this.owner;
   }
   ...
}

The template code is really small, but now you could only have to model classes and their associations and you get the right JavaBeans code from the model. Our JavaBeans template is not specifix for entities, you could use it to generate JavaBeans code for just any modelled class. But we only call this template for classes stereotyped with <<Entity>> for now. You remember that the model contains another class <<DAO>> LibraryDAO for which no code is generated yet.

Constraints can be provided in three different ways:

We want to implement constraint checks by using the Check language. The syntax for check files is similar to those for Extensions, as it uses also the oAW Expressions framework. Check files have the file extension .chk and must be found on the classpath.

In our example we want to implement the following constraint:

Constraint 1 must be fulfilled, otherwise an error message should be printed and the generation process should not be started. If constraint 2 is not fulfilled a warn message should be printed, but the generation process should not be stopped.

As the constraints that should be implemented are specific for associations the check file should be named AssociationChecks.chk. Create this file in templates/java.

import org::openarchitectureware::meta::uml::classifier;

context AssociationEnd ERROR Class.NameS+"->"+Opposite.Class.NameS+": 
   Navigable association ends must have a role name" :
   isNavigable ? !isUnnamed : true;
	
context AssociationEnd WARNING Class.NameS+"->"+Opposite.Class.NameS+": 
   Not navigable association ends should have no role name":
   isNavigable ? true : isUnnamed;

The syntax is rather simple. Both constraints should be checked for the metaclass AssociationEnd, so the appropriate namespace has to be imported. The expression following the colon is the constraint. If it is not fulfilled the message is printed. When error messages are printed the workflow will be interrupted.

To execute the constraint checks the generator workflow has to be extended. The constraint check is configured by a workflow component CheckComponent. Insert this code into workflow.oaw right between the cartridge classicinit.oaw and the dirCleaner component.

<component class="org.openarchitectureware.check.CheckComponent">
   <metaModel class="org.openarchitectureware.type.impl.java.JavaMetaModel">
   	<typeStrategy class="org.openarchitectureware.type.impl.oawclassic.OAWClassicStrategy" 
   		convertPropertiesToLowerCase="false"/>
   </metaModel>
   <checkFile value="java::AssociationChecks"/>
   <expression value="me.getElements('ModelElement')"/>
   <abortOnError value="true"/>
</component>

Also the constraint checker has to know which metamodel it should use. It is the same configuration as for the Generator component ^[11].

The checkFile property specifies the qualified name of the check file.

Finally, the expression property defines for which elements to constraints should be applied. In our case we select all elements in the MetaEnvironment. However, for our special case it would be satisfactory to select only all elements of type AssociationEnd. For larger projects it could be of advantage to select the right subset of elements for improving performance.

Start the generator. The generator should run without complaining, because all constraints are fulfilled in the example model for now.

Now open the model; we will change the model in a way that both constraints are not fulfilled.

First, edit the association between Book and Author. Take the association end named author and remove the name. Set the navigable flag to false for the opposite end named writtenBooks.

Save the model and re-run the generator. The generator now produces the expected messages and stops execution, because there is one constraint error and one warning.

4316 INFO  Starting: org.openarchitectureware.check.CheckComponent
4667 ERROR Workflow interrupted. Reason: Errors during validation.
4667 WARN  Book->Author: Not navigable association ends should have no role 
           name [<<AssociationEnd>> writtenBook] 
4667 ERROR Author->Book: Navigable association ends must have a role name [<<AssociationEnd>> ]