VisualDCT Plugins
Project:	VisualDCT
Classification:	User's Documentation
Identification:	CSL-DOC-02-XX
Copyright © 2002 by Cosylab Ltd. All Rights Reserved.

Document History

Revision	Date	Author	Section	Modification
1.0	2002-09-21	Sunil Sah
			all	Created.

Scope

This document contains information on writing plugins for VisualDCT and their installation.

Confidentiality

This document is classified as a public document. Redistribution and use, with or without modification, are permitted provided that:

1. the copyright notice is retained
2. a reference to the original document is made in case of modifications
3. this document may not be distributed for profit except as explicitly permitted by valid licenses.

Audience

The audience of this document are the users of VisualDCT who wish to create or use its plugins.

References

ID	Author	Reference	Revision	Date	Publisher
1	Matej Sekoranja	VisualDCT Project		2002	Cosylab, Ltd.

Table of Contents

How to Read this Document

This document's meta-information (authors, revision history, table of contents, ...) can be found above. What follows below is the body of the document. The body is composed of several sections, which may be further composed of subsections.

Typographical styles are used to denote entities of different kinds. For a full list of entities and their respective typographic conventions, please refer to the Styles section of the XML Documentation document.

When viewing the document in a non-printed form, it is possible to submit comments regarding a given section to the document's owner. This is achieved by clicking the mail icon next to the section title. For this to work, your mail must be configured to properly handle the mailto URLs.

This document is divided into three sections. The first describes how to create a VisualDCT plugin. The second explains how to include the parameters of the plugin and the information that is required by VisualDCT. The last section is about Plugin Manager, which can be used to install and manipulate the plugins within VisualDCT.

For the resource to be used as a VisualDCT plugin, it must contain a class that implements the Plugin interface. Descriptions of specific methods are given below, followed by an example.

Plugin interface contains the following methods:

• public void start(): This method will be called at the time the plugin is started.
• public void stop(): This method will be called when the plugin is stopped.
• public void destroy(): This method will be called when the plugin is to be destroyed.
• public String getAuthor(): This method should return the String containing the name and/or e-mail address of the plugin author.
• public String getDescription(): This method should return the String containing a short description of the plugin.
• public String getName(): This method should return the String containing the name of the plugin.
• public String getVersion(): This method should return the String containing the plugin version number.
• public void init(Properties properties, PluginContext context): This method is called when the plugin is initiated. The parameter properties contains the parameters of the plugin, while the context enables access to information on runtime environment.

This is an example of a plugin. When it is initiated, it checks the version of VisualDCT using the parameter context, and manipulates with its parameters using properties.

import java.util.*;
import com.cosylab.vdct.plugin.*;

public class SimplePlugin implements Plugin
{

int interval = 0;

public void start()
{
	System.out.println("SimplePlugin was started.");
}

public void stop()
{
	System.out.println("SimplePlugin was stopped.");
}

public void destroy()
{
	System.out.println("SimplePlugin was destroyed.");
}

public String getAuthor()
{
	return "sunil.sah@cosylab.com";
}
	
public String getDescription()
{
	return "A simple plugin implementation.";
}
	
public String getName()
{
	return "SimplePlugin";
}
	
public String getVersion()
{
	return "1.0";
}

public void init(Properties properties, PluginContext context)
{
	// check for required version of VisualDCT
	if(context.getVersion().compareTo("2.1") < 0)
	{
		System.out.println("SimplePlugin requires VisualDCT v2.1 or newer version.");
		throw new Exception();
	}

	// read a property
	String property = properties.get("interval").toString();
	if(property != null)
		interval = Integer.parseInt(property);

	// set a new property, the time when SimplePlugin was last initiated
	properties.put("lastrun", new Date().toString());
}

};

Listing 1: Example of a plugin

There are currently three special types of plugins in VisualDCT:

• com.cosylab.vdct.plugin.LinkTypeConfigPlugin
• com.cosylab.vdct.plugin.DebugPlugin
• com.cosylab.vdct.plugin.ExportPlugin

VisualDCT plugins are distributed as Java Archive (jar) files.

The jar file must include the following two files:

• Java class file with the plugin implementation.
• .vdctplugins.xml file with the plugin information.

The .vdctplugins.xml file includes the name of the plugin class, its autostart switch and optionally the parameters. It may contain information on multiple plugins.

This in an example of xml file for the class named SimplePlugin. It will be started automatically by default, and has one parameter, interval, set to 1000.

Plugin Manager is used for VisualDCT plugin management. It can be accessed by   Plugins  -  Plugin Manager...  .

Plugin table contains a list of currently installed plugins. The information of a plugin is divided into several columns:

1. The Autostart column displays a checkbox indicating whether or not the plugin will automatically be started at the time the VisualDCT is started. See Autostart plugins (4.2.3.) section for more information.
2. The Status column displays the state of a plugin. It can be one of the following:
   • Not loaded: The plugin has not been loaded.
   • Loaded: The plugin has been loaded.
   • Invalid: The plugin could not have been initialized due to an error.
   • Initialized: The plugin was initialized, but it has not been started.
   • Started: The plugin was initialized and started.
   • Stopped: The plugin was started, but it is currently stopped.
3. The Name column displays the plugin name.
4. The Version column displays the current plugin's version number.
5. The Description column displays a short description of the plugin.
6. The Author column displays the e-mail address of the plugin's creator.

Figure 1: Plugin Manager

A new plugin can be installed by clicking on a   Install...   button, and then selecting the plugin's jar file. The jar must contain a .vdctplugins.xml file with the required information about the new plugin.

The jar with the new plugin must be added to the classpath before it can be installed within the VisualDCT.

To start or stop a specific plugin it must first be selected. To select a plugin in the table, move with the mouse cursor over it and press the left mouse button.

When the plugin is selected, click on the   Start   button to start it, or the   Stop   button to stop it.

Each plugin has an autostart switch.

When VisualDCT is started, all installed plugins are initiated. Then, all plugins that have autostart switch enabled are automatically started.

To change the autostart switch of a plugin, move the mouse cursor over its checkbox in the Autostart column, and press the left mouse button. The checkbox indicates the current status.

To uninstall a plugin, select it in the table and press the   Uninstall   button. This will permanently uninstall the plugin. If you wish to restore the previous state, you have to re-install the plugin with the install command.

To perform an action on several plugins at once, these plugins must all be selected.

To select a series of plugins, move the mouse cursor over the first one in the table, press and hold the left mouse button, drag the mouse to the last plugin, and release the button. To select specific plugins, hold down the   Ctrl   key, and click on them one after another.