History Flow API

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 “XXXpluginYYY.jar” (“XXX” and “YYY” can be any sequence of characters, or can be omitted).

(A JAR’s filename must actually match the regular expression “(?i).*plugin.*\\.jar$“).

A plugin JAR file must contain a manifest. Several attributes can be specified in the manifest:

  • PluginClass is mandatory, and specifies the main class of the plugin (which must implement the IHistoryProvider interface);
  • RequiresJTidy is optional. Set this to true to 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-Path is 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);
  • date;
  • content – the actual text of the version;
  • comment (the edit summary, in the case of MediaWiki articles).
This entry was posted in Uncategorized and tagged , . Bookmark the permalink.

1 Response to History Flow API

  1. Would it be possible to get History Flow to work with Google Docs?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s