jakarta-tomcat-4.0.3 
|__bin                        Binary executable files
|__classes                    Classes available to all Web applications
|__common                     Classes available to internal classes and
                              Web applications
|   |__classes                Common Java classes
|   |__lib                    Common Java classes in Java Archive (JAR) format
|__conf                       Configuration files (such as passwords)
|__jasper                     JAR files used to process and run JSP pages
|__lib                        JAR files available to Web applications
|__logs                       The server's log files
|__server                     Internal Tomcat classes
|__webapps                    Directory for Web applications
|__work                       Scratch directory for holding temporary files

We'll get more familiar with this directory structure when we start using it in depth in the coming days.

Note in particular the webapps directory, which is where the Web applications you create go so they're accessible to the browser. For instance, the examples from Day 1 will go into the ch01 directory we'll add to webapps:

webapps 
|__ch01                       Our folder for Day 1 examples

The directory containing Web applications must also contain a directory named WEB-INF, with two subdirectories, classes and lib. WEB-INF, classes, and lib might all be empty, but Tomcat will expect them to be there before running your application:

webapps 
|__ch01                       Our folder for Day 1 examples
    |__WEB-INF                Information about Day 1's Web applications
         |__classes           Java classes used by Day 1's Web applications
         |__lib               JAR files used by Day 1's Web applications

We'll create the ch01, WEB-INF, classes, and lib directories we need in a moment, but first, let's start Tomcat itself.

In particular, the environment variables to set are the following:

The way you actually set these variables varies by operating system. For example, to set JAVA_HOME to C:jdk1.4 in Windows 2000 Professional, you can select Start, Settings, Control Panel to open the control panel, and double-click the System icon in the control panel. Next, click the Advanced tab as you see in Figure 1.3. Doing so opens the Environment Variables dialog box; click the New button in the System Variables part, opening the New System Variable dialog you see in Figure 1.4.

Figure 1.3. The Advanced tab in the System Properties dialog in Windows 2000 Professional.

Figure 1.4. Setting an environment variable in Windows 2000 Professional.

You can enter the new setting for JAVA_HOME as you see in Figure 1.4: C:jdk1.4. To change the PATH variable, which already exists, you click the Edit button in the System Variables section and edit the PATH variable to add the Java bin directory to it. For example, if your path looks something like this:

C:WINDOWS;C:Program Files 

you'd add a semicolon and the path of the Java bin directory:

C:WINDOWS;C:Program Files;C:jdk1.4in 

How you set environment variables depends on the operating system, however; for example, the process is completely different in Windows 95/98, where you must edit the C:autoexec.bat file instead.

You can also set the environment variables when you start Tomcat itself, and you might find that more convenient. You'll find the directions for starting Tomcat in the running.txt document that comes with Tomcat.

To start Tomcat, you'll need a command prompt. In Windows, that's the DOS prompt, which you get in a DOS window. You can open a DOS window by selecting Start, Programs, Accessories, Command Prompt in Windows 2000 Professional; Start, Programs, MS-DOS Prompt in Windows 98, and so on.

