Introduction

The goal of this tutorial is to create an entity type by using the entities.xml file. The behavior and UI integration is not part of this tutorial, how to achieve this will be explained in further tutorials.

If there are problems with the tutorial, feel free to ask in the Developer Mailing List.

Preconditions

This tutorial requires a project that is set up according to the tutorial "Creating and configuring a new Nomad PIM plugin project".

Tutorial project access

The project that is the result of the tutorial is available in the subversion repository:

createEntityType tutorial project	The project created in this tutorial
	tutorial/createEntityType/trunk

You can use it to quickly access the tutorial results.

Entity types

Entities types are a core concept of Nomad PIM. Basically, they are somehow like classes.

The main difference is that the attributes and the behavior of classes can be extended by inheritance, whereas entity types can be extended by extension point mechanisms that allow plugins to add attributes and behavior to entity types.

It is important to note that there are no specialization semantics, which means that whereas subclassing specializes a class, an entity type behavior or attribute extension extends all entities of that type. In that sense, entity types provide a extendible, class-based programming paradigm without inheritance.

The problem that one needs inheritance is partly solved by the fact that the behavior is grouped into interface adapters, and there can be an inheritance in interfaces (which are plain old java interfaces).

Creating a notification entity type

In this tutorial, you create an entity type for notifications. This type will later be used to trigger custom notifications after a delay. The fact that the seconds are stored as an integer value is of course not perfect, but this serve in a later tutorial as an introduction to the not yet existing upgrade framework.

The first step is to change the file source/model/Entities.xml as follows:

                    
<entities 
  xmlns:ui="http://nomadpim.org/xsd/ui"
  xmlns:persistence="http://nomadpim.org/xsd/persistence">

  <entity name="Notification" package="org.nomadpim.tutorial">
    <attribute name="Title" type="String"/>
    <attribute name="Text" type="String"/>
    <!-- Delay in seconds -->
    <attribute name="Delay" type="Integer"/>
    
    <persistence:file>org.nomadpim.tutorial.xml</persistence:file>
    
  </entity>

</entities>
                      
        

I think this is mostly self-explaining. The "persistence:file"-element specifies in which file the entities are stored. If you have any questions, feel free to ask in the Developer Mailing List.

After saving, the code should be generated automatically. Lets take a look at the results.

Generated Java code

In the specified package, a class file with the name of the entity type is created. It contains a special constant "TYPE_NAME" that can be used later for referring to this entity type, and constants for each attribute that refer to a property of that specific type. The attribute constants will be used later to get attribute values from entities. Additionally, code in the class constructor is generated that does some part of linking this all to the framework.

Modified plugin.xml

The second part of linking the code to the framework is by using some extension points of the Nomad PIM core module. The file "src/model/plugin.xml" is combined with generated code to the file "plugin.xml", which is overwritten. So remember to modify "src/model/plugin.xml" instead of "plugin.xml" if you want to extend some extension points or define your own.

The modified "plugin.xml" should look like this:

                    
<?xml version="1.0" encoding="UTF-8"?>
<plugin>
<extension point="org.nomadpim.core.typeProperties">
<configuration typeName="notification" 
               configurator="org.nomadpim.tutorial.Notification"/>
</extension>
<extension point="org.nomadpim.core.type">
<configuration file="org.nomadpim.tutorial.xml" 
               typeName="notification" 
               typeClass="org.nomadpim.tutorial.Notification"/>
</extension>
<extension point="org.eclipse.ui.newWizards"/>
<extension point="org.eclipse.ui.views"/>
<extension point="org.nomadpim.core.ui.typeIcon"/>
<extension point="org.nomadpim.core.ui.typeFormatter"/>
<extension point="org.nomadpim.core.ui.editorConfiguration"/>
</plugin>
                      
        

The "org.nomadpim.core.type" extension defines new entity types, in this case the type "notification". Each type is stored in a file defined there.

The "org.nomadpim.core.typeProperties" extension adds properties to entity types. Whereas each type can only be defined once, properties may be added multiple time by different plugins, extending the type.

Congratulations!

You just created your first entity type. You can now continue with creating the basic entity UI.