Exercise 6. Backward Compatibility

What This Exercise Is About

Using the PurchaseOrder model, you will experiment with how to support backward compatibility. In particular, you will make changes to the model and customize code to support automatic migration of data based on the original schema.

For your reference, here again is the UML class diagram describing the purchase order model:

Extended PO model


What You Should Be Able To Do

At the end of the lab, you should be able to:

Required Materials

General Advice / Warnings

Exercise Instructions

This exercise is carried out entirely using the Eclipse Software Development Kit (SDK) version 3.2 with the Eclipse Modeling Framework (EMF) 2.2 installed into it. The exercise instructions refer to this product as either Eclipse or as "the workbench".

These instructions are located in the exercises/Exercise6_Backward_Compatibility folder. If you browse into this location by expanding the folders, you should find one additional folder: org.eclipse.emf.tutorial.advanced.po. This is an Eclipse project that you will import into your workspace to complete this exercise.

The folder exercises/Solution6 contains examples of the files you will create during this exercise.


Directions

Step A: Verify workbench configuration

  1. See Exercise 1, Step A.

Step B: Import the project into the workspace

  1. See Exercise 1, Step B.

Step C: Generate the Code

  1. Generate all code from the genmodel file.
    1. Open the PurchaseOrder.genmodel file available in the model folder of the project imported in step B (if not already open).
    2. Select the topmost node PurchaseOrder, right-click, and select Generate All.
    3. The code should be compiled automatically as it is generated, and should recompile whenever it is changed. If you have disabled automatic building in the workbench preferences, you can initiate compilation manually by selecting Build All from the Project menu.
    4. Generate the code

    5. Three new projects will be created: org.eclipse.emf.tutorial.advanced.po.edit (edit support code not dependent on Eclipse), org.eclipse.emf.tutorial.advanced.po.editor (editor code dependent on Eclipse), and org.eclipse.emf.tutorial.advanced.po.tests (JUnit test skeletons for exercising any volatile features and operations defined in the model). Additionally, new classes and packages will be created within the org.eclipse.emf.tutorial.advanced.po project.

Step D: Create a Model Instance (Run Generated Model Editor Code)

All steps below will be done in a second, testing workbench, or Eclipse Application workbench.

  1. Launch a new Eclipse Application to try out your editor.
    1. Select your plug-in project org.eclipse.emf.tutorial.advanced.po in the Package Explorer.
    2. Select Run As -> Eclipse Application from the Run toolbar drop-down or menu. Note that the Run menu is context-sensitive, so options available under Run As will change depending on where your cursor is (which view/editor and what file type).
    3. Once it opens, close or minimize the Welcome view.
    4. Select About Eclipse SDK from the Help menu, click on Plug-in Details, and look for the contributed PurchaseOrder plug-ins, org.eclipse.emf.tutorial.advanced.po, org.eclipse.emf.tutorial.advanced.po.edit, org.eclipse.emf.tutorial.advanced.po.editor, and org.eclipse.emf.tutorial.advanced.po.tests.
    5. About Eclipse SDK Plug-in Details

  2. The Customer Model wizard can now be used to create a new instance of the model.
    1. Bring up the File -> New -> Project... dialog.
    2. Expand General and select Project. Click the Next button.
    3. Give the project a name, such as customers, and click the Finish button.
    4. Right-click the project and select New -> Other... from the pop-up menu.
    5. Expand Example EMF Model Creation Wizards and select Customer Model. Click the Next button.
    6. Enter a file name for the customer model, such as My.customer. Make sure it ends with a .customer extension. Then, click the Next button.
    7. Select Customer as the model object and click the Finish button.
    8. The newly created customer model is opened in an editor.
  3. The root object in this editor corresponds to the My.customer resource. Under it lies an instance of the Customer class.
  4. The steps below will show you how to use the model editor to create instance data.
    1. Expand the platform:/resource/customers/My.customer resource to see the Customer object.
    2. If the Properties view isn't already showing, right-click the Customer object and select Show Properties View from the pop-up menu.
    3. In the Properties view, click on the Value column of the Id property, and provide a name for the item ("1" for example).
    4. In the Properties view, click on the Value column of the Name property, and provide a name for the item ("My Customer" for example). The label in the editor will be updated when you hit Enter.
    5. In the Properties view, click on the Value column of the Vip property, and select true.
    6. Select File -> Save to serialize the customer.
    7. My Customer

  5. Close the model and exit the Eclipse Application.
    1. Select File -> Close to close customer model.
    2. Select File -> Exit to exit the Eclipse Application.