To set the environment variables (if you haven't set them already), you can type the following at the DOS prompt. (Make the version numbers and paths match what you have installed, of course. )

C:>SET JAVA_HOME=C:jdk1.4 
C:>SET CATALINA_HOME=C:	omcatjakarta-tomcat-4.0.3
C:>SET PATH=%PATH%;C:jdk1.4in

Note the last statement, SET PATH=%PATH%;C:jdk1.4in, which is an easy way of adding C:jdk1.4in to the end of the path, without making any changes to the rest of the path.

In the Unix bash shell, this might look something like this in your .bashrc file (start a new shell to make the changes take effect):

JAVA_HOME=/jdk1.4 
export JAVA_HOME
SET CATALINA_HOME=/tomcat/jakarta-tomcat-4.0.3
export CATALINA_HOME
SET PATH=/usr/local/bin:/jdk1.4/bin
export PATH

In the Unix tcsh shell, it might look like this in your .tcshrc file (start a new shell to make the changes take effect):

setenv JAVA_HOME /jdk1.4 
setenv CATALINA_HOME /tomcat/jakarta-tomcat-4.0.3
setenv PATH /usr/local/bin:/jdk1.4/bin

After these environment variables are set, we're ready to start Tomcat. Again, this process is operating system-dependent; see the Tomcat document running.txt for more details. In Windows, go to the Tomcat bin directory (the bin directory is right under the directory that Tomcat unzips itself to, such as C: omcatjakarta-tomcat-4.0.3in if Tomcat was unzipped in C: omcat) and type startup:

C:	omcatjakarta-tomcat-4.0.3in>startup 

In Unix, that command might look like this:

/tomcat/jakarta-tomcat-4.0.3/bin/startup.sh 

That's it—now Tomcat is running. In Windows, you'll see a new DOS window open and a message similar to this appear:

Starting service Tomcat-Apache 
Apache Tomcat/4.0.3

Don't close this new window—that's where Tomcat is running. So how do we put Tomcat to work? You'll need a browser, such as Microsoft Internet Explorer (which you can pick up free at http://www.microsoft.com/windows/ie/default.asp), or Netscape Navigator (free at http://browsers.netscape.com/browsers/main.tmpl). Run the browser now and enter the URL http://localhost:8080/index.html, which should bring up the page you see in Figure 1.5.

Figure 1.5. Running the Tomcat server.

To stop Tomcat, you use the shutdown command. It looks something like this in Windows:

C:	omcatjakarta-tomcat-4.0.3in>shutdown 

and this in Unix:

/tomcat/jakarta-tomcat-4.0.3/bin/shutdown.sh 

That's our first step—getting Tomcat itself running. We've already made progress—now let's see whether we can display some of our own pages using this server.

The pages into which we embed our JSP are Hypertext Markup Language (HTML) pages. (This book assumes you are already familiar with HTML.) HTML is a specification of the World Wide Web Consortium (W3C), and you can find the official home page for HTML at http://www.w3.org/MarkUp. The current version of HTML is 4.01, and you can find HTML's official specification at http://www.w3.org/TR/html4/.

We've already seen our first HTML example, ch01_01.html; that example didn't do anything except support a title for the page and display the text Hello there!:

<HTML> 
    <HEAD>
        <TITLE>
            A Web Page
        </TITLE>
    </HEAD>

    <BODY>
        Hello there!
    </BODY>
</HTML>

That's okay as far as it goes, but it doesn't go very far. This page is very static, and Web developers wanted more as the Web became more and more popular. At first, client-side programming became popular, using script languages like JavaScript.

Despite the name, JavaScript is not related to Java. It actually began in 1995, when a Netscape Communications Corporation developer named Brendan Eich was given a new project to work on. The original idea was to give Netscape Navigator something extra; Eich took a look around and decided that what was needed was a scripting language that was fast and easy to use.

He called his creation LiveScript, but it was renamed JavaScript (although developed by Netscape, Sun had the trademarks on Java, so, interestingly, the name JavaScript is actually a trademark of Sun Microsystems). The new language was announced in a joint press conference with Netscape and Sun on December 4, 1995.

Unlike JSP, which is all about programming on the server, scripting languages like JavaScript are all about programming on the client side, in the browser. You enclose your JavaScript code in a <SCRIPT> element in an HTML page—for example, you can see how to use JavaScript to write the message Hello there! to a Web page while that page is being loaded in Listing 1.2.

<HTML>
    <HEAD>
        <TITLE>
            A Web Page
        </TITLE>
    </HEAD>

    <BODY>
        <SCRIPT LANGUAGE="JavaScript">
            <!—
                document.write("Hello there!")
            //—>
        </SCRIPT>
    </BODY>
</HTML>

This creates the same results as we saw for our HTML page in Figure 1.7, but now we're using JavaScript to write to the Web page. Client-side programming like this can be useful—you'll see that we can use JavaScript to pass data to JSP documents on the server—but it's extremely limited. As a result of security restrictions, for example, you can't access files from JavaScript. And because JavaScript has to be built into the browser, it has to be relatively small, and can't contain more than a small fraction of the power of a full programming language like Java. In fact, during all the time HTML and scripting languages like JavaScript were developing, so was Java.

Java wasn't originally created for the Internet. The first version was actually begun in 1991 and written in 18 months at Sun Microsystems. In fact, it wasn't even called Java in those days; it was called Oak, and it was used internally at Sun.

The original idea for Oak was to create an operating system-independent language. Many programmers were confining themselves to programming for the IBM PC at that time, but the corporate environment can include all kinds of programming platforms, from the PC to huge mainframes, and the inspiration behind Oak was to create something that could be used on all those computers. (Actually, the original inspiration for Oak was not what you'd call especially glamorous—Sun wanted to create a language it could use in consumer electronics. )

Oak was renamed Java in 1995 when it was released for public consumption, and as you probably know, it's become very popular. Even though it's not targeted at the Internet, you can still use it to display the message Hello there!; Listing 1.3 details a small Java application named ch01_03.java that does just that.

public class ch01_03
{
    public static void main(String[] args)
    {
        System.out.println("Hello there!");
    }
}

You compile ch01_03.java with the Java compiler, which is named javac. If you've set up your path to include the Java bin directory as we saw earlier, you can use the javac command at the command prompt; here's how that might look in Windows (make sure you're in the same directory as ch01_03.java):

C:>javac ch01_03.java 

This creates ch01_03.class, which you can run with the Java tool, simply named java. Here's how that would look in Windows:

C:>java ch01_03 

You can see the results in Figure 1.8, where our Java application is displaying the message Hello there!

Figure 1.8. Running a Java application.

JSP is based on Java, and a lot of this book is about learning to use Java. Java's a big part of the Internet now because Sun couldn't ignore the Internet, and Java's first attempt at working with the Internet was to introduce applets.

Here's an example called ch01_04.java. The Java applet you see in Listing 1.4 displays our Hello there! message.

import java.applet.Applet;
import java.awt.*;

public class ch01_04 extends Applet
{
    public void paint(Graphics g)
    {
        g.drawString("Hello there!", 60, 100);
    }
}

To use this applet, you must first compile it with javac:

C:>javac ch01_04.java 

This creates ch01_04.class, which you can use in the HTML <APPLET> element. Here's a sample Web page that does this by setting aside an area 200×200 pixels in which to display the applet in Listing 1.5.

<HTML>
    <HEAD>
        <TITLE>A Web Page</TITLE>
    </HEAD>

    <BODY>
        <APPLET CODE="ch01_04.class" WIDTH="200" HEIGHT="200"></APPLET>
    </BODY>
</HTML>

If you store the applet, ch01_04.class, and this Web page, ch01_05.html, in the webappsch01 directory, you can see the applet at work by navigating to http://localhost:8080/ch01/ch01_05.html, as you see in Figure 1.9.

Figure 1.9. Viewing an applet.

Applets can display text like this, along with buttons, and so on, but like JavaScript, they're very limited. In fact, their time is mostly past as new client-side applications like Flash take over; the standard version of the newest Netscape Navigator no longer even supports applets by default.

But the Internet was still there to conquer. With the demise of applets, Java turned to the server side of things, and its first step in the server was to implement servlets.

Listing 1.6 shows a sample servlet, ch01_06.java, written in pure Java that will display our message.

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class ch01_06 extends HttpServlet
{
    public void doGet(HttpServletRequest request,
        HttpServletResponse response)
        throws IOException, ServletException
    {
        response.setContentType("text/html");
        PrintWriter out = response.getWriter();

        out.println("<HTML>");
        out.println("<HEAD>");
        out.println("<TITLE>");
        out.println("A Web Page");
        out.println("</TITLE>");
        out.println("</HEAD>");
        out.println("Hello there!");
        out.println("</BODY>");
        out.println("</HTML>");
    }
}

Compiling ch01_06.java into ch01_06.class takes an additional step we haven't seen before. Much of the support for servlets is not built into the core of Java, but is stored in a Java Archive (JAR) file named servlet.jar, which stores many specialized .class files internally.

Tomcat comes with servlet.jar (located in the jakarta-tomcat-4.0.3commonlib directory), and to access it, we have to set the CLASSPATH environment variable, which is specific to Java. As you might expect from the name, CLASSPATH indicates where Java can look for the .class files it needs when getting an application ready to run; we're using CLASSPATH because we need a number of servlet .class files stored in servlet.jar. Here's how you can set the CLASSPATH variable to include servlet.jar in Windows (change the path to servlet.jar as needed):

C:>SET CLASSPATH=C:	omcatjakarta-tomcat-4.0.3commonlibservlet.jar 

Now Java can find what it needs to compile servlets. You might have already set CLASSPATH to other locations, so if you just want to add servlet.jar to the CLASSPATH without affecting the rest of what's already in CLASSPATH, you can do the following in Windows (like other environment variables, you separate the locations and JAR filenames in the CLASSPATH variable with semicolons):

C:>set classpath=%CLASSPATH%;d:	omcatjakarta-tomcat-4.0.3commonlibservlet.jar 

You'll see more on using and setting CLASSPATH in Day 11, “Creating More Powerful JavaBeans.” Now that we have access to servlet.jar, navigate to the directory where our sample servlet ch01_06.java is located, and use javac to create ch01_06.class (this assumes javac is in your computer's path) :

C:>javac ch01_06.java 

Now transfer ch01_06.class to jakarta-tomcat-4.0.3webappsch01classes—note that we have to use the classes directory for Java classes like ch01_06.class.

And that's it—all we have to do now is navigate to http://localhost:8080/ch01/servlet/ch01_06. You can see the results in Figure 1.10-note that it looks just like our original HTML document, but this time, we've created this Web page on the server.

Figure 1.10. Using a servlet.

Servlets are very powerful, but they're not easy to program. As a result, they haven't become very popular. But Java and the Internet was a match meant to be—and the next step is JSP.

JSP is built on top of servlets, but JSP is much easier to program, and that's the whole point—that's why JSP has taken off.

JSP, a specification of Sun Microsystems, first appeared in 1998. The official versions, 1.0 and 1.1, both appeared in 1999, and both were very popular. The current version, 1.2, appeared in 2001, and is the most popular implementation yet; this is the version we'll be using in this book.

Internally, each JSP page is actually converted into a servlet by the server (we'll see exactly how that works in Day 13). In other words, this is really a book about servlets—but they're acting entirely behind the scenes.

From our point of view, JSP pages are simply HTML pages with embedded Java in them. And by using JSP, we avoid all the hassle of creating full-blown Java applications—the server will do all that for us, taking our Java snippets of code and compiling them for us automatically.

It's clear that Sun had gotten the message about making things easy for the programmer when it came up with JSP, and we're the winners. Let's use JSP now to create the Web page we've already developed—you can see what it looks like in Listing 1.7, ch01_07.jsp (giving this document the extension .jsp means Tomcat will know that it is a JSP document and treat it accordingly):

<HTML>
  <HEAD>
    <TITLE>A Web Page</TITLE>
  </HEAD>

  <BODY>
    <% out.println("Hello there!"); %>
  </BODY>
</HTML>

Figure 1.11. Our first JSP.

And that's it—now we've created and run our first JSP! Let's see what makes it tick.

There are three types of scripting elements in JSP:

<HTML> 
  <HEAD>
    <TITLE>A Web Page</TITLE>
  </HEAD>

  <BODY>
    <% out.println("Hello there!"); %>
  </BODY>
</HTML>

Declarations

String msg = "Hello there!"; 

This declares a new variable named msg that holds the text Hello there!. In Java, you must declare variables before you use them, giving them a name. After you've named a variable, you can refer to it in your code using that name.

There's a special set of tags, <%! and %>, that you can use to declare variables in JSP (you can also declare variables in scriptlets, which is a more common thing to do). Here's an example: In this case, the code declares the variable msg:

<HTML> 
  <HEAD>
    <TITLE>A Web Page</TITLE>
  </HEAD>

  <BODY>
    <%! String msg = "Hello there!"; %>
  </BODY>
</HTML>

Now you can use this new variable in a scriptlet; for example, here's how you can display the text in msg in the Web page using the out.println method:

<HTML> 
  <HEAD>
    <TITLE>A Web Page</TITLE>
  </HEAD>

  <BODY>
    <%! String msg = "Hello there!"; %>
    <% out.println(msg); %>
  </BODY>
</HTML>

That's what the process looks like in overview; you'll get all the details on declaring and using variables in Day 2.

<HTML> 
  <HEAD>
    <TITLE>A Web Page</TITLE>
  </HEAD>

  <BODY>
    <%! String msg = "Hello there!"; %>
    <%= msg %>
  </BODY>
</HTML>

You can use JSP comments to document what's going on in a JSP page; they act like notes to you or other programmers. Comments are purely for the benefit of the programmers that work on the page, because the server will strip them out before sending the page back to the browser. You enclose the text in a comment between the tags <%-- and --%>.

Here's an example; in this case, the code includes the comment Display the message now. to this JSP example:

<HTML> 
  <HEAD>
    <TITLE>A Web Page</TITLE>
  </HEAD>

  <BODY>
    <%-- Display the message now. --%>
    <% out.println("Hello there!"); %>
  </BODY>
</HTML>

This comment lets you and other programmers know what's going on in your JSP. You can add as many comments to a JSP as you like—they're entirely for the benefit of programmers, and will all be stripped out before the page is sent back to the browser.

JSP directives let you give directions to the server on how a page should be processed. There are three directives in JSP; we'll see them throughout the book, but here's an overview:

The page directive is going to be a useful one for us as we work with Java. You can use this directive to configure the page you're working on. Like other directives, you use the special tags <%@ and %> with this directive; to create a page directive, you also include the keyword page like this: <%@ page ... %>.

<%@ page errorPage="error.jsp" language="java" 
    contentType="application/xml" import="java.sql.*" %>
<HTML>
    <HEAD>
        .
        .
        .

As you can already see, the page directive is going to give us a lot of programming power.

The include directive, which looks like <%@ page ... %>, lets you include another page in the current page. When you include a page at a particular point, that page's entire contents are simply inserted at that point.

The taglib directive (which looks like this: <%@ taglib ... %>) specifies a library of custom JSP tags (see Days 9 and 10) that you want to use in the current page. Tag libraries let you define your own JSP tags. We're going to see how to use this directive later, so we won't go into the details now.

There are two types of actions: custom and standard. Custom actions are actions you create yourself, and standard actions come built into JSP. Here are the standard actions in overview:

We'll get all the details on these standard actions when we put them to work in the coming days. And that's it—that completes our overview of JSP syntax. Now we've got the foundation we'll need to move on to Day 2.