Exercise 1. Cross-Resource Containment

What This Exercise Is About

In the tutorial you've learned that containment references can be split across multiple files. The slides contained code snippets demonstrating how to use this feature in your application. This exercise presents how to use the generated editor to accomplish the same results.

The following UML diagram represents the model used in this exercise.

What You Should Be Able To Do

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

• Customize .ecore and .genmodel files to allow cross-resource containment.
• Specify the resources that contain the instances in your model.

Required Materials

• Eclipse 3.2
• Eclipse Modeling Framework (EMF) 2.2

General Advice / Warnings

• Eclipse conventions suggest naming plug-in projects with a fully qualified plug-in ID, such as com.example.po. Do not use dashes in project names - this will create invalid entries in your MANIFEST.MF file.
• Make sure you're using the IBM JDK or else have implemented the Sun JDK Crimson DOM bug workaround (http://eclipse.org/emf/downloads-xerces.php).

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/Exercise1_CrossResource_Containment 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/Solution1 contains examples of the files you will create during this exercise.

Directions

Step A: Verify workbench configuration

1. Ensure Eclipse is running, and that EMF is properly installed.
1. Bring up the Help -> About Eclipse SDK dialog.
2. Click on Feature Details. Click the Feature Id column heading to order the features by that field. Then, check that at least the following EMF features are listed:

• org.eclipse.emf
• org.eclipse.emf.source
• org.eclipse.xsd
• org.eclipse.xsd.source

2. Ensure that the JDK used by Eclipse is valid.
1. Bring up the Help -> About Eclipse SDK dialog.
2. Click on Configuration Details. Scroll down to where eclipse.vm is shown. This should be something like:
   eclipse.vm=c:\ibm-java2-1.4\bin\java,
   eclipse.vm=/opt/ibm-java2-1.4/bin/java, or similar
3. If your Eclipse install has defaulted to using the Sun JDK 1.4, you must use a different one to avoid a bug in the Crimson DOM when importing from XSD. The following JDKs will work:
• IBM JDK 1.4.2sr2 or later
• IBM JDK 5.0
• Sun JDK 5.0

Step B: Import the project into the workspace

1. Switch to the Java perspective, if not already there.
1. Select Window -> Open Perspective -> Java.
2. Select File -> Import....
3. Expand the twisty next to General and select Existing Projects into Workspace. Hit Next >.
4. Keep Select root directory selected, enter the full path of the org.eclipse.emf.tutorial.advanced.po folder located in this exercise's folder, and hit Enter. You can also use the Browse... button to navigate up to this folder.
5. Make sure org.eclipse.emf.tutorial.advanced.po is selected in the Projects list and select Finish.

Step C: Customize the Generator and Ecore Models to allow Cross-Resource Containment

1. Enable the Containment Proxies option in the PurchaseOrder generator model.
1. Open the PurchaseOrder.genmodel file available in the model folder of the project imported in step B.
2. Select the topmost node PurchaseOrder, right-click, and select Show Properties View (if this view is not already shown).
3. Scroll the Properties view to find the Model twisty. Underneath is the Containment Proxies property. Set that property to true.



2. Ensure that the PurchaseOrder's items reference is resolving proxies.
1. Open the po.ecore file available in the model folder of the project imported in step B.
2. Select the items reference of the PurchaseOrder class, right-click, and select Show Properties View (if this view is not already shown).
3. Scroll the Properties view to find the Resolve Proxies property and verify that it is set to true.

Step D: 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.
2. Select the topmost node PurchaseOrder. Make sure you select the genmodel root, not a package or class below in the tree, as the selected node will determine what artifacts are generated. The benefit here is that if you later make changes that affect just a single class, you can regenerate only the relevant code, which is faster than regenerating everything.
3. Right-click and select Generate All.



4. 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.
2. 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.
3. Observe the Problems view. There should be warnings about code never being used locally. These stubs will be used by tests that you could write to test your model, but that is out of the scope of this exercise. You can safely ignore these warnings.

Step E: Create a Model Instance (Run Generated 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.
2. The PurchaseOrder 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 po, 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 PO Model. Click the Next > button.
6. Enter a file name for the PurchaseOrder model, such as PO.po. Make sure it ends with a .po extension. Then, click the Next > button.
7. Select Purchase Order as the model object and click the Finish button.
8. The newly created PurchaseOrder model is opened in an editor.
3. The root object in this editor corresponds to the PO.po resource. Under it lies an instance of the PurchaseOrder class.
4. The steps below will show you how to use the model editor to create instance data. You can also skip this step by copying the Solution1/data/PO.po file to your runtime workspace, then editing the resulting file if desired.
1. Expand the platform:/resource/po/PO.po resource to see the Purchase Order object.
2. Right-click the order and select New Child -> Item from the pop-up menu. A new Item is added to the purchase order.
3. If the Properties view isn't already showing, right-click the new Item object and select Show Properties View from the pop-up menu.
4. In the Properties view, click on the Value column of the Product Name property, and provide a name for the item ("p1" for example). The label in the editor will be updated when you hit <Enter>.
5. Repeat the last steps to add one or two more items, using different names for each item.
6. Select File -> Save to serialize the purchase order.

Step F: Split the objects into separate files

All the objects created until now are located in the PO.po resource. In this step, you will use the Control... menu action to place the items in different resources. In this context, "to control an object" means to separate it from the resource of its container and, similarly, "to uncontrol the object" means to put it back in the containment tree.

1. Right-click the first item created in the previous step and select Control... from the pop-up menu.
2. Enter the URI ("platform:/resource/po/items.po" for example) of the new resource that will store the selected item or use the Browse Workspace... button.
3. Press the OK button when done.



4. Notice the changes in the editor:
1. The "controlled" item has now a visual indication that it is located in a separate resource.
2. The new resource is loaded in the editor's resource set, hence presented in the tree viewer



5. Select File -> Save to save the changes made to the purchase order.
6. Notice that the items resource is now available in the workspace. Open this resource and analyze its content.



7. Spend a couple of minutes experimenting with the other items. Try to control them to either new or existing resources.

Step G: Bring the objects together

1. "Uncontrol" all controlled items.
1. Right-click one of the controlled items in the editor for the PO.po resource and select Uncontrol.
2. Notice the changes in the editor. The items are now located in the PO.po resource (but the resources containing them were not deleted).



If all items are located in the PO.po resource, the other resources (items.po for example) won't be loaded into the editor's resource set the next time the resource is opened.

Summary

You customized an existing model to enable cross-resource containment and generated the model, edit, and editor code. You created an instance of the model and controlled one or more contained objects.