Introducing Enhydra

Over the last few months, we have looked at Java servlets and JavaServer Pages. Enhydra, as a J2EE-compliant application server, fully supports these technologies. Moreover, as an open-source server, Enhydra uses the Jakarta-Tomcat engine as the basis for its servlets and JSPs. As we will see later, it is possible (and often preferable) to use Enhydra's own advanced form of web applications.

It's relatively easy to create servlets using the tools that come with Enhydra. And indeed, Enhydra's authors have spent a great deal of time creating a system that is not only powerful when deployed, but relatively easy to work with during development.

If you are used to simply writing a servlet, compiling it and dropping it into a directory, then you will find that Enhydra gets in the way, complicating the process. This is in no small part due to the way in which Enhydra applications are deployed—rather than requiring an external server, Enhydra expects that you will want to test (and run) many of your web applications independently of any others.

To create a simple servlet, we will use the application generation wizard (appwizard) that comes with Enhydra, which you can invoke as $ENHYDRA/bin/appwizard. The appwizard is not an IDE but rather a sophisticated file-copying program that provides a basic skeleton application that already works.

When you first run appwizard, it will ask you whether you want to develop a web application (i.e., standard servlet) or an Enhydra super servlet. Choose a standard web application; super servlets will come later. The next screen will ask whether you want to produce output in HTML or WML, the latter being the standard XML-based format for cellular internet applications. We will use HTML and will call both the project directory and the package “atf”. By default, Enhydra applications are placed under your home directory in the subdirectory enhydraApps. Choose a license under which your code will be released, and appwizard will generate files for your new application.

And indeed, appwizard creates a large number of automatically generated files and directories. Among them are:

To build the application, simply run a make in the root directory of our project. (The Enhydra Enterprise documentation makes a big deal out of saying that it now uses the Java-based Ant build tool in favor of make, but application creation still appears to rely on make.)

After make completes its work, there will be a new output subdirectory at the top level of our application, parallel to src and input. The output directory contains everything we need in order to launch our application, including a standard Java .war (web archive) file containing our .class files, XML descriptors, JSPs and images:

WEB-INF/classes/atf/presentation/WelcomeHTML.class
WEB-INF/classes/atf/presentation/WelcomeServlet.class
WEB-INF/classes/atf/presentation/RedirectServlet.class
media/Enhydra.gif
index.jsp
WEB-INF/web.xml

Notice that we have three .class files here, while there were only two in src/atf/presentation/. That's because XMLC turned the HTML file from src/resources into a Java source file, which was then turned into a Java .class file.

So with just two commands, appwizard and make, we have managed to create a full, running Enhydra application. The application, as it stands, doesn't do anything particularly complex or interesting, but it provides us with a skeleton that we can then modify and extend.

To run our application, we run output/start4. This starts the application on port 9000 (defined in input/conf/servlet/servlet.conf.in). If you point your web browser to http://localhost:9000/, you will see the output from our servlet: the Enhydra logo, the name of our application (atf), the current time and date and a hyperlink that redirects you back to the application.

The HTML page is generated by XMLC and demonstrates how XMLC is integrated into the rest of Enhydra. XMLC compiles src/atf/resources/Welcome.html into a Java servlet, which is then turned into a .class file. The Java class created by XMLC includes a hook for each of the <span> tags in the file, allowing retrieval and modifications of anything within a <span> tag that has an ID attribute.

WelcomeServlet, the servlet that is initially executed in our application, displays the current time and date by creating an instance of the XMLC-generated class:

now = DateFormat.getTimeInstance(DateFormat.MEDIUM) .format(new Date());
welcome = new WelcomeHTML();
welcome.getElementTime().getFirstChild() .setNodeValue(now);

In other words, we replace the text within the <span> tag with an ID of “time” by turning the HTML file into a DOM-accessible tree and then changing the value of a specific node.

To add additional servlets to our application, we can write and save them in src/atf/presentation. Note that the package will be atf.presentation and not simply atf. We will write a very simple class, Foo, which you can see in Listing 1. Except for the package name, there isn't any difference between traditional servlets and Foo.java.

Listing 1. Foo.java

Now we need to tell the servlet engine to map a URL to our servlet. We do this in src/WEB-INF/web.xml. This XML file is divided into two parts: the first maps servlet classes to servlet names, and the second maps servlet names to URLs. Listing 2 contains a version of web.xml modified to handle mapping our Foo servlet.

Listing 2. Modified Version of web.xml

Finally, we need to include our new class in the Makefile, adding the name of our class to the CLASSES variable:

CLASSES = WelcomeServlet \
RedirectServlet Foo

Run make and check that Foo.class has been added to the application with:

jar tvf output/archive/atf.war

If it all works, then run output/start4, and point your browser to http://localhost:9000/foo. You should see the HTML output delivered by our new Foo servlet.