Apache Tomcat Servlet and JavaServer Pages Development with JBuilder Foundation

By: David Intersimone

Abstract: The steps outlined in this document were tested on and will work with JBuilder 3.5 Foundation and Tomcat 3.1. You can also use this document to set up Tomcat to work with JBuilder 3.5 Professional and Enterprise editions.

Apache Tomcat Servlet and JavaServer Pages Development with JBuilder Foundation

Debbie Carson and Ken Chan
Senior Technical Writer, and R&D Engineer, JBuilder
Inprise/Borland

The steps outlined in this document were tested on and will work with JBuilder 3.5 Foundation and Tomcat 3.1. You can also use this document to set up Tomcat to work with JBuilder 3.5 Professional and Enterprise editions.


Introduction - the Jakarta Project

Sun Microsystems has delivered the latest versions of JavaServer PagesTM (JSP) and Servlets source code to the Apache Software Foundation http://www.apache.org to be developed and released under the Apache development process as the official JSP 1.1/Servlets 2.2 reference implementation. Apache, Sun, and a variety of other companies and individuals are openly developing a robust Reference Implementation that is freely available to any company or individual. This reference implementation, developed under the project name Jakarta and code-named Tomcat, will be the only reference implementation available. This implementation is available to any company or developer to be used in Web servers, development tools, and to create dynamic, interactive Web sites.

The mission of the Jakarta Project is to provide commercial-quality server solutions based on the Java Platform that are developed in an open and cooperative fashion. The flagship product, Tomcat, is a reference implementation of the Java Servlet and JavaServer PagesTM (JSP) Specifications which can run standalone as well as integrated into the Apache Web Server. This reference implementation provides an operational definition for the Enterprise JavaTM JSP and Servlet application-programming interfaces (APIs). All final releases of the Servlet and JSP implementations will conform to the latest versions of the Servlet and JavaServer Pages specifications available from Sun. These specifications are defined and evolved through the Java Community Process and can be found at http://java.sun.com/products/servlet/ and http://java.sun.com/products/jsp/.


Introduction - servlets and JSPs

JSP and Java Servlets technologies are critical components of the JavaTM 2 Platform, Enterprise Edition (J2EE). A servlet is a Java program that extends the functionality of a Web server, generating dynamic content and interacting with Web clients using a request-response paradigm. JavaServer PagesTM (JSP) are a further abstraction to the servlet model. JSPs are an extensible Web technology that uses template data, custom elements, scripting languages, and server-side Java objects to return dynamic content to a client. Typically the template data is HTML or XML elements, and in many cases the client is a Web browser.

"E-business requirements demand that modern enterprise applications be accessible to users across the Internet. J2EE fully supports Web clients using servlet and JavaServer Pages technology. Servlets and JSP are server components that normally run within a Web server. Servlets are written as Web server extensions (i.e., separate from the HTML page), while JSP embeds the Java code directly in HTML. At deployment time, the JSP Java code is automatically converted into a servlet. Servlets process Web requests, pass them into the back-end enterprise application systems, and dynamically render the results as HTML or XML client interfaces. Servlets also manage the browser user's session information, so that users don't need to repeatedly input the same information." (Patricia Seybold Group, "JavaTM 2 Platform Enterprise Edition: Ensuring consistency, Portability, and Interoperability" © 1999)


JBuilder and Servlet/JSP development, debugging, and testing

JBuilder Foundation, recently voted the the best Java IDE and best Java compiler by the readers of JavaWorld magazine, makes the development, debugging, and testing of JSPs and servlets quicker and easier than ever!

JBuilder includes ServletExpressTM for rapid development of HTML front-ends to Java services and visual tools to rapidly create HTML front-ends to JSPs or Servlets. The JBuilder IDE includes a servletrunner to enable you to test and debug your servlets without leaving the development environment!

