This chapter describes how to create effective Java servlets to control interactions in Netscape Application Server applications.

• Introducing Servlets
• Designing Servlets
• Creating Servlets
• Invoking Servlets

• Servlets are created and managed at run time by the servlet engine, a component of NAS that runs inside the Java server.
• The input data on which servlets operate is encapsulated in an object called the request object. A servlet's response to a query is encapsulated in an object called the response object.
• Servlets call EJBs to perform business logic functions. Servlets call JSPs to perform page layout functions.
• You can extend a servlet's functionality by using APIs provided with NAS. You are not required to use any of these APIs in order to create a servlet.
• Servlets control user sessions in order to provide some persistence of user information between interactions.
• Servlets can be a part of a particular application, or they can reside separately in order to be available to multiple applications. The latter type are said to be members of the generic (or default) application.
• Servlets can be dynamically reloaded while the server is running.
• Servlets are addressable as URLs. The buttons on your application's pages usually point to servlets. Servlets can also call other servlets.

1. Process incoming request from client

When a user clicks a button to submit information to your application, form, page, and session data are passed as a parameter to a servlet in a request object. A response object is also passed which contains information about the client itself. The servlet can manipulate these objects as well as forward them to other application components.

If an instance of the servlet does not already exist, NAS instantiates it when it is called. Servlet configuration information is loaded into NAS when the servlet is instantiated.

2. Generate content

The servlet dispatches business logic tasks by invoking business objects (EJBs). The servlet may also invoke other servlets, JSPs, or other classes as needed to perform discrete tasks. The servlet gathers results in the request object.

3. Create a response

The servlet generates a response by either creating a browser page and sending it directly to the client, or by dispatching the task to a JSP. The servlet remains in memory, available to process another request.

• Generic servlets extend javax.servlet.GenericServlet. Generic servlets are protocol independent, meaning that they contain no inherent support for HTTP or any other transport protocol.
• HTTP servlets extend javax.servlet.HttpServlet. These servlets have built-in support for the HTTP protocol and are much more useful in a NAS environment.

Servlets are instantiated by the servlet engine. After the servlet is instantiated, the servlet engine runs its init() method to perform any necessary initializations. Override this method only if you need to perform an initial function for the life of the servlet, such as initializing a counter.

When a request is made, NAS hands the incoming data to the servlet engine, which processes the request, including form data, cookies, session information, and URL name-value pairs, into an object of type HttpServletRequest called the request object. Client metadata is encapsulated as an object of type HttpServletResponse and is called the response object. The servlet engine passes both as parameters to the servlet's service() method.

The most straightforward servlet expects one certain request and provides one certain response, as in the following diagram:

You can write a single servlet to handle many similar (or even dissimilar) requests by setting a conditional flag for each request, as in the following diagram:

flag = request.getParameter("flag");
if ( flag.equals("step1")) {
    process_step1;}
else if ( flag.equals("step2")){
    process_step2;}
}

If reusable code is your goal, you can create several small servlets to handle individual functions in the course of a request, and each servlet can call other servlets for subprocessing using the forward() method, as in the following diagram:

• Design the servlet into your application, or, if you want it to be accessed in a generic way, design it so that it accesses no application data.
• Create a class that extends either GenericServlet or HttpServlet, overriding the appropriate methods so that they handle requests.
• Write a servlet configuration file, or assign your servlet to an existing configuration file.
• If your servlet is part of an application, write an application configuration file that includes your servlet configuration file. If your servlet stands alone (i.e., is part of the generic application), add its configuration file to the application configuration file for the generic application.

• Writing the Servlet's Class File
• Creating the Servlet's Configuration File
• Accessing Optional NAS Features

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
public class myServlet extends HttpServlet {
    servlet methods...
}

You can override the class initializer init() if you need to initialize or allocate resources for the life of the servlet instance, such as a counter. The init() method runs after the servlet is instantiated but before it accepts any requests. For more information, see the servlet API specification.

