NetWare 6.0 Web Infrastructure Part 8: Tomcat

Joe Harmon is part of Novell's Web Services Support team. This material is adapted from some excellent training sessions he recently presented here at Novell. He graciously allowed us to share it with you in this series of articles.

Integration of Tomcat and Apache

MOD_JK

MOD_JK is a module that allows Apache and Tomcat to communicate. The MOD_JK module is needed in order for Apache to be able to plug into Tomcat. This is accomplished through the JKMOUNT statement. An example of the load statement you would need is as follows:

JKMOUNT

The JKMOUNT statement allows URL's within Apache to be assigned to Tomcat. An example of a JKMOUNT would be as follows:

JkMount /*.jsp ajp13
JkMount /servlet/* ajp13

AJP12 and AJP13 protocols

http://jakarta.apache.org/tomcat/tomcat-3.3-doc/mod_jk-howto.html#s82

MOD_JK can use either the original Ajpv12 protocol or the newer Ajpv13 protocol. Both protocols are enabled by default. The "Ajp13" Connection Handler in Tomcat will give you the benefit of a faster protocol and the ability to identify requests made via HTTPS.

The default installation of Tomcat 3.3 comes with connectors for both protocols in the sys:tomcat/33/conf/nwserver.xml. The default choice by the ApacheConfig directive will be to use the "ajp13" worker which uses the Ajpv13 protocol. Even though mod_jk uses the Ajpv13 by default, you shouldn't remove the Ajpv12 connector present in the server.xml file. The Ajpv12 connector is also used for shutting down Tomcat.

MOD_JK.LOG

This is the log file that records the communication between Tomcat and Apache.

Servlets

Servlet Definition from the Servlet Specification:

"A servlet is a web component, managed by a container, that generates dynamic content. Servlets are small, platform independent Java classes compiled to an architecture-neutral byte code that can be loaded dynamically into and run by a web server. Servlets interact with web clients via a request response paradigm implemented by the servlet container. This request-response model is based on the behavior of the Hypertext Transfer Protocol (HTTP)."

** NOTE ** Java servlets are one of the most exciting new technologies. Servlets are efficient, persistent, portable, robust, extensible, secure, and they have received wide acceptance in the industry. Good for replacing CGI. Servlets solve many of the problems present in CGI.

Efficiency - A servlet's initialization code is executed only the first time the Web server loads it. After the servlet is loaded, handling new requests is only a matter of calling a service method. This is a much more efficient technique than loading a completely new executable with every request.

Persistence - Servlets can maintain state between requests. When a servlet is loaded, it stays resident in memory while serving incoming requests. A simple example of this would be a Vector that holds a list of categories used in an online catalog. When the servlet is initialized, it queries the database for a list of categories and stores these categories in a Vector. As it services requests, the servlet accesses the Vector that holds the categories instead of querying the database again. Hence, performance is improved drastically.

Portability - Servlets are developed using Java; therefore, they are portable. This enables servlets to be moved to new operating system without changing the source. You can have code compiled in Win NT and move it to a Solaris box without making any changes.

Browser >> Servlet >> Browser

** NOTE ** The browser issues a request to a particular URL that may also include parameters.

The servlet generates the content dynamically and returns in a response to the browser.

JSPs

JSP Definition from the JSP Specification:

"JavaServer Pages technology is the Java platform technology for building applications containing dynamic Web content such as HTML, DHTML, XHTML and XML. The JavaServer Pages technology enables the authoring of Web pages that create dynamic content easily but with maximum power and flexibility."

JSP vs Servlets

Readability

Java embedded into HTML as opposed to servlets with content (HTML) embedded into Java code

** NOTE ** As a general rule, JSPs are best for textual output. Servlets better for binary output, like images, or PDFs.

Advantage - The biggest strength of JSP is that it looks like HTML or XML. Hence, persons who are familiar with HTML or XML can easily modify JSP. People who are weak in Java can use JSP. There is no need to be a Java guru to use JSP. When JSPs are compiled they automatically become servlets. Hence, it is difficult to point to any technical disadvantages of a JSP that aren't in servlets. Probably the only disadvantage, but also a strength, is the capability to mix Java code with HTML. If you do not organize your code you might end up with a mess of huge JSP files with HTML interspersed between huge blocks of Java code.

JSP LAB

Now we will create our first JSP (Java Server Page) to go into our Web Application. This will be used later on when we build our web application. We will name it DATEANDTIME.JSP. The contents are as follows:

<HTML>

<BODY>

Today's date and time are: <%= new java.util.Date() %>

</BODY>

</HTML>

Summary - Servlets vs JSPs

JSPs

HTML with some embedded Java (but not too much!)

Better separation of concerns

Visual tools (evolving)

Single content type (per JSP)

Servlets

Java embedded with HTML content

More flexibility (including content type)

Better with binary data (files or dynamic images)

Better as mediator or controller (in MVC)

The use of JSPs and Servlets usually follows the 80/20 rule. You will probably use JSPs for 80% of your web application. Servlets will only be used 20% of the time.

The biggest strength of JSP is that it looks like HTML (or XML). Because JSP eventually become servlets, it's difficult to point to any technical disadvantage that are present in servlets.

Separate Instance of Tomcat

TOMCAT33.NCF

How to run multiple instances of Tomcat on NetWare 6

Under the SYS:/TOMCAT/33/BIN directory you will find a TOMCAT33.NCF file. Make a copy of this file and call it what you want. In this example, MYTOMCAT.NCF will be used.

The -ns parameter is if you want the new version of tomcat to appear in its own screen. If this parameter is left out then it will be sent to the logger screen by default.

**Note** The logger screen has the ability to scroll back up the screen.The -Xms128m and -Xmx256m parameter specifies the maximum and minimum amount of memory for Tomcat to use. If you are using applications that do not ship with NetWare 6 by default, then you may want to bump up this parameter.

**Note** These parameters cannot go over the amount of RAM that you have on your server.We renamed the NWSERVER.XML to be MYSERVER.XML. This will make more sense as we move on to the next step.

NWSERVER.XML

The next file that we are going to create is the MYSERVER.XML file. To do this we need to go to the SYS:/TOMCAT/33/CONF directory and copy the NWSERVER.XML file. Once that is copied we will give it the name of MYSERVER.XML file.

Here we will need to make several changes so that we can properly manage our web applications and so we don't run into any port conflicts.

Now we will need to go take a look at the SYS:/TOMCAT/33/CONF directory. Here is where you will define your web applications directory structure. By default, NetWare 6 uses applications that are defined by nwapps-NameOfWebApp.xml. In our example we defined this as myapps-NameOfWebApp.xml. **NOTE** By default this is apps-NameOfWebApp.xml on other platforms.

Below is an example of the APPS-EXAMPLES.XML that is installed with Tomcat by default on NetWare 6. Since by default APPS-EXAMPLES.XML is not being used by NetWare 6, we will use it for our new web application. If you desire to create your own web application, you can follow this example.

NWAPPS-MYAPP.XML LAB

In order for us to use this we will need to create a copy of it and rename it as MYAPPS-EXAMPLES.XML.

The context path is listed as /examples. This is the URL that we will be using to access this web application.

The docBase is where all of the servlets, JSPs, html, class files, etc., will be placed for the web application.

<?xml version="1.0" encoding="ISO-8859-1"?>

<webapps>

<!-- Setting special properties for /examples ( as an example of overriding the defaults )

(1) The first thing that we need to do is to create the directory structure that will hold our web application.

Under the SYS:/WEBAPPS directory we will create a directory called TESTAPP. Under that directory we will need to create a WEB-INF directory. Then under the WEB-INF directory we will create a CLASSES and LIB directory. (see example below)

**NOTE** The CLASSES and LIB directory are not necessary for a Web Application, but we will be creating them for this example.

(2) Now we need to create a deployment descriptor (WEB.XML) file. The default code for this is listed below. Once the WEB.XML file is created, place it under the SYS:/WEBAPPS/TESTAPP/WEB-INF directory.

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app

PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"

"http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">

<web-app>
</web-app>

(3) Now we need to add a ServletContext to our web application. The ServletContext will define the methods that the Web Applications components will use. In this example our ServletContext will be called MYAPPS-TESTAPP.XML. This will need to go to the SYS:/TOMCAT/33/CONF directory.

**NOTE** NWAPPS is the default descriptor that is defined for the default instance of Tomcat on NetWare 6. If you are running your own instance of Tomcat you could change this descriptor accordingly.

<?xml version="1.0" encoding="ISO-8859-1"?>

<webapps>

<!-- Setting special properties for TestApp context -->

<Context path="/TestApp"

docBase="SYS:/webapps/TestApp"

debug="0"

reloadable="false" >

</Context>

</webapps>

(4) The next step is to create an INDEX.HTML file so we can test the context path and make sure it is working. We will be first testing this with Tomcat, since we have not yet integrated it with Apache. Tomcat has an HTTP listener that loads on 8080 if it is enabled. It is disabled by default. We will go and enable it.

**NOTE** One thing to keep in mind is that 8080 is the default port for BorderManager Proxy. If you are running anything on port 8080 then you will need to change the port that the Tomcat HTTP listener is running on. If you go to SYS:/TOMCAT/33/CONF you will find a file called NWSERVER.XML. Open this file in a text editor and do a search for 8080. You will find the following section listed below.

**NOTE** After removing the comment marks it will be necessary to restart Tomcat by doing the following:

JAVA -EXIT
TOMCAT33

If everything loaded correctly you should be able to see that the port loaded in the logger screen:

(5) Now we will move on to creating a simple INDEX.HTML file as seen below:

<p align="center"><b><font size="6">TestApp Home</font></b></p>

We will save this out to the SYS:/WEBAPPS/TESTAPP directory as INDEX.HTML. Now if we go to http://DomainName:8080/TestApp we should see the following:

If you see this page then your ServletContext is working properly.

(6) Now we will create our first JSP (Java Server Page) to go into our Web Application. This will be saved to the SYS:/WEBAPPS/TESTAPP directory. We will name it DATEANDTIME.JSP. The contents are as follows:

<HTML>

<BODY>

Today's date and time are: <%= new java.util.Date() %>

</BODY>

</HTML>

Open a browser and go the following URL:http://DomainName:8080/TestApp/DateAndTime.jsp

If you see the following information then you know that your sample JSP is working.

(7) The next thing that we will do is to deploy a servlet to our Web Application. The first servlet that we will create will be called MYFIRSTSERVLET.JAVA and will need to be compiled into MYFIRSTSERVLET.CLASS

(8) After the servlet is compiled, place the MYFIRSTSERVLET.CLASS file in the SYS:/WEBAPPS/TESTAPP/WEB-INF/CLASSES directory. Next we will need to edit the WEB.XML file to add the information needed to run the servlet.

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app

PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"

"http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">

<web-app>

<servlet>

<servlet-name>

MyFirstServlet

</servlet-name>

<servlet-class>

MyFirstServlet

</servlet-class>

</servlet>

<servlet-mapping>

<servlet-name>

MyFirstServlet

</servlet-name>

<url-pattern>

/MyFirstServlet

</url-pattern>

</servlet-mapping>

</web-app>

WAR files

Web Archives

All components related to a web application are bundled together into a web archive file.

Web components include

HTML pages

JSP files

Servlets

JARs and supporting class files

Images, JavaScript files, stylesheet files, and more

Supporting classes

Web archives are JAR files with the ".war" extension

Definition

How to Create

How to deploy

Upgrading from Tomcat 3.3.1 to Tomcat 4.0

NOTE - For the following examples it is assumed that your Tomcat was installed in the
<C:\Program Files\Apache Group\Jakarta-Tomcat-3.3a>
If this is not the case, you will need to modify the instructions accordingly.

Move your <NPS> directory from the <Tomcat-3.3a\webapps\> directory to the <Tomcat-4.0.3\webapps\> directory

Copy the mod_jk.conf file from the <Tomcat-3.3a\conf\jk\> directory <Tomcat-3.3a\conf\jk\> directory to the <Tomcat-4.0.3\conf\> directory

Copy the workers.properties file from the <Tomcat-3.3a\conf\jk\> directory <Tomcat-3.3a\conf\jk\> directory to the <Tomcat-4.0.3\conf\> directory

Modify the mod_jk.conf on the line that starts out with <JkWorkersFile> to point the workers.properties that you just moved.

For example before the change it might read
JkWorkersFile "C:\Program Files\Apache Group\Jakarta-Tomcat-3.3a\conf\jk\workers.properties.
And after the change it might read JkWorkersFile "C:\Program Files\Apache Group\Jakarta-Tomcat-4.0.3\conf\workers.properties.

Note that Tomcat 4.0.3 does NOT have the <JK> directory under the <conf> directory anymore.

Then do a search and replace for all instances of "C:\Program Files\Apache Group\Jakarta-Tomcat-3.3a\"

Replace it with "C:\Program Files\Apache Group\Jakarta-Tomcat-4.0.3\"

This is done in mod_jk.conf. This will make sure that it is looking for the webapps in the correct directory structure.

This should be changed to
Include "C:\Program Files\Apache Group\Jakarta-Tomcat-4.0.3\conf\mod_jk.conf"
Make sure that you SAVED the changes to each file.
And that they are not just sitting opened with the changes present but unsaved.
At this point restart Tomcat and Apache and everything should be working.
- Please verify that the Portal is still functioning After these steps and
Before you install SP1.

Increasing the amount of RAM that Tomcat Can Use

(1) Open your TOMCAT33.NCF file found in the SYS:/TOMCAT/33/BIN directory. Here we will need to add two parameters to the file: one for the minimum heap size and one for the maximum heap size. The parameters are as follows:

-Xms128m -Xmx256m

(2) Now we will insert these parameters into the TOMCAT33.NCF file. At the bottom of the file you will find the following line:

** IMPORTANT ** Each java process is allocated 512 meg of user space within the RAM that it can use. Some of that is used for java threads, socket communication, etc. So what is really available is not much more than 400 meg which can be allocated to a java process. This information can be seen at the server by typing in the command JAVA -SHOW and then finding out what the ID is for the Tomcat java process. Then at the server console you can type JAVA -SHOWMEMORY# with the # representing the Tomcat process ID. Then switch over to the logger screen and you should see how much memory is being allocated within the Tomcat process. An example is shown below:

** NOTE ** The main statistics to look at here are the reserved heap and the committed heap. The reserved heap represents our -Xmx switch. This is the maximum memory that is allocated to the individual java process. What we show here by default is 68161536 which equates to 65 meg. The committed heap represents the -Xms switch. This is the minimum amount of memory that will be committed to the individual java process. In this instance we have 11124732 which equates to 8 meg of committed memory.

(4) To verify that our switches have changed our committed and reserved heap sizes we will need to take down java and then restart tomcat. See example below:

JAVA -EXIT

** IMPORTANT ** If the console comes back with MODULE JAVA.NLM UNLOADED, then you can startup tomcat by typing in TOMCAT33 at the console prompts. If it comes back that it is still cleaning up resources in the background, and you have a console prompt, then you can type in JAVA -EXIT again to force java down.

(5) Once tomcat is started again then you can check the memory again and it should now show up.

** TROUBLESHOOTING ** If you do not show the new memory size then one of the following probably happened.
(A) You reloaded Tomcat before JAVA was completely unloaded.
(B) You specified a maximum heap (-Xmx) that was too large. The most that this can be is around -Xmx386m without additional configuration.
(C) Your -Xms parameter is larger than your -Xmx parameter.

On NetWare 6 we have the option of loading the AUTOEXEC.BAT file with a -u switch to increase the amount of memory that can be used by the JVM. This switch can be used in conjunction with java heap parameters to dedicate more memory to memory-intensive Web Applications. Examples of memory-intensive web application on NetWare 6 are Novell Portal Services 1.5 and eGuide 2.0.

There are a few things that should be noted before using the -u parameter. The -u parameter allows you to specify a higher amount of memory than exists on your server. This could create problems if you are trying to specify memory that you don't have. So what should be done to avoid this? Well, don't exceed the amount of RAM that you have on your server with the -u parameter. In fact, you would be well advised not to go above three-quarters of the amount of RAM that you have. Remember that the JVM is not the only application on the server that will be using the RAM. Take care to leave some RAM available for other processes.

(6) Edit the AUTOEXEC.BAT file found at the root of the C:\ drive. It should look similar to the example below:
C:
CD \NWSERVER
SERVER

(7) After editing the file to add the -u switch, it should look similar to the example below, with the exception that the number value may be different depending on the desired amount of RAM needed for the JAVA process.

C:
CD \NWSERVER
SERVER -u1000000000** NOTE ** In this example we are specifying 1 GIG of RAM to be used. The parameter is measured in bytes. This will get past the limit specified in step (4). You should now be able to increase your heap size above 400 MEG.