The benefits of running Tomcat "inside" JBuilder include:

  • JBuilder Foundation is available free-of-charge for the Windows, Solaris, or Linux platforms. Visit http://www.borland.com/jbuilder/foundation to get yours today!
  • Tomcat is available free of charge from http://jakarta.apache.org.
  • Tomcat is the official Reference Implementation for the JSP 1.1 and Servlet 2.2 technologies. JBuilder is an award winning visual development environment for building Pure JavaTM applications, JSPs, and Servlets. Using JBuilder and Tomcat can be the entry point to enterprise application development.
  • If you develop your code in JBuilder, and it runs in Tomcat, it will most likely comply with the JavaServer PagesTM and ServletsTM specifications.
  • You can step through your code using JBuilder's integrated debugger.


Setting up JBuilder to run with Tomcat 3.1

This section provides the steps necessary to set up JBuilder 3.5 to work with Tomcat.

Downloading and installing JBuilder 3.5 Foundation and Tomcat 3.1 Beta

  1. Download and install JBuilder Foundation from http://www.borland.com/jbuilder/foundation. Select a platform on which to download JBuilder, and follow the download instructions for that platform.

    Tomcat 3.1 will also work with JBuilder Professional or Enterprise.

  2. Download the Tomcat 3.1 binaries and source code from http://jakarta.apache.org. The runtime (jakarta-tomcat.*) and source (jakarta-tomcat.*) are separate archives.

  3. Unzip (or un-tar) both the binaries and source code into the same location. All the files are stored under /jakarta-tomcat, so if you unzip to C:/, you end up with everything under C:/jakarta-tomcat; if you choose somewhere else, adjust accordingly. There is one duplicate file, an older license file in the source archive; you can ignore it.

Setting up the JBuilder environment for Tomcat

This section assumes that JBuilder was installed to the default directory suggested during installation, and that Tomcat was unzipped to the root directory as suggested above.

  1. Run JBuilder Foundation.

  2. Close any existing projects in JBuilder using File|Close Project.

  3. Create a new project by selecting File|New Project. Create this project in a directory other than the /jakarta-tomcat directory so that you won't lose it when you replace the beta. For example, in the Project File option of the Project Wizard, enter a project name and location with a format similar to the following: <home>/jbprojects/tomcat31/tomcat31.jpr.

    Select Finish to close the Project Wizard.

  4. Create a new library, called "Tomcat 3.1", and add it to your project. To do this,

    1. Select Project|Project Properties.
    2. Select the Required Libraries tab of the Paths page.
    3. Select the Add button. Select the New button.
    4. Enter "Tomcat 3.1" in the Name field of the Edit Library dialog.
    5. Select the Class tab. Select the Add button. Browse to the following jar files in the /jakarta-tomcat/lib directory to include them as part of the library:
      • jasper.jar
      • servlet.jar
      • xml.jar
      • webserver.jar

      Files to add to library

    6. Set the source path of the library to C:/jakarta-tomcat/src/share. To do this,
      1. Select the Source tab on the Edit Library dialog.
      2. Click the Add button.
      3. Browse to /jakarta-tomcat/src/share.
    7. Select OK to close the Edit Library dialog.
    8. Select Tomcat 3.1 in the Select One Or More Libraries dialog, then select OK.

  5. Save these project properties by selecting OK to close the Project Properties dialog.

Running Tomcat

If running JBuilder Foundation edition,

  1. Set the VM Parameters. Tomcat 3.1 uses the tomcat.home system property, set with a VM parameter like: -Dtomcat.home=C:/jakarta-tomcat. To do this,

    1. Select Project|Project Properties.
    2. Select the Run page.
    3. Enter the VM parameter into the VM Parameters field. Make sure to point to the directory to which you installed Tomcat: -Dtomcat.home=C:/jakarta-tomcat.
    4. Click OK.

  2. Select File|Save All.

  3. Select Project|Make Project to compile these files.

  4. Click the Run button on the toolbar to run Tomcat.

If running JBuilder Professional or Enterprise editions,

  1. Set the VM Parameters as Run Configurations. Tomcat 3.1 uses the tomcat.home system property, set with a VM parameter like: -Dtomcat.home=C:/jakarta-tomcat. To do this,

    1. Select Run|Configurations to take advantage of the run configurations feature.
    2. Edit the <Default> configuration.
    3. Set the Main class to org.apache.tomcat.startup.Tomcat.
    4. Type in the VM parameter -Dtomcat.home=C:/jakarta-tomcat.
    5. Add a new configuration called "Stop Tomcat". Use the same main class and VM parameter, and "-stop" (no quotes) as the Application Parameter.

  2. Select File|Save All.

  3. Select Project|Make Project to compile these files.

  4. Click the Run button on the toolbar to run Tomcat.

