Using the SDO Data Graph Editor

Using the SDO data graph editor
Last updated: October 12, 2004
This tutorial describes how to generate an SDO model and use the SDO data graph editor to create and edit a data graph that contains an instance of the model. The SDO data graph editor is a simple Eclipse editor for SDO data graphs, provided with the EMF implementation of SDO. It allows you to edit and serialize SDO data graphs, usually for testing purposes. However, it also serves as an example of an editor that could be used in an SDO client to edit, with intermediate saving, a data graph returned from a Data Mediator Service (DMS).
The model used in this tutorial is an XML Schema corresponding to the following UML class diagram:

The screenshots are based on version 3.0.1 of the Eclipse SDK and version 2.0.1 of EMF.
Contents
Step 1:Importing the Model from XML Schema
Step 2:Generating the SDO Model
Step 3:Creating SDO Instances with the Data Graph Editor
contents
Step 1: Importing the Model from XML Schema
This section describes how to import a model defined by a schema, in order to generate an SDO model from it. This involves creating an EMF project containing an Ecore representation of the model. EMF uses Ecore to describe models and to drive the generation of code to implement them. A generator option determines whether that code will implement the EMF or SDO API.
As a result, this step is exactly the same whether you intend to generate an EMF or SDO model. You can refer to theGenerating an EMF Model using XML Schema tutorial for more details on this first step. You can also start with other model forms, such as a Rational Rose class diagram or a set of annotated Java interfaces. For details, see theGenerating an EMF Model tutorial.
Note: If you‘re using a Sun Java Developer‘s Kit (JDK), you may see an error message (a null pointer exception or "Specify a valid XML Schema and try loading again") when importing your XSD. Refer to theinstallation instructions to fix this. If you are using an IBM JDK, this doesn‘t apply to you.
In Eclipse, we recommend you switch to the Java perspective. Then, select "File" > "New" > "Project...". In the first page of the wizard, select "EMF Project", under "Eclipse Modeling Framework". Click "Next".
In the next page of the wizard, name the project "SDOLibrary". Click "Next". Then, make sure "Load from an XML Schema" is selected and click "Next".
In the next page, click "Browse File System..." and point tolibrary.xsd. Refer to the above note if you see an error message. Click "Next".
In the last page, select the "library" package as the root package to generate and click "Finish".
By now, the framework should have created a Java project configured to use EMF/SDO, and two files in it:
org.example.library.ecore: the EMF core model for our library library.genmodel: the generator model for our library, which is opened in the main view.
contents
Step 2: Generating the SDO Model
Library.genmodel should be open in the main view. It has a "Library" model as its root, with a "Library" package under it. That "Library" package has 3 classes defined ("Book", "Library", and "Writer"), and the "BookCategory" enumerated type:

Step 2.0 Setting the SDO properties on the generator model
To view the "Library" model properties, right-click the root "Library" model and select "Show Properties View".
If you have already used EMF, you have probably noticed no difference between creating EMF and SDO models so far. However, now we must indicate that we want our model classes to implement the SDO API.
To generate SDO Java classes, right-click the "Library" root model and choose "Set SDO Defaults". You should see changes in the model properties after doing so (highlited below). For example, "Root Extends Class" (under "Model Class Defaults") changes from org.eclipse.emf.ecore.impl.EObjectImpl to org.eclipse.emf.ecore.sdo.impl.EDataObjectImpl:

Note: The Ecore model (org.eclipse.example.library.ecore) hasn‘t been modified. Only the .genmodel file is modified with SDO settings.
Save library.genmodel.
Step 2.1: Generating the model code
Right-click the "Library" root model and select "Generate Model code". This will generate Java packages, classes, and a plugin.xml file under the SDOLibrary project:

The org.eclipse.example.library package contains Java interfaces Book, BookCategory, Library and Writer, as well as an interface for a factory for creating instances of those interfaces. Note that the Library, Book, and Writer interfaces are simple Java Beans with getters and setters. They do not extend the EMF or SDO interfaces.
The org.eclipse.example.library.impl package contains Java classes which implement the interfaces defined in the org.eclipse.example.library package. If you look at the BookImpl class, for example, you will see it implements Book, and extends EDataObjectImpl. That makes it an SDO DataObject. Refer to theIntroduction to Service Data Objects article for the definitions of data object and other SDO concepts.
If you disabled automatic compilation of code, compile the code by selecting "Project" > "Build All".
contents
Step 3: Creating SDO Instances with the Data Graph Editor
This section describes how to use the SDO data graph editor to create and edit a data graph containing an instance of the generated "Library" model.
Step 3.0: Launching the Eclipse run-time workbench
Select "Run" > "Run As" > Run-time workbench:

