How to extend Notes 8: dynamic extensions using Java

I get so many question on how to extend Notes 8 that I finally decided to create a series of blog posts on how to do it. All the posts in the series may be found under the extending_notes8 tag. In all of the examples I assume a working knowledge of Eclipse and Java programming and how to work with extension points.

As I briefly mentioned in my last post ("How to extend Notes 8: capture group LiveText recognizers with a Java action") it's possible to create new extensions to Lotus Notes using Java and hence inject functionality into the client dynamically. It's very cool functionality and it allows you to inject anything from content types and recognizers to sidebar panels. I've used this a lot previously and also demoed it in my "How dynamic are your Notes sidebar plugins?" demo. Watch the Flash video and see how you can make sidebar panels come and go on demand.

Now on to the code...

The trick to dynamic extensions is to inject extensions into the Extension Registry at runtime. The Extension Registry is where Eclipse reads the plugin contributions from plugin.xml files into at startup. If we inject an extension, and the receiving plugins are set up to handle dynamically adding extensions you are golden. Let me show you have to use the Extension Registry.

final String extensionXml = ...;
final IExtensionRegistry reg = Platform.getExtensionRegistry();
InputStream ins = new ByteArrayInputStream(extensionXml.getBytes());
Bundle bundle = Activator.getDefault().getBundle();
IContributor contr = ContributorFactoryOSGi.createContributor(bundle);
reg.addContribution(ins, contr, false, null, null, null);

1. Defines the extension XML to add (more on this later).
2. Gets the extension registry from the platform.
3. Reads the extension XML into an input stream.
4. Retrieves the bundle.
5. Creates a new contributor that is the object that makes the contribution to the extension registry.
6. Adds the contribution to the registry.

So what is the extension XML mentioned above?

The extension XML is the XML that defines the extension you're adding. It's actually any piece of XML you would stick in your plugin.xml file either manually or using the UI editor. An example could be a custom recognizer and content type as shown below as a snippet from Java.

final String extensionXml = "<?xml version=\"1.0\" encoding=\"utf-8\" ?>" +
"<?eclipse version=\"3.2\"?>" +
"<plugin>" + 
"<extension id=\"DCR.ExampleRecognizer.%s\" 
   point=\"com.ibm.rcp.annotation.regex.regexTypes\">" + 
"<regexTypes contentTypeId=\"DCCT.ExampleContentType.%s\" 
   id=\"DCR.ExampleRecognizer.%s\" match=\"([A-Z]{4})-(\\d{4})\" 
   name=\"Example Recognizer\">" + 
"<group contentTypePropertyId=\"pn\" number=\"2\"/>" + 
"<group contentTypePropertyId=\"pf\" number=\"1\"/>" + 
"<group contentTypePropertyId=\"contents\" number=\"0\"/>" + 
"</regexTypes>" + 
"</extension>" +  
"<extension id=\"DCCT.ExampleContentType.%s\" 
   point=\"com.ibm.rcp.content.contentTypes\">" + 
"<contentSet>" + 
"<type category=\"Recognized Content\" 
   id=\"DCCT.ExampleContentType.%s\" 
   name=\"Example Content Type\">" + 
"<property description=\"Entire Contents\" id=\"contents\"/>" + 
"<property description=\"Product Family\" id=\"pf\"/>" + 
"<property description=\"Part Number\" id=\"pn\"/>" + 
"</type>" + 
"</contentSet>" + 
"</extension>" + 
"</plugin>";

That's how you do it. Tomorrow I'll show how to combine it with our custom recognizer and content type to inject it dynamically into the LiveText system in Lotus Notes. Stay tuned...