The article "Java Servlets - Configuring Server" made reference to a test servlet named DXTest. In this article I am going to show you how this simple Servlet was built. Here is the java class file for your servlet folder and here is the full java source for import into your Java program if you are as lazy as me.

To refresh your memory, this is what happens when you run the DXTest Servlet on your server:

Not exactly going to rock you but if we start simple and move on from there then hopefully eventually we will.

In a previous article ("Java Servlets - Getting Started") I mentioned the three methods you only need to worry about with Servlets - namely service(), doGet() and doPost(). Well in this article I am going to narrow it down even more - we will only concentrate on doGet() - a request to the Servlet from the browser.

First of all though as we are writing Servlets for Domino, you will need to import the Notes.jar and the NCSOW.jar files into your Java program in order to do any development work. With VisualAge for Java you can add them as a feature using the same method as described in my "Java Servlets - Getting Started" article.

If I find time I shall put up a forum for servlet development - as from experience the actual correct method of importing the Notes.jar and NCSOW.jar files etc into your Java program is harder than the actual development! In the meantime search notes.net for answers to peoples queries on the subject. As usual if you find any explanations that you feel may help others - send them to me and I will post them up.

Ok, now with that out of the way we can do some code work. The first thing you have to sort out is which class files you need to do your development and declare them. The following is how we would achieve this:

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
import lotus.domino.*;

These are the standard four class files I would use for Domino Servlet development. The first class provides methods for reading and writing data streams/outputs to browser etc. The second and third are the key classes required for developing Servlets and the final class contains all the methods etc required to connect to and use a Domino Server. These 'import' statements are positioned before your public class statement (Unfortunately I do not have time to teach Java from scratch so a little knowledge is required).

The NotesFactory class found within the lotus.domino.* classes instantiates a Domino Session Object. Once this session is created you can access Domino Objects as normal (as you would from Lotusscript - although methods/objects are generally missing the Notes part of the name - ie session class instead of NotesSession).

Now as I have mentioned before, security with servlets is a different ball game to that of Agents. The servlet runs with server access rights if the NotesFactory class's createSession method is used without parameters. Otherwise, a servlets rights are set by the username and password specified in the createSession method. This is not as straightforward as it sounds as when you write your code - you do not know the users name and password - unless the servlet will run as a single fixed user. There are other methods, but I shall write an article on this as it involves an awful lot more than what I could write here.

Another point to mention, you do not specify the servername when writing servlets so just use "" instead as they can only run on the server in which they reside.

When you access Domino objects from a servlet, you must also initiate a NotesThread object. This entails the use of the sinitThread and stermThread methods of the NotesThread class. The best way to approach this is by using a try/catch/finally block eg:

try{

NotesThread.sinitThread();

// Your Domino Access Code goes here

} catch (NotesException e) {

// Exception handling

} finally {

NotesThread.stermThread();}

Well thats a whole load of theory done, now time to put it into practice. Don't worry if it looks a bit frightening i'm sure it did to me when I first started down the Java route. I'm sure you will find it easier when you see how the code is actually put together. Here is the full doGet() method for the DXTest Servlet:

public void doGet(HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException {

// using the setContentType method of the HttpServletResponse Object to set output to HTML

res.setContentType("text/html");

// using the getWriter method of the HttpServletResponse Object to create a stream to output text (using the Print Writer object)
PrintWriter out = res.getWriter();

// using the PrintWriter to output basic HTML for page structure
out.println("<HTML><HEAD></HEAD>");
out.println("<BODY TOPMARGIN=0 LEFTMARGIN=0 MARGINHEIGHT=0 MARGINWIDTH=0>");
out.println("Domino Servlet Manager setup Correctly<br>");

// Connecting to Domino Server with thread and exception handling
try{

NotesThread.sinitThread();

// Creating session with server (with server access rights)
Session s = NotesFactory.createSession();

// Printing out more html and using the getServerName() method of the NotesSession class to display the current server name
out.println("Server Name: "+s.getServerName()+"<br><br>");
out.println("http://www.projectdx.org");

// Recycling the Notes Session object
s.recycle();

}catch (NotesException n){

// Handling any exceptions (prints them out)
out.println("Exception ID:"+n.id);
out.println("Exception description: "+n.text);

}finally{ NotesThread.stermThread();}

// Printing out final HTML and closing stream
out.println("</BODY></HTML>");
out.close();

}

Thats it. You will note the try/catch/finally block as mentioned before. I have added comments to the code but in addition you will note the line:

PrintWriter out = res.getWriter();

This is the key to how you send output back to the browser. Once initiated you simply do out.println("Your text/HTML").

Once compiled and placed into your servlet folder you simply would enter the URL: http://yourservername/servlet/DXTest and it should run. - Unless of course you have changed the alias name via the servlets.properties file (as per a previous article).

As a reminder, links to the compiled DXTest.class file and source (.java) files are at the top of this document.

Questions? - steve.castledine@projectdx.org