This should launch a second instance of Eclipse, called a run-time workbench, which picks up the capability provided by our "Library" project.
Step 3.1: Creating a new Library data graph instance
In the run-time workbench, select "File" > "New" > "Project...". In the first page of the wizard, select "Project" from under "Simple" and click "Next". Name the project "MyLibrary" and click "Finish".
Right-click the "MyLibrary" project and select "New" > "Other...". Then, select "Data Graph Model" under "Example EMF Model Creation Wizards" and click "Next". Click "Next" again to accept the default file name.
In the next page of the wizard, we must select the model and class to instantiate in the data graph. The "Model URI" combo box contains namespace URIs identifying all of the EMF models registered with the framework. However, we may only select a model that has been generated with "Set SDO Defaults" to implement the SDO API.
Select http://www.example.eclipse.org/Library as the "Model URI", and Library as the "Model Object":

Click "Finish".
This creates and opens a new SDO data graph instance, My.datagraph, in the data graph editor, with an SDO data object of type "Library" as its root object, and an SDO change summary. If you expand "My.datagraph" and "Data Graph", you should see the following:

Step 3.2: Creating instance SDO data objects attached to the instance data graph
Right-click the root "My.datagraph" model and select "Show Properties View".
In the SDO programming model, data graphs contain a "change summary" and logging should be turned on before any changes are made. This is so that SDO Data Mediator Services (DMSs) know what was changed in a data graph since its creation. Typically, DMSs turn on change logging before they provide a data graph to clients.
From the data graph editor, turn on logging by right clicking "Changes logging=false" and selecting "Start Logging":

Now, we‘ll create instances of "Book" and "Writer" and make sure the constraints defined inlibrary.xsd are enforced by the editor. Later, we‘ll also see how the SDO constraints are enforced.
In the properties view, name the "Library" root object, for example, "The Open Library".
Then, in the data graph editor, right-click the "Library" object and select "New Child" > "Writer":

In the properties view, name this writer, for example, "Erich Gamma".
From the data graph editor, right-click the "Library" root object and this time select "New Child" > "Book".
In the properties view, specify the book title, for example, "Contributing to Eclipse". Click the value field for the "author" property of the book. From there you will be able to select the author you created before:

Now create another instance of "Book" (e.g., with title "Eclipse Modeling Framework"), and "Writer" (e.g., "Frank Budinsky"). You have two options to do so. Either from the "Library" root object, as described previously, or from one of the existing books or authors, using the "New Sibling" context menu. Select the new book and set its author to the new author in the properties view.
If you select the "Contributing to Eclipse" book, and try to change the value of its author property, you will see the editor will not let you have more than one author for it (as defined in the model). However, if you select an author instance, you will be able to specify zero or more books associated with it. For example, highlight the "Erich Gamma" writer and in the properties view, click the value field for "books" and then the "..." button on its right-hand side:

A dialog box pops up. On the right-hand side are the choices available for the multiplicity-many "books" reference. On the left-hand side are the currently selected values. Select the "Eclipse Modeling Framework" book and click "Add". Note that the list of books is ordered and you can modify the order:

Click "OK".
As a result of doing this, the "Frank Budinsky" author will no longer have any association with the "Eclipse Modeling Framework" book. That is because the model says a book can only have one author.
Step 3.3: Looking at the changes made
Now that we are done making changes to the data graph, we will turn logging off. In the data graph editor, right-click "Changes logging=true" and select "Stop Logging". Doing this turns off change recording, thereby providing a summary of the modifications that were made to a data graph since logging was turned on (typically since its creation).
The SDO change summary is in a format that allows DMSs to update backend data sources efficiently and incrementally. In this example, there is no data source or DMS (you are acting as the DMS by creating instance data objects).
If you expand "Changes", you should see something like this:

These are all the changes made while change summary logging was enabled. Note that "Changes" has a property named "Objects to Detach". These are all the objects that were added to the data graph (and which need to be detached to roll-back).
We already made sure that the editor enforced the constraints imposed by the model. SDO itself imposes constraints on data graphs, too.
The first constraint is that a data graph can only have one root object, in our case the "Library" object. If you try, you‘ll see that you won‘t be able to add other children directly to the "Data Graph" object or any siblings to the "Library" object.
The second constraint is that a data graph needs to respect closure. Simply put, this means that all the data objects in a data graph need to be (directly or indirectly) contained (the black diamond association) by the root object. This is fine in our case because we choose "Library" as the root object, and it has black-diamond associations with both "Book" and "Author". However, we couldn‘t have choosen an instance of "Book" as the root object and added instances of "Writer" because those writers wouldn‘t have been "contained" by the "Book" root object.
Step 3.4 Serializing the data graph
Now you can save the data graph. Doing so will serialize "My.datagraph" to an XML instance document on disk.
Close "My.datagraph". In the navigator view, right-click "My.datagraph" and select "Open With" > "Text Editor". This will show you the serialization format, which is the same as the on-the-wire format used by SDO clients and DMSs.