Step E: Customize the Ecore Model

  1. Make a copy of the model to preserve the original schema.
    1. Select the customer.ecore file available in the model folder of the project imported in step B.
    2. Right-click and select Copy from the pop-up menu.
    3. Select the model folder, right-click, and select Paste from the pop-up menu.
    4. Specify "customer2006.ecore" as the new name and press the OK button.
  2. Change the name of the Customer's id and vip attributes.
    1. Open the customer.ecore file available in the model folder of the project imported in step B.
    2. Select the customer package, right-click, and select Show Properties View (if this view is not already shown).
    3. Scroll the Properties view to find the Ns URI property and change it to http://www.eclipse.org/emf/tutorial/advanced/2007/Customer. Since we're changing the schema for the model, we're effectively creating a new version of it, and one convention for identifying schema versions is via the schema's namespace URI (using, for example, the year the schema was created/modified - we'll pretend we're making this change next year).
    4. Select the id attribute of the Customer class.
    5. Scroll the Properties view to find the name property and change it to identifier. We'll preten we've decided that we don't want to use the "id" abbreviation anymore.
    6. Select the vip attribute of the Customer class.
    7. Scroll the Properties view to find the name property and change it to vIP (note this uppercase 'I' and 'P'). This will result in "nicer" accessors (i.e. isVIP() and setVIP(boolean)) for this attribute.
    8. Select File -> Save to serialize the new schema.
    9. customer.ecore

  3. Regenerate all code from the genmodel file.
    1. Close and re-open the PurchaseOrder.genmodel file (to ensure that the generator model is in sync with the changed schema).
    2. Select the topmost node PurchaseOrder, right-click, and select Generate All.
  4. Update the generated package extension for the customer schema.
    1. Select the plugin.xml file available in the org.eclipse.emf.tutorial.advanced.po project folder.
    2. Right-click, and select Open With -> Text Editor from the pop-up menu.
    3. Change the uri attribute for the customer generate package extension to be "http://www.eclipse.org/emf/tutorial/advanced/2007/Customer".
    4. Select File -> Save to save the plug-in manifest.
    5. plugin.xml


Step F: Try to Open the Model Instance

