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.
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)
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
)
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.
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” .
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”
<?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>
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>
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»
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:
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.
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>
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.
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” .
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