19 May 2014

Domino OSGI (Part 2) - Configuring Eclipse for XPages OSGI Plugins

In my previous post I described how to initially setup eclipse in preparation for creating your own XPage plugins. This will then allow you to deploy your Plugins from eclipse and debug when necessary.

To use your own controls you will need to create a plugin and install this into Domino Designer and onto the Domino Server. My preference is wrap the plugin up into an update site and install as described in this article: How to install the new XPages Extension Library with the Eclipse Update Site database

One of the issues with the above is that if you are constantly making changes to the control (eg. adding new properties) you need to continually export them to an update site, import the new update into Designer and restart, which after a few times becomes frustrating.
So to get around the issue i make a couple of changes to my local Designer configuration as described below.

Open your notes directory, navigate to the framework directory, create a new folder and name as you feel suitable (e.g. jmc-plugins). Inside the newly created folder create another folder called eclipse.
Next navigate to the framework\rcp\eclipse\links folder and create new text file named again as you feel suitable ensuring it has the extension ".link" (e.g. jmc-plugins.link)
Inside your newly created text file add the following:
  path=C\:/Program Files (x86)/IBM/Notes/framework/jmc-plugins
ensuring the path is to your newly created directory.

What the link file does is tells Designer to look in the new folder to load any additional plugins/features which will then allow you to export you plugin directly into this folder.

Unfortunately this will not work just yet as Designer by default does not allow you to plugins in this way, to resolve this you need to edit the following file
Change the transient attribute on the config tag to false and replace all the instances of policy="MANAGED-ONLY" to policy="USER-EXCLUDE"

For these settings to take effect you will need to completely close Notes/Designer/Administrator and re-open. I have read that you need to use the following when restarting Designer using the command "designer.exe -RPARAMS -clean". I can't remember doing this myself.

6 May 2014

Domino OSGI (Part 1) - Configuring Eclipse for XPages OSGI Plugins

Recently I have been writing some of my own XPage components, initially i began writing them inside domino in the nsf that was using them.
I eventually i began to put some of the controls inside other nsfs, but as always i had to make some fixes enhancements to the bugs Features that I happened to code into the components. I then had to go back to the other databases and apply these enhancements.
So, I decided it was time to write my own plugin to deploy the components to the server so they would be available to all applications also giving me one place to update.

In the next series of posts I'm going to describe how i set up my environment to create plugins using eclipse.

Part 1 - Downloading and Configuring Eclipse

Firstly download Eclipse, I use Eclipse IDE for Java EE Developers however i think Eclipse for RCP and RAP Developers is also suitable.
Extract the Eclipse folder from the downloaded zip into your desired location eg: c:\Program Files\Eclipse
I then create a shortcut on my desktop to the eclipse.exe

Next download XPages SDK for Eclipse RCP from OpenNTF and the Domino Debug Plugin from IBM. Extract the update site from the Domino Debug Plugin zip file (com.ibm.domino.osgi.debug.site.zip)

Now we have everything we can start Eclipse and configure accordingly. When you first start Eclipse you will be prompted to choose your workspace. Change if you wish or just click OK.
Once inside eclipse go to Help -> Install New Software. When the Install window loads click Add to link to a new repository. Enter a name 'Domino Debug Plugin', click Archive and select the debug plugin update site you extracted earlier.
Click ok. Expand the list and select the Domino OSGI Debug feature
Click Next -> Next -> Accept the license -> Click Finish
OK the security warning
Don't bother restarting yet. Go back and install the XPages SDK as we did with the Debug plugin above:
Once the XPages SDK is installed restart Eclipse.

Now we need to configure the XPages SDK. Goto Window -> Preferences and select XPages SDK at the bottom.
Ensure you tick Automatically create JRE and fill in the fields accordingly
Click Apply.
Next go to Java -> Compiler and drop the compliance level to 1.6 (assuming it's not there already). Click Apply.

Go to Java -> Installed JREs and select XPages Notes JRE (This will not be here if you did not tick the box above)
Go to Plug-in Development -> OSGi Frameworks and select Domino OSGi Framework. Click Apply.

Finally we need to create a Target platform, fortunately this is easy with the XPages SDK installed.
Go to Plug-in Development ->Target Platform and click Add
Select Template Notes Install Target
Click Next. Click Finish.
Now select the Target we just created and click Apply.
Click OK

There we go, we are now ready to begin creating a plugin!