Getting yourself ready to create servlets

Jake Howlett, 28 April 2002

Category: Java; Keywords: Java servlet netbeans

Servlets. Should we bother using them or not? That's the question I've been asking myself recently. After all, what can we do with servlets that we can't do with agents? That's a rhetorical question by the way, I appreciate that both have their own particular strengths and which one you choose is down to the each situation. Knowing the strengths of each is key to making the right decision in the first place. Hence I need to get to know more about servlets.

One of the things I like about Domino is that the whole design of a site can be, and usually is, centralised within one file. This file is then very easy to replicate its design between multiple servers. When we start talking about servlets we lose this approach and need to start thinking about how to distrubite the resulting servlet files to and between servers. This has always been one of the things that detracted me from using them - who wants to deal with system administrators any more than they have to ;o). Despite this, the release of Domino 6 means we can/will/should/may [choose word depending on Lotus's current whim] be able to create servlets from within the Domino Designer IDE. Domino then takes charge of the distribution of the necessary files for us.

Recently I came across a situation that meant I needed to use servlets and I will talk about that more in the next article. Once I started playing I found I wanted to carry on trying more and more. Servlets have lots to offer - for one thing using them means that it's less work for the Agent Manager if the code were to have been an agent. Also, they are potentially faster as they are loaded in to the server's memory when they first run. By contrast, agents are loaded and compiled each time they are requested.

With this article I want to try and share with you some of the things that confused me while I was getting started. Hopefully then it will be a little less painful for you guys if you choose to follow me.


The first thing that I stumbled on was the version of Java you have to use to compile your servlet. I wrote and compiled a simple servlet on my PC which only had the Java 2 v1.4 JDK. When this servlet ran there was an error message telling me I had a "bad major version number" or something similar. It turns out that this is because Domino still uses the 1.1.8 JDK and I would have to use this. Unless you already use that version (type "java -version" at the command prompt to find out) you will need to download it from here.

Last year, Johan Känngård wrote a great article about creating servlets within the Domino IDE. Whilst this works okay I think it's better to use a dedicated Java IDE where you have the added bonus of code highlighting and code-completion helpers. My current favourite IDE is NetBeans. Not only is it free but it is one of the easiest I've found to get to grips with and it looks good too. The others, VisualAge in particular, scare me with how hard to understand they can be.

Before you start you need to check the server you use is setup to allow servlets to run. This is discussed in detail in this article. The basic approach is to simply accept the defaults in the Domino Directory's Server document, like below:

Server's Servlet Settings

Configuring a Netbeans project:

How you configure the IDE that you choose to use should, in essence, be very similar. If you are going to use IBM's VisualAge then the setup has been detailed in this LDD article. Here I'll show how to do it in NetBeans.

From the Project menu choose Project Manager and then using the New button create a project called something like "Domino Servlets", as below:

NetBeans's Project Manager

Select this new project and use the Open button to open it in the NetBeans IDE.

Before starting to write any servlets we are going to have to mount the files to this project that contain the necessary classes. These files are packages and usually end in .jar. Most importantly we need the Java Servlet Development Kit. This can be found in the file called jsdk.jar in your Domino directory. Also, to do any work with Domino objects from our servlets, we need the Domio classes. These are found in the file called Notes.jar in your Domino directory.

To mount these two archives: Open the Filesystems tab of the Explorere pane in the Netbeans IDE. Right-click the top Filesystems node and and select Mount and then Archive.

NetBeans's Project Manager

Navigate to the each file in turn, adding them to the project, as below:

NetBeans's Project Manager

Now when you ask NetBeans to compile any servlets you create in this project it will know to use these archives when looking for the classes you reference in your code. All that's left to do is to tell NetBeans that this project should use the 1.1.8 JDK when it's doing the compiling. To do this we need to add a new Compiler Type. Open the Options window from the Tools menu and expand the Building twisty and then the Compiler Types twisty. To add a new one, right-click Compiler Types and choose New - External Compilation, as below:

Creating a new Compiler

Call this new compiler something like "Servlets 1.1.8" and, when you're done, select it from the list so that the settings show up, as in the shot below. By default the compiler will use the JDK that is set in the system's Java_Home environment variable. We need to change our new project to use the Java compiler that's in the directory where we installed the 1.1.8 JDK. For me, this was D:\Java\J1sdk1.1.8. The settings you need to change are:

Options for our new compiler

Once you've made these changes to your new compiler all that's left to do is make it the favoured compiler that Netbeans uses for this project. To do this right-click on the Compiler Types node again and choose "Change Order..." from the menu. Select your new compiler and keep hitting the "Move Up" button until it's the topmost in the list. Close all the option boxes and you're now ready to start creating servlets.

Making the compiler the default

Creating the servlets:

Your Netbeans IDE is now ready for action. From the Filesytems tree of the Explorer pane add a new directory where you will be create your servlets. Right-click this new directory and from the New option select Servlet. This will open a Java file that contains the skeleton code required for any servlet.

To compile the servlet once you've added any of the code you need, right-click in the editor and choose Compile. If all goes well the Output window will tell you when it finishes. Your servlet class file will be in the same directory that you mounted to the project. Move this to the servlet directory of your server and you can test it from there. Remember that the file name is case-sensitive when you type it in the browser.

If you have the permissions needed it's handy to share the server's servlet directory, map a drive to it and then configure the "outputpath" of the new compiler to send the servlets straight to the server. Remember that each time you recompile a servlet you will need to restart the HTTP server so that it drops its from memory.

Taking it further:

The possibilities for the use of servlets are huge. Too much for me to go in to now. I think this is enough for one article. Hopefully enough to get you started with some experiments of your own anyway. Within the next couple of weeks I will post some of the code I've been playing with recently, helped along by Brendon Upson and Jon LeDrew. Hopefully then you will see why I am so interested in sharing it with you. In the mean time, feel free to let me know if you have any ideas that you want to share.

If you want to read more about using Servlets with Domino then LDD Today has quite a few articles that should make for interesting reading. If you want to see the code requried to start accessing Domino objects then this article has a section on it.