Getting started with Java servlets

    To get Java servlets up and running requires more than knowledge about Java in general or servlets in particular: one needs to know about servers, servlet containers, and XML.  To get started, it is useful to have some "cookbook" instructions, however published books shy away from such instructions, in part because the technical details keep changing.  A Web-based guide can be more current: this document is meant to get you started using the book "Java Servlet Programming".  This guide takes a lowest-common-denominator platform using recent versions of free servlet-related software that you can run on your local computer as well as a low cost reliable Web-hosting arrangement for running your servlets from the Web.

• Local operating system: Windows 98
• Local Java Development Kit / Runtime Environment:  Sun SDK Standard Edition 1.4.1_03 
• Local Servlet container: Tomcat 4.1.24
• Servlet-friendly Web-hosting: Lunarpages.com

Preparing the environment on your local computer

• Preparation: Your computer may already be littered with various old Sun Java Runtime environments (JREs) and Software Development Kits (SDKs).  You may want to simplify your system by uninstalling some of these.
  
• Downloading SDK/JRE: The Sun SDK Standard Edition version 1.4.1_03 can be downloaded from here.  (The Enterprise Edition is not chosen for these instructions because it does not support Windows 98.  Beta versions are not chosen since they are less reliable and their newer capabilities are not referred to in the published book.)
  
• Installing SDK/JRE: The default installation directory is c:\j2sdk1.4.1_03.  Installing here has advantages over more conventional locations such as in "Program Files" because spaces are not used in the path; spaces can cause problems.  Accept the choice to install the JRE unless you have the current JRE installed already.
  
• Download Tomcat:  The Tomcat servlet container version 4.1.24 can be downloaded from here.  (Beta versions are not chosen since they are less reliable and their newer capabilities are not referred to in the published book.)  Choose the jakarta-tomcat-4.1.24.exe version since it contains the whole package and installs itself.
  
• Install Tomcat:  The default installation directory is c:\Program Files\Apache Group\Tomcat 4.1, the form used in this document.  Accept the default installation with HTTP/1.1 Connection 8080 and choose an administrator password.  
  
• Set up a Java compiler: Sun's "javac" will work but you may want to use your existing Integrated Development Environment (IDE).  It is possible to use a variety of IDEs, even old ones that do not come with any servlet support:
  • Sun's "javac": You should make sure your c:\Autoexec.bat file includes the path for the javac program:
    SET PATH=c:\j2sdk1.4.1_03\bin\;
    This takes effect after re-booting and frees you from having to specify the path for javac all the time.  You may need to increase your DOS environment space if you already have a long PATH command.  You should also set the CLASSPATH in c:\Autoexec.bat to include the servlet.jar file in Tomcat:
    SET CLASSPATH=.;c:\Program Files\Apache Group\Tomcat 4.1\common\lib\servlet.jar;
    where the initial period includes the current directory in the classpath.  This takes effect after re-booting and should free you from having to specify the classpath every time you invoke javac.  However, there are circumstances in which this will not work (see Outdated Compilers below).  In such cases you can specify the classpath every time you invoke javac using commands (or batch files) of the form:
    javac -classpath "c:\Program Files\Apache Group\Tomcat 4.1\common\lib\servlet.jar" Hello.java
  • Outdated compilers:  It is even possible to use a very old and non-standards-compliant Java 1 compiler to develop servlets. Here are instructions for the worst case scenario of people using Microsoft Visual J++ 6.0:  
    • For each project, set the classpath inside VJ++ using Project | ProjectName Properties | Classpath and select "All Configurations" from the Configuration choice and use the New button to add c:\Program Files\Apache Group\Tomcat 4.1\common\lib\servlet.jar to the classpath.
      
• Start Tomcat: Tomcat creates an icon called "Start Tomcat" which uses Tomcat's "bootstrap.jar" application to start the server.  It should start your server automatically; it rumbles along for a few seconds writing into a DOS window named "java".
  
• Test that your installation worked:  Type the following URL into a Web browser: 
  http://localhost:8080/
  If all is well you should see a fancy page that congratulates you for having set up Tomcat properly and offers various resources.
  
• Stop Tomcat: When you are done, use the "Stop Tomcat" icon to stop the server.

Setting up Tomcat on your local computer for easy use:

• Enable use of the "ROOT" folder:  As described in Marty Hall's instructions un-comment the line:
  
  <Context path="" docBase="ROOT" debug="0"/>
  
  in the following Tomcat file:
  c:\Program Files\Apache Group\Tomcat 4.1\conf\server.xml
  
• Enable running servlets without modifying a web.xml file: As described in Marty Hall's instructions un-comment the following lines:
  
      <servlet-mapping>
          <servlet-name>invoker</servlet-name>
          <url-pattern>/servlet/*</url-pattern>
      </servlet-mapping>
  
  in the following Tomcat file:
  c:\Program Files\Apache Group\Tomcat 4.1\conf\web.xml
  
• Create the classes folder: Create a classes folder as:
  c:\Program Files\Apache Group\Tomcat 4.1\webapps\ROOT\WEB-INF\classes\
  NOTE: You may need to change a Windows setting to see the proper capitalization.  In Windows Explorer make sure this is selected as checked: 
  View | Folder Options | View | Files and Folders | Allow all uppercase names.

Running a simple servlet

• Compile a simple servlet: Compile one of the examples from Chapter 2 of "Java Servlet Programming" (code can be downloaded from here).  You can do this in a folder separate from Tomcat.
  
• Start Tomcat: as above.
  
• Put the class file in the Tomcat folder and run the servlet: Put your servlet in the classes folder for ROOT:
  c:\Program Files\Apache Group\Tomcat 4.1\webapps\ROOT\WEB-INF\classes\
  and it should work when you type into a Web browser a URL such as:
  http://localhost:8080/servlet/HelloWorld
  It may be convenient to make an HTML file with a link using the URL.  It should work.
  
• Stop Tomcat: When you are done, use the "Stop Tomcat" icon to stop the server.

Running a servlet needing a web.xml file

    Servlets often use "Deployment Descriptors" in a "web.xml" file found in the folder containing the "classes" folder.  If you have never dealt with servlets or xml before these will be unfamiliar files containing instructions that will determine whether or not your servlets work properly.  For this reason you need to work with these files even if you don't understand them yet.  Here is how to get going:

• Compile a servlet needing a web.xml file: Compile one of the examples from Chapter 3 of " Java Servlet Programming" such as InitCounter (example 3.4; InitCounter.java can be downloaded from here).
  
• Use the relevant web.xml file:  For example 3.4 the relevant web.xml code (example 3.3; web.xml can be downloaded from here) specifies the <servlet-name> of counter. This file should be used as the web.xml file in:
  c:\Program Files\Apache Group\Tomcat 4.1\webapps\ROOT\WEB-INF\
  
• Put the class file on Tomcat: put the class file in:
  c:\Program Files\Apache Group\Tomcat 4.1\webapps\ROOT\WEB-INF\classes\
  
• Start Tomcat: it is necessary to restart the server after changing a web.xml file.  It is not necessary to restart the server after changing a class file.
  
• Run the servlet: using a URL such as:
  http://localhost:8080/servlet/counter
  or make an HTML file with a link using this URL.  It should work.
  
• Stop Tomcat: When you are done, use the "Stop Tomcat" icon to stop the server.

Running a servlet using commercial hosting

Lunarpages.com offers domain hosting for $96 per year, and for an additional $24 per year you can specify Java servlet support.  The servlet container is Resin.  Follow these directions to get your servlets running on the Web:

• Class file placement and URLs: To get a URL of the form:
  mydomain.com/servlet/classname
  put your classes in:
  /home/domainID/public-html/WEB-INF/classes
  To do this you have to create the classes folder yourself. If you are unable to create the classes folder contact Lunarpages support and they will have someone enable the relevant permissions. Although you can use Microsoft FrontPage to create your Web site, Lunarpages recommends using their Web-based file manager program or an FTP program to upload servlet-related files.
  
• Writing files on the server: To write a file from a servlet you need to specify the path to your file area.  Here is how to specify the path to "my_file.txt" in the "WEB-INF" folder:
  fileWriter = new FileWriter(getServletContext().getRealPath("/") + File.separator + "WEB-INF" + File.separator + "my_file.txt"); 
  
• Saving your folders from being deleted: If you leave an empty folder within:
  /home/domainID/public-html/WEB-INF/
  it seems to get deleted.  Placing a file within a folder, even a dummy index.html file, prevents this.

If you have any comments about this page please contact Mickey Segal.