public class myServlet extends HttpServlet {
    int thisMany;
    public void init (ServletConfig config) throws ServletException {
        super.init(config);
        thisMany = 0;
    }

You can override the class destructor destroy() to write log messages or to release resources that would not be released through garbage collection. The destroy() method runs just before the servlet itself is deallocated from memory. For more information, see the servlet API specification.

out.println("myServlet was accessed " + thisMany " times.\n");

When a request is made, NAS hands the incoming data to the servlet engine, which processes the request, including form data, cookies, session information, and URL name-value pairs, into an object of type HttpServletRequest called the request object. Client metadata is encapsulated as an object of type HttpServletResponse and is called the response object. The servlet engine passes both objects as parameters to the servlet's service() method.

public void doGet (HttpServletRequest request, 
                   HttpServletResponse response)
            throws ServletException, IOException {
    doPost(request, response);
} 

String username = request.getParameter("username");

request.setAttribute("favoriteDwarf", "Dwalin");

import cart.ShoppingCart; 
...
// Get the user's session and shopping cart 
   HttpSession session = request.getSession(true); 
   ShoppingCart cart = (ShoppingCart)session.getValue(session.getId());
   // If the user has no cart, create a new one 
   if (cart == null) { 
        cart = new ShoppingCart(); 
        session.putValue(session.getId(), cart); 
   } 

String jndiNm = "Bookstore/cart/ShoppingCart"; 
javax.naming.Context initCtx; 
Object home; 
    try { 
          initCtx = new javax.naming.InitialContext(env); 
    } catch (Exception ex) { 
          return null; 
    } 
    try { 
          java.util.Properties props = null; 
          home = initCtx.lookup(jndiNm); 
    } 
    catch(javax.naming.NameNotFoundException e) 
    { 
          return null; 
    } 
    catch(javax.naming.NamingException e) 
    { 
          return null; 
    } 
    try { 
          IShoppingCart cart = ((IShoppingCartHome) home).create(); 
          ... 
} catch (...) {...} 

• Synchronize access to all instance variables, as in the following example:
  public synchronized void method() (whole method) or
  synchronized(this) {...} (block only). Because synchronizing slows response time considerably, synchronize only blocks, or write your blocks so that they do not need to be synchronized.

For example, this servlet has a thread-safe block in doGet() and a thread- safe method called mySafeMethod():

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
public class myServlet extends HttpServlet {

public void doGet (HttpServletRequest request, 
                   HttpServletResponse response)
            throws ServletException, IOException {
    //pre-processing 
    synchronized (this) {
        //code in this block is thread-safe
    }
    //other processing;
    } 
public synchronized int mySafeMethod (HttpServletRequest request) {
    //everything that happens in this method is thread-safe
    }
}

• Create a single-threaded servlet by implementing SingleThreadModel. In this case, when you register a single-threaded servlet with NAS, the servlet engine creates a pool of 10 servlet instances (i.e., 10 copies of the same servlet in memory) that can be used for incoming requests. A single-threaded servlet can be slower under load because new requests must wait for a free instance in order to proceed, but this is less of a problem with distributed, load-balanced applications since the load automatically shifts to a less busy kjs process.

For example, this servlet is completely single-threaded:

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
public class myServlet extends HttpServlet 
    implements SingleThreadModel {
    servlet methods...
} 

• Creating a Response Page in a Servlet
• Creating a Response Page in a JSP

You can generate the output page within a servlet by writing to the output stream. The recommended way to do this depends on the type of output.

response.setContentType("text/html");

PrintWriter output = response.getWriter();
output.println("Hello, World\n");

ServletOutputStream output = response.getOutputStream();
output.print(binary_data); 

Servlets can invoke JSPs in two ways:

• The include() method in the RequestDispatcher interface calls a JSP and waits for it to return before continuing to process the interaction. The include() method can be called multiple times within a given servlet.

This example shows a JSP invocation using include():

RequestDispatcher dispatcher = getServletContext().getRequestDispatcher("JSP_URI"); dispatcher.include(request, response); ... //processing continues

• The forward() method in the RequestDispatcher interface hands control of the interaction to a JSP. The servlet is no longer involved with output for the current interaction after invoking forward(), thus only one call to the forward() method can be made in a particular servlet. Note that you can not use the forward() method if you have already defined a PrintWriter or ServletOutputStream object.

This example shows a JSP invocation using forward():

RequestDispatcher dispatcher = getServletContext().getRequestDispatcher("JSP_URI"); dispatcher.forward(request, response);

You can reload servlets into NAS without restarting the server. Simply overwrite the servlet by redeploying. NAS "notices" the new component and reloads it within 10 seconds. For more information, see Dynamic Reloading.

1. Stop the server.
2. Deploy the new configuration file.
3. Execute servletReg configFile.ntv on the server to register the new configuration file.
4. Restart the server.

http://server:port/NASApp/appName/servletName?name=value 

http://www.my-company.com/NASApp/OnlineBookings/directedLogin 

http://server:port/servlet/servletName?name=value 

http://www.leMort.com/servlet/calcMortgage?rate=8.0&per=360&bal=180000 

http://server:port/NASApp/Office/ShowSupplies?name=value 

• Include another servlet's output using the include() method from the RequestDispatcher interface. include() calls a servlet by its URI and waits for it to return before continuing to process the interaction. include() can be called multiple times within a given servlet.

For example:

RequestDispatcher dispatcher = 
    getServletContext().getRequestDispatcher("Office/ShowSupplies"); 
dispatcher.include(request, response);

• Hand control of the interaction to another servlet using the forward() method in the RequestDispatcher interface. takes the servlet's URI as a parameter.

Note that forwarding a request means that the original servlet is no longer involved with output for the current interaction after invoking forward(), thus only one forward() call can be made in a particular servlet.

This example shows a servlet invocation using forward():

RequestDispatcher dispatcher = 
    getServletContext().getRequestDispatcher("Office/ShowSupplies"); 
dispatcher.forward(request, response);