plugins/org.eclipse.emf.compare.mpatch.doc/html/tutorial.html - emfcompare/org.eclipse.emf.compare - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

 <!--
  Copyright (c) 2010, 2011 Technical University of Denmark.
  All rights reserved. This program and the accompanying materials
  are made available under the terms of the Eclipse Public License v1.0
  which accompanies this distribution, and is available at
  http://www.eclipse.org/legal/epl-v10.html

  Contributors:
     Patrick Koenemann, DTU Informatics - initial API and implementation

  $Id: tutorial.html,v 1.2 2010/10/04 16:18:57 pkonemann Exp $
 -->

 <html>
 <head>
 	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 	<title>MPatch Tutorial</title>
 </head>

 <body>
 <h1>MPatch Tutorial</h1>

 <p>Quick overview of what you learn in the tutorial:</p>
 <ul>
 <li>Setup example project</li>
 <li>Compare two models with EMF Compare</li>
 <li>Create MPatch from EMF Compare comparison</li>
 <li>Apply MPatch to another model</li>
 </ul>
 <p>The contents of this tutorial is also shown in the (outdated) <a href="http://modeldiff.imm.dtu.dk/modeldiff/index2.php?option=com_content&task=view&id=70&Itemid=67" target="_blank">screencasts</a>; please note that the screencasts use the old term <i>model-independent differences</i> instead of <i>MPatch</i>.</p>
 <hr title="Setup example project" alt="Setup example project" />
 <p>The tutorial uses a shipped example for illustrations. To import it into your workspace, select <em>Window</em> -> <em>Show View</em> -> <em>Other...</em> -> <em>Plug-ins</em>, and look for the plugin <em>org.eclipse.emf.compare.mpatch.example</em>. Right click it and select <em>Import As</em> -> <em>Source Project</em>.</p>
 <p style="text-align: center;"><img src="images/import_example.png" border="0" alt="Import example" title="Import example" /></p>
 <p>You should now have a project available in your workspace containing the following files:</p>
 <p style="text-align: center;"><img src="images/files.png" border="0" alt="Example models" title="Example models" /></p>
 <p><em>model/library.ecore</em> - the base version of a simple library model  <br /><em>model/library_karl.ecore</em> - a modified version of the base version <br /><em>model/library_eve.ecore</em> - another modified version of the base version</p>
 <p>The <em>.ecorediag</em>-files are diagrams for the models. If you installed the Ecore Tools, you should be able to open these files and view the models graphically.</p>
 <hr title="Model-comparison with EMF Compare" alt="Model-comparison with EMF Compare" />
 <p>At the moment, <em>MPatches</em> are not created directly, but from existing differences created with EMF Compare. The reason is that we do not want to introduce yet another model-comparison algorithm but instead use existing solutions which are already flexible and exdendable.</p>
 <p>To compare <em>library.ecore</em> and <em>library_karl.ecore</em>, select both files, right click and select <em>Compare With</em> -> <em>Each Other</em>. Then a model comparison dialog should open which shows both model and their differences in EMF Compare:</p>
 <p style="text-align: center;"><img src="images/emfdiff.png" border="0" alt="EMF Compare" title="EMF Compare" /></p>
 <hr title="MPatch creation" alt="MPatch creation" />
 <p>The process of creating MPatches involves a set of optional transformations which add further features as explained below.</p>
 <p>There are currently two ways of starting the transformations:</p>
 <ol>
 <li>From within the comparison dialog: Select 'Export as MPatch' (see previous screenshot).</li>
 <li>From an <em>.emfdiff</em>-file which was previously saved from a comparison dialog ('Export as emfdiff') by right-clicking it and selecting <em>MPatch</em> -> <em>Transform emfdiff to MPatch</em>.</li>
 </ol>
 <p>In the end, a wizard for the creation of MPatches is started. Select the <em>library</em> folder as the parent folder and enter <em>karls_diff.mpatch</em> as a file name. Select the transformations 'Intuitive Grouping', 'Scope Expansion', and 'Unbound Symbolic References' on the next wizard page (their order doesn't matter), make sure the <em>Condition-based symbolic reference creator</em> is selected, and press <em>Finish</em>:</p>
 <p style="text-align: center;"><img src="images/create.png" border="0" alt="Optional transformations" title="Optional transformations" /></p>
 <p>The <em>Intuitive Grouping</em> structures the changes in groups. <em>Unbound Symbolic References</em> makes changes not only applicable to one single but to a set of model-elements. <em>Scope Expansion</em> modifies the MPatch such that the changes are applicable to slightly changed models. The <em>condition-based symbolic reference creator</em> produces references which are required by some of the transformations.<br />Please see <a href="http://modeldiff.imm.dtu.dk/modeldiff/index.php?option=com_content&view=article&id=61&Itemid=66">this page</a> for more detailed explanations.</p>
 <p>Next you should see a summary of the transformation results and you should have a file <em>library/karls_diffs.mpatch</em> in your example project:</p>
 <p style="text-align: center;"><img src="images/result.png" border="0" alt="Transformation result" title="Transformation result" /></p>
 <hr title="MPatch application" alt="MPatch application" />
 <p>Now we are going to apply the just created differences to the other model.</p>
 <p>Right-click <em>karls_diff.mpatch</em> and select <em>MPatch</em> -> <em>Apply MPatch</em>. This opens the wizard for MPatch application:</p>
 <ol>
 <li> Selection of MPatch<br /><img src="images/apply1.png" border="0" alt="Select MPatch for application" /><br /><br /></li>
 <li>Selection of the model to which the MPatch should be applied;<br />please select <em>model/library_eve.ecore</em> from the workspace here.<br /><img src="images/apply2.png" border="0" alt="Select target model" /><br /><br /></li>
 <li>Resolution of symbolic references;<br />this page is the most important for MPatch application--in order to effectively use MPatches, you need to understand what happens here:<br />It defines to which model elements (the model was choosen in the previous step) each individual change should be applied.<br />The symbols have the following meaning:<br /><img src="images/tut_apply_blue.png" border="0" width="16" height="16" /> -- The number of resolved model elements does not match the required number<br /><img src="images/tut_apply_red.png" border="0" width="16" height="16" /> -- The change is not applicable to the set of selected model elements<br /> <img src="images/tut_apply_green.png" border="0" /> -- Resolution is ok, the change can be applied.<br />The number of resolved model elements can be changed by clicking the button [...] in the table cell which shows the resolved model elements.<br /><img src="images/apply3.png" border="0" alt="Resolve symbolic references" /><br />Note that a change can be applied to multiple model elements at once because if the 'Unbound Symbolic References' transformation was performed!<br />Note also that the user can make a selection by ticking (thus ignoring) changes, which is already done for the unknown changes.<br /><br /></li>
 <li>Storing an intermediate emfdiff (optional);<br />If the intermediate models should be saved after the application process (ticking <em>Store intermediate models</em> in step 3), then the wizards asks for a place to store the emfdiff file.<br /><br /></li>
 <li>Storing an intermediate model (optional);<br />If the intermediate models should be saved, the wizards asks for a place to store a copy of the model selected in step 2.<br /><br /></li>
 <li>Review all settings;<br />
 When clicking <i>Finish</i>, a message confirms the application of the four changes. If <em>Review result with EMF Compare</em> is ticked, then a comparison of the unchanged and the changed model is opened afterwards.<br /><img src="images/apply4.png" border="0" alt="Review all settings" /><br /><img src="images/application.png" border="0" alt="Review all settings" /><br /><br /></li>
 <li>Review result with EMF Compare (optional);<br />EMF Compare opens and shows all applied changes in a comparison view. Please note that due to a <a href="/modeldiff/index.php?option=com_content&view=article&catid=38%3Abugs-and-features&id=57%3Abug-visualization-of-differences-after-difference-application&Itemid=57">bug (or feature?!) in EMF Compare</a>, any changes in this view are discarded if the intermediate models are not saved.<img src="images/final_compare.png" border="0" alt="Review all settings" /><br />
 Now we can see:
 <ul>
 <li><i>Citylibrary.authors</i> was added although the original class was <i>Library</i>.
 <li><i>Book.authors</i> (attribute) has been deleted although the original feature was called <i>author</i> and the book was located in another package.
 <li><i>Book.authors</i> (reference) has been added although the original class was located in another package.
 </ul></li>
 </ol>
 <p>Now you know the basic steps to use MPatches.</p>

 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

	<!--
	Copyright (c) 2010, 2011 Technical University of Denmark.
	All rights reserved. This program and the accompanying materials
	are made available under the terms of the Eclipse Public License v1.0
	which accompanies this distribution, and is available at
	http://www.eclipse.org/legal/epl-v10.html

	Contributors:
	Patrick Koenemann, DTU Informatics - initial API and implementation

	$Id: tutorial.html,v 1.2 2010/10/04 16:18:57 pkonemann Exp $
	-->

	<html>
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	<title>MPatch Tutorial</title>
	</head>

	<body>
	<h1>MPatch Tutorial</h1>

	<p>Quick overview of what you learn in the tutorial:</p>
	<ul>
	<li>Setup example project</li>
	<li>Compare two models with EMF Compare</li>
	<li>Create MPatch from EMF Compare comparison</li>
	<li>Apply MPatch to another model</li>
	</ul>
	<p>The contents of this tutorial is also shown in the (outdated) <a href="http://modeldiff.imm.dtu.dk/modeldiff/index2.php?option=com_content&task=view&id=70&Itemid=67" target="_blank">screencasts</a>; please note that the screencasts use the old term <i>model-independent differences</i> instead of <i>MPatch</i>.</p>
	<hr title="Setup example project" alt="Setup example project" />
	<p>The tutorial uses a shipped example for illustrations. To import it into your workspace, select <em>Window</em> -> <em>Show View</em> -> <em>Other...</em> -> <em>Plug-ins</em>, and look for the plugin <em>org.eclipse.emf.compare.mpatch.example</em>. Right click it and select <em>Import As</em> -> <em>Source Project</em>.</p>
	<p style="text-align: center;"><img src="images/import_example.png" border="0" alt="Import example" title="Import example" /></p>
	<p>You should now have a project available in your workspace containing the following files:</p>
	<p style="text-align: center;"><img src="images/files.png" border="0" alt="Example models" title="Example models" /></p>
	<p><em>model/library.ecore</em> - the base version of a simple library model <br /><em>model/library_karl.ecore</em> - a modified version of the base version <br /><em>model/library_eve.ecore</em> - another modified version of the base version</p>
	<p>The <em>.ecorediag</em>-files are diagrams for the models. If you installed the Ecore Tools, you should be able to open these files and view the models graphically.</p>
	<hr title="Model-comparison with EMF Compare" alt="Model-comparison with EMF Compare" />
	<p>At the moment, <em>MPatches</em> are not created directly, but from existing differences created with EMF Compare. The reason is that we do not want to introduce yet another model-comparison algorithm but instead use existing solutions which are already flexible and exdendable.</p>
	<p>To compare <em>library.ecore</em> and <em>library_karl.ecore</em>, select both files, right click and select <em>Compare With</em> -> <em>Each Other</em>. Then a model comparison dialog should open which shows both model and their differences in EMF Compare:</p>
	<p style="text-align: center;"><img src="images/emfdiff.png" border="0" alt="EMF Compare" title="EMF Compare" /></p>
	<hr title="MPatch creation" alt="MPatch creation" />
	<p>The process of creating MPatches involves a set of optional transformations which add further features as explained below.</p>
	<p>There are currently two ways of starting the transformations:</p>
	<ol>
	<li>From within the comparison dialog: Select 'Export as MPatch' (see previous screenshot).</li>
	<li>From an <em>.emfdiff</em>-file which was previously saved from a comparison dialog ('Export as emfdiff') by right-clicking it and selecting <em>MPatch</em> -> <em>Transform emfdiff to MPatch</em>.</li>
	</ol>
	<p>In the end, a wizard for the creation of MPatches is started. Select the <em>library</em> folder as the parent folder and enter <em>karls_diff.mpatch</em> as a file name. Select the transformations 'Intuitive Grouping', 'Scope Expansion', and 'Unbound Symbolic References' on the next wizard page (their order doesn't matter), make sure the <em>Condition-based symbolic reference creator</em> is selected, and press <em>Finish</em>:</p>
	<p style="text-align: center;"><img src="images/create.png" border="0" alt="Optional transformations" title="Optional transformations" /></p>
	<p>The <em>Intuitive Grouping</em> structures the changes in groups. <em>Unbound Symbolic References</em> makes changes not only applicable to one single but to a set of model-elements. <em>Scope Expansion</em> modifies the MPatch such that the changes are applicable to slightly changed models. The <em>condition-based symbolic reference creator</em> produces references which are required by some of the transformations.<br />Please see <a href="http://modeldiff.imm.dtu.dk/modeldiff/index.php?option=com_content&view=article&id=61&Itemid=66">this page</a> for more detailed explanations.</p>
	<p>Next you should see a summary of the transformation results and you should have a file <em>library/karls_diffs.mpatch</em> in your example project:</p>
	<p style="text-align: center;"><img src="images/result.png" border="0" alt="Transformation result" title="Transformation result" /></p>
	<hr title="MPatch application" alt="MPatch application" />
	<p>Now we are going to apply the just created differences to the other model.</p>
	<p>Right-click <em>karls_diff.mpatch</em> and select <em>MPatch</em> -> <em>Apply MPatch</em>. This opens the wizard for MPatch application:</p>
	<ol>
	<li> Selection of MPatch<br /><img src="images/apply1.png" border="0" alt="Select MPatch for application" /><br /><br /></li>
	<li>Selection of the model to which the MPatch should be applied;<br />please select <em>model/library_eve.ecore</em> from the workspace here.<br /><img src="images/apply2.png" border="0" alt="Select target model" /><br /><br /></li>
	<li>Resolution of symbolic references;<br />this page is the most important for MPatch application--in order to effectively use MPatches, you need to understand what happens here:<br />It defines to which model elements (the model was choosen in the previous step) each individual change should be applied.<br />The symbols have the following meaning:<br /><img src="images/tut_apply_blue.png" border="0" width="16" height="16" /> -- The number of resolved model elements does not match the required number<br /><img src="images/tut_apply_red.png" border="0" width="16" height="16" /> -- The change is not applicable to the set of selected model elements<br /> <img src="images/tut_apply_green.png" border="0" /> -- Resolution is ok, the change can be applied.<br />The number of resolved model elements can be changed by clicking the button [...] in the table cell which shows the resolved model elements.<br /><img src="images/apply3.png" border="0" alt="Resolve symbolic references" /><br />Note that a change can be applied to multiple model elements at once because if the 'Unbound Symbolic References' transformation was performed!<br />Note also that the user can make a selection by ticking (thus ignoring) changes, which is already done for the unknown changes.<br /><br /></li>
	<li>Storing an intermediate emfdiff (optional);<br />If the intermediate models should be saved after the application process (ticking <em>Store intermediate models</em> in step 3), then the wizards asks for a place to store the emfdiff file.<br /><br /></li>
	<li>Storing an intermediate model (optional);<br />If the intermediate models should be saved, the wizards asks for a place to store a copy of the model selected in step 2.<br /><br /></li>
	<li>Review all settings;<br />
	When clicking <i>Finish</i>, a message confirms the application of the four changes. If <em>Review result with EMF Compare</em> is ticked, then a comparison of the unchanged and the changed model is opened afterwards.<br /><img src="images/apply4.png" border="0" alt="Review all settings" /><br /><img src="images/application.png" border="0" alt="Review all settings" /><br /><br /></li>
	<li>Review result with EMF Compare (optional);<br />EMF Compare opens and shows all applied changes in a comparison view. Please note that due to a <a href="/modeldiff/index.php?option=com_content&view=article&catid=38%3Abugs-and-features&id=57%3Abug-visualization-of-differences-after-difference-application&Itemid=57">bug (or feature?!) in EMF Compare</a>, any changes in this view are discarded if the intermediate models are not saved.<img src="images/final_compare.png" border="0" alt="Review all settings" /><br />
	Now we can see:
	<ul>
	<li><i>Citylibrary.authors</i> was added although the original class was <i>Library</i>.
	<li><i>Book.authors</i> (attribute) has been deleted although the original feature was called <i>author</i> and the book was located in another package.
	<li><i>Book.authors</i> (reference) has been added although the original class was located in another package.
	</ul></li>
	</ol>
	<p>Now you know the basic steps to use MPatches.</p>

	</body>
	</html>