In both cases, you are now running Tomcat with the default configuration. Two directories are created, logs and work, off the directory at startup, which is /jbuilder/bin by default.

Stopping Tomcat

If running JBuilder Foundation edition,

  1. Click the Reset Debugging Session button, which looks like this: Reset debugging button

If running JBuilder Professional or Enterprise editions,

  1. To stop Tomcat, click the drop-down list next to the Run button and choose Stop Tomcat.

This tells the currently running Tomcat process to stop. It shuts down the server by uninitializing resources and calling the servlet's destroy method, if one exists, to ensure that Tomcat terminates gracefully.


Using Tomcat in JBuilder

When Tomcat is running, enter http://localhost:8080/ in your Web browser. The Tomcat Version 3.1 Beta page loads.

Tomcat Version 3.1 Beta

To run one of the sample servlets that ships with Tomcat, select Servlet Examples, then select a servlet. Voila!

To create a servlet using JBuilder, refer to the JBuilder documentation. If using JBuilder Professional or Enterprise, you can use the Servlet wizard to help. To use Tomcat, simply add the Tomcat library to your project and set the Run configuration options.

Using Tomcat and JBuilder you can debug servlets in the JBuilder IDE while the servlet is running, make changes to the source, and reload the running servlet to see the changes without stopping and restarting the Web server.

There's nothing special you need to do to debug servlets and JavaBeans called from JSP files, you simply choose Debug Project instead of Run Project. Tomcat's default configuration includes an invoker servlet, and the classpath for your project is included when you start Tomcat, so it can find the classes. For example, you would test a servlet by entering the URL of the servlet, such as http://localhost:8080/servlet/whatever.Servlet1.

To debug JSPs, you need to put the JSP page where the Web server can find it. For the default Tomcat configuration, you can use the default context at C:/jakarta-tomcat/webapps/ROOT, which you would then access with a URL like http://localhost:8080/whatever.jsp.

The next section provides an example of debugging and testing servlets using Tomcat. A future revision will include an example of debugging and testing JSPs, so check back frequently.


Example: creating, debugging, and testing a servlet running JBuilder 3.5 Foundation and Tomcat 3.1

Now that Tomcat is up and running, it's time to create a servlet in JBuilder, and then debug and test it. To understand the power of using JBuilder 3.5 Foundation and the Tomcat 3.1 Beta together, we will create the traditional "Hello World" servlet in JBuilder, set a breakpoint and debug the servlet, and run the servlet from your Web browser.

The example walks through setting up a new project, adding servlet code to the project, adding the Tomcat libraries so that Tomcat can be started and stopped as necessary, debugging the servlet, and unit testing the servlet!

Create the project and set up JBuilder to use Tomcat for this project

Follow these steps to create a new project for the "Hello World" servlet:

  1. Create a new project by selecting File|New Project. Create this project in the default location , specifying a project name and location with a format similar to the following: <home>/jbprojects/HelloWorld/HelloWorld.jpr.

    Select Finish to close the Project Wizard.

  2. Add the Tomcat library to this project, as follows:

    1. Select Project|Project Properties.
    2. Select the Required Libraries tab of the Paths page.
    3. Click Add to add the Tomcat library.
    4. Select the Tomcat library you created in the previous section, or create the library now following the steps in the previous section. Click OK.
    5. Click OK to close the Project Properties dialog. You must close the Project Properties dialog before the next step to make the Tomcat class available as a Main Class.

  3. Set the Run Configuration. To do this,

    1. Select Project|Project Properties.
    2. Select the Run page.
    3. Enter the following VM parameter into the VM Parameters field: -Dtomcat.home=C:/jakarta-tomcat. Make sure to point to the directory to which you installed Tomcat.
    4. Click the Set button next to the Main Class.
    5. Browse to or select org.apache.tomcat.startup.Tomcat.
    6. Click OK twice to close the Properties dialog.

  4. Select File|Save All.

