Creating a plugin in DeepaMehta #hackership

Tweet

The day that I’m able to write properly DeepaMehta in the first try, will be amazing!!

Anyway, the thing is that in hackership I’m building a webcalendar as a petproject to learn more ruby & rails, but one of my goals at some point of my learning process is to work with graph databases and semantics. I find that the representation of knowledge needs graphs and the retrieve of information semantics.

A year ago, more or less, DeepaMehta appeared into my life, I found it a really, really cool project, one of those that at some point you want to take part of. No idea when or how.

DeepaMehta is a webclient and an application developpment framework and in its webpage says

DeepaMehta represents information contexts as a network of relationships. This graphical representation exploits the cognitive benefits of mind maps and concept maps. Visual maps — in DeepaMehta called Topic Maps — support the user’s process of thinking, learning, remembering and generating ideas

You also can read more about the concept behind it.

During the last DeepaMehta Lounge, a possibility was opened, to try it to use it with the webcalendar, let’s say to have it as the database behind the scene, probably is not the best thing to do, since it’s a framework and you can directly develop in it, but it’s Java, and for the moment I have no idea of Java, and I want to continue with Ruby & Rails but, having a specific idea in mind, I want to learn some basics of how DM works. So for the moment, I’m going to use it as database and communicate with it through its REST API.

So to do that I need to build a plugin. I was very lucky to be able to go through this process with some of the DM core members, so the least I can do is to share what I learned :). Let’s do it.

First, let’s install DeepaMehta, for that we have to check the requirements, as an Ubuntu user, they are the following:

DeepaMehta requires JAVA 1.6 or later:
sudo apt-get install default-jdk

For the development system you will also need to install maven and git:

sudo apt-get install maven git-core

Then I want to build DM from source so I have to clone the software from github
git clone git://github.com/jri/deepamehta.git
cd deepamehta
mvn install -P all

This may take a while, so just be patient  :). Once it has finish, you need to run DM
mvn pax:run

This starts the DeepaMehta server and then opens the DeepaMehta web client in a browser window.
If no browser window appears open it manually:

 http://localhost:8080/de.deepamehta.webclient/

You will see

There on the top-right corner is a login link, click on it and put user admin and password empty. You’re DM is ready!!

Now is time to start writing the plugin.

First you have to create a directory with the name of the plugin, better if somehow reflects that is your plugin and is uniquely identified. In my case I named the directory cgc-calendar, name that I will use as the id of the project, though is not mandatory.

Inside our directory you need to set up a specific directory structure

cgc-calendar/
    pom.xml
    src/
        main/
            resources/
                migrations/
                    migration1.json
                plugin.properties

where

• pom.xml file stands for Project Object Model and is a representation in XML of the maven project
• migration1.json A migration is a sequence of operations that transform the database, defines the database schema and ensure its structure and content is compatible with the code
• plugin.properties is a file that allows the developer to configure certain aspects of the plugin

Ok, now let’s see how the files look like.

We’ll check first the pom.xml

<project>

<modelVersion>4.0.0</modelVersion>

<name>CGC Calendar</name>
<groupId>net.abriraqui.cgc-calendar</groupId>
<artifactId>cgc-calendar</artifactId>
<version>0.1-SNAPSHOT</version>
<packaging>bundle</packaging>

<parent>
<groupId>de.deepamehta</groupId>
<artifactId>deepamehta-plugin-parent</artifactId>
<version>4.2-SNAPSHOT</version>
</parent>

</project>

Let’s try to understand a bit the file

<name> Is the human readable name of the plugin
<groupId> must be globally unique name under which you collect the project’s artifacts. So a best practice to achieve this is to write first, the top-level domain and then your specific subdomain, in my case net.abriraqui.cgc-calendar
<artifactId> is the name of the generated .jar file. Within the group this name must be unique and in my case I use cgc-calendar.

Under <parent> are all the specifications referred to DM, here you have to be careful and set correctly the <version> of DM that you are using, in my case 4.2-SNAPSHOT

Next is to define the migration1.json file, here we are including all the database structure of the app. This case is a very basic one as shown in the following diagram

So we have to translate this into a json file.
Now we have to have in mind several things, DM uses graphs to represent knowledge, so we must forget about tables, join tables, etc in DM everything are nodes and relations or in DM language, topics and associations.

