[[PageOutline]] = Plugin Development Guide = DeepaMehta is made to be extensible by 3rd-party developers. Developers extend DeepaMehta by developing plugins (resp. "modules" resp. "applications" which is all synonymous). == Setup the development environment == The best way to start with DeepaMehta plugin development is to build DeepaMehta from source. This way you get a hot-deploy environment, that is DeepaMehta redeploys your plugin automatically once you compile it. This is very handy while development. Requirements: * **Java 6** (newer versions //might// work as well, older versions do //not// work) * **Maven 3** (older versions do //not// work) * **Git** Build DeepaMehta from source: {{{ #!sh git clone git://github.com/jri/deepamehta.git cd deepamehta mvn install -P all }}} This builds all components of the DeepaMehta Standard Distribution and installs them in your local Maven repository. After a minute or so you'll see: {{{ #!txt ... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 53.515s ... }}} == A very simple plugin: Tagging == Let's start with a very simple plugin. This plugin will just create a new topic type called `Tag`. Once the plugin is installed the topic type will appear in the DeepaMehta webclient's //Create// menu, so you can create instances. And you will be able to fulltext search for tags. Developing such a simple plugin involves no Java coding at all. All is declarative, mainly in JSON format. Of course the topic type could be created interactively as well, by using DeepaMehta's type editor. However, being packaged as a plugin you can publish it. When other DeepaMehta users install your plugin they can use your type definitions. === Create the plugin === You create the plugin just by creating directories and text files. A DeepaMehta plugin project adheres to a certain directory structure and file name conventions. Setup a directory structure as follows: {{{ #!txt dm4-tagging/ pom.xml src/ main/ resources/ migrations/ migration1.json plugin.properties }}} The plugin directory can have an arbitrary name and exist at an arbitrary location. By convention the plugin directory begins with `dm4-` as it is aimed to the DeepaMehta 4 platform. Create the file **`pom.xml`** with this content: {{{ #!xml 4.0.0 DeepaMehta 4 Tagging org.mydomain.dm4 tagging 0.1-SNAPSHOT bundle de.deepamehta deepamehta-plugin-parent 4.1.1-SNAPSHOT }}} Create the file **`migration1.json`**: {{{ #!js { topic_types: [ { value: "Tag", uri: "domain.tagging.tag", data_type_uri: "dm4.core.text", index_mode_uris: ["dm4.core.fulltext"], view_config_topics: [ { type_uri: "dm4.webclient.view_config", composite: { dm4.webclient.show_in_create_menu: true } } ] } ] } }}} Create the file **`plugin.properties`**: {{{ #!txt requiredPluginMigrationNr=1 importModels=de.deepamehta.webclient }}} === Setup for Hot-Deployment === In order to let DeepaMehta hot-deploy the plugin you must include it in DeepaMehta's hot-deployment list. In DeepaMehta's **`pom.xml`**: add the plugin's `target` directory (here: `/home/myhome/deepamehta-dev/dm4-tagging/target`) to the `felix.fileinstall.dir` property's `CDATA` section. Important: don't forget to append a comma to the previous line: {{{ #!xml ... ... }}} Now start DeepaMehta. In the directory `deepamehta` (where you've build): {{{ #!sh mvn pax:run }}} This starts DeepaMehta in development mode, that is with hot-deployment activated. You'll see a lot of information logged, commulating with: {{{ #!txt ... Apr 6, 2013 11:21:20 PM de.deepamehta.core.impl.PluginManager checkAllPluginsActivated INFO: ### Bundles total: 32, DeepaMehta plugins: 16, Activated: 16 Apr 6, 2013 11:21:20 PM de.deepamehta.core.impl.PluginManager activatePlugin INFO: ########## All Plugins Activated ########## Apr 6, 2013 11:21:20 PM de.deepamehta.plugins.webclient.WebclientPlugin allPluginsActive INFO: ### Launching webclient (url="http://localhost:8080/de.deepamehta.webclient/") ... }}} Then a browser windows opens automatically and displays the typical DeepaMehta webclient. The terminal is now occupied by the //Gogo// shell. Press the return key some times and you'll see its `g!` prompt. Type the `lb` command to get the list of activated bundles: {{{ #!sh g! lb }}} The output looks like this: {{{ #!txt START LEVEL 6 ID|State |Level|Name 0|Active | 0|System Bundle (3.2.1) ... 14|Active | 5|DeepaMehta 4 Help (4.1.1.SNAPSHOT) 15|Active | 5|DeepaMehta 4 Topicmaps (4.1.1.SNAPSHOT) 16|Active | 5|DeepaMehta 4 Webservice (4.1.1.SNAPSHOT) 17|Active | 5|DeepaMehta 4 Files (4.1.1.SNAPSHOT) 18|Active | 5|DeepaMehta 4 Geomaps (4.1.1.SNAPSHOT) 19|Active | 5|DeepaMehta 4 Storage - Neo4j (4.1.1.SNAPSHOT) 20|Active | 5|DeepaMehta 4 Core (4.1.1.SNAPSHOT) 21|Active | 5|DeepaMehta 4 Access Control (4.1.1.SNAPSHOT) 22|Active | 5|DeepaMehta 4 Webclient (4.1.1.SNAPSHOT) 23|Active | 5|DeepaMehta 4 Webbrowser (4.1.1.SNAPSHOT) 24|Active | 5|DeepaMehta 4 Type Search (4.1.1.SNAPSHOT) 25|Active | 5|DeepaMehta 4 Workspaces (4.1.1.SNAPSHOT) 26|Active | 5|DeepaMehta 4 Notes (4.1.1.SNAPSHOT) 27|Active | 5|DeepaMehta 4 Type Editor (4.1.1.SNAPSHOT) 28|Active | 5|DeepaMehta 4 Contacts (4.1.1.SNAPSHOT) 29|Active | 5|DeepaMehta 4 Facets (4.1.1.SNAPSHOT) 30|Active | 5|DeepaMehta 4 File Manager (4.1.1.SNAPSHOT) 31|Active | 5|DeepaMehta 4 Icon Picker (4.1.1.SNAPSHOT) }}} The //DeepaMehta 4 Tagging// plugin does not yet appear in that list as it is not yet build. === Build the plugin === In another terminal: {{{ #!sh cd dm4-tagging mvn clean package }}} This builds the plugin. After some seconds you'll see: {{{ #!txt ... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 3.988s ... }}} Once build, DeepaMehta hot-deploys the plugin automatically. In the terminal where you've started DeepaMehta the logging informs you about plugin activation: {{{ #!txt Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginImpl readConfigFile INFO: Reading config file "/plugin.properties" for plugin "DeepaMehta 4 Tagging" Apr 6, 2013 11:38:40 PM de.deepamehta.core.osgi.PluginActivator start INFO: ========== Starting plugin "DeepaMehta 4 Tagging" ========== Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginImpl createPluginServiceTrackers INFO: Tracking plugin services for plugin "DeepaMehta 4 Tagging" ABORTED -- no consumed services declared Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginImpl addService INFO: Adding DeepaMehta 4 core service to plugin "DeepaMehta 4 Tagging" Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginImpl addService INFO: Adding Web Publishing service to plugin "DeepaMehta 4 Tagging" Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginImpl registerWebResources INFO: Registering Web resources of plugin "DeepaMehta 4 Tagging" ABORTED -- no Web resources provided Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginImpl registerRestResources INFO: Registering REST resources of plugin "DeepaMehta 4 Tagging" ABORTED -- no REST resources provided Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginImpl registerRestResources INFO: Registering provider classes of plugin "DeepaMehta 4 Tagging" ABORTED -- no provider classes provided Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginImpl addService INFO: Adding Event Admin service to plugin "DeepaMehta 4 Tagging" Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginManager activatePlugin INFO: ----- Activating plugin "DeepaMehta 4 Tagging" ----- Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginImpl createPluginTopicIfNotExists INFO: Installing plugin "DeepaMehta 4 Tagging" in the database Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.MigrationManager runPluginMigrations INFO: Running 1 migrations for plugin "DeepaMehta 4 Tagging" (migrationNr=0, requiredMigrationNr=1) Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.MigrationManager$MigrationInfo readMigrationConfigFile INFO: Reading migration config file "/migrations/migration1.properties" ABORTED -- file does not exist Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.MigrationManager runMigration INFO: Running migration 1 of plugin "DeepaMehta 4 Tagging" (runMode=ALWAYS, isCleanInstall=true) Apr 6, 2013 11:38:40 PM de.deepamehta.core.util.DeepaMehtaUtils readMigrationFile INFO: Reading migration file "/migrations/migration1.json" Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.MigrationManager runMigration INFO: Completing migration 1 of plugin "DeepaMehta 4 Tagging" Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.MigrationManager runMigration INFO: Updating migration number (1) Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.AttachedTopic update INFO: Updating topic 2690 (new topic (id=-1, uri="", typeUri="dm4.core.plugin_migration_nr", value="1", composite={})) Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.AttachedDeepaMehtaObject updateSimpleValue INFO: ### Changing simple value of topic 2690 from "0" -> "1" Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginImpl registerListeners INFO: Registering listeners of plugin "DeepaMehta 4 Tagging" at DeepaMehta 4 core service ABORTED -- no listeners implemented Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginImpl registerPluginService INFO: Registering OSGi service of plugin "DeepaMehta 4 Tagging" ABORTED -- no OSGi service provided Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginManager activatePlugin INFO: ----- Activation of plugin "DeepaMehta 4 Tagging" complete ----- Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginManager checkAllPluginsActivated INFO: ### Bundles total: 33, DeepaMehta plugins: 17, Activated: 17 Apr 6, 2013 11:38:40 PM de.deepamehta.core.impl.PluginManager activatePlugin INFO: ########## All Plugins Activated ########## Apr 6, 2013 11:38:40 PM de.deepamehta.plugins.webclient.WebclientPlugin allPluginsActive INFO: ### Launching webclient (url="http://localhost:8080/de.deepamehta.webclient/") ABORTED -- already launched ... }}} When you type again `lb` in the DeepaMehta terminal you'll see the plugin in the list of activated bundles: {{{ #!txt START LEVEL 6 ID|State |Level|Name 0|Active | 0|System Bundle (3.2.1) ... 30|Active | 5|DeepaMehta 4 File Manager (4.1.1.SNAPSHOT) 31|Active | 5|DeepaMehta 4 Icon Picker (4.1.1.SNAPSHOT) 32|Active | 5|DeepaMehta 4 Tagging (0.1.0.SNAPSHOT) }}}