Debian Codegraph @

doc/org.eclipse.emf.doc/tutorials/xlibmod/xlibmod.html

raw
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">&nbsp;</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 &nbsp;</li>
98
99 <li>Click on "Plug-in Details".<br/>
100 <img src="images/../../clibmod/images/img002.gif" alt="Plug-in Details"/><br/>
101 &nbsp;</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 &nbsp;</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">&nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</li>
130
131 <li>Select "XML Schema" and click the "Next" button.<br/>
132 <img src="images/img101.gif" alt="XML Schema"/><br/>
133 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</li>
160 </ul>
161
162 <hr/>
163 <p style="text-align: right"><a id="step2" name="step2">&nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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">&nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</li>
262 </ul>
263
264 <hr/>
265 <p style="text-align: right"><a id="step4" name="step4">&nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &nbsp;</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 &lt;?xml version="1.0" encoding="UTF-8"?>
367 &lt;library:Library xmlns:library="http://www.example.eclipse.org/Library">
368 &lt;name>Skills Center&lt;/name>
369 &lt;writers>
370 &lt;name>JRR Tolkien&lt;/name>
371 &lt;books>#//@books.0&lt;/books>
372 &lt;/writers>
373 &lt;books>
374 &lt;title>Fellowship of the Ring&lt;/title>
375 &lt;pages>324&lt;/pages>
376 &lt;category>ScienceFiction&lt;/category>
377 &lt;author>#//@writers.0&lt;/author>
378 &lt;/books>
379 &lt;/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>