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.
Prerequisites:
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 Notes.net article. The basic approach is to simply accept the defaults in the Domino Directory's Server document, like below:
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:
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.
Navigate to the each file in turn, adding them to the project, as below:
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:
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:
