Fixing a wierd widget installation issue (Content is not allowed in prolog)

For our OnTime Group Calendar 2011 Notes user interface which is Java plugin based we have seen some strange problem reports with customers reporting that the widget installs but after installation an error message is displayed on screen (“The widgets below had issues during the installation. See the log for more details.”). The wierd thing about the reports were that the customers reported that the widget (and hence the plugins) actually installed just fine and worked after a client restart. What’s even funnier is that the same plugins installed without error if the customer used HTTP and not NRPC for their update site access protocol. In the log (Help/Support/View Trace) the below error messages was shown (my highlighting):

Could not access digest on the site: no protocol:
[Fatal Error] :1:1: Content is not allowed in prolog.
org.eclipse.ui.WorkbenchException: Content is not allowed in prolog.
	at org.eclipse.ui.XMLMemento.createReadRoot(Unknown Source)
	at org.eclipse.ui.XMLMemento.createReadRoot(Unknown Source)
Caused by:
org.xml.sax.SAXParseException: Content is not allowed in prolog.
	at org.apache.xerces.parsers.DOMParser.parse(Unknown Source)
	at org.apache.xerces.jaxp.DocumentBuilderImpl...
	... 11 more

This really had me scratching my head.

After reseaching and Googling I found a post called “Java: “Content is not allowed in prolog” – causes of this XML processing error” which led me in right direction.

When I opened the widget XML file in an editor and switched to HEX mode I saw this:

3 invisible bytes were inserted at the start of the file. I copy/pasted the XML into a new file which solved the issues. The 3 bytes actually turn out to be what’s called a Byte order mark or BOM for short. From the wikipedia article I found out that the BOM for a UTF-8 file is those exact bytes and I did save the file as UTF-8 in my editor.

The UTF-8 representation of the BOM is the byte sequence 0xEF,0xBB,0xBF. A text editor or web browser interpreting the text as ISO-8859-1 or CP1252 will display the characters  for this.

But the bytes were not there in my editor but only in the file that I received from a customer. So how did the bytes get there?!

So after more research and playing around I found out that the BOM is added by Notepad on Windows. But of course!! A lot of customers receive the XML file and change the update site URL to point to their own servers and if they use Notepad for this the BOM is added (see “The Notepad file encoding problem, redux” for more details).

But how to fix it? Telling customers not to use Notepad to edit the XML file would be a no-go as many probably no not use another editor. And even if they did the problem would probably still arise in some situations and we would spend time diagnosing it. The solution I’ve opted for is to change the encoding of the file to ASCII and change the encoding declation in the XML file to ASCII as well. The content of the XML file is unchanged and now customers can change it using Notepad without issues.

Creating a keystore for plugin signing the easy way

Previously when creating keystores for plugin signing I’ve used a lot of dark magic, crying at the moon and a custom tool I wrote called KeystoreUtil to convert between different formats. The other day I was doing a consulting gig on plugin signing and came up with an easier way just using iKeyman and the Java tooling. I created a presentation with the various commands and screenshots and put it on Slideshare.

Hope it will help someone.

DNUG 2011 video of yours truly – Plug yourself in and your apps will never be the same!

The kind people from DNUG was kind enough to tape my presentation in November and send me a link to the video. Sides being extremely weird to see one self on video I thought someone might enjoy it – so here it is. Further down is the presentation on Slideshare from BLUG.

Link to video.

I will be giving two sessions at DNUG in November

As mentioned previously I’ll be speaking at DNUG in November in Bamberg in Germany where I will be giving my “jumpstart your plugin development”-session about all the plugin development goodness. Besides that I’m also going to join forces with Rene Winkelmeyer (of among other things File Navigator fame) in a two hour session on XPages Extensibility Library titled “XPages Extensibility under the hood”. One hour on the basics and a full hour hands-on labs. Hope to see many of you there.

March Lotus Technical Information and Education (LTIE) community meeting

If you’re interested in plugin development and the recently published RedWiki on plugin development for Lotus Notes, Sametime and Symphony (easy url is be sure to join us for the March March Lotus Technical Information and Education (LTIE) community meeting. The conference call will be on 22 March at 10am Central Time (10am Eastern, 3pm CET).

For more info head over to the Lotus Technical Information and Education wiki on Lotus Greenhouse (look under “When we meet” at the bottom of the page).

On plug-ins, features, update sites and extension.xml files…

I’m receiving quite a few e-mails asking questions about features, plug-ins, update sites and extension.xml files and how they relate so I thought I would try and clarify things.

Term Description
Plug-in The smallest unit of code you use to create functionality for an Eclipse based client. This is where the actual Java code is.
Feature Used to package and bundle plug-ins together. Features are thin wrappers for plug-ins and is basically a single file called feature.xml. You can bundle multiple plug-ins into a single feature. When installing code into Notes you actually install the features which in turn point to the plug-ins to copy to the client. You can only manage features through the Notes “code UI” (File/Application/Application Management) though you can install code into the platform by simply copying the plug-ins into the appropriate directories in the file system. This is not recommended… 🙂
Update site Update sites are used to deploy features to clients. An update site is simply a directory containing a

  • “plugins”-directory containing a jar-file per plug-in
  • “features”-directory containing jar-file per feature
  • site.xml file describing which features and plug-ins (and in what versions) are available on that particular update site

When an Eclipse based client contacts an update site it reads and parses the site.xml file to discover what’s available there.

Update Sites may be remote or local. A local update site is a directory on a local hard drive or LAN drive with the above structure or a zip-file with the above structure. An update site may also be remote and may be read using HTTP (any server will do) or it may be read using NRPC if you’re using a Notes 8+ client. When using NRPC you use the Update Site Notes database template.

extension.xml These files are used when installing code using the MyWidgets sidebar plug-in and is a shorthand for manually installing code. There is no magic at work here. When you drop an extension.xml file onto the sidebar panel the following steps are performed:

  1. The extension.xml file is parsed and verified to be a valid XML file
  2. The features to be installed are located and a dependency graph is assembled so any required features are identified
  3. The update site address specified in the extension.xml file is contacted and each missing feature in the dependency grapg is attempted installed “bottom up”
  4. The client is restarted

How to deploy widgets and/or plugins in your organization

Deploying widgets and/or plug-ins in your organization is very easy and there’s a number of options for doing it.

  1. Desktop policies
  2. Widget catalog via MyWidgets
  3. Drag’n’drop of widgets to the MyWidgets sidebar plug-in

Using a desktop policy is just a administration shorthand for using the widget catalog via MyWidgets.

The first thing you really should do, if not simply using publishing widgets created through the MyWidgets functionality, is to read up on and understand the Lotus Expeditor provisioning manifest syntax. The manifest is used to specify where the update site server is and which features and in which version to install. The manifest looks weird at first but it’s actaully easy enough. Unfortunately there isn’t a nice UI for creating these provisioning manifests but I head rumors in the Meet the Developers lab at Lotusphere that a UI is coming. Soon… 🙂

And now for the time and frustration saver…

Absolutely make sure that you put the widget catalog in the root of the Domino server to make sure it ends up in the root of the Notes client. If you do not do this and you specify a widget catalog in the preferences the Notes client wont apply updates to the widgets when new versions are available. This is a bug at least in Notes 8.5 GOLD.