Plugin Development Guide

The Model

The model layer exposes the entities which refine the global d2 model. The union of all the entities provided by the various plugins activated for a given project forms the model for that project.

The entities composing the model layer are nothing but mere POJO augmented with JPA annotations [JPA].

A Typical entity will be similar to this:

package org.decisiondeck.myplugin.model;

import javax.persistence.Entity;
import javax.persistence.Table;
import javax.persistence.ManyToOne;
import javax.persistence.JoinColumn;
import javax.persistence.Column;
import javax.persistence.CascadeType;
import javax.persistence.FetchType;
import javax.persistence.Transient;

import org.decisiondeck.model.base.AbstractEntity;
import org.decisiondeck.model.core.Criterion;

@Entity
@Table(name="MyPluginID_MyPersistentBean")
public class MyPersistentBean extends AbstractEntity
{
    @ManyToOne(cascade={CascadeType.PERSIST, CascadeType.MERGE, CascadeType.REFRESH}, fetch=FetchType.EAGER)
    @JoinColumn(name="Criterion_ID", unique=false, nullable=false, insertable=true, updatable=true)
    private Criterion criterion;

    @Column(name="Weight", unique=false, nullable=true, insertable=true, updatable=true)
    private Float weight;

    @Transient
    private int foo;

    public Criterion getCriterion()
    {
        return criterion;
    }

    public void setCriterion(Criterion criterion)
    {
        this.criterion = criterion;
    }

    public Float getWeight()
    {
        return weight;
    }

    public void setWeight(Float weight)
    {
        this.weight = weight;
    }

}

We declare here that the POJO MyPersistentBean is a persitent entity (@Entity annotation) that maps to “MyPluginID_MyPersistentBean” table (@Table annotation). Its properties criterion (@ManyToOne annotation) and weight (@Column annotation) are persistent but not the foo attribute (@Transient annotation). Also we distingate between simple properties (of primitive type) which map to database primitives (Column) and relationships that map to database relations (ManyToOne, OneToMany, OneToOne and ManyToMany annotations). Please refer to [JPA] for more information.

It is also required to register those persistent beans within the d2 environment. This is done declaratively through the plugin.xml descriptor. You need to add a “refines” element such as the one described below:

<refines>
        <entityProvider>
                <id>org.decisiondeck.myplugin</id>
                <entityNames>
                        <entityName>org.decisiondeck.myplugin.model.MyPersistentBean</entityName>
                </entityNames>
        </entityProvider>
</refines>

This tells the plugin engine that a new persistent class should be registered with Hibernate. In return Hibernate needs to be able to access this class. For that purpose you need to add the following entry in your bundle MANIFEST:

Eclipse-RegisterBuddy: org.decisiondeck.dao.core,
 org.decisiondeck.lib.hibernate

This will make your classes available to both org.decisiondeck.dao.core and org.decisiondeck.lib.hibernate bundles.

The data access layer

As said before data access is achieved through Hibernate. Thus you don’t have to deal with JDBC directly (except for the most extreme cases), but you will rather converse with the database throughout Hibernate API. You need to create a DAO (Data Access Object) class that will encapsulate the calls to Hibernate. A generic dao which covers the selection, removal and update of entities, is provided by the org.decisiondeck.dao.core bundle.

Two cases may arise : either your persistent bean depends on the project, or it doesn’t. In the first case your DAO should inherit from ProjectEntityDao, in the second case it should inherit from GenericDao. In both case, you just have to handle specific situations since all generic persistence scenarios are already dealt with in the superclass.

For instance suppose you want to retrieve all the MyPersistentBean instances whose weight property is greater than a given value, you would create such a DAO:

public class MyPersistentBeanDao extends ProjectEntityDao<MyPersistentBean>
{
    public MyPersisteBeanDao()
    {
        //required
        setManagedClass(MyPersistentBean.class);
    }