Adding the servlet code

To add the servlet code to the existing project,

  1. Generate the Servlet class files. If you have JBuilder Professional or Enterprise editions, you can create this files by running the Servlet Wizard.

    1. Select File|New Class to create a new class within this project.
    2. Change the Class Name to HelloServlet.
    3. Check Generate Main Function option.
    4. Click OK to close the Class Wizard.

  2. Modify the file in the Source pane to resemble the following.

    /**
     * Title:        <p>
     * Description:  <p>
     * Copyright:    Copyright (c) <p>
     * Company:      <p>
     * @author
     * @version 1.0
     */
    package helloservlet;
    
    import javax.servlet.*;
    import javax.servlet.http.*;
    import java.io.*;
    import java.util.*;
    
    public class HelloServlet extends HttpServlet {
    
    public void init(ServletConfig config) throws ServletException {
      super.init(config);
      }
    
    public void doGet(HttpServletRequest request, HttpServletResponse response) 
    	throws ServletException, IOException {
    
    PrintWriter out = new PrintWriter (response.getOutputStream());
    response.setContentType("text/html");
    out.println("<FONT COLOR=GREEN>");
    out.println("Hello, your servlet is running. Last time run is " + new java.util.Date());
    out.println("</FONT>");
    out.close();
    }
    }
    

  3. Select File|Save All to save your work.

  4. Select Project|Make Project to compile these files.

Debugging and unit testing the servlet

To debug the servlet, first we set a breakpoint, as follows:

  1. In the Source pane, find the line of code:
    out.println("Hello, your servlet is running. Last time run is " + new java.util.Date());.

  2. Right-click or invoke the context menu on this line of code. Select Toggle Breakpoint. A red dot appears in the margin and the line of code is highlighted in red as well.

  3. Select Run|Debug Project. A tab appears in Message pane for Tomcat. This indicates that Tomcat is running.

Next, we run the servlet in a browser and debug it within JBuilder, as follows. Using JBuilder Professional or Enterprise editions, we could run and debug the servlet from within JBuilder using the servletrunner utility.

  1. Start your Web browser.

  2. Enter http://localhost:8080/servlet/helloservlet.HelloServlet in the Location, URL, or Web Address field of the browser. This field is case-sensitive, so be sure to enter the package and class names in the proper case.

    JBuilder displays with the code at the breakpoint highlighted.

    Debugger

  3. Click the Resume Debugging Session button in the Message View window.

    Resume debugging session button

    The rest of the servlet is debugged.

  4. Select the browser again.

  5. The text of the servlet displays in the browser, and should look like this:

    Running Servlet Hello World

Changing code and re-running the servlet

Now that the servlet is running, you can change some code in the servlet, select Reload or Refresh from your browser, and the servlet will attempt to reload. At the designated breakpoint, JBuilder will display with the code at the breakpoint highlighted. When you select Resume, the servlet reloads in the browser window. To see how this works,

  1. Go to the Source window in JBuilder.

  2. Stop Tomcat by selecting it in the Message pane and clicking the Reset Debugging Session button, which looks like this:

    Reset debugging session button

  3. Change the line directly before the breakpoint from
    out.println("<FONT COLOR=GREEN>");
    to
    out.println("<FONT COLOR=RED>");

  4. Select File|Save All.

  5. Select Run|Debug Project.

  6. Select Reload or Refresh in your browser. JBuilder displays with the code at the breakpoint highlighted.

  7. Click the Resume button.

  8. Return to the browser and the servlet reloads! The font is now in red and the date fields also reflects that the servlet has reloaded.

This example isn't exactly rocket science, but you get the point! JBuilder 3.5 Foundation and Tomcat 3.1 provide a powerful combination for creating, testing, and debugging servlets. JBuilder Professional and Enterprise editions provide even more tools that enable rapid development of JSPs and servlets.

You can also use JBuilder 3.5 Foundation and Tomcat 3.1 to create, test, and debug JavaBeans used in JSP files or servlets, as well as to create, test, and debug JSPs. Check back to this location shortly for an example of both of these, as well as for examples that create the same applications using the JBuilder 3.5 Professional and Enterprise editions.


Server Response from: ETNASC01