Note that the plugin-sdk has unit tests that test generation of plugins and execution of unit tests for the generated plugins. To run the unit tests, execute "ant -f plugin-sdk.xml test" from IRIS or Desktop. After running the plugins will be left intact. The Plugin Tutorial walks through how these plugins are created. The IRIS plugin SDK test is run with each nightly build.

As a very simple example, suppose we want to create an IRIS plugin that exposes a service other plugins can use. In particular, this service adds 2 numbers together. The first step in writing a plugin is to define the initialization file for the plugin SDK. Here it is:

<beans>
    <bean id="com.sri.iris.tools.pluginsdk.PluginParams" class="com.sri.iris.tools.pluginsdk.PluginParams">
        <property name="pluginName" value="adder" />
        <property name="sourcePackage" value="com.sri.iris.plugins.adder" />
        <property name="className" value="AdderImpl" />
        <property name="pluginDescription" value="Service used to add numbers" />
        <property name="jarFiles">
            <list>
                <!-- No external jars needed for this plugin -->
            </list>
        </property>
        <property name="dependencies">
            <list>
                <!-- No dependencies -->
            </list>
        </property>
        <property name="buildDependencies" value="true" />
        <property name="pluginLocations">
            <list>
                <bean class="com.sri.iris.tools.pluginsdk.PluginLocations">
                    <property name="destDir" value="../plugins" />
                    <property name="destRefParam" value="${iris.plugins.dir}" />
                    <property name="srcDir" value="../plugins-src" />
                    <property name="srcRefParam" value="${iris.plugins.src.dir}" />
                </bean>
            </list>
        </property>
    </bean>
</beans>

In the iris/plugins-src directory, put this configuration into a file named "pluginInit-adder.xml" and then execute the following:

Note: The "pluginInit-adder.xml" file must also include the <?xml> and <!DOCTYPE> tags as shown in the iris/plugins-src/pluginInit-sample.xml file.

    ant.bat -f plugin-sdk.xml generate-plugin -Dplugin.initFile=pluginInit-adder.xml

This invokes the plugin SDK. Note that some Velocity context errors may be reported; this is to be expected and they are not actually errors. The plugin SDK will create the following directory structure under iris/plugins-src:

The adder plugin is then implemented in the following steps:

Now the plugin can be tested. Before testing, note that Ant must be compiled with JUnit support. To do this, make sure junit.jar is placed in the Ant lib directory before compiling Ant, or download the JUnit libraries for Ant and install them.

To test the plugin, open a prompt and navigate to the "iris/plugins-src/adder/test" directory. Then execute "ant test". Make sure IRIS is not already running, because the unit test will bootstrap IRIS and if IRIS is running this can cause resource conflicts. Note that executing the test target automatically builds the plugin first. When the tests are complete the following HTML unit test report file will be generated:

    adder/test/dest/testresults/html/index.html

Next suppose we want to write a plugin that multiplies number. Just for kicks let use implement a plugin that multiplies over addition using the adder plugin. Although you probably would never do this it demonstrates simple plugin dependency. Here is the plugin initialization file for the SDK:

<beans>
    <bean id="com.sri.iris.tools.pluginsdk.PluginParams" class="com.sri.iris.tools.pluginsdk.PluginParams">
        <property name="pluginName" value="multiplier" />
        <property name="sourcePackage" value="com.sri.iris.plugins.multiplier" />
        <property name="className" value="MultiplierImpl" />
        <property name="pluginDescription" value="Service used to multiply numbers" />
        <property name="jarFiles">
            <list>
                <!-- No external jars needed for this plugin -->
            </list>
        </property>
        <property name="dependencies">
            <list>
                <value>adder</value>
            </list>
        </property>
        <property name="buildDependencies" value="true" />
        <property name="pluginLocations">
            <list>
                <bean class="com.sri.iris.tools.pluginsdk.PluginLocations">
                    <property name="destDir" value="../plugins" />
                    <property name="destRefParam" value="${iris.plugins.dir}" />
                    <property name="srcDir" value="../plugins-src" />
                    <property name="srcRefParam" value="${iris.plugins.src.dir}" />
                </bean>
            </list>
        </property>
    </bean>
</beans>

Here the "adder" plugin is put in the dependencies list. To be brief, the IMultiplier source, implementation and unit test code is left out here. This code can be viewed after running the plugin SDK unit tests described above. Here is the modified configuration file "multiplier.xml":

<beans>
    <bean name="com.sri.iris.plugins.multiplier.IMultiplier"
          class="com.sri.iris.plugins.multiplier.MultiplierImpl"
          init-method="startup" destroy-method="shutdown" lazy-init="true">
        <description>
            Service used to multiply numbers
        </description>
        <property name="adder">
            <description>
                The IMultiplier services implements multiplication on top of addition.
                This is done to demonstrate and test single-plugin dependency.
            </description>
            <ref bean="com.sri.iris.plugins.adder.IAdder" />
        </property>
    </bean>
