| 1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| 2 |
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 3 |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| 4 |
<head> |
| 5 |
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> |
| 6 |
<link rel="stylesheet" href="images/../../../css/book.css" type="text/css"/> |
| 7 |
<link rel="stylesheet" href="images/../../../css/emf-book.css" type="text/css"/> |
| 8 |
<title>Generating an EMF Model using XML Schema (XSD)</title> |
| 9 |
</head> |
| 10 |
<body lang="EN-US" xml:lang="EN-US"> |
| 11 |
<h1>Generating an EMF Model using XML Schema (XSD)</h1> |
| 12 |
|
| 13 |
<p>Last updated: May 21, 2008</p> |
| 14 |
|
| 15 |
<p>This tutorial provides a step-by-step description for creating an EMF model |
| 16 |
from an XML Schema and then generating a simple model editor for it. Following |
| 17 |
this tutorial will show how easy EMF makes it to go from a simple model |
| 18 |
definition in an XML Schema to a fully functioning editor for that model.</p> |
| 19 |
|
| 20 |
<p>The screenshots are based on version 3.2.0 RC6 of the Eclipse SDK and version 2.2.0 RC6a |
| 21 |
of EMF.</p> |
| 22 |
|
| 23 |
<p>The XML Schema file we use in this tutorial can be found here: |
| 24 |
<a target="_code" href="images/../library.xsd">library.xsd</a>. Save it |
| 25 |
somewhere on your workstation for later use.</p> |
| 26 |
|
| 27 |
<p>The basic mapping rules from XML Schema to Ecore are:</p> |
| 28 |
|
| 29 |
<ul> |
| 30 |
<li>A schema maps to an EPackage. Any included schemas that declare different |
| 31 |
target namespaces map to their own EPackages.</li> |
| 32 |
|
| 33 |
<li>A complex type definition maps to an EClass.</li> |
| 34 |
|
| 35 |
<li>A simple type definition maps to an EDataType.</li> |
| 36 |
|
| 37 |
<li>An attribute declaration or a nested element declaration maps to an |
| 38 |
EAttribute or EReference, depending on its type.</li> |
| 39 |
|
| 40 |
<li>An EClass called DocumentRoot is created to hold any top-level element |
| 41 |
or attribute declarations.</li> |
| 42 |
</ul> |
| 43 |
|
| 44 |
<p>From a modeling perspective, XML Schema is not as expressive as Ecore. It can |
| 45 |
neither specify the type of a reference target nor define bidirectional |
| 46 |
references (though EMF provides its own way to overcome these limitations).</p> |
| 47 |
|
| 48 |
<hr/> |
| 49 |
<h2>Contents</h2> |
| 50 |
|
| 51 |
<table border="0" cellspacing="2" cellpadding="2" width="100%"> |
| 52 |
<tr> |
| 53 |
<td valign="top" width="60">Step 0:</td> |
| 54 |
<td valign="top"><a href="#step0">Prerequisites</a></td> |
| 55 |
</tr> |
| 56 |
|
| 57 |
<tr> |
| 58 |
<td valign="top">Step 1:</td> |
| 59 |
<td valign="top"><a href="#step1">Import the Model from XML Schema</a> |
| 60 |
</td> |
| 61 |
</tr> |
| 62 |
|
| 63 |
<tr> |
| 64 |
<td valign="top">Step 2:</td> |
| 65 |
<td valign="top"><a href="#step2">Generate the EMF Model Code</a> |
| 66 |
</td> |
| 67 |
</tr> |
| 68 |
|
| 69 |
<tr> |
| 70 |
<td valign="top">Step 3:</td> |
| 71 |
<td valign="top"><a href="#step3">Generate an Editor for the |
| 72 |
Model</a> </td> |
| 73 |
</tr> |
| 74 |
|
| 75 |
<tr> |
| 76 |
<td valign="top">Step 4:</td> |
| 77 |
<td valign="top"><a href="#step4">Run the Generated Editor</a> |
| 78 |
</td> |
| 79 |
</tr> |
| 80 |
</table> |
| 81 |
<br/> |
| 82 |
|
| 83 |
<hr/> |
| 84 |
<p style="text-align: right"><a id="step0" name="step0"> </a><a href="#top">contents</a></p> |
| 85 |
<h2>Step 0: Prerequisites</h2> |
| 86 |
|
| 87 |
<p>This tutorial requires both the EMF Runtime package, which includes the |
| 88 |
EMF generator and related plug-ins, and the XML Schema Definition (XSD) |
| 89 |
Runtime package. This latter package provides an EMF model of XML Schema, which |
| 90 |
EMF relies on for reading schemas. For simplicity, a combined EMF and XSD SDK |
| 91 |
package is available. After installing the package(s), verify that they are |
| 92 |
available in your Eclipse environment:</p> |
| 93 |
|
| 94 |
<ul> |
| 95 |
<li>Bring up the "Help/About Eclipse Platform" dialog.<br/> |
| 96 |
<img src="images/../../clibmod/images/img001.gif" alt="Help/About Eclipse Platform"/><br/> |
| 97 |
</li> |
| 98 |
|
| 99 |
<li>Click on "Plug-in Details".<br/> |
| 100 |
<img src="images/../../clibmod/images/img002.gif" alt="Plug-in Details"/><br/> |
| 101 |
</li> |
| 102 |
|
| 103 |
<li>Check that the highlighted set of plug-ins are present.<br/> |
| 104 |
<img src="images/img001.gif" alt="Required plug-ins: org.eclipse.emf, org.eclipse.emf.codegen, org.eclipse.emf.codegen.ecore, org.eclipse.emf.codegen.ecore.ui, org.eclipse.emf.codegen.ui, org.eclipse.emf.common, org.eclipse.emf.common.ui, org.eclipse.emf.converter, org.eclipse.emf.ecore, org.eclipse.emf.ecore.edit, org.eclipse.emf.ecore.editor, org.eclipse.emf.ecore.xmi, org.eclipse.emf.edit, org.eclipse.emf.edit.ui, org.eclipse.emf.importer, org.eclipse.emf.mapping, org.eclipse.emf.mapping.ui, org.eclipse.emf.mapping.xsd2ecore, org.eclipse.emf.mapping.xsd2ecore.editor, org.eclipse.xsd, org.eclipse.xsd.ecore.importer, org.eclipse.xsd.edit, org.eclipse.xsd.editor"/><br/> |
| 105 |
</li> |
| 106 |
</ul> |
| 107 |
|
| 108 |
<p>Additional EMF and XSD plug-ins are not required for this tutorial. |
| 109 |
They may or may not appear, depending on which packages you installed.</p> |
| 110 |
|
| 111 |
<hr/> |
| 112 |
<p style="text-align: right"><a id="step1" name="step1"> </a><a href="#top">contents</a></p> |
| 113 |
<h2>Step 1: Import the Model from XML Schema</h2> |
| 114 |
|
| 115 |
<p>Create a new EMF project in the workspace:</p> |
| 116 |
|
| 117 |
<ul> |
| 118 |
<li>Bring up the "File/New/Project..." dialog.<br/> |
| 119 |
<img src="images/../../clibmod/images/img101.gif" alt="File/New/Project..."/><br/> |
| 120 |
</li> |
| 121 |
|
| 122 |
<li>Expand "Eclipse Modeling Framework" and select "EMF Project". Click the |
| 123 |
"Next" button.<br/> |
| 124 |
<img src="images/../../clibmod/images/img102.gif" alt="EMF Project"/><br/> |
| 125 |
</li> |
| 126 |
|
| 127 |
<li>Give the project a name, say, "library". Then, click the "Next" button.<br/> |
| 128 |
<img src="images/../../clibmod/images/img103.gif" alt="Name the project"/><br/> |
| 129 |
</li> |
| 130 |
|
| 131 |
<li>Select "XML Schema" and click the "Next" button.<br/> |
| 132 |
<img src="images/img101.gif" alt="XML Schema"/><br/> |
| 133 |
</li> |
| 134 |
|
| 135 |
<li>Click on the "Browse" button and locate the schema file.<br/> |
| 136 |
<img src="images/img102.gif" alt="Browse for schema file"/><br/> |
| 137 |
</li> |
| 138 |
|
| 139 |
<li>The schema will be examined, and a default generator model name will be |
| 140 |
suggested. You can change the name in the entry box if you wish. You can also |
| 141 |
select "Create XML Schema to Ecore Map" to generate a model of the mapping |
| 142 |
used for your schema. Then, click the "Next" button.<br/> |
| 143 |
<img src="images/img104.gif" alt="Generator model name"/><br/> |
| 144 |
</li> |
| 145 |
|
| 146 |
<li>In general, more than one package may be produced from a single schema if it |
| 147 |
includes other schemas that declare different target namespaces. Select the |
| 148 |
package for which you want to generate an EMF model -- in this case, the only |
| 149 |
package, "org.eclipse.example.library". Click the "Finish" button.<br/> |
| 150 |
<img src="images/img105.gif" alt="Select package"/><br/> |
| 151 |
</li> |
| 152 |
|
| 153 |
<li>An Ecore model (library.ecore) and a generator model (library.genmodel) will |
| 154 |
be created. If "Create XML Schema to Ecore Map" was checked above, a mapping |
| 155 |
model (library.xsd2ecore) will also be created. It can be opened to see exactly |
| 156 |
how the schema was mapped to Ecore. The generator model is automatically opened |
| 157 |
in the main view.<br/> |
| 158 |
<img src="images/img106.gif" alt="Opened generator"/><br/> |
| 159 |
</li> |
| 160 |
</ul> |
| 161 |
|
| 162 |
<hr/> |
| 163 |
<p style="text-align: right"><a id="step2" name="step2"> </a><a href="#top">contents</a></p> |
| 164 |
<h2>Step 2: Generate the EMF Model Code</h2> |
| 165 |
|
| 166 |
<p>The generator model shows a root object, representing the whole model. This |
| 167 |
model object has children that represent its packages, whose children then |
| 168 |
represent classifiers (classes and datatypes, including enumerated types). The |
| 169 |
children of classes are class attributes, references, and operations; the |
| 170 |
children of enumerated types are enum literals.</p> |
| 171 |
|
| 172 |
<ul> |
| 173 |
<li>The model can be expanded to see its various elements.<br/> |
| 174 |
<img src="images/img201.gif" alt="Expanded generator model"/><br/> |
| 175 |
</li> |
| 176 |
|
| 177 |
<li>There are properties associated with each object. If the Properties view |
| 178 |
isn't already showing, right-click the "Library" model object and select "Show |
| 179 |
Properties View" from the pop-up menu, or simply double-click the "Library" |
| 180 |
object.<br/> |
| 181 |
<img src="images/../../clibmod/images/img202.gif" alt="Show Properties View"/><br/> |
| 182 |
</li> |
| 183 |
|
| 184 |
<li>These properties control the behavior of the code generator.<br/> |
| 185 |
<img src="images/img203.gif" alt="Generator model properties"/><br/> |
| 186 |
</li> |
| 187 |
</ul> |
| 188 |
|
| 189 |
<p>In most cases, the properites need not be changed from their default values, |
| 190 |
but these options can provide a great deal of control over the code that gets |
| 191 |
generated. For now, select several different generator model objects, and |
| 192 |
observe their properties.</p> |
| 193 |
|
| 194 |
<p>The generator model is also the place where you initiate the code generation. |
| 195 |
By right-clicking on an object in the model, you can generate code for it.</p> |
| 196 |
|
| 197 |
<ul> |
| 198 |
<li>Right-click the "Library" model object and select "Generate Model Code" from |
| 199 |
the pop-up menu.<br/> |
| 200 |
<img src="images/img204.gif" alt="Generate Model Code"/><br/> |
| 201 |
</li> |
| 202 |
|
| 203 |
<li>Observe the generated files.<br/> |
| 204 |
<img src="images/img205.gif" alt="Generated files"/><br/> |
| 205 |
</li> |
| 206 |
</ul> |
| 207 |
|
| 208 |
<p>After generation, the class interfaces and enum class will have been created, |
| 209 |
and a new pair of interfaces will have been created for the package itself and |
| 210 |
for the factory. There will also be two new packages, with "impl" and "util" |
| 211 |
suffixes, which contain implementations of the interfaces and additional utility |
| 212 |
classes, and both types of manifest files for the model plug-in: "plugin.xml" and "MANIFEST.MF".</p> |
| 213 |
|
| 214 |
<p>If you change the model, you can regenerate it, and changes will be merged |
| 215 |
with any hand modifications that may have been made to the code. You can also |
| 216 |
selectively generate a subset of the model code by right-clicking on a package, |
| 217 |
class, or enum object and selecting "Generate Model Code" from the pop-up |
| 218 |
menu.</p> |
| 219 |
|
| 220 |
<hr/> |
| 221 |
<p style="text-align: right"><a id="step3" name="step3"> </a><a href="#top">contents</a></p> |
| 222 |
<h2>Step 3: Generate an Editor for the Model</h2> |
| 223 |
|
| 224 |
<p>A fully functional Eclipse editor can also be generated for any model. By |
| 225 |
default, it is split between two plug-ins: an "edit" plug-in includes adapters |
| 226 |
that provide a structured view and perform command-based editing of the model |
| 227 |
objects; an "editor" plug-in provides the UI for the editor and wizard.</p> |
| 228 |
|
| 229 |
<ul> |
| 230 |
<li>In the generator, right-click the "Library" model object and select |
| 231 |
"Generate Edit Code" from the pop-up menu.<br/> |
| 232 |
<img src="images/img301.gif" alt="Generate Edit Code"/><br/> |
| 233 |
</li> |
| 234 |
|
| 235 |
<li>Right-click the model object again and select "Generate Editor Code" from |
| 236 |
the pop-up menu.<br/> |
| 237 |
<img src="images/img302.gif" alt="Generate Editor Code"/><br/> |
| 238 |
</li> |
| 239 |
|
| 240 |
<li>Observe the generated projects in the Package Explorer view, with "edit" and |
| 241 |
"editor" suffixes.<br/> |
| 242 |
<img src="images/../../clibmod/images/img303.gif" alt="Edit and editor projects"/><br/> |
| 243 |
</li> |
| 244 |
</ul> |
| 245 |
|
| 246 |
<p>In general, if you wish to generate the model, edit, and editor plug-ins in a |
| 247 |
single step, you can do so by selecting "Generate All" from the pop-up menu. This will also create a tests plug-in, containing generated JUnit test code.</p> |
| 248 |
|
| 249 |
<p>The code should be compiled automatically as it is generated, and should |
| 250 |
recompile whenever it is changed. If you have disabled automatic building in the |
| 251 |
workbench preferences, you can initiate compilation manually:</p> |
| 252 |
|
| 253 |
<ul> |
| 254 |
<li>Select "Build All" from the "Project" menu.<br/> |
| 255 |
<img src="images/../../clibmod/images/img304.gif" alt="Project/Build All"/><br/> |
| 256 |
</li> |
| 257 |
|
| 258 |
<li>Observe the Problems view. There should be no errors in the library, |
| 259 |
library.edit, and library.editor projects.<br/> |
| 260 |
<img src="images/../../clibmod/images/img305.gif" alt="No errors"/><br/> |
| 261 |
</li> |
| 262 |
</ul> |
| 263 |
|
| 264 |
<hr/> |
| 265 |
<p style="text-align: right"><a id="step4" name="step4"> </a><a href="#top">contents</a></p> |
| 266 |
<h2>Step 4: Run the Generated Editor</h2> |
| 267 |
|
| 268 |
<p>In order to test the new plug-ins, a second instance of Eclipse must be |
| 269 |
launched. The plug-ins will run in this workbench.</p> |
| 270 |
|
| 271 |
<ul> |
| 272 |
<li>Select one of the projects and choose "Run As/Eclipse Application" from the |
| 273 |
"Run" menu or toolbar drop-down.<br/> |
| 274 |
<img src="images/../../clibmod/images/img401.gif" alt="Run/Run As/Eclipse Application"/><br/> |
| 275 |
</li> |
| 276 |
|
| 277 |
<li>Wait for a second instance of the Eclipse platform to come up. Bring up the |
| 278 |
"Help/About Eclipse Platform" dialog, click on the "Plug-in Details" button, and |
| 279 |
verify that the generated plug-ins are there.<br/> |
| 280 |
<img src="images/../../clibmod/images/img402.gif" alt="Generated plug-ins: library.editor, library.edit, library"/><br/> |
| 281 |
</li> |
| 282 |
</ul> |
| 283 |
|
| 284 |
<p>The Library Model wizard can now be used to create a new instance of the |
| 285 |
model.</p> |
| 286 |
|
| 287 |
<ul> |
| 288 |
<li>Bring up the "File/New/Project..." dialog.<br/> |
| 289 |
<img src="images/../../clibmod/images/img101.gif" alt="File/New/Project..."/><br/> |
| 290 |
</li> |
| 291 |
|
| 292 |
<li>Expand "General" and select "Project". Click the "Next" button.<br/> |
| 293 |
<img src="images/../../clibmod/images/img403.gif" alt="Simple Project"/><br/> |
| 294 |
</li> |
| 295 |
|
| 296 |
<li>Give the project a name and click the "Finish" button.<br/> |
| 297 |
<img src="images/../../clibmod/images/img404.gif" alt="Name the project"/><br/> |
| 298 |
</li> |
| 299 |
|
| 300 |
<li>Right-click the project and select "New/Other..." from the pop-up menu.<br/> |
| 301 |
<img src="images/../../clibmod/images/img405.gif" alt="New/Other..."/><br/> |
| 302 |
</li> |
| 303 |
|
| 304 |
<li>Expand "Example EMF Model Creation Wizards" and select "Library Model". |
| 305 |
Click the "Next" button.<br/> |
| 306 |
<img src="images/../../clibmod/images/img406.gif" alt="Library Model"/><br/> |
| 307 |
</li> |
| 308 |
|
| 309 |
<li>Enter a file name for the library model. Make sure it ends with |
| 310 |
a ".library" extension. Then, click the "Next" button.<br/> |
| 311 |
<img src="images/../../clibmod/images/img407.gif" alt="Name the library model file"/><br/> |
| 312 |
</li> |
| 313 |
|
| 314 |
<li>Select "Library" as the model object and click the "Finish" button.<br/> |
| 315 |
<img src="images/../../clibmod/images/img408.gif" alt="Select the model object"/><br/> |
| 316 |
</li> |
| 317 |
|
| 318 |
<li>The newly created library model is opened in the main view.<br/> |
| 319 |
<img src="images/../../clibmod/images/img409.gif" alt="New library model"/><br/> |
| 320 |
</li> |
| 321 |
</ul> |
| 322 |
|
| 323 |
<p>The root object in this editor corresponds to the My.library resource. Under |
| 324 |
it lies a single library, the object which was selected as the model object in |
| 325 |
the wizard.</p> |
| 326 |
|
| 327 |
<ul> |
| 328 |
<li>Expand the "platform:/resource/librarytest/My.library" resource to see the |
| 329 |
"Library" object. Select it.<br/> |
| 330 |
<img src="images/../../clibmod/images/img410.gif" alt="Expanded resource"/><br/> |
| 331 |
</li> |
| 332 |
|
| 333 |
<li>If the Properties view isn't already showing, right-click the "Library" |
| 334 |
object and select "Show Properties View" from the pop-up menu.<br/> |
| 335 |
<img src="images/../../clibmod/images/img411.gif" alt="Show Properties View"/><br/> |
| 336 |
</li> |
| 337 |
|
| 338 |
<li>In the Properties view, click on the "Value" column of the "Name" property, |
| 339 |
and give a name to the library. The label in the main view will be updated when |
| 340 |
you hit Enter.<br/> |
| 341 |
<img src="images/../../clibmod/images/img412.gif" alt="Name the library"/><br/> |
| 342 |
</li> |
| 343 |
|
| 344 |
<li>Right-click the library and select "New Child/Writer" from the pop-up menu. |
| 345 |
A new writer is added to the library.<br/> |
| 346 |
<img src="images/../../clibmod/images/img413.gif" alt="New Child/Writer"/><br/> |
| 347 |
</li> |
| 348 |
|
| 349 |
<li>Enter the name of the writer in the Properties view.<br/> |
| 350 |
<img src="images/../../clibmod/images/img414.gif" alt="Name the writer"/><br/> |
| 351 |
</li> |
| 352 |
|
| 353 |
<li>Similarly, a book can be added to the library.<br/> |
| 354 |
<img src="images/../../clibmod/images/img415.gif" alt="New Child/Book"/><br/> |
| 355 |
</li> |
| 356 |
|
| 357 |
<li>All the book's attributes and references can edited in the Properties |
| 358 |
view.<br/> |
| 359 |
<img src="images/../../clibmod/images/img416.gif" alt="Book properties"/><br/> |
| 360 |
</li> |
| 361 |
|
| 362 |
<li>You can save, close, and then re-open the model using the text editor if you |
| 363 |
wish to see the schema-based XML serialization (right-click "My.library", |
| 364 |
then select "Open With/Text Editor").<br/> |
| 365 |
<pre> |
| 366 |
<?xml version="1.0" encoding="UTF-8"?> |
| 367 |
<library:Library xmlns:library="http://www.example.eclipse.org/Library"> |
| 368 |
<name>Skills Center</name> |
| 369 |
<writers> |
| 370 |
<name>JRR Tolkien</name> |
| 371 |
<books>#//@books.0</books> |
| 372 |
</writers> |
| 373 |
<books> |
| 374 |
<title>Fellowship of the Ring</title> |
| 375 |
<pages>324</pages> |
| 376 |
<category>ScienceFiction</category> |
| 377 |
<author>#//@writers.0</author> |
| 378 |
</books> |
| 379 |
</library:Library></pre></li> |
| 380 |
</ul> |
| 381 |
|
| 382 |
<hr/> |
| 383 |
<p style="text-align: right"><a href="#top">contents</a></p> |
| 384 |
</body> |
| 385 |
</html> |