Bundle Inspector – Diagnosing XPages Plugin Resolution problems

A common task with XPages development is to installing some plugins that provide additional functionality.
If you do any plugin development of your own, you end up doing this task a lot more as you create new plugins, install new versions etc.

It is also common to encounter some problems after installing plugins to your Domino Server! Maybe your expected plugin doesn’t load up at all? maybe the wrong version is loading?

The standard method of diagnosing these problems is to use the OSGi console via the Domino Console (for the server) or by launching Designer with the -RPARAMS -console arguments.

However to provide a more user friendly way to diagnose problems, I have written a plugin for both the Domino Server and Domino Designer which provides a little more user friendly experience of diagnosing plugin problems than the standard method of using the OSGi console.

Disclaimer: Throughout this I use the words Plugin and Bundle interchangeably. Technically in OSGi they are called Bundles, but Eclipse calls them plugins, so there is a weird overlap. But for the purpose of this they are the same thing.

The Some common root causes are:

• You plugin is not loading at all
  Maybe your Server/Domino designer is not actually configured to load plugins from where you think it is?
• Some extra versions of the plugin are being loaded from somewhere you didn’t realise
  Plugins can be loaded from more than one location, for example NSF Update Sites, File system, Eclipse Workspace Projects (when developing on a local Domino Server). So it is often very important to inspect exactly what plugins are loaded and where they are loading from.
• You plugin is loaded but some of it’s dependencies cannot be resolved
  Even when plugins do load correctly, they may have problems resolving their dependencies, and then they end up with the state ‘INSTALLED’ but not resolved, and effectively useless.

How to Install Bundle Inspector

Download the latest release of GregorbyteXspLibrary, and Install the ‘Bundles Inspector’ feature to your Domino Server and Domino Designer.
I am assuming if you have a need for the Bundle Inspector, then you must know how to install plugins to Domino Server or Designer, but if you don’t know then let me know via a comment and I will detail the process.

You can also install the other main feature of GregorbyteXspLibrary if you would like some other XPages controls that I have blogged about before.

Using in Domino Designer

After you have installed and restarted, you should see 2 new buttons in the toolbar / menu bar

The Puzzle piece button will launch the Bundle Inspector. You can then filter for a particular plugin that you are having a problem with.

Note that by default it is a ‘starts with’ match,  but you can use wildcards such as * if you would like to do a ‘contains’ match as I am here for anything with ‘gregor’ in it.

• Plugins are sorted alphabetically ascending, and then descending by version, so the most recent version should be at the top.
• Plugins that are Resolved will show the green puzzle piece icon, plugins that have not resolved will show the grey puzzle piece icon.
• Beneath the list you can view the ‘location’ of  the selected plugin e.g. where did the plugin load from.

If you would like to see the reason why a plugin has not resolved, select it from the list and click OK, as you can see here, the libphonenumber is plugin is not loaded because there is a newer version of it loaded.

Using on a Domino Server

The way Bundles Inspector works on the server is, by providing a ‘bundlesBean’ from an XspLibrary. To use this bean, you need to setup a particular page in an XPages Database.

For these steps, It is assumed that you have the Bundles Inspector plugin installed to both your server and your Domino Designer.

Setup the XPage

It is a good idea to put the BundleInspector XPage in a database that does not depend on any other Xpages libraries. This way, if there is a problem with any of the Xpages libraries that you usually use, it will not affect the BundlesInspector Xpage. You can also put access control on this database if you want to restrict who can use the Bundles Inspector.

Go to the XPages Properties page and enable the ‘com.gregorbyte.xsp.bundlesinspector’ library

Then Create a new xpage in your desired database

Select the ‘Copy Sample XPage to Clipboard’ button.

You should then see the confirmation message

Go to the Source tab of your XPage and paste the contents over the top

Feel free to customise this page to however you like, you could change the colours layout etc. The page is merely provided as a starting point.

Using the Bundle Inspector for the Server

Navigate to your XPage in your web browser. (The XPage should be on the Server that you are diagnosing bundles for)

• You can filter for the plugin your are interested in using the filter
• There is also an example of including a quick link to a common search e.g. extlib
• The bundle location is shown in the table so you can see where the plugin is loading from
• The bundle state is shown on the Right, green means resolved, red means not resolved

If a plugin is not resolved you can click the ‘Diagnose’ button and the diagnosis will show beneath the row of the plugin

 

Conclusion

So there you have it, the aim of the Bundle Inspector is to give a better experience for diagnosing plugin problems.

Let me know what you think, would this help you? any improvements? Can you think of a better name the Bundle Inspector? I don’t really like it but that is what I went with…

If you have any problems installing let me know!