Tomcat Installation and Set-Up
By Ryan Stewart.
Index
- Overview
- Installation
- Developing Applications
- Summation
- Resources
Overview
Read Me!
This isn't intended to be a dry, read-me-and-fall-asleep document. It's intended to be a hands-on guide through setting up the development environment you'll need in order to work on projects in this office. Since it's intended for use within the office, it is written to stay within the standards we use here.
If you want to use it as a reference to set up a development environment at home, you can easily do so. There will just be some parts you'll skip over. I strongly recommend following this guide all the way through because later parts depend on your understanding some earlier parts. I've broken it up into Tasks that must be completed. A task is marked like this:
When you see one of these, do it. If you don't know how to do it, read the explanation following. It gives detailed instructions. However, always read any notes that you come across. They contain vital or helpful information that you shouldn't miss. Notes look like this:
A Note
I've also tried to write this guide so that people with varying levels of experience can spend as much or as little time as they need and reach the same end. I've done my best to point out the things that you can skip and the things that you shouldn't. At the very minimum, everyone needs to read and follow all of the tasks and notes. If you understand and do what they say, you should be fine and ready to start working on projects. Any time you need more detail, read the explanations provided.
The rest of this "Overview" section (the "What is...?" headings) is purely informational. You can skip it if you want and go straight to "The Installation". That's where the fun starts.
What is Java?
Java is a programming language which is completely unrelated to JavaScript, so get that idea out of your head right now and we'll all be much happier. If you want the history of the language's development, it is available in most any book you can buy on the subject and probably online somewhere as well. The Standard Edition of Java is free and open source. The Enterprise Edition is free, but the source code is hard to come by. We will be using parts of both of these.
What is NetBeans?
NetBeans is an integrated development environment (IDE) sponsored by Sun Microsystems and built for the purpose of creating Java applications, applets, web applications, and pretty much anything else that can be done with Java, as well as some related things such as HTML, XML, and Ant scripts. Its functionality can also be extended by downloading custom modules written for that purpose. For those without prior programming experience, an IDE is a program that puts all your tools in one place. In NetBeans, you have a code editor, compiler, debugger, file templates and creation wizards, support for internal (controlled by NetBeans) web servers, database connectivity, CVS interactivity, and a host of other functions, many of which you may never touch or even figure out what they do.
What is Tomcat?
Tomcat is basically a lightweight web server, but as mentioned above, it was actually designed to be a servlet/JSP container. A servlet/JSP container is required to be able to run servlets or JSPs that you write. Unlike a normal program, such as a Java application or applet, servlets and JSPs cannot be run on their own. They have to be put into a valid container. Tomcat provides this. It was/is developed as part of the Jakarta project, which "creates and maintains open source solutions on the Java platform for distribution to the public at no charge" (from their website). The project has no paid staff. All work is done on a volunteer basis.
The Installation
The order in which you install the components is important. Tomcat requires Java to run. NetBeans may not require it (I'm not sure) but is pretty useless without it. Therefore, our installation order will be:
- Java
- NetBeans
- Tomcat
Checking out Your Hard Drive
This is the first part you can skip if you're doing this at home. Currently, when you get a newly imaged computer from the WGMs, it has a large hard drive but only a small part if it is available for use. Go to Start -> Programs -> Administrative Tools and start Computer Management. In the window, under Storage, click Disk Management. It should show a representation of your drives in the right hand pane. If there is unpartitioned space, you'll need to create a new partition and logical drive. First, consider what drive letter you'll want to use. Most likely, your CD-ROM drive is currently your D: drive. If you'd like to use D: for your new hard drive partition, change the CD-ROM drive letter by right clicking on its box in the bottom part of the Disk Management view. When that's done, right click on your hard drive's unpartitioned space, and select "Create New Partition". Select "Extended Partition" from the dialog box, and click next to go through the subsequent screens. The default settings should be correct. When that's finished, right click on the newly created extended partition, and select "Create logical drive". This will take you through a series of dialogs that allows you to select a drive letter and a volume label, among other things. Now you should have an empty secondary drive ready for use. Use this drive for projects and other things. Be careful of putting things on your C drive. It's relatively small. If you need clearer instructions on what to do, someone around you should be able to help.
From this point on, I'll assume you're working from the D: drive, as that is how most of the computers here in the office are set up.
On with the show...
Installing Java
The Java documentation found on the download page is extremely useful. Downloading it is a good idea since the internet access here occasionally leaves you high and dry.
The full title is Java 2 Platform, Standard Edition, and is shortened to J2SE. At the time of this writing, the latest, non-beta version of J2SE is 1.4.2_04. Go to http://java.sun.com/, and you'll likely see a link directly to the SDK download in the "Popular Downloads" box on the right side of the screen. Otherwise, click "Downloads" on the left side of the screen. In the select box under J2SE, find J2SE 1.4.2 and select "All platforms" underneath it, and then click the Go button. You'll see a page divided into several sections. Scroll down past the NetBeans Cobundle (it's evil) to the section titled "Download J2SE v. x.x.x". There should be a column labeled JRE and one labeled SDK. The JRE is the Java Runtime Environment, and only allows you to run Java programs, not write them. Click the download link for the SDK, agree to the license agreement, and it will take you to a page with multiple download links. The Windows links are at the top. You have an option for "Windows Offline Installation" or "Windows Installation". The difference is that the first downloads a file containing everything you need to install Java without being connected to the internet, whereas the second downloads a small starter program that then goes online and downloads the files necessary for installation. Click the one you want and save it somewhere that you can find it.
Run the executable that you downloaded. That's about it. By default, it will be installed in a directory like C:\j2sdk1.4.2_04. Obviously it changes with the version that you install.
This is in preparation for installing Tomcat later on. Right click on My Computer, select Properties, go to the Advanced tab, and click the Environment Variables button. Under System Variables, which takes up the bottom half of the window, click New. For the name, put JAVA_HOME (case doesn't really matter). For the value, put in the path where Java was installed. By default, this is "C:\j2sdk1.4.2_04". "Okay" your way out of there, and you're done installing Java.
Installing NetBeans
This one isn't as complicated as Java. Go to http://www.netbeans.org. There is a download pane to the left that will probably have the link you want. At this time, version 3.5.1 is the latest stable release, but 3.6 looks to be released soon. Also, you want the NetBeans IDE, not the NetBeans Platform. If you can't find the link to the left, click on the Download tab at the top, and then click "The NetBeans IDE". Look closely to find the Windows download link. When you find it, you will be taken to a page with a survey on it. Read carefully near the top and you'll find a link to skip the survey and go straight to the download. Once again, accept the license agreement and you're good to go.
This one's easy. Run the executable. Click Next a few times. You're done.
Installing Tomcat
It's important to use Tomcat 4 here in the office because it supports the same J2EE specification that the Air Force servers do (J2EE 1.3). Tomcat 5 moves up to J2EE 1.4.
Being part of a rather large collection (the Jakarta project), this is a little more difficult to find than the previous downloads. Start out at http://jakarta.apache.org/. On the left, under Downloads, you'll see Binaries. Click it. Then start scrolling down. Soon you'll come to a list of all the things you can download from Jakarta. They are in alphabetical order, and a lot of them will start with 'C'. Keep scrolling until you get to "Tomcat". When you find the version you want to use, download the executable version. The link should look something like "4.1.30 exe".
Make sure to install Tomcat as a Windows NT service. It will make things much easier later on.
Run the executable. When it gives you a list of options, check off "NT Service". This will cause it to be installed as a service in Windows NT/XP, which allows you to easily restart it when needed. After the installation, it will ask you for a username and password for the Tomcat admin. Don't forget the password. You'll want it later.
Developing Applications
By "applications" here, I mean web applications. That is the focus of our efforts at this time. There is a lot involved in this, but if you've gone through the installation section of this guide, you have all the tools necessary to develop and deploy a web application. I'll start you off with some very simple examples and hopefully lead you to understand how an entire webapp can be fit together from its many pieces. First, though, some thought needs to be given to how you will keep your files organized.
Organizing Your Files
If you've done only a little programming before or you're just starting out, you may not understand the importance of keeping your files organized. After you've worked here for a few months or a year, though, you could easily have several projects that you're working on or using for reference along with some things you've developed on your own. If you don't keep them separate, nasty things can happen, so let's start by creating a few directories to keep things organized.
This one's pretty self explanatory. Open Windows Explorer (or My Computer or however you prefer to navigate your local drives), go to the D: drive, and create a new folder. Name it "Projects". This folder is just your base folder. You won't put any files in here. You will create other directories in it to hold your projects. Let's start off by creating a simple Java program in your projects folder.
Your First Java Program
This section contains no tasks essential to setting up the development environment. It is simply a tutorial for creating and running a simple Java program in NetBeans. If you are already familiar with the process, you may skip this section and go to "Your First Web Application".
First, open Windows Explorer and create a new directory in D:\Projects named "javaStuff". Then start NetBeans. Now go get a glass of water or something while you wait for NetBeans to load. If this is the first time you've run NetBeans, you'll see the welcome screen. Look over it if you want. You can access it at any time via the Help menu (just select "Welcome Screen"), so close it for now. Now we will create a new Project to do your work in.
Creating a Project in NetBeans
Click the Project menu, and select Project Manager. If you haven't used it before, you should see one project listed under "Existing Projects": Project Default. Click the New... button and type "Java Stuff" to create a new project named Java Stuff. A dialog box may pop up asking you what type of project to create. Make sure "Java 2 Standard Edition" is selected and click Finish. Shortly you'll see the NetBeans interface again.
Mounting a filesystem
The interface consists of a left and right pane with the left pane split again into top and bottom panes. Look now at the top pane on the left. This is your "Explorer" view. In NetBeans 3.5.1, there are tabs along the bottom of this view. In later versions, they may be at the top. You will probably see three tabs there labeled Filesystems, Project Java Stuff, and Runtime. Click the Filesystems tab if it isn't already selected. This view should be empty except for a little box looking thing (a computer?) with the word "Filesystems" next to it. In order to work with files in NetBeans, you must "mount" a filesystem. Right click on the little computer or the word Filesystems next to it. On the menu that pops up, go to Mount, then to Local Directory. You will see a familiar file browsing dialog. Navigate to your D:\Projects directory, and select the javaStuff directory. Then click Finish. Don't try to double click the folder. That will only open it in the dialog. You have to select it and press Finish. You should now see your directory listed under Filesystems in Windows Explorer style. You can expand and collapse folders to view and hide their contents. Right now, though, your folder has no contents. Let's make some.
Creating a Java source file
Right click on your mounted filesystem in the Explorer view. Go to New on the popup menu, then to Java Main Class. It will ask you for a file name. Enter "HelloWorld" without the quotes. Then click Finish. (You can click Next to see the other options it gives you for creating Java classes. It can do a lot of the building for you.) NetBeans will create the basic framework of a simple Java program for you. You will see your new file in the Explorer view (if you have the filesystem expanded) and its contents in the source editor on the right. Erase the contents of the new source file and copy the following code into it.
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello world!");
}
Running a program
When your code is ready to compile and run, you have several options within NetBeans. Here are three easy ways to compile and run your program in one step:
- With the focus either in the source editor or on your file in the Filesystems view, press F6.
- Right click anywhere in the source editor and select Execute from the menu.
- Right click on your file in the Filesystems view and select Execute from the menu.
About the Results of Running the Program
When you run the program, several things will happen. First, NetBeans will compile your code. When you try to execute a program that hasn't been compiled, it automatically compiles it for you. Then it will execute the compiled code. As a result of these two things, you will see a new pane pop up below the editor pane in NetBeans. This is the Output Window. First of all you'll probably notice the words "Hello world!" with a black box on the line following it. The black box is the insertion cursor. At this point you can type something and it will appear in that window below "Hello world!". If you look toward the bottom of this pane, you should also see that there are two tabs here. One is labeled "Compiler" and the other, active tab is labeled "HelloWorld". Note that this matches the name of the Java program you just made. Click on the compiler tab, and you should see the words "Finished HelloWorld.". As I said before, the first thing NetBeans did was compile the code. This tab was created as a result. Then it ran the code, which caused the other tab to be created. Any time you run a program in NetBeans, any output will be shown here on a tab labeled with the program's name. You may have also noticed a white pane on the right side of this output pane. It probably appeared while the program was running and disappeared when it was finished. This is the Execution View. It shows you everything that NetBeans is currently running. You can get another look at it by opening the View menu and selecting Execution View.
Conclusion
And that's your first Java program (unless it's not). If you want to know more about the language, see the list of resources at the end of this document.
Your First Web Application
This section also contains no tasks essential to setting up the development environment. It contains instructions on creating a web module in NetBeans and setting up a context in Tomcat to view it. If you are already familiar with these topics, you're done. See the references at the end of this document for more information.
Now I'll show you how to create a new web application from scratch in NetBeans and configure Tomcat to view it. When you get to the end of this section, it may seem like a lot of work for very little return, but the important thing here is the process. By the time we're done, you'll know how to create and deploy a web application and be familiar with its parts. This will apply to any webapp, no matter how complex it is. First, create a folder in D:\Projects called "myWebApp". Next, create a new project in NetBeans named "My Web App". Finally, mount D:\Projects\myWebApp in the new project. If you have trouble with any of this, look back to the "Setting Up a NetBeans Project" section.
Creating a new Web Module
Right click on your mounted filesystem, select New, and select "All Templates...". You'll be presented with a dialog box with all of the files NetBeans currently knows how to create broken down into rough categories. Find the "JSPs & Servlets" category and expand it. Select "Web Module" and click next. NetBeans will ask you for a directory to create it in. Since you used the right click menu, it's already filled in with the directory you chose. Click Finish.
Getting Familiar with the File Structure
A couple of things will happen when you create the Web Module. Most obvious will be new the dialog box that pops up. It's informing you that NetBeans knows how to display a web module in an organized manner in the Project view. If you click on the Project tab in your Explorer pane (after closing the dialog), you'll see your mounted folder with a web module icon. If you expand it, you'll see that NetBeans has set up a viewing structure for you, even if you don't know what you're looking at. Don't worry about that for now. Go back to the Filesystems view. Another thing you'll notice is that there appears to be a second mounted filesystem. NetBeans did this automatically. Don't remove it or NetBeans will freak out.
In the Filesystem view, expand everything as far as possible. You should see something like this:
D:\Projects\myWebApp
- WEB-INF
classes
lib
web
D:\Projects\myWebApp
: /WEB-INF/classes
Now look at your myWebApp folder in Windows Explorer. You'll see that NetBeans is simply displaying the file structure exactly as it is. When you told it to create a new Web Module it created the WEB-INF folder and everything in it. This is the essential structure of a J2EE web module. Technically, you now have a valid, deployable web application in your myWebApp folder. The WEB-INF folder itself is never visible to the client. It's strictly for server side stuff. The "classes" folder is where you put Java classes that support your application. The lib folder is where you put JAR (Java Archive) files. These are archived class files. Finally, there's web.xml. This is called the "application deployment descriptor". It's basically your settings file for the entire application. Finally, there's the second filesystem that NetBeans mounted. It's actually nothing new. It's simply the "classes" folder inside the WEB-INF folder. It's not really important to the web application. NetBeans itself needs this so that it can find the Java classes that are stored here. (It has to do with how Java works in NetBeans.) You can either ignore it or use it as a shortcut to the "classes" folder, but as I said before, do not remove it. So now you have an empty web application. "Great. What now?" you may say. Now we will create a JSP for your webapp.
Your First JSP
"Whoa, hold up. What," you may ask, "is JSP?" JSP stands for Java Server Pages. It is part of Java's server side technology, which means it is meant to be run on web servers as opposed to clients. Its main purpose is the generation of dynamic web pages. It essentially has the whole power of the Java language behind it making it a very powerful tool. An individual file is generally referred to as "a JSP". These files are the building blocks that we construct working web applications from.
Creating a JSP
We'll be working in NetBeans in your mounted D:\Projects\myWebApp folder (which should also contain the WEB-INF folder created in the last section). Right click on the mounted filesystem, select New, and select All Templates... again. You may have noticed that "Web Module" now shows at the bottom of your "New" menu. When you select something from "All Templates..." it is added to the bottom of this menu. It keeps your five most recent "New" items. In the dialog, open JSPs & Servlets again, select JSP, and click Next. It will ask you for a name. Name it "myFirstPage". You should see it appear beneath WEB-INF in the myWebApp filesystem, and its contents will be shown in the source editor.
Exploring Your First JSP
NetBeans should have created an eleven line file for you (including all the blank lines). Right click the grey margin on the left side of the source editor and select "Show Line Numbers" to show the line numbers (duh). Line one is a JSP directive. This particular directive (there are many) sets the type of content which will be sent to the client requesting this page. The "text/html" type is the default and is just plain HTML. There are many possible types such as images, Office documents, sounds, etc. Using Java to create byte streams from files, any of these kinds of files can be sent via JSP. You may notice that most of the rest of the lines in the file are just regular HTML. They are sent to the client exactly as they are. In fact, a JSP can have nothing but HTML in it and it will work just fine. Lines six and seven should appear in grey. That's because they are each inside a JSP comment block which is started by ol<%- and ended by ol -%> . These are statements provided by NetBeans that give you simple examples of interacting with JavaBeans. Don't worry about them right now. They are actually little used in that form anyway. Delete them if you want, and then type "Hello World!" somewhere between the ol<body> and ol</body> tags. (But not inside the comments or it won't show up!) Save it.
Deploying Your Web Application
Now we come to Tomcat. If you installed Tomcat as a service (highly recommended), it is most likely already running. If you didn't, it probably is not running. Either way, the first thing you'll need to know is how to start and stop it when you want to.
Starting and Stopping Tomcat as a Service
You need to find your Windows "Services" application. It is in Administrative Tools which is normally in Control Panel, but can also be added to your Start Menu (under Programs) in your Start Menu properties. Since everyone should have it in Control Panel, we'll go that way. Click Start -> Settings -> Control Panel. If you have "Expand Control Panel" enabled in your Start Menu properties, keep on going through to Administrative Tools -> Services. Otherwise, when your Control Panel window opens, double click Administrative tools, then double click on Services. (I'd recommend making a shortcut to Services on your desktop or in your Quick Launch bar, as you'll likely be using it often.) You should now see the Services application. "Apache Tomcat 4.1" should be listed near the top. Most likely, its status will be "Started". That means it's running. To refresh the window, click the Action menu and select Refresh. If you click on the Tomcat entry (and it's running) you'll notice that two of the four buttons on the right side of the toolbar light up. You should recognize the first as the universal symbol for stop. The other is restart. Quite simply, to restart your web server, select it and press the restart button. To stop it, select it and press the stop button. I'll let you figure out how to start it on your own.
Starting and Stopping Tomcat Not as a Service
When you installed Tomcat it put a folder in your Start Menu named "Apache Tomcat 4.1". Within that folder, you should see "Start Tomcat" and "Stop Tomcat". Guess what they do. Click "Start Tomcat", and you'll see a Windows command prompt window open and a few lines of text. This is Tomcat starting. Do not close this window! The window is where Tomcat is running. If you close it, you close Tomcat. When you do want to stop Tomcat, it's recommended that you use the "Stop Tomcat" option in the Start Menu rather than just closing this window.
How to Run a Web Application in Tomcat
There are several ways to set up a web application within Tomcat. I will only cover the way we do it here, which gives you a great deal of flexibility in development.
Make sure that your Tomcat server is running. Click on the following link or open a browser window and type in the address bar: http://localhost:8080/admin. This should take you to the Tomcat Administration Tool. If it doesn't work, get someone around you to help figure out what's wrong.
This is where you need the username and password you entered when you installed Tomcat. Enter them and click Login. In the left pane that again looks like an Explorer view, look under "Tomcat Server" at the top to find "Service (Tomcat-Standalone)". Expand this. Then click on "Host (localhost)". This should bring up some content on the right.
At the top right of the new content, you'll see a "Host Actions" select box. Select "Create New Context" within it. You'll see a new screen with several options in it. The two important fields are the two empty text boxes labled "Document Base" and "Path". The first is the physical location of a folder on your hard drive. The second is what you want to type in the address bar of a browser to access that folder.
For instance, put "D:\Projects\myWebApp", without the quotes, in the Document Base field (assuming you've followed this guide up to this point). And in the Path field, put "/myWebApp", again without the quotes. It's important to recognize that Document Base takes backslashes (\) while Path takes forward slashes (/) and also that Path must begin with a forward slash. Click the Save button at the top right.
When you get the "Save Successful!" message, click the Commit Changes button at the top of the screen. After it does its thing, click Log Out. Now restart your server. (It seems that you shouldn't have to, but I rarely have much luck with creating a new context then immediately using it.)
After it finishes restarting, click or type into your browser's address bar http://localhost:8080/myWebApp. It should take you to a directory listing showing two files. One is ".nbattrs" and is a NetBeans file. Don't worry about that. The other should be your JSP, "myFirstPage.jsp". Click on its name. After a brief pause for the server to compile the page, you should see "Hello World!" displayed in the browser. Congratulations. You just wrote a web application.
Summation
Unless I've forgotten something, this should be the basic knowledge you need to start using the tools we use to develop applications.
Resources
- Java
- http://java.sun.com/docs/books/tutorial/ - The Java Tutorial: a great place to start learning Java. "Your First Cup of Java" is an excellent introduction to the language.
- http://java.sun.com/docs/codeconv/ - Java Code Conventions: why and how to write Java according to standards
- http://java.sun.com/j2se/1.4.2/docs/api/index.html - Java (SE) API Specifications: everything you'll ever need to know about the Java 2 Standard Edition classes
- http://java.sun.com/j2ee/sdk_1.3/techdocs/api/index.html - Java (EE) API Specifications: same as above, but for Enterprise Edition
- Other Web Related
- http://www.w3schools.com - W3 Schools: The very basics of many web-related technologies like HTML, CSS, and SQL.
- http://www.w3.org/TR/CSS2/ - CSS2 Specification: the official spec for CSS
- CVS
- http://w1.858.telia.com/~u85831169/cvs-command.html - CVS Commands
- http://www.cvsnt.org/wiki/CvsIndex - CVSNT manual
- http://www.cvshome.org - CVS home page
- http://cvsgui.sourceforge.net/howto/cvsdoc/index.html - Excellent CVS How To
