JAX-RS or THE way to do REST in Domino Part 1

The IBM Domino community has had servlets on its mind lately, and XAgents, and Rest Services.  These are all great advances to using IBM Domino in a modern world.  However to bring IBM Domino into a more modern age of Java Development we must go beyond just writing servlets like it was 1999.  The next few blog posts will show you how to setup a REST Service that uses JAX-RS and runs on Domino.  This will require creating an OSGi plugin.  I am going to assume you have never written such and will try to explain all of the pieces that need to be done and why.

Below are the first few steps to create the plugin.

1.  Download Vanilla Eclipse.  Any version should work, but I would recommend getting the latest, which is Eclispe Luna SR2.  Specifically the one for Java EE Developers.  Its available here:


After its downloaded unzip it somewhere, There isn’t an install just a bunch of files that need to be on your hard drive somewhere.

Once that done you can go about running it by executing “eclipse.exe” There are a few welcome screens that you can skip to get to the screen that is somewhat similar to Domino Designer Workspace.

2a.  I’m making an assumption here that you are either running a local full Domino Server or you have File Access to an install.  If you don’t have either of these, you really should consider it as it will make all of your development work a lot easier, even your normal XPages work.

To give you a little more understanding of how OSGi works, it helps to know that you are creating a bundle (plugin) and that it will interact with other bundles all within a container.  When dealing with Java in our XPages context we tend to think of Java as either source “.java” or libraries “.jar” files.  We need to add a third category of a bundle to create a plugin that does much.  So with that said we have to create whats called a “Target Platform”  inside of eclipse.  This is a profile of what environment will your bundle run in.  For our limited example all we need to add is the directories of where the Domino Bundles live.  There is a couple of them and its really just so our new Bundle can see those.

From the Eclipse menu go to Window-> Preferences.  This will open a dialog.  On the left side of the Dialog you should see Plug-in Development


Expand that section and you will see a new area called “Target Platform” Click on it and you should see a single platform called “Running Platform”, we will be creating a new one, so click “Add”


From there it will prompt if you want to start from an old one or from scratch.   We will be creating one from scratch. So leave it on

“Nothing: Start with an empty target definition”


In the Locations Tab you will Add 4 Directories


C:\Program Files\IBM\Domino\data\domino\workspace\applications\eclipse\plugins\

C:\Program Files\IBM\Domino\jvm\lib\ext\

C:\Program Files\IBM\Domino\osgi\rcp\eclipse\plugins\

C:\Program Files\IBM\Domino\osgi\shared\eclipse\plugins\

Once you have completed these steps you now have setup Eclipse to be able to develop OSGi Bundles for Domino.  In the next part we will create the bundle and discuss each part of the plugin.xml that needs to be setup to create a JAX-RS Service.


6 thoughts on “JAX-RS or THE way to do REST in Domino Part 1

  1. JAX-RS is definitely the way to go. It seems to be the core of DAS, looking at a focus le of articles on Domino app dev wiki. Just a suggestion, XPages SDK for Eclipse RCP project from OpenNTF makes setting up target platforms and JREs very easy. The latest version also includes the debug plugin, to allow you to debug the code by running your plugins directly from Eclipse. I find that invaluable.

    • I am aware of the XPages SDK project, it is a great resource, but hopefully this will give another perspective on how to do OSGi Development without installing more stuff.

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