Dec 272013
 

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

Deepamehta

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

webcalendar UML

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: [
        ...
    ]
}

So a simplyfied representation of the event should look like something similar to

webcalendar2

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

The first line is require in order to be able to run the migrations and the second line
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.

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

  3 Responses to “Creating a plugin in DeepaMehta #hackership”

  1. Thank you for this great article! It provides a good help in making DM approachable for new developers! I appreciate the clear language and structure as well as the handcrafted illustrations.

    While our personal “hackership”, which I enjoyed very much, I was not always as clear/complete as I could have been. So here I like to fill some of my gaps resp., relating to your article, suggest some improvements:

    – Before the introducing quote you could say that DeepaMehta is both, a *Webclient*, and an application development platform. (Most of the quote relates to the Webclient while the remainder of the article refers to the development platform).

    – The plugin directory name must not necessarily match the Maven artifact ID. You’re free to choose any name. Anyway, it’s not a bad idea to let these names match.

    – A migration does not only define the database schema. In general a migration transforms the DB to ensure its structure and content is compatible with your code.

    – For better readability the pom.xml contents could be indented.

    – I would not say the project is a description of the project (which would be more verbose) but just, exactly as you said, “the human readable name of the plugin”.

    – The must not actually be a valid URL, but a globally unique name under which you collect the project’s artifacts. To fulfill the “globally unique” requirement it is best practice to begin the name with a reversed domain name (as you’ve described). You could use e.g. “net.abriraqui.cgc-calendar” as the group ID.

    – Generally in Maven the is the name of the generated .jar file (the Java binary). Within the group this name must be unique. Your choice (“cgc-calendar”) is a good one. (So, with the group ID suggested above “cgc-calendar” appears twice, which is fine. That’s because your project consist of only 1 artifact, but in general there may be many). Remember: the artifact ID must not necessarily match the plugin’s directory name.
    http://maven.apache.org/guides/mini/guide-naming-conventions.html

    – I would not say relationships in DeepaMehta are *hypergraph* relationships. In a hypergraph a relationship can have more than 2 ends. In DM it has always 2. Although one thing is special with the DM data model: at a relationship’s end there can be both: a node (as usual), or a relationship (!). Anyway, if this structure is equivalent to a hypergraph is an ongoing discussion (Jürgen says yes, I say no 🙂

    – It is a convention in DM to use underscores in URIs instead of dashes. So it should be e.g. “cgc.calendar.start_date”. (While our hackership I told differently.)

    – A type’s “value” property is its (human readable) *name*, not actually a “description” (which would possibly more verbose).

    – I would talk about “Event”, “Start Date”, and “End Date” as *Topic Types* (instead of Topics). The distinction is like in OO: a type is like a *class* while a topic is like an *instance* of a class. However, it is technically correct to talk of DM Types as Topics, because in DM Type is derived from Topic. But the more specific term might make things more clear for the reader (especially if she is familiar with OO).

    – The plugin.properties file should contain a 2nd line:
    importModels=de.deepamehta.webclient
    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 (e.g. when you publish a custom DM distro). While our hackership I omitted that setting.

    – In the latter code examples indentation is a bit out of place.

    – At the article end: you should say that this configuration goes to DM’s “global” pom.xml. This is found at the top-level of its home directory.

    Hmh, I feel little like a rigid schoolmaster now 😉
    Your article is great!

  2. Jörg,thanks for the feedback 🙂 … the best way to learn is having someone that shows you how to improve, so thank you for the time spent giving such a detailed comment, I’ll update the post with your observations 🙂

 Leave a Reply

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

(required)

(required)