• Topics – representing any concept, from people, countries, and organizations to software modules, individual files, and events,
• Associations – representing hypergraph relationships between topics

Next step is to define the migration,  we will be doing a declarative migration, that is the one using json to define it. In it you can define 4 things: topic types, association types, topics, associations. The general format is:

{
    topic_types: [
        ...
    ],
    assoc_types: [
        ...
    ],
    topics: [
        ...
    ],
    associations: [
        ...
    ]
}

This is the diagram that we have to translate to a migration in json format (migration1.json), which looks like

{
    topic_types: [
        {
            value: "Start date",
            uri: "cgc.calendar.start_date",
            data_type_uri: "dm4.core.number",
            index_mode_uris: ["dm4.core.key"]
        },
        {
            value: "End date",
            uri: "cgc.calendar.end_date",
            data_type_uri: "dm4.core.number",
            index_mode_uris: ["dm4.core.key"]
        },
        {
            value: "Event",
            uri: "cgc.calendar.event",
            data_type_uri: "dm4.core.composite",
            assoc_defs: [
                {
                    child_type_uri:        "cgc.calendar.start_date",
                    child_cardinality_uri: "dm4.core.one",
                    assoc_type_uri:        "dm4.core.composition_def"
                },

                {
                    child_type_uri:        "cgc.calendar.end_date",
                    child_cardinality_uri: "dm4.core.one",
                    assoc_type_uri:        "dm4.core.composition_def"
                }       
            ],

            view_config_topics: [
                {
                    type_uri: "dm4.webclient.view_config",
                    composite: {
                        dm4.webclient.show_in_create_menu: true
                    }
                }
            ]
          }
       ]
}

Let’s understand what it all means or at least try to 😉

We are defining different “nodes” / topics  of our graph, those are event, start_date, end_date.

Each topic_type has a

• value, is the  human readable name
• uri, the unique identifier
• data_type, to determine the type of data

In the case of the dates, we have a

value: “Start date”,
uri: “cgc.calendar.start_date”,
data_type_uri: “dm4.core.number”, there are no date type, so we use directly number to specify dates

when looking at the event we see that the data_type is a composite, which would mean that is a topic type composed of ,or that needs, other topics types to be defined. In the case of event is quite clear, it needs an start_date, end_date, to say that, we have to define the association as follows

assoc_defs: [
                {
                    child_type_uri:        "cgc.calendar.start_date",
                    child_cardinality_uri: "dm4.core.one",
                    assoc_type_uri:        "dm4.core.composition_def"
                }

So now we are almost done with the first very simplified definition of event but in order to see our topic type  in the graphical interface we need to add to the migration, some configuration info

view_config_topics: [
                {
                    type_uri: "dm4.webclient.view_config",
                    composite: {
                        dm4.webclient.show_in_create_menu: true
                    }
                }
            ]

where say that we want to see our recent created topic type in the create menu. Now in the create drop down menu of DM you will be able to see event as topic type and you can now use it in your projects 🙂

The last thing to explain is what goes inside the plugin.properties, for the moment the file consists of one line, referring to the migration

requiredPluginMigrationNr=1
importModels=de.deepamehta.webclient


Once you’ve made any changes to the plugin files, you have to build the plugin again. So in the terminal you have to put:

$ mvn clean package

In order to let DM know of the existence of your plugin(so you can see it on your browser), you must add  the plugin’s target directory (here: /home/myhome/cgc-calendar/target) to the felix.fileinstall.dir property’s CDATA section, which is in DM’s “global” pom.xml. This is found at the top-level of its home directory. Important: don’t forget to append a comma to the previous line

<project>

<felix.fileinstall.dir>
<![CDATA[
${project.basedir}/modules/dm4-core/target,
${project.basedir}/modules/dm4-webservice/target,
${project.basedir}/modules/dm4-webclient/target,
…
${project.basedir}/modules/dm4-storage-neo4j/target,
/home/myhome/cgc-calendar/target
]]>
</felix.fileinstall.dir>
…

</project>

So for a start with Deepamehta is not bad 🙂 … I’ll continue working on it, probably slowly since I have to do also the Rails part 😀 but as I do things I’ll be writing them and also I’ve set up a repo on github for it

This declares your plugin makes use of the DM Webclient data model (namely its type dm4.webclient.view_config). DM then takes care the Webclient is installed *before* the Calendar plugin. However, this is only of importance if Calendar is installed along with DM