Exercise 2. The Static API: Creating, Loading, Saving
What This Exercise Is About
Using the Purchase Order model you generated in Exercise 1, you will
now load a model instance and make changes to it programmatically.
In Exercise 1, we generated an editor that integrates into the
Eclipse IDE. EMF can also be used in standalone applications, headless
Eclipse applications, and RCP (Rich Client Platform) applications. In
all cases, you can use the same APIs to load, save, and modify your
data. In this exercise, you will work on a simple, standalone
application, with no dependency on the Eclipse platform.
For your reference, here again is the UML class diagram describing
the purchase order model:

What You Should Be Able To Do
At the end of the
lab, you should be able to:
- Create and configure a Java project for standalone development with EMF
- Programmatically create an instance of a generated model
- Modify items in a model instance
- Load and save model instance data
Required Materials
- Eclipse 3.2
- Eclipse Modeling Framework (EMF) 2.2
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."
In your workspace, there should be a EMF_Workshop/Exercise2_Create_Load_Save folder
that contains these instructions, as well as the following three files:
- CreatePOInstance.java shows how to create a model instance programmatically. Review it to get a feel for what's required to perform this step. Note that the code does not show how to save the generated instance, which we will be doing in this exercise.
- po.xml contains the instance data that would be generated from CreatePOInstance.java, if that data was then serialized to a file. This will be your starting point for this exercise. We will first load this instance, then change it, and save the modified data to a second file.
- Exercise2.java is the class you will modify to perform the work noted above.
The solution to this exercise is available in the EMF_Workshop/Solution2 and
EMF_Workshop/Solution2_Optional folders. Each contains a complete project with
source code and data.
Directions
Step A: Verify workbench configuration
- See Exercise 1, Step A.
Step B: Create & Configure a Java Project
- Switch to the
Java Development perspective, if not already there.
- Select Window
-> Open Perspective -> Java.
- Import the required EMF dependencies to the workspace as linked binary projects.
- Right-click in the Package Explorer and select Import... (or select File -> Import/Export...).
- Select Plug-in Development -> External Plug-ins and Fragments. Hit Next.
- Select Select from all plug-ins and fragments found at the specified location.
- Select Binary projects with linked content. Hit Next.
- Using the text field or by scrolling in the left-hand list, search for:
- org.eclipse.emf.common
- org.eclipse.emf.ecore
- org.eclipse.emf.ecore.change
- org.eclipse.emf.ecore.xmi
- org.eclipse.xsd
- These plugins contain the runtime EMF libraries we'll need in this and following exercises. Select them, then hit Add --> to add them to the right-hand list. Hit Finish.
- Create a new Java Project, called Exercises, with a separate source and output folders called src and bin.
Add the EMF dependencies and the existing com.example.po project, which contains the generated model, to the new project's build path.
- Right-click in the Package Explorer, and select New -> Project..., or just hit CTRL-N.
- Select Java Project and Hit Next.
- Name the project Exercises.
- Select the radio button for Create separate source and output folders.
- Click Configure default...
- Under Source and output folder, select Folders. Source folder name and Output folder name should be set to src and bin, respectively. Click OK. Hit Next.
- Switch to the Projects tab, and click Add....
- Select the following projects:
- com.example.po
- org.eclipse.emf.common
- org.eclipse.emf.ecore
- org.eclipse.emf.ecore.change
- org.eclipse.emf.ecore.xmi
- org.eclipse.xsd
- Click OK, and then Finish to close the wizard.
- Review the classpath file for the Exercises project.
- Eclipse stores a project's build path information in a .classpath file. To see it, switch to the Navigator view (Window -> Show View -> Navigator), then open the Exercises project folder.
- Open the .classpath file to see what Eclipse has generated for you. Eclipse uses this information to ensure that the correct .class and .jar files are on the classpath when compiling the project.
- Switch back to the Package Explorer view.
- Create a data folder in the root of the Exercises project.
- Select the root of the Exercises project in the Package Explorer.
- Right-click and select New -> Folder, or just hit CTRL-N and browse for General -> Folder.
- Set the name to be data. Hit Finish.
- Copy po.xml from the Exercise 2 source folder to the Exercises/data folder.
- Select po.xml, then hit CTRL-C to copy (or Edit -> Copy).
- Select the new data folder created in the last step, Exercises/data, and hit CTRL-V to paste (or Edit -> Paste).
- Create a package under the src folder in the Exercises project, called exercises.
- Select the src folder under Exercises in the Package Explorer.
- Right-click and select New -> Package, or just hit CTRL-N and browse for Java -> Package.
- Set the name to be exercises. Hit Finish.
- Copy java code from the Exercise 2 source folder into Exercises/src/exercises.
- Select CreatePOInstance.java and Exercise2.java, then hit CTRL-C to copy (or Edit -> Copy).
- Select the new package created in the last step, Exercises/src/exercises, and hit CTRL-V to paste (or Edit -> Paste).
Step C: Load the Model Instance
- Switch to the
Java Development perspective, if not already there.
- Select Window
-> Open Perspective -> Java.
- Open the file Exercise2.java.
- Work your way through the loading portion of the exercise by filling in the missing code for each of the first six TODO comments.
- The last TODO in this step is to print out the shipTo address data.
- You can activate Eclipse's code completion by pressing CTRL-SPACE. Selecing a class or member name and then pressing F2 will display the Javadoc; F3 will jump to the declaration. These shortcuts provide a good way to explore the APIs for EMF and your model.
- If you run into trouble or are pressed for time, you can copy code from the JPages folder under the Exercise 2 source folder.
- Run your code. There are several ways to do this.
- Right-click in the body of the Java file, and select Run As -> Java Application.
- Select from the Run menu Run As -> Java Application.
- Click the Run button in the coolbar (a green circle with a white triangle in it, or a "play" button) and select Run As -> Java Application.
- Hit SHIFT-ALT-X (eXecute). Wait one second for the context menu to open, then then hit J (Java Application).
You should see the following output:
name: Scarlet O'Hara
street: 321 Backwoods Lane
city: Louisville
state: AL
zip: 67655
Step D: Modify the Data
- The next two TODOs describe a change that you should make to the data. Fill in the missing code.
To remove an item according to its part number, you'll need to iterate through all of the items in the purchase order, checking that attribute.
- You can try running the application again, though no additional output will be produced.
Step E: Save the Modified Instance
- Fill in the code for the final TODO, to put the updated purchase order in
a new resource and serialize it to the console and a new file.
- Run again from the Run menu, the Run button, a right-click, or hit CTRL-F11. You should see the following output:
name: Scarlet O'Hara
street: 321 Backwoods Lane
city: Louisville
state: AL
zip: 67655
<?xml version="1.0" encoding="UTF-8"?>
<po:order xmlns:po="http://www.example.com/po" orderDate="2006-03-20">
<shipTo>
<name>Scarlet O'Hara</name>
<street>321 Backwoods Lane</street>
<city>Louisville</city>
<state>AL</state>
<zip>67655</zip>
</shipTo>
<billTo>
<name>Rhett Butler</name>
<street>123 Iditarod Lane</street>
<city>Nome</city>
<state>AK</state>
<zip>34582</zip>
</billTo>
<po:comment>Plasma Television (STV999876) is discontinued and
has been removed from the order.</po:comment>
<items partNum="SWH123456">
<productName>Wireless Headphones</productName>
<quantity>2</quantity>
<price>75.0</price>
<po:comment>Backordered</po:comment>
<shipDate>2006-03-23</shipDate>
</items>
</po:order>
- Compare the contents of the new po-updated.xml file to the above console output.
- Select the data folder in the Package Explorer. Right click and select Refresh from the pop-up menu, or just hit F5.
This refreshes the workspace view of that folder based on the state of the actual file system.
- Open the new po-updated.xml file in the text editor.
Step F: [Optional] Run Code On The Commandline (No Eclipse)
- If you need to know how to run an Eclipse launch configuration without Eclipse, follow these steps:
- Switch to the Debug perspective (Window -> Open Perspective -> Debug).
- Right-click the last entry in the Debug view, and select Properties.
- If you execute the given command line from the Exercises folder (or save to a .bat or .sh file in the root of the Exercises project folder), you will produce the same data/po-updated.xml file as in the preceeding step.
- Under Windows, you may not get console output unless you change javaw to java.
- Under Linux, you may have to set execute permission on the script file before you can execute it.
Step G: [Optional] Open the Updated Model Instance in the PurchaseOrder Model Editor
- If you want to open the po-updated.xml file in your PurchaseOrder model editor,
launch your second workbench, then copy the file into its workspace.
- Rename it to have a .po extension so that when double-clicked, Eclipse will automatically open it in your model editor.
Step H: [Optional] Update CreatePOInstance.java to Serialize the In-Memory Intance
- CreatePOInstance.java shows how to create an instance of a purchase order in memory, but does not show how to serialize that data to a file. If you would like to do so, use what you've learned above to implement a savePOData() method that saves the purchase order to po.xml.
- The solution is available in EMF_Workshop/Solution2_Optional/Exercises/src/exercises/CreatePOInstance.java.
Summary
You have learned how to load, change, and save an instance of an EMF model programmatically. You created a standalone EMF application, with no Eclipse dependencies. Although you used Eclipse to manage your classpath, you then ran the resulting code without Eclipse, directly in the Java virtual machine. Finally, you opened the modified instance in your PurchaseOrder model editor to graphically review the changes that your application made.