In March 2005 IBM released History Flow, a tool for visualising the evolution of documents over time. The tool has been designed to allow new plugins to easily be added, but at the moment it isn’t open source, and there isn’t any documentation for the API. Fortunately the API isn’t too difficult, so I thought I would investigate History Flow a bit more.
A plugin has two purposes:
- it helps the user to locate a document;
- it converts the historical versions of that document into an internal format that can then be displayed visually by History Flow.
Packaging a plugin
Plugins are packaged as JAR files. They are automatically discovered by History Flow (by its
DocumentHistoryPluginManager class) provided that:
- they are placed in the “plugins” directory (in C:\Program Files\History Flow Visualization, by default); and
- they have a name of the form “
XXX” and “
YYY” can be any sequence of characters, or can be omitted).
(A JAR’s filename must actually match the regular expression “
A plugin JAR file must contain a manifest. Several attributes can be specified in the manifest:
PluginClassis mandatory, and specifies the main class of the plugin (which must implement the
RequiresJTidyis optional. Set this to
trueto indicate that the plugin requires the JTidy library, which can be used for HTML checking and formatting. History Flow will not load plugins that depend on JTidy if it is not present, although History Flow itself will still run;
Class-Pathis a standard attribute which is useful if the plugin depends on any other JAR files besides JTidy.
The plugin code
IHistoryProvider requires two methods to be implemented.
getActionText() should return the text that is displayed on History Flow’s “File” menu. The MediaWiki plugin is listed as “MediaWiki article…”, for example.
The second method,
getHistory(), is called when the menu option is selected. It should display the dialog box (or boxes) that allows the user to choose a document, and then return an object implementing the
IDocumentHistory interface. An instance of the
DocumentHistoryImpl class can be used for this. The object consists of:
- the name of the document;
- the document’s source (text that indicates where the document was retrieved from);
- an array of document versions;
- the document’s content type.
The document version objects must implement the
IVersion interface; an instance of the
VersionImpl class is suitable. Each version has the following properties:
- name (this is left blank in the case of MediaWiki articles);
- author (either the username or IP address for MediaWiki articles);
- content – the actual text of the version;
- comment (the edit summary, in the case of MediaWiki articles).