    public List<MyPersistentBean> selectHighValues(Float f, boolean strictly)
    {
        Criteria criteria = getSession().createCriteria(MyPersistentBean.class);

        if ( strictly )
        {
                criteria = criteria.add(Restrictions.gt("weight", f));
        }
        else
        {
                criteria = criteria.add(Restrictions.ge("weight", f));
        }

        //criteria.list returns a non modifiable list
        return new ArrayList<MyPersistentBean>(criteria.list());
    }
}

You could also request a generic dao:

IDao<MyPersistentBean> dao = DaoRegistry.getInstance().createGenericDao(MyPersistentBean.class);

   or, if MyPersistentBean depends on the project :

IDao<MyPersistentBean> dao = DaoRegistry.getInstance().createProjectEntityDao(MyPersistentBean.class);

You may want to read the Hibernate documentation [HIB] to learn more about the various ways to query the database.

The service layer

This layer encapsulates the various entity managers. In d2 context these managers often don’t do much more than delegating to the DAO. For instance:

public class MyPluginService
{
    public void save(MyPersistentBean myBean)
    {
        try
        {
            DaoRegistry.getInstance().getDao(MyPersistentBean.class).save(myBean);
            ModelEventManager.getInstance().fireEntityEvent(ModelEventType.UPDATED, myBean);
        }
        catch (DaoException e)
        {
            throw new ServiceException("Unable to save entity", e);
        }
    }
}

Event management

Events are triggered whenever an entity is created, modified, deleted, and about to be persisted or removed. If you need to be notified when such an event occur you simply register an IModelEventListener as shown below:

ModelEventManager.getInstance().registerListener(
        new IModelEventListener()
        {
            public Class<?>[] getEntityClasses()
            {
                return new Class[] { MyPersistentBean.class };
            }
            public void handleEntityEvent(ModelEvent event)
            {
                ...
            }
        }
);

You will be notified of any persistent changes of instances of MyPersistentBean (and only instances of that class). The parameter event passed to handleEntityEvent allows to know which entities have changed and the type of the event triggered.

ModelEventType type = event.getType();
List<AbstractEntity> changedEntities = event.getEntities();
...

A pre removal (resp. pre persist) event is triggered whenever an entity is about to be deleted (resp. persisted). When you receive such an event you can either raise a veto, or take certain actions to ensure that your model is consistent. For instance:

ModelEventManager.getInstance().registerListener(
         new IModelEventListener()
         {
             public Class<?>[] getEntityClasses()
             {
                 return new Class[] { Criterion.class } ;
             }

             public void handleEntityEvent(ModelEvent event)
             {
                 if ( event.getType() == ModelEventType.PREREMOVE )
                 {
                     if ( preventCriterionRemoval() )
                     {
                         throw new VetoException("[MyPlugin] Reason of the veto");
                     }
                     else
                     {
                         //delete or update relevant entities (or do nothing)
                         ...
                     }
                 }
             }
         }
     );
 }

The UI Layer : Configuration

Plugin configuration implies editing two files:

• /META-INF/MANIFEST.MF

• /plugin.xml

  In the manifest file, add org.decisiondeck.view (eventually org.decisiondeck.view.core as well) to be able to access the core classes.

  You can extend the UI through a few extension points (only similar to Eclipse ones : we don’t use Eclipse extension registry). If you want to plug a new Navigation item (in the navigation panel), add the following to your plugin.xml:

  <services>
          <service>
                  <extend>org.decisiondeck.NavigationMenuItem</extend>
                  <id>ITEM ID</id>
                  <className>YOUR CLASS NAME HERE</className>
                  <roles>
                          <role>coordinator</role>
                          <role>decision maker</role>
                  </roles>
          </service>
  </services>
  

  The registered class must implement org.decisiondeck.view.navigation.INavigationMenuItem interface. you may want to inherit from the abstract class org.decisiondeck.view.navigation.AbstractNavigationMenuItem.

  The roles list the authorized roles for the items. Roles not listed there won’t see the navigation item. For now new roles can’t be registered and only three roles exist:

  • coordinator
  • decision maker
  • evaluator