Servlet Reloading Guide

This guide discusses the steps necessary to effectively use the servlet reloading feature of Tynamo™ with your applications. It is a companion to the Servlet Reloading document, which discusses some points in further detail.

One of the main reasons for using servlet reloading is the ability to change the behaviour of your application on the fly, to "hot swap". Due to the way it is implemented, the feature can be enabled or disabled with no difference to the end user. Your applications will look and behave exactly the same. This is the main difference from the Loader Servlet.

The disadvantage is that the server must be restarted whenever the servlet.props file is updated.

There are three sections:

  1. Steps to Activate This Feature,
  2. Examples, and
  3. Discussion

Steps to Activate Reloading

  1. Set these properties in the webserver.props file:
    servlet.reloadingEnabled=true
    servlet.classpath=/web/classes

    The classpath setting can be changed to suit your needs, but this is discussed in more detail below.

  2. Set up your servlets in the servlets.props file.
  3. Build, deploy, and then start the server.
  4. Change and update your servlets as needed.

[Top]


Examples

Start by setting up a servlet in servlets.props:

HelloWorld.mapping=/servlet/HelloWorld
HelloWorld.class=HelloWorldServlet

Start the Server

Build, deploy, and start the server as usual. Then, try to access the HelloWorld servlet:

http://{Device address}/servlet/HelloWorld

You should get an error stating that the servlet cannot be found. This is expected because we haven't yet given it the servlet class. It is looking for a class with a full name of HelloWorldServlet because that's what is specified for the HelloWorld.class property above.

Create the Servlet

Next, write the servlet code:

import java.io.IOException;
import javax.servlet.ServletOutputStream;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

/**
 * Simple Hello World servlet.
 *
 * @author Shawn Silverman
 */
public class HelloWorldServlet extends HttpServlet {
    /**
     * Process a GET request.
     */
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
        throws ServletException, IOException
    {
        resp.setContentType("text/html");
        ServletOutputStream out = resp.getOutputStream();
        out.print("<html><head><title>Hello World Servlet</title></head><body>");
        out.print("<h1>Hello, World!</h1>");
        out.print("</body></html>");
    }
}

Save this code as HelloWorldServlet.java in a convenient place.

Compile

Next, compile this into HelloWorldServlet.class. The servlet-2_2.jar file in the device/lib/ directory of the Tynamo™ distribution contains the javax.servlet servlet framework, so this needs to be in your classpath. A sample command-line is (note that the line may be wrapped, but should be on one line):

javac -target 1.1 -classpath <tynamo-dist>/device/lib/servlet-2_2.jar HelloWorldServlet.java

The -target 1.1 option is required if you are using JDK 1.4 or later, and is not required otherwise.

Upload

Use an FTP client to place the HelloWorldServlet.class file into a directory named /web/classes on your device. Remember that the servlet container is expecting to find classes here because that's what was specified for its classpath.

Finally, use your web browser to go to this location:

http://{Device address}/servlet/HelloWorld

The page should look like this:

Hello, World!

Reload the page and notice that it takes less time to load. This is because the servlet is now loaded and initialized.

Change

Change the page text to read "Changed!" instead of "Hello, World!", then recompile and upload the class again.

Reload the page, and you should now see:

Changed!

[Top]


Discussion

One of the first things you may notice is that the servlet takes slightly longer than normal to load the first time it is accessed. This is because more work has to be done by the firmware and by the server: The classfile must be loaded and checked. Then, the server loads the class via a Class.forName call and has to verify it has the correct superclass. Next, the servlet is initialized via its init() method, and finally its GET handler is invoked.

Once the servlet has been accessed once, it does not need to repeat the first part ot the process.

Classnames

The full classname of the servlet dictates where it must be placed in the filesystem, but does not affect how the servlet is loaded, unlike the Loader Servlet.

The class must be located in the correct directory structure underneath the servlet classpath (servlet.classpath property in webserver.props). For example, if our servlet class was named com.xxx.Myservlet, then it must be placed into /web/classes/com/xxx/MyServlet.class in order for the reloading engine to find it.

Regardless of how you name your class, though, the servlet will be accessed with the exact same URL, as specified by the servlet mapping (HelloWorld.mapping property for our example).

Different Classpath

It is not required that you use the /web/classes directory for your classes. You can specify anything you like, provided the location you put them and the servlet classpath match. Simply change the servlet.classpath property in webserver.props to your desired location.

A change in this setting requires a server restart.

Referenced Classes

It is important to note that if your servlet depends on other classes, then these must also be uploaded to the location of the servlet classpath, using the correct directory structure if they are in a package.

The Servlet Mapping

Unlike the Loader Servlet, servlet reloading requires that a mapping for each servlet is specified in the servlet.props file as normal. This means that the URL used to access the servlet does not need to change when reloading is turned off.

In other words, use one entry in this file per servlet class as before, and remember to restart the server when anything in this file changes.

[Top]


Servlet reloading is discussed in more detail in the Servlet Reloading document.