OpenCDS CreatePlugin

From OpenFrag

Jump to: navigation, search

Contents

Create your own plugin

Some developers like to extend applications as much as they can. This fact hasn't gone unnoticed in OpenCDS. Plugins can basically add a feature or extra functionality to OpenCDS, which can be very useful to other users if you decide to share your plugin. These plugins usually consist out of one or more jar files. This jar file contains a file that OpenCDS needs for gathering information about the plugin. Think about stuff like name, version, main class, etc.

Analysis

Let's say we want a plugin that continuously logs a message. This is the idea, after the idea we move to the construction phase. Let's first see how our jar needs to look. Here is a tree hierarchy, explained in detail.

META-INF/ - A folder usually added. It is NOT required by OpenCDS, but sure comes in handy.
|
|
Package/ - The package where you .class file is in.
|
|
plugin.properties - The configuration file.

This is actually not very hard. This is just the standard way a jar looks, except for the properties file. Let's have a look at that first shall we?

The plugin.properties file

A properties file is needed by OpenCDS to determine name, version, and main class. Such a file looks like: 

plugin.class = TestPlugin.TestPlugin
plugin.name = My Test Plugin
plugin.version = 1.0

It is all very obvious. Please note that if you don't have this file in your jar, your plugin won't be loaded at all. So! Now we have a plugin.properties file, in the root of our jar!

The actual class

Now we actually need to get a little bit more technical - adding the class with our code. As a plugin, you have access via a PluginInterface to various subsystems of OpenCDS. Think about the download, plugin, language -systems. Please, use these systems with care. You basically got complete access over those systems. The reason that the access is not limited, is because the users chooses what plugin he/she installs. If the plugin he or she installed, is doing bad things, they will probably remove it.
Every plugin extends the Plugin class from OpenCDS. This is to show to OpenCDS that we are, indeed, a plugin that can be started, and destroyed. Be sure to add the OpenCDS.jar to your classpath.

  1. package TestPlugin;
  2.  import org.openfrag.OpenCDS.core.plugin.*;
  3.  import org.openfrag.OpenCDS.core.logging.*;
  4.  
  5.  public class TestPlugin extends Plugin
  6.  {
  7.  }

This is a simple start. This example will not compile, as we have not defined some necessary methods yet. The class is instantiated by OpenCDS, and when started, the parameter to the initialize method will be provided by OpenCDS. The parameter is the PluginInterface, from which you can gain access to OpenCDS subsystems. It is recommended to save a reference to this parameter in your initializing class!

  1. package TestPlugin;
  2.  import org.openfrag.OpenCDS.core.plugin.*;
  3.  import org.openfrag.OpenCDS.core.logging.*;
  4.  
  5.  public class TestPlugin extends Plugin
  6.  {
  7.    private PluginInterface m_PluginInterface;
  8.    <
  9.    /**
  10.     * Initializes the plugin.
  11.    */
  12.    public void initialize(PluginInterface pluginInterface)
  13.    {
  14.      m_PluginInterface = pluginInterface;
  15.    }
  16.    
  17.    /**
  18.     * Destroys the plugin.
  19.    */
  20.    public void destroy()
  21.    {
  22.    }
  23.  }

When our plugin is started, initialize is called. Here you can start your sequence, or do whatever it is you want to do. The destroy method is called when we, obviously, want to destroy your plugin. This method should undo all made changes, if any. Let's add the rest of our code. We wanted to log a message continuously right? Let's say every five seconds.

  1. package TestPlugin;
  2.  import org.openfrag.OpenCDS.core.plugin.*;
  3.  import org.openfrag.OpenCDS.core.logging.*;
  4.  import java.awt.event.ActionListener;
  5.  import java.awt.event.ActionEvent;
  6.  import javax.swing.Timer;
  7.  
  8.  public class TestPlugin extends Plugin
  9.  {
  10.    private PluginInterface m_PluginInterface;
  11.    
  12.    /**
  13.     * Initializes the plugin.
  14.    */
  15.    public void initialize(PluginInterface pluginInterface)
  16.    {
  17.      m_PluginInterface = pluginInterface;
  18.      <br>
  19.      int delay = 5000; // The amount of seconds between messages.
  20.      ActionListener performer = new ActionListener()
  21.      {
  22.        public void actionPerformed(ActionEvent event)
  23.        {
  24.          Logger.getInstance().log("TestPlugin", "Hey!");
  25.        }
  26.      };
  27.      new Timer(delay, performer).start();
  28.    }
  29.    
  30.    /**
  31.     * Destroys the plugin.
  32.    */
  33.    public void destroy()
  34.    {
  35.    }
  36.  }

Oi, that was all! Please note that your plugin is ran in another thread, so you could have use a while loop aswell.

Deploy

Now we have got a jar file, with the configuration file, and the plugin's class file, let's place it in the OpenCDS/plugins/ folder. Just place it there, and start OpenCDS. You should see: 

[16:58:53]  (INFORMATION)	:  Loaded plugin: My Test Plugin

at the least. This simply indicates that your plugin is ok, and has been loaded. Note that it has not started yet. To start your plugin, you must first add it to your configuration.properties file in the OpenCDS root folder. You can do this by going to the Configuration dialog, and setting your plugins there, or by manually editing the configuration.properties file. The syntax when manually editing is: 

Plugins.Load = PluginName,AnotherPluginsName

So it would become, if no other plugins are installed: 

Plugins.Load = My Test Plugin

Once this is done, start OpenCDS again, and this is what you should see now: 

[17:02:50]  (INFORMATION)	:  Loaded plugin: My Test Plugin
[17:02:50]  (INFORMATION)	:  Started plugin: My Test Plugin
[17:02:50]  (TestPlugin)	:  Starting sequence
[17:02:55]  (TestPlugin)	:  Hey!
[17:03:00]  (TestPlugin)	:  Hey!

Submit your plugin

We have a small database of OpenCDS approved plugins. These plugins are judged by us, and if they are useful/handy enough, they will be enlisted in the plugin installer. This is great for people who want to share their plugins with others - we will probably accept any useful plugin at this point, so don't hasitate to email Levia.

Conclusion

This concludes this tutorial to show you the bare basics of the plugin system. Please read other tutorials if you want more specific information.

Retrieved from "http://wiki.openfrag.org/wiki/OpenCDS_CreatePlugin"
Personal tools
OpenFrag