XSD Tutorial

Setup
Overview
Step 1: Create a Project
Step 2: Define a Meta Model using XML Schema
Step 3: Create a Model using XML
Step 4: Create a Template using Xpand
Step 5: Create a Workflow
Step 6: Execute Workflow aka Generate Code

This tutorial shows how XML and XML Schemas Definitions (XSD) can be used to generate software. It illustrates how XML files are treated as models, XSDs as meta models and how this integrates with oAW. This tutorial is an introduction, for in-depth details see XSD Adapter.

Setup

XSD support for oAW comes with oAW 4.3.1 or later. Make sure the following plugins are installed as well:

  • XSD - XML Schema Definition Runtime ( http://www.eclipse.org/xsd/, available via Ganymede Update Site)

  • Web Tools Platform (WTP) (WTP is not required to use oAW XSD support, but helpful, as its provides a nice XML Schema editor and a schema-aware XML editor. (http://www.eclipse.org/webtools/ , available via Ganymede Update Site)

Overview

This tutorial explains how you can do code generation with openArchitectureWare, using XML Schema Definitions as meta models and XML files as models. To keep things easy, the introduced example is a minimalistic one. A text file is generated from contents specified in XML. The general concept of models, meta models and why and when code generation is useful, is not explained. At the end, a deeper view under the hood is taken to understand how XML Schemas are transformed to EMF Ecore models, and which flexibilities/restrictions this approach provides.

All source files listed within this tutorial are also available as an example project wich can be imported into the Eclipse workspace by running "File" / "New" / "Example..." / "openArchitectureWare Examples using an XSD Meta Model" / "M2T custom XML to Text via Xpand (minimal Example)". This will create the project org.openarchitectureware.xsd.demo.m2t.minimal project in your workspace. This minimal example is based on "M2T custom XML to Java via Xpand" (org.openarchitectureware.xsd.demo.m2t.xml2javawizard) which is more comprehensive and recommended for further reading.

To generate code from XML files with oAW, at least files of the following four types are needed:

  • Meta Model ( metamodel.xsd )

  • Model ( model.xml )

  • oAW Xpand Template ( template.xpt )

  • oAW Workflow ( workflow.oaw )

Figure 63. Minimalistic oAW XSD Project

Minimalistic oAW XSD Project

Step 1: Create a Project

To create a Project, create an ordinary openArchitectureWare-Project. This is done in Eclipse by changing to the openArchitectureWare perspective and clicking on "File" / "New" / "openArchitectureWare Project". After entering a name for the project it is created.

After the project is created, support for XSD meta models needs to be activated. Click with your right mouse button on the project and open the properties window. Then go to the "openArchitectureWare" page, "enable project specific settings" and activate the "XSD Metamodels" checkbox. There is no need to leave support for any other meta models activated, except you are sure that you want to use one of them, too. Figure 64, “Activate XSD Meta Model Support for Project” shows how the configuration is supposed to look like.

Figure 64. Activate XSD Meta Model Support for Project

Activate XSD Meta Model Support for Project

Then, org.openarchitectureware.xsd needs to be added to the project's dependencies. To do so open the file META-INF/MANIFEST.MF from your project and navigate to the "Dependencies"-tab. org.openarchitectureware.xsd needs to be added to the list of "Required Plug-ins", as it is shown in Figure 65, “Required Dependencies for Project” .

Figure 65. Required Dependencies for Project

Required Dependencies for Project

Step 2: Define a Meta Model using XML Schema

In case you are not going to use an existing XML Schema Definition, you can create a new a new one like described below. These steps make use of the Eclipse Web Tools Platform (WTP) to have fancy editors.

In Eclipse, click on "File", "New", "Other..." and choose "XML Schema" from category "XML". Select the project's "src" folder and specify a filename. Clicking on "finish" creates an empty XSD file. It is important that the XSD file is located somewhere within the project's classpath.

This XML Schema consists of two complex data types, which contain some elements and attributes. "complex" in the XSD terminology means that as opposed to simple data types that they can actually have sub-elements and/or attributes. This example is too minimalistic to do anything useful.

The complex Type Wizard contains the elements startpage , name , welcometext , and choicepage . Except for choicepage all elements have to contain strings, whereas the string of startpage must be a valid id of any ChoicePage . The complex type ChoicePage just contains an id and a name . For oAW it does not make any difference if something is modeled as an XML-attribute or XML-element. Just the datafield's type defines how oAW treats the value.

To get an overview how schemas can be used by the oAW XSD Adapter, see the section called “How to declare XML Schemas”

Internally, the oAW XSD Adapter transforms the XSD model to an Ecore model which oAW can use like any other Ecore model. For more information about that, see the section called “Behind the scenes: Transforming XSD to Ecore”

Figure 66. WTP Schema Editor

WTP Schema Editor

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://www.example.org/wizard" 
  xmlns:tns="http://www.example.org/wizard"
  elementFormDefault="qualified">

  <complexType name="Wizard">
    <sequence>
      <element name="startpage" type="IDREF" />
      <element name="name" type="string" />
      <element name="welcometext" type="string" />
      <element name="choicepage" type="tns:ChoicePage" />
    </sequence>
  </complexType>

  <complexType name="ChoicePage">
    <sequence>
      <element name="title" type="string" />
    </sequence>
    <attribute name="id" type="ID" />
  </complexType>

  <element name="wizard" type="tns:Wizard" />
</schema>

Step 3: Create a Model using XML

As the title says, data in XML-Format will be the model. And as a model has to be valid according to a meta model, the XML files must be valid according to the XSD.

In case you are not going to use an existing XML file, you can create a new one like described below. These steps require the Eclipse Web Tools Platform (WTP) to be installed.

In Eclipse, click on "File", "New", "Other..." and choose "XML" from category "XML". After specifying a filename within folder "src" choose "create XML file from an XML Schema" and select you XML Schema Definition file. Telling Eclipse which schema to use has three advantages: Eclipse validates XML files, there is meta model aware code completion while editing and Eclipse creates a xsi:schemaLocation-attribute which tells anyone who reads the XML file where the schema file is located. This tutorial does not use the xsi:schemaLocation-attribute and introduces the schema file in the oAW workflow instead. For all possible ways see the section called “How to declare XML Schemas” . It is important that the XML file is located somewhere within the project's classpath.

<?xml version="1.0" encoding="UTF-8"?>
<wizard xmlns="http://www.example.org/wizard">
  <startpage>start</startpage>
  <name>My Example Setup</name>
  <welcometext>Welcome to this little demo application.</welcometext>
  <choicepage id="start">
    <title>Wizard Page One</title>
  </choicepage>
</wizard>

Step 4: Create a Template using Xpand

Create an ordinary oAW Xpand file: Being in the openArchitectureWare perspective, go to "File", "New", "xPand template". The Xpand language itself is explained by several other oAW documents. Having XSD meta model support activated like described in the section called “Step 1: Create a Project” , oAW scans and watches all it's projects for suitable meta models. Based on what is found, the Xpand editor provides meta model aware code completion.

This example imports "metamodel" at the beginning, which refers to a file called metamodel.xsd that you have created within the project's classpath in the section called “Step 2: Define a Meta Model using XML Schema” . The define-block can be understood as a function named "Root" which takes one object of type metamodel::Wizard as a parameter. This is the meta model's type for the XML's root object. The file-block creates a file named wizard.txt and writes the text that is surrounded by the file-block into the file. name , welcometext and choicepage.title are elements or attributes defined in the XSD meta model. Their values are stored within the XML file and this templates inserts them into the generated ( wizard.txt ) file.

«IMPORT metamodel»

«DEFINE Root FOR metamodel::Wizard»
«FILE "wizard.txt"»
Name: «name»
Welcometext: «welcometext»
First Page Title: «choicepage.title»
«ENDFILE»
«ENDDEFINE»

Step 5: Create a Workflow

The workflow ties together model, meta model and templates and defines the process of how to generate code.

To create a new workflow file, switch to the openArchitectureWare perspective, click on "File", "New" and "Workflow file". After specifying a folder and a filename an empty workflow is created.

The minimalistic approach consists of two steps:

  1. Read the Model: This is done by org.openarchitectureware.xsd.XMLReader . It needs exactly one uri element which defines the XML file. A further nested element of type org.openarchitectureware.xsd.XSDMetaModel tells the XMLReader which metamodel to use. XSDMetaModel can contain multiple schemaFile elements. How the schemas are used for the XML file is determined based on the declared namespaces. modelSlot defines a location where the model is stored internally, this is like a variable name which becomes important if you want to handle multiple models within the same workflow.

  2. Generate Code: This part just does the regular code generation using Xpand and is not specific to the oAW XSD Adapter at all. The generator org.openarchitectureware.xpand2.Generator needs to know which meta model to use. This example references the previously declared one. The expand element tells the generator to call the definition named Root within file template.xpt using the contents of slot model as parameter. Element outlet defines where to store the generates files.

<workflow>
  <component class="org.openarchitectureware.xsd.XMLReader">
    <modelSlot value="model" />
    <uri value="model.xml" />
    <metaModel id="mm"
      class="org.openarchitectureware.xsd.XSDMetaModel">
      <schemaFile value="metamodel.xsd" />
    </metaModel>
  </component>
  <component class="org.openarchitectureware.xpand2.Generator">
    <metaModel idRef="mm" />
    <expand value="template::Root FOR model" />
    <outlet path="src-gen" />
  </component>
</workflow>

Step 6: Execute Workflow aka Generate Code

Before you actually execute the workflow, or in case of errors, you can use Figure 67, “Files of this Tutorial” to double check your files.

Figure 67. Files of this Tutorial

Files of this Tutorial

To execute the workflow, click with your right mouse button on the workflow file and choose "Run As", "oAW Workflow", as it is shown in the section called “Step 6: Execute Workflow aka Generate Code” .

Figure 68. Execute Workflow

Execute Workflow

When executing the workflow, this output is supposed to appear in Eclipse's Console View. If that View does not pop up automatically, you can reach it via "Window", "Show View", "Console".

0    INFO  WorkflowRunner     - ----------------------------------------------------------------
10   INFO  WorkflowRunner     - openArchitectureWare 4.x Development
10   INFO  WorkflowRunner     - (c) 2005-2008 openarchitectureware.org and contributors
10   INFO  WorkflowRunner     - ----------------------------------------------------------------
10   INFO  WorkflowRunner     - running workflow: workflow.oaw
11   INFO  WorkflowRunner     - 
601  INFO  XSDMetaModel       - Loading XSDSchema from 'metamodel.xsd'
1531 INFO  OawXSDEcoreBuilder - Creating EPackage 'metamodel' from XSDSchema
                                'file:/.../bin/metamodel.xsd' (http://www.example.org/wizard)
1617 INFO  CompositeComponent - XMLReader: Loading XML file model.xml
1711 INFO  CompositeComponent - Generator: generating 'template::Root FOR model' => src-gen
1847 INFO  Generator          - Written 1 files to outlet [default](src-gen)
1847 INFO  WorkflowRunner     - workflow completed in 231ms!

After code generation, there is a file called wizard.txt within the src-gen folder. Its contents is supposed to look like shown below. You should be able to recognize the structure you've defined within the template file and the contents from your XML model.

Name: My Example Setup
Welcometext: Welcome to this little demo application.
First Page Title: Wizard Page One