Creating a Servlet for IBM Domino

Another tool in your Web Development toolbox…

Over a few posts I’m going to build a Servlet in Java and deploy it on a Domino server and progressively make it do more useful things.

The next few posts will cover:

  • Creating the basic Servlet
  • Tweaking OpenLog from OpenNTF to provide a mechanism for logging
  • Enable the Servlet to use Domino objects via the Extension Library
  • Using the Apache HTTP libraries to access other web resources
  • Create and return some XML.

Along the way we’ll have a quick chat about Thread Safety.

As with so many things in Notes and Domino development there are many ways to get the job done. Servlets being no exception. In addition to this method you could also deploy one as OSGi plugin or create a simpler xAgent.  This is just one way.

I have to acknowledge some help I’ve had along the way including Niklas Heidloff, Nathan Freeman and Sven HasselBach (via his blog which shares a link to a Chinese Developerworks article).  I will also come to thank Paul Withers as it’s his implementation of Openlog that I’ll be gently tweaking so I can use it in the Servlet.

The method described in the following posts runs within the context of a single NSF but is easy to create and manage.  The OSGi method for creating a Servlet ( is a little trickier to create and manage for a more traditional Notes developer audience, I think.

What is a servlet?

Read more ›

Tagged with: , , ,
Posted in Coding, XPages

Creating a basic Domino Servlet

All of the code will be provided in a database I have to figure out how to make it available since free accounts don’t allow the storing of zip files.  Perhaps I could share a Dropbox folder?

If you’ve come here directly there is a short introduction available here: Creating a Servlet for IBM Domino

Apologies for the death by screenshot, I know the modern way is YouTube but I’m a sadist apparently 🙂  Some credit for the stuff in this post belongs to:

Sven HasselBach (via his blog which shares a link to a Chinese Developerworks article

Begin at the beginning…

I’m going start with a new blank application, you don’t have to.

Create a new application

It’s all java from now on.  You could open the Java Perspective or like me the Package Explorer view.


This bit is optional…

This next little section isn’t necessary to get the Servlet running but I normally want to create variables whose values will not change during the lifecycle of the Servlet. If I create a mechanism for using them at the beginning I’m more likely to use it.

If you want to skip it look below for text < resume here 🙂 > below.

Right click on the Code/Java source folder (highlighted in the image above) and choose new.

Open the Package Explorer view

Expand the Java Folder and choose package.


Name the package in reverse domain format. I’m going to use this package for classes that support the Servlet like Constants.


Right click the new package and choose new. From the Java folder choose Class.


Name the new Class. I’m calling this one Constants and I’ll use it to create static final variables that will be used every time the Servlet is instantiated (like global variables in Lotuscript).


The new Class will open in the Editor.  In the image I’m adding a new variable DEBUG. The convention I’m adopting is to have variables in this file named in uppercase.


< resume here 🙂 >

Making a package, and Servlet Class

Right click the Code/Java folder and choose new. Create a new Package and name it.  I’ve called mine com.jho.servlets.



Create a new Class by right clicking in the servlets package and choosing New and click OK.


The new class will extend javax.servlet.HttpServlet


Making the Servlet talk

I’ve added some methods signatures.  Most take  HttpRequest and HttpResponse arguments. We’re going to work on the doGet method which will provide a response when we request http://<your server>/servlets.nsf/XSP/exampleservlet


In the doGet method I create a PrintWriter that we’ll use to send data back to the requester. I’ve set the content-type on the response object to “text/plain”.  For other uses it might be set the “application/xml” or “text/html”.  The PrinterWriter responds with “Servlet Running” before we close it.


Our Servlet Class is now ready to do work but before it can be created by the Server we need to create a mechanism by which the it can map the request url to the Servlet and instantiate it.

Adding an external jar

Open the Project Properties, choose Java Build Path and click “Add External JARs”


The jar we’re after is lwpd.domino.adapter.jar <Notes program directory>\osgi\shared\eclipse\plugins\


Click Open, and then OK to close the Project Properties.

Building a Servlet Factory:

Create a new package and name it com.jho.factory or your domain.factory


Right click on the package and create a new class.  Name the class ServletFactory and click Browse beside Interfaces.

In the choose Interface field type IServlet, and because we added that jar earlier Notes should know about the IServletFactory interface.  Choose that and click add.


Click Finish to create the new Class which will open in the editor.


This class will match the the incoming url with a Servlet, and return a new instance of the Servlet.  I’ve added the code for the Class below.


Why am I using a HashMap for just one Servlet? Let’s say I wanted to create two or three Servlets and have this factory create instances of those. I can simply add to the HashMap. It’s not terribly efficient code, particularly if I had loads of Servlets but I don’t at the moment.

package com.jho.factory;
import javax.servlet.Servlet;
 import javax.servlet.ServletException;
 import java.util.HashMap;
 import java.util.Iterator;
 import java.util.Map;
public class ServletFactory implements IServletFactory {
private static final Map<String,String> servletClasses = new HashMap<String,String>(1);
 private static final Map<String,String> servletNames = new HashMap<String,String>(1);
 private ComponentModule module;
public void init(ComponentModule module){
      servletNames.put("exampleservlet","Example Servlet");
 this.module = module;
public ServletMatch getServletMatch(String contextPath, String path)
throws ServletException {
try {
 String servletPath = "";
 //iterate the servletNames map
 Iterator it = servletNames.entrySet().iterator();
 Map.Entry<String, String> pairs = (Map.Entry<String, String>);
 if (path.contains("/" + pairs.getKey())){
 String pathInfo = path;
 return new ServletMatch(getWidgetServlet(pairs.getKey()),servletPath,pathInfo);
 } catch(Exception e) {
    return null;

 public Servlet getWidgetServlet(String key) throws ServletException {
        return module.createServlet(servletClasses.get(key),servletNames.get(key),null);

Save and close the class.

There’s just one more important step.

Expand the Code/Java folder and right click the folder.  Choose new and find “Folder” in the wizard.

Name the folder META-INF and ensure it’s being created in <your database>/Code/Java


Create another folder within META-INF and call it services.

Create a new file within services and call it The file should open in the editor, add the fully qualified name of your ServletFactory class. In this example the only line in the file should read:



Save and close the file.

Edit the database ACL and make the default reader, add an entry for anonymous and make that reader.  Build your project (because you have Build Automatically turned off 🙂 ). Copy or replicate the database to your server.

Open a browser, and go to the location:

http://<servers fqdn>/<path to database>/XSP/exampleservlet

For example

Your server should return the text “Servlet Running”


In the next post we’ll add some logging before making it a wee bit more functional.

Tagged with: , ,
Posted in Coding, Tips, XPages

Good xPage Foundations

I’m starting a new xPage project.  A little early to start writing code but I’m laying the foundations after gathering some requirements and sketching an architecture.

Perhaps you’d be interested in my foundations and you might have some you could suggest….

Layout – This is for internal use and I’m going to use the Extension Library Application Layout Control

Managed Beans – I like them, and the first one I’m adding is called Constants.  I use this one in application scope to hold values for view names etc unless they would be better placed in a configuration document.  Managed Beans are good use them.

Scoped variables – keep a track of them.  Think about when you should remove them from longer lived scope.

Create a configuration document mechanism – You shouldn’t design a system where you the designer have to edit code to change email addresses, locations/replica id’s, Logging levels etc

Logging – Use logging from day 1, it’s harder to retrofit and easier to get into the habit of using it as you code. Use your own or OpenLog. I like to create logging levels, and be able to change them from a configuration document.  Provided I’ve placed logging in all the right places I can elevate the level to see what’s going on in the application as it’s running if there are issues or lower them so that only errors are logged.

On the subject of errors – handle them! If the user needs to know about an error control the way they are displayed but don’t allow them to see an “unexpected runtime error” page.  If you think about error handling from the beginning, establish a pattern for handling error and apply that consistently you will reduce the possibility of users seeing your bad coding.

Server Page Persistence (App Properties XPages tab) – I’m choosing “Keep the current page in memory”

Garbage in is garbage in – validate user inputs on the client side and server side.

Lifecycles are important – you understood the various events in traditional Notes form design.  The xPage lifecycle is no less important.

Buy & dip into or read the three IBM Press xPage Books:

Mastering xPages
xPages Extension Library
xPages Portable Command Guide

Turn off “Build Automatically” from the Projects menu in designer as there are unintended consequences – see Paul Withers excellent investigation

I’m sure there are more I’ll post them here but I’m convinced imposing a discipline on yourself to lay good foundations and build on those will stand your application and you in good stead.

Tagged with: , , ,
Posted in Coding, Tips, XPages

On getting to there (XPages fluency) from here

I recently got involved in a couple of brief discussions about continuing professional development.  Both were in the context of transitioning from traditional IBM/Lotus Notes & Domino development to the new cheese of XPages.

In the discussion we recognised that there are a number of N&D developers that have yet to look at XPages in any depth or take advantage of the many excellent resources the community has been developing.  The feeling was that for some developers XPages appears hard, perhaps too hard.  If that’s describes how you feel then I wrote this post to encourage you.

From the film Jacob’s Ladder:

Eckhart saw Hell too. He said: “The only thing that burns in Hell is the part of you that won’t let go of life, your memories, your attachments. They burn them all away. But they’re not punishing you,” he said. “They’re freeing your soul. So, if you’re frightened of dying and… you’re holding on, you’ll see devils tearing your life away. But if you’ve made your peace, then the devils are really angels, freeing you from the earth.”

Seem a bit too melodramatic? If you grasp the idea that the only painful bit about getting started is holding on to the old ways too firmly, forgive a man the odd indulgence and read on 🙂

Why do I care?  Because I put off getting started too.  “It’s another one of those shiney technologies that IBM introduces and quickly drops”, “I’ll have a look at it when it’s a bit more mature & I have more time”.

When XPages surfaced I had spent the best part of 12 years working with cc:Mail, Notes, and Websphere Portal Server.   I was busy developing and maintaining applications for the Notes client and the Web but it was painful, really painful.

The arrival of XPages promised a way out of all of that. Web standards, commonly understood programming languages, isn’t hamstrung by all the legacy stuff and peculiarly Notesy way of doing things we’ve had to learn over the years.  At last a chance to rub shoulders with the current crop of web platforms & do things properly.  Why as a life long learner, and a magpie wouldn’t I grasp that with both hands?

“How much time will I have to invest in getting up to speed?”,  “I know I can get my work done using the skills I know today why should I take a risk when I’m already busy by straying off the beaten track?”, “It doesn’t feel like a gentle evolution this is a step changes it feels revolutionary….”,”I have to learn JAVA?”

Not all of those statements apply to me. I was a certified JAVA developer 🙂

Lots of us N&D developers fell into development because we were the only ones that showed an interest in it or were just willing to have a go.  We built our comfort zone over a long period of time and this XPage thing seemed to be tearing away at the foundations.  That’s unsettling at the very least perhaps a bit frightening.

Remember when you started developing in Notes? It was designed to make it easy for you to click and drag fields on to forms, to create views, framesets.  You could get stuff done, make work easier and do it quickly.  You were a hero!

Life was simpler then and so were the requirements.  You probably hit many limitations and found ways round them but things have contmoved on & it’s become harder and harder to keep up with the needs of the people that use your applications by using the same old techniques & with the perceptions others have of the competition.

The good news is you can still be a hero, you can keep making things better, you can still make a difference.  If you are currently developing web applications in Domino you can do it more easily with XPages.  You can still do drag and drop development like you are used to, but you can go way way beyond that.  You’re not tied down by the limitations of Notes like you have been.

Have your ever tried maintaining state information in a traditional Domino web application?  For example steps in a complex transaction like a purchase or an application form?  Maybe you passed data forward and back with parameters on the url, you encrypted them to make them tamper proof, wrote code to diagnose what stage you were being asked to progress or revert to. Hateful. Particularly in six months when you have to change to incorporate new steps.  With XPages you can store information like this in little containers that exist for as long as a page is viewed, or a user remains logged in or for the life of an application. Getting it there is as easy as putting it there (sessionScope.put(“process_step”,”3″)) and getting it back (sessionScope.get(“process_step”)).

I hate “hide when” with a passion.Hate.IT. What if instead you could use dot notation to hide or display bits of your page?  Well you can: getComponent(“myTextField”).rendered = true.

There are loads of examples where the knowledge that you have is very transferable. Like @Formula  you can still use that.

What if you have just been developing client apps all this time?  Your learning curve is a bit steeper it’s true. You are going to need to develop some new skills:

JavaScript (and eventually you will want to know JAVA but not necessarily straightaway).  The good news is that programming languages share lots of the same concepts: variables, loops, conditions, error handling it’s grammar.  So if you’ve done some Lotuscript programming that’s going to stand you in good stead.

CSS, HTML etc etc. It’s starting to get daunting? Well XPages provides enough of the basics for you to get things up and running with a little knowledge.  You can use the built in theme of ONEUIV2 and the Application layout control to build an attractive layout with navigation in just a few clicks.  Do that from scratch and it will take ages. Imagine IKEA for your web application.

Just because the hill is steep that’s not an excuse not to climb if you’d prefer not to be left at the bottom.  You’ll acquire confidence, knowledge and understanding as you go!

All that’s left is to get started.  So where do you go?

If you know your way around the Domino Designer client then Matt White and Tim Clarks XPages Blast 2012 is pretty good (  Otherwise consider investing a little cash in subscribing to again it’s Matt White (I’m not affilliated, but I’m a customer :-)) or FREE of charge there’s David “100,000 viewings can’t be wrong” Leedy’s Intro to XPages on (

Now strike whilst the irons hot!  Print the XPages blast slides, watch David’s video.  Let it wash over you and then go back and watch it again.  You’ll feel better.

If you haven’t already got a copy of the latest Domino Designer for Eclipse grab a copy here: you can do quite a lot of the groundwork working against local databases.

Good luck!  If you need more help ask questions let’s see if the stuff you need isn’t already out there…

Tagged with: , , , , ,
Posted in XPages