iReport
User manual iReport comes with two plugins, the Massive compiler and the Text Wizard besides a simple “Hello World!” plugin provided as sample.
Plugin configuration XML file
The plugin configuration XML file, used as the deployment descriptor, is really simple (here is the DTD that describes their tags) .
<?xml version="1.0" encoding="UTF-8"?>
<!--
Document : iReportPlugin.dtd
Created on : 19 maggio 2004, 8.09
Author : Giulio Toffoli
Description: This DTD define the XML descriptor for an iReport plugin.
-->
<!--
iReportPlugin is the root element.
ATTRIBUTES:
name The name of plugin
class The class that extends
it.businesslogic.ireport.plugin.IReportPlugin
loadOnStartup If true, the plugin will be instanced on iReport startup
hide If true, this plugin will be not visible on plugin menu
-->
<!ELEMENT
iReportPlugin
(Author?,Description?, IconFile?)>
<!ATTLIST iReportPlugin
name NMTOKEN #REQUIRED
class NMTOKEN #REQUIRED
loadOnStartup (true | false) "false"
hide (true | false) "false"
configurable (true | false) "false">
<!ELEMENT
Author
(#PCDATA)>
<!ELEMENT
Description
(#PCDATA)>
<!--
Icon file should be a file in the classpath i.e. com/my/plug/in/icon.gif
Is used as optional icon for menu.
Dim: 16x16
-->
<!ELEMENT
IconFile
(#PCDATA)>
The root element is iReportPlugin and here are their attributes:
name class
It is the plugin name;
It is the java class that implements the plugin; it must be present in the classpath together with all required classes; if a jar is needed to run the plugin, you have to put it in the iReport’s lib directory;
loadOnStartup iReport keeps in memory one and only one instance for each plugin: setting this attribute to true
it is possible to force iReport
hide
to instance the plugin when iReport starts, without waiting for an invocation by the user;
If it is set to true
, this attribute can hide the plugin (it will be hidden in all the menu entries related to this plugin);
156
Plugins
and additional tools
configurable
If set to true
, iReport will enable the button “Configure” for this plugin in the window shown on figure 15.3.
If you want, you can specify the author name for a plugin (tag
Author
, not used at this time), a small plugin description (tag
Description
) and a 16x16 pixel icon that will be used for the menu (tag
IconFile
): since the icon file is loaded as java resource, the value for this tag must be a path in the classpath (e.g.
/it/businesslogic/ireport/icons/menu/new.gif).
Below is the XML file used to activate the “Example 1” plugin shipped with iReport.
<iReportPlugin
name="Example 1"
class="it.businesslogic.ireport.plugin.examples.HelloWorld"
loadOnStartup="false" hide = "false" configurable = "true">
<IconFile>/it/businesslogic/ireport/icons/menu/new.gif</IconFile>
<Description>
This example shows how to create a very simple
plugin for iReport.
</Description>
</iReportPlugin>
To disable a plugin, you have to remove the XML file from the plugin directory (or simply change its extension to something different from .xml).
The it.businesslogic.ireport.plugin.IReportPlugin class
The most difficult part related to the creation of a plugin is to program it. You have to create a new java class that extends the abstract class
it.businesslogic.ireport.plugin.IReportPlugin. This one contains two “entry points”; they are the methods configure and call; the first is invoked only if the plugin is labelled as “configurable” and more exactly when the user hits the button
“Configure” visible on figure 15.3, the second one is invoked when the user selects the plugin name from the menu on figure 15.1.
Here is the class IReportPlugin source code. package it.businesslogic.ireport.plugin; import it.businesslogic.ireport.gui.MainFrame;
/**
* This class must be extended by all iReport plugin.
* To install a plugin into iReport, put the plugin xml in the plugin
* directory of iReport.
* See plugin documentation on how to create a plugin for iReport
*
157
iReport
User manual
* This is the first very simple interface to plugin. I hope to
* don't change it, but we can't say what it'll happen in he future...
*
* @author Administrator
*/ public abstract class IReportPlugin {
MainFrame mainFrame = null;
String name = "";
/**
* This method is called when the plugin is selected from the plugin menu
*/
public abstract void call();
/**
* This method is called when the plugin configuration button on plugin
* list is selected.
* Configuration file of plugin should be stored in
* IREPORT_USER_HOME_DIR/plugins/
*/
public void configure(){}
/**
* Retrive the plugin name. Please note that the plugin name must be
* unique and should be used as filename for the configuration file if
* needed. This name can be different from the name specified in XML,
* that is the name used for the menu item.
*/
public String getName(){
return name;
}
/** Getter for property mainFrame.
* @return Value of property mainFrame.
*
*/
public it.businesslogic.ireport.gui.MainFrame getMainFrame() {
return mainFrame;
}
/** Setter for property mainFrame.
* @param mainFrame New value of property mainFrame.
*
*/ public void setMainFrame(
it.businesslogic.ireport.gui.MainFrame mf) {
this.mainFrame = mf;
}
}
As you can see, the only real abstract method is call. In effect, the method configure is implemented (with a void body) and this because there is not much sense in forcing the user to implement it in the plugin if it is not used (that is when the plugin is not configurable).
It is good idea to define a plugin constructor without arguments and set a value for the class attribute name. As soon as the plugin is instanced, iReport will call the plugin method setMainFrame to fill the attribute mainFrame, that is a reference to the core class of iReport: through this class you can access reports, you can compile, you can modify the iReport configuration, etc...
Now we will focus on the method call. We have already talked about the fact that iReport creates and keeps in memory only one instance of each plugin: this means
158
Plugins
and additional tools that the method call is not thread safe. This suggests to us that the class that extends
IReportPlugin should be a kind of container for the real plugin; the method call should be the only entry point to run the plugin code. At this point it’s possible to describe two types of plugins: the ones that have a single persistent instance, that survive between two consecutive plugin calls, and the other ones that use multiple
“volatile” instances, that burn and die when the plugin code ends: in this case the call method is implemented to create a new instance of the core plugin class each time the plugin is executed.
The following listing represents a simplified example of how a plugin with persistent instance should work. public class MyPlugin extends IReportPlugin {
MyPluginFrame frame = null;
Public MyPlugin()
{
setName(“my sample plugin”);
}
/**
* This method is called when the plugin is selected from the plugin menu
*/ public t void call()
{
if (frame == null)
{
frame = new MyPluginFrame();
}
if (!frame.isVisible()) frame.setVisible(true);
}
}
The example MyPluginFrame class is the core of this plugin and it is shown any time the user selects this plugin from the menu. The Massive compiler plugin works in this way. The plugin window can be opened and closed many times, but the
MyPluginFrame is never deallocated and it keeps its state untouched.
If you have to create a new different instance of the plugin core class each time the plugin is executed, the call method must be converted in something like this: public class MyPlugin extends IReportPlugin {
Public MyPlugin()
{
setName(“my sample plugin”);
}
/**
* This method is called when the plugin is selected from the plugin menu
*/ public t void call()
{
MyPluginFrame frame = new MyPluginFrame();
frame.show();
}
}
159
