Creating the Entity Domain Model

This tutorial will take you step by step through creating the Entity domain model using EMF. The completed domain model is available in the source tree, but may not exactly match this tutorial due to refactoring since this tutorial was created. The UML diagram for the model created in this tutorial is:

To get started creating the model, launch Eclipse (I assume you are using Eclipse 3.7 or later and have EMF installed) and create a new Empty EMF Project. For the project name, I've used org.eclipselabs.etrack.domain.entity.

The wizard will create a plugin project, and you may notice that the MANIFEST.MF is incomplete. The EMF generator will automatically add the necessary headers to the manifest when the Java classes are generated. Expand the newly created project, select the model folder and create a new Ecore Model. Name the model entity.ecore.

The wizard will create an empty model and open it with the ecore editor. The first thing we'll do is to model the package to hold the classes. Right-click in the editor and select Show Properties View. Expand the top level platform node in the editor and select the package node (looks like a purple square). Using the properties view, set the following values for the package:

• Name: entity
• Ns Prefix: org.eclipselabs.etrack.domain.entity
• Ns URI: http://www.eclipselabs.org/etrack/domain/entity

You must specify the name, prefix, and URI for the package. The name will be used as part of the java package name for the generated code. The prefix and URI are used by EMF to identify your model and must be unique across all models in your system.

Now, we can define the classes in the Entity Domain model. We will start by creating the Address class along with its attributes. A class is defined in EMF as an EClass and attributes are defined in EMF as an EAttribute. To create an EClass, right-click on the package and select New Child -> EClass. In the properties view, set the Name to Address. To create an EAttribute, right click on the Address class and select New Child -> EAttribute. Using the properties view, set the EType to EString and set the Name to street.

The remaining Address attributes are created the same way as the street attribute. After creating the remaining attributes, your Address EClass should look like:

Create the Email and Phone classes the same way you created the Address class. The Address, Email, and Phone classes all implement the CategorizedItem interface. EMF supports modeling interfaces with attributes which causes all classes implementing that interface to include the attributes modeled in the interface. To create the CategorizedItem interface, right-click on the package and select New Child -> EClass. In the properties view, set the Name to CategorizedItem, set Abstract to *true, and Interface to true. Add an EAttribute with Name set to category and EType set to EString

To tell EMF that Address implements CategorizedItem, select Address and in the properties view, click to edit the ESuper Types property. To the right of the field, click the ... button that appears. This is how you edit multi-valued properties in the view.

From the Choices panel, choose CategorizedItem and click Add, then click OK*.

Repeat this procedure for the Email and Phone classes. Your ecore model should now look like:

We are almost ready to model the Entity class. The Entity class does not have any attributes, only references. References are modeled in EMF as an EReference. The Entity class has references to Address, Email, Phone, and LinkMap. So far, we have modeled all except LinkMap. LinkMap has a key attribute and a value reference to a LinkedContent. We are going to model a LinkMap such that references to it are created as a Map instead of a List. First, model LinkedContent just as you did for Address. Then model LinkMap as an EClass and in the Instance Type Name to java.util.Map$Entry.

Creating an EClass of instance type java.util.Map$Entry with a key and value EStructuralFeature (EAttribute or EReference) tells EMF to create a Map<key_type, value_type> where key_type is the EType of the key structural feature and value_type is the EType of the value structural feature. To model the key attribute, right-click on LinkMap and select New Child -> EAttrubte. The attribute name must be key, and in our case the type is EString. To model the value EReference, right-click on LinkMap and select New Child -> EReference. Set the Name property to value, Containment to true, and EType to LinkedContent.

All of the classes referenced by the Entity class are modeled so we can now model an Entity. Create an EClass named Entity and add an EReference for each of the Address, Email, Phone, and LinkMap types. For each of the references, set Containment to true, Resolve Proxies to false, and Upper Bound to -1.

Setting resolve proxies to false will cause the referenced object to be embedded in the referencing object when persisted. In this case, when an Entity instance is retrieved by a client, the Address, Email, Phone, and LinkMap instances will be included in the transfer over the network. In the case of the LinkMap reference to LinkedContent where resolve proxies was set to true (cross-document containment), the LinkedContent instance is persisted in a separate resource and will not be transferred over the network when the client obtains an instance of an Entity. Only when the LinkMap value is access will the proxy be resolved and the instance transferred over the network to the client.

Creating a Person, by now, should be straightforward. A Person is simply an EClass with two attributes and an Entity as the super type.

A Group is similar to a Person except that is has a non-containment reference to Entity. When creating the EReference, leave Containment set to false.

Your ecore model is complete (be sure to save it) and should look as follows:

Once the ecore model is ready, the next step is to create an EMF genmodel. Using the New wizard, select EMF Generator Model and click Next.

Choose the model directory to contain the generator model, set the File name to entity.genmodel and click Next.

Select Ecore model for the model importer and click Next.

Set the Model URIs to platform:/resource/org.eclipselabs.etrack.domain.entity/model/entity.ecore, click Load, then click Next. If you have the entity.ecore file selected in the navigator when you bring up the new wizard, the URI will be automatically filled out for you.

Make sure the entity package is checked, then click Finish

When the genmodel editor opens, select the Entity root node and in the Properties view, set Containment Proxies to true. Also set Suppress Interfaces to true. By default, EMF will generate an interface and implementation for each of the modeled EClass objects. It is not absolutely necessary to suppress the interface generation, but I find the interfaces unnecessary when creating domain (data) models.

Expand the root Entity node and select the Entity package. In the Properties view, set the Base Package to org.eclipselabs.etrack.domain. Save the genmodel.

Select the Entity root node in the genmodel editor again, right-click, and one-by-one, select the following:

• Generate Model Code
• Generate Edit Code
• Generate Editor Code

When you generate the model, EMF will create Java classes from your ecore, and also complete the MANIFEST.MF. When you generate the edit and editor code, EMF will create two new bundles in your workspace. If you expand the source tree in your model bundle, you should see:

The editor generated by EMF is suitable for experimenting with your newly created domain model. Let's launch a runtime workbench and create an entity model. Right-click on the editor bundle and select Run As -> Eclipse Application. The runtime workbench will appear. Create a new General Project with any name you like. Using the New wizard, create a new Entity Model and click Next.

Give the model a name that ends in .entity and click Next. Using the drop down, select Person for the model object and click Finish.

When the editor opens, right-click anywhere in the editor and select Show Properties View. Expand the root node and select the Person. You can use the properties view to set their first and last name. To add an address to the person, right-click the Person node and choose New Child -> Address. The address should be automatically selected and you can use the properties view to set the address attributes.

You have just created a domain model from scratch, complete with a working editor for experimenting with the model. Once you are comfortable with EMF, you will find that creating a domain model takes minutes instead of days.