</beans>

Note that the adder plugin is specified as a dependency by referring to its bean (the IAdder class name). All that MultiplierImpl needs to do to get the dependency is define a setter method "setAdder" which takes the IAdder instance as the one parameter. From MultiplierImpl.java:

    public void setAdder(IAdder adder) {
        this.adder = adder;
    }

Up until now the "plugin.xml" file has not been discussed. The "plugin.xml" for the multiplier plugin demonstrates the use of a custom ClassLoader and ApplicationContext inheritance to allow plugin dependencies:

<beans>
    <bean id="com.sri.iris.plugins.multiplier.ClassLoader"
          class="java.net.URLClassLoader"
          dependency-check="none" lazy-init="true">
        <constructor-arg>
            <list>
                <value>${iris.plugins.dir}/multiplier/multiplier.jar</value>
            </list>
        </constructor-arg>
        <constructor-arg>
            <ref bean="com.sri.iris.plugins.adder.ClassLoader" />
        </constructor-arg>
    </bean>
    <bean id="com.sri.iris.plugins.multiplier.ApplicationContext"
           class="org.springframework.context.support.FileSystemXmlApplicationContext"
           init-method="refresh" lazy-init="true">
        <description>Service used to multiply numbers.
        This is the config file which sets up classpath and dependencies for
        the plugin. See multiplier.xml for the plugin beans.</description>
        <constructor-arg>
            <list><value>${iris.plugins.dir}/multiplier/multiplier.xml</value></list>
        </constructor-arg>
        <constructor-arg>
            <value>false</value>
        </constructor-arg>
        <constructor-arg>
                <ref bean="com.sri.iris.plugins.adder.ApplicationContext"/>
            </constructor-arg>
        <property name="classLoader">
            <ref bean="com.sri.iris.plugins.multiplier.ClassLoader"/>
        </property>
    </bean>
</beans>

Note the following about this configuration file:

This plugin displays UI which means it involves user interaction. Due to the aforementioned legacy code requirement, UI plugins need to declare remote references to server beans. The specification for the plugin configuration file differs when generating UI plugins. In particular, the arithmeticui plugin config specifies the property:

        <property name="isClientPlugin" value="true" />

When generating a client plugin, IRIS does not generate a "plugin.xml" file. Instead IRIS generates all other files mentioned and in addition:

The UI plugins are loaded as part of the bootstrap process into a separate application context. See this link for details.

<beans>
    <bean class="com.sri.iris.plugins.arithmeticui.ArithmeticUIImpl" id="arithmeticui"
          init-method="startup" destroy-method="shutdown" lazy-init="true">
        <description>
            Puts up an IRIS UI for the adder and multiplier unittest plugins
        </description>
        <property name="adder">
            <ref bean="com.sri.iris.plugins.adder.IAdder" />
        </property>
        <property name="multiplier">
            <ref bean="com.sri.iris.plugins.multiplier.IMultiplier" />
        </property>
        <property name="viewerHost">
            <ref bean="com.sri.iris.ui.IViewerHost" />
        </property>
        <property name="appUri"><value>http://iris.sri.com/app/arithmeticui</value></property>
        <property name="appName"><value>Airthmetic UI</value></property>
        <property name="appFolder"><value>Debug</value></property>
    </bean>
</beans>

public class ArithmeticUIImpl implements IPlugin
{
    private IAdder adder;
    private IMultiplier multiplier;
    private IViewerHost viewerHost;
    private String appUri;
    private String appFolder;
    private String appName;
    private boolean started = false;

    private Logger log = Logger.getLogger(ArithmeticUIImpl.class);

    public void startup() throws Exception {
        if (getAdder() == null) {
            throw new AbortException("IAdder not set");
        }
        if (getMultiplier() == null) {
            throw new AbortException("IMultiplier not set");
        }
        if (viewerHost == null) {
            throw new AbortException("IViewerHost not set");
        }
        log.info("Starting up ArithmeticUIImpl plugin");
        viewerHost.installNamedViewer(appUri, new ArithmeticUIPane(adder, multiplier), null, null, false);
        viewerHost.addToApplicationTree(appName, appUri, appFolder);
        started = true;
    }

    public void shutdown () {
        log.info("Shutting down ArithmeticUIImpl plugin");
    }

    protected IViewerHost getViewerHost() {
        return viewerHost;
    }

    protected boolean isStarted() {
        return started;
    }
    
    // ... <snip />
}