Getting yourself ready to create servlets

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 Notes.net 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:

  • External Compiler:
    • D:\Java\j1sdk1.1.8\bin\javac -classpath {classpath} {files}
  • Classpath ("Expert" tab):
    • D:\Java\j1sdk1.1.8\lib\classes.zip;C:\Lotus\Notes\Notes.jar;C:\Lotus\Notes\jsdk.jar

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.


  1. You won, Jake! :-)

    Great article! I gave up creating servlets in Netbeans a while ago, but it seems it works! Haven´t tried it myself yet though...

    1. Re: You won, Jake! :-)

      If I am teaching Johan things about Netbeans then it's time well spent ... ;o)

      Jake -codestore

  2. Another nice (free) Java IDE: Eclipse

    The (free) Eclipse IDE is real nice. Don't let the boring design of the http://www.eclipse.org site fool you, Eclipse has 'it' (Speed, open, good-looking, extensible).

    And visit my Eclipse plugin overview site at http://eclipse-plugins.2y.net whenever you are in need for a specific Eclipse plugin. (Sorry no Domino related plugins for now...)

    1. Re: Another nice (free) Java IDE: Eclipse

      Cheers for the link. Seen Eclipse mentioned in a few places now so I though I would give it a go.

      It does NOT work!!!

      I appreciate this may be due to something I did/didn't do and that it's a Monday morning but I expect programs I download to work and not to have to spend time finding out why.

      All I get is the splash-screen and nothing else. I have the right version of the JRE. Note that I am not looking for help as to why - I am going to stick to Netbeans which comes with a nice MSI style installer and automated incremental updates.

      Jake -codestore

      Show the rest of this thread

      • avatar
      • jey
      • Thu 2 May 2002

      Re: IDE? bah, humbug

      What are IDEs for, other than to make Visual XXXX people feel at home?

      It's not that difficult to find a good editor (JEdit for instance, a little slow, but very well featured; or EMACS/vim for hard-core devs), set up CVS, ANT and the JDK and you have all you need.

      One nice thing about Eclipse (or at least the Websphere Application Developer instance of it) is its integration with CVS and ANT.

      Show the rest of this thread

  3. Forte' (aka NetBeans is tops)

    I think Forte is indeed the best. I wanted to try out a number of java IDEs to see which was best. I had been using Forte'(NetBeans). I tried Visual Age and although I started to understand it (very little), and could compile a Java class. I never found where VA puts the darn things. So I gave up on it and uninstalled it. I also tried Borlands JBuilder. It looked like a comic book compared to Forte'.

    I know some folks who are very impressed with Oracles JDeveloper. Pricey though.

    As far as I'm concerned, Forte' is the best you can write practically every type of file you would need and it's free.


    • avatar
    • Ian
    • Thu 2 May 2002

    Possible problems with running servlets


    I'd just thought I'd drop a quick line here incase anyone else runs into the problems I had when going through the today article about running servlets with Visual Age... bearing in mind that I'm completely new to this area...

    First thing:

    The article tells you to specify a path in the server config doc, where you are going to store your servlets. NOTE you have to manually create this directory as Notes doesnt do it for you - which isnt mentioned in the article...

    Secondly - I'll just point you at this post on notes.net

    http://www-10.lotus.com/ldd/46dom.nsf/55c38d716d632d9b8525689b005ba1c0/f1578326f 31371c5852568ff0061a1dc?OpenDocument&Highlight=0,servlet

    As of writing this I'm still trying to get the thing to work, but seem to have overcome the first two problems... but why cant Lotus first test these articles out on people completely new to the technology first and document the potential pitfalls into the article, it sure would save a lot of trouble....

    Rant over,


  4. authentication using servlets

    Can a servlet be used to pass user variables for session authentication?

    For example, I do not want to use the default server page for session authentication. I want to have a customized login page per application and the user id and password entered on this page should be used for session authentication.

    Even if I don't use a servlet, any cluz?


  5. NetBeans andJDK versions

    Jake, I am trying to follow the path you took to get started writing servlets. I downloaded JDK (because you mentioned Domino still uses 1.1.8) and then went to download NetBeans. The NetBeans requirements says you need JDK 1.3 or higher. Has Domino changed which version of the JDK it uses ? What should I do now ? uninstall JDK and download JDK 1.3 ? Thank you for your assistance.

    Bron M. Burda Corporate Commercial Finance Application Support bron.m.burda@bankofamerica.com

    P.S. I support a complex Notes application. I need to webify the app and also remove all dependency on the Notes Client because we are moving away from Lotus Notes and the client licenses expire at end of year 2003. Hence my interest in Servlets. I have not worked with JAVA before. If you can offer any other advice on how to attack this problem I would glady put on my "Great American's List" and send lots of positive Kharma in your direction.

      • avatar
      • Jake Howlett
      • Tue 19 Nov 2002

      Re: NetBeans andJDK versions

      Hi Bron,

      The confusing thing about the Java environments is that you can have more than one installed at a time on your PC.

      You need the higher version to actually run NetBeans and the older 1.8 version so that it can use this to compile your servlets.

      Glad you think I'm great but I'm not American...

      Jake -codestore

      Hide the rest of this thread

      1. Re: NetBeans andJDK versions

        Thanks!...how about "Honorary American" ?

        1. Re: NetBeans andJDK versions

          Just wanted to let you know that we compile servlets quite happily here with j2sdk1.4.1_01.

          All you need to do is add: -target 1.1 to the compiler syntax and it will generate compatible bytecode.

          While I quite like the functionality that Netbeans provides it's major failing is performance. It's just too slow!

          I'm currently looking at Eclipse which is much faster because of the SWT implementation, but for now I have some compile scripts and DOS edit :D

Your Comments


Navigate other articles in the category "Java"

« Previous Article Next Article »
Sending HTML mail via SMTP part 1   Forcing attachments to always download

About This Article

Author: Jake Howlett
Category: Java
Keywords: Java; servlet; netbeans;


Print Friendly

Let's Get Social

About This Website

CodeStore is all about web development. Concentrating on Lotus Domino, ASP.NET, Flex, SharePoint and all things internet.

Your host is Jake Howlett who runs his own web development company called Rockall Design and is always on the lookout for new and interesting work to do.

You can find me on Twitter and on Linked In.

Read more about this site »