All steps below will be done in a second, testing workbench, or Eclipse Application workbench.

  1. Launch the Eclipse Application again.
    1. Select your plug-in project org.eclipse.emf.tutorial.advanced.po in the Package Explorer.
    2. Select Run As -> Eclipse Application from the Run toolbar drop-down or menu. Note that the Run menu is context-sensitive, so options available under Run As will change depending on where your cursor is (which view/editor and what file type).
    3. Once it opens, close or minimize the Welcome view (if open).
  2. Try to open your customer model.
    1. Open the My.Customer file available in the customers project created in step D. Notice that the contents of the editor that opens don't look quite right - something is wrong.
    2. Select the Window -> Show View -> Error Log menu item to open the Error Log view. An error should be listed, with a message relating to a PackageNodeFoundException.
    3. Error Log view

    4. Select the error in the Error Log view, right-click, and select Event Details from the pop-up menu. A dialog will appear, showing the details of the event. Obviously, since we updated the namespace URI for the customer schema in step E, the package cannot be found for our model (it's still referencing the old URI). Of course, even if it could, there would still be problems since we renamed some of the attributes used in the model.
    5. Event Details

    6. Press the OK button to close the Event Details dialog.
  3. Close the model and exit the Eclipse Application.
    1. Select File -> Close to close customer model.
    2. Select File -> Exit to exit the Eclipse Application.

Step G: Create an Ecore2Ecore mapping

  1. Create an Ecore2Ecore mapping between the original and new schema versions.
    1. Select the customer2006.ecore file available in the model folder of the project imported in step B.
    2. Right-click and select Map to Ecore... from the pop-up menu.
    3. Expand the Workspace and org.eclipse.emf.tutorial.advanced.po twisties in the Resource Selection dialog, select the customer.ecore Ecore model, and press the OK button.
    4. Resource Selection

    5. Select the id attribute of the Customer class in the input Ecore model (on the left), select the identifier attribute of the Customer class in the output Ecore model (on the right), and select the Ecore to Ecore Mapping Editor -> Create Mapping menu item.
    6. id to identifier mapping

    7. Select the vip attribute of the Customer class in the input Ecore model (on the left), select the vIP attribute of the Customer class in the output Ecore model (on the right), and select the Ecore to Ecore Mapping Editor -> Create Mapping menu item.
    8. vip to vIP mapping

    9. Select File -> Save to save the mapping.

Step H: Generate an Ecore2XML mapping

  1. Generate an Ecore2XML mapping between the original and new schema versions.
    1. Select the customer2006_2_customer.ecore2ecore file available in the model folder of the project imported in step B.
    2. Right-click and select Generate Ecore to XML Mapping... from the pop-up menu.
    3. Ecore to XML mapping

    4. Explore the mapping in the editor that has opened.


Step I: Customize the Resource Factory to Support Data Migration

  1. Add a dependency to the org.eclipse.emf.mapping.ecore2xml plug-in.
    1. Select the plugin.xml file available in the org.eclipse.emf.tutorial.advanced.po project folder.
    2. Right-click, and select Open With -> Plug-in Manifest Editor from the pop-up menu.
    3. Select the Dependencies tab and press the Add... button.
    4. Select the org.eclipse.emf.mapping.ecore2xml plug-in and press the OK button.
    5. Plug-in dependencies

  2. Customize the CustomerResourceFactoryImpl.java class.
    1. Open the CustomerResourceFactoryImpl.java source file available in the org.eclipse.emf.tutorial.advanced.customer.util package of the project imported in step B.
    2. Uncomment the commented code in the createResource(URI) method and select File -> Save to save the changes.
    3. Customized resource factory implementation

    4. Analyze the customized resource factory implementation.

Step J: Try Again to Open the Model Instance

All steps below will be done in a second, testing workbench, or Eclipse Application workbench.

  1. Launch the Eclipse Application again.
    1. Select your plug-in project org.eclipse.emf.tutorial.advanced.po in the Package Explorer.
    2. Select Run As -> Eclipse Application from the Run toolbar drop-down or menu. Note that the Run menu is context-sensitive, so options available under Run As will change depending on where your cursor is (which view/editor and what file type).
    3. Once it opens, close or minimize the Welcome view (if open).
    4. Open the My.Customer file available in the customers project created in step D. Notice that the contents of the editor that opens don't look quite right - something is wrong.
  2. Try to open your customer model.
    1. Open the My.Customer file available in the customers project created in step D. Notice that the contents of the editor look right this time.
    2. Select the Window -> Show View -> Error Log menu item to open the Error Log view. No new errors should be listed.
    3. Expand the platform:/resource/customers/My.customer resource to see the Customer object.
    4. If the Properties view isn't already showing, right-click the Customer object and select Show Properties View from the pop-up menu. Notice that the properties of the customer have the names from the new schema.
  3. Close the model and exit the Eclipse Application.
    1. Select File -> Close to close customer model.
    2. Select File -> Exit to exit the Eclipse Application.

Summary

You experimented with Ecore2Ecore mappings, Ecore2XML mappings, and extended metadata, and how they can be used to support backward compatibility.