2. Tools Used in This Document

In this document, we will use the following tools:

a JDK Java 1.5
the TOMCAT web server (http://tomcat.apache.org/),
the ECLIPSE development environment (http://www.eclipse.org/) with the WTP plugin (Web Tools Package).
a browser (IE, NETSCAPE, MOZILLA Firefox, OPERA, ...).

These are free tools. In general, many open-source tools can be used in web development:

`IDE JAVA`	`Jbuilder Foundation`	http://www.borland.com/jbuilder/foundation/index.html
`IDE JAVA`	`Eclipse`	http://www.eclipse.org/
`Bibliothèques JAVA`	`Struts`	http://struts.apache.org/
`Bibliothèques JAVA`	`Spring`	http://www.springframework.org
`SGBD`	`MySQL`	http://www.mysql.com/
	`Postgres`	http://www.postgresql.org/
	`Firebird`	http://firebird.sourceforge.net/
	`Hypersonic`	http://hsqldb.sourceforge.net/
	`SQL Server Express 2005`	http://msdn.microsoft.com/vstudio/express/sql/
	`Oracle Express`	http://www.oracle.com/database/index.html
`Conteneurs de servlets`	`Tomcat`	http://tomcat.apache.org/
	`Resin`	http://www.caucho.com/
	`Jetty`	http://jetty.mortbay.org/jetty/
`Navigateurs`	`Netscape`	http://www.netscape.com/
`Navigateurs`	`Mozilla`	http://www.mozilla.org

2.1. J ava 1.5

The Tomcat 5.x servlet container requires a Java 1.5 virtual machine. You must therefore first install this Java version, which can be found at Sun at version url [http://www.sun.com] -> [http://java.sun.com/j2se/1.5.0/download.jsp] (May 2006):

Step 2:

Step 3:

Run the JDK 1.5 installation from the downloaded file.

2.2. The Tomcat 5 Servlet Container

To run servlets, we need a servlet container. Here we present one of them, Tomcat 5.x, available at url http://tomcat.apache.org/. We provide the installation procedure (May 2006). If a previous version of Tomcat is already installed, it is best to uninstall it first.

To download the product, follow the link above:

You can download the .exe file for the Windows platform. Once downloaded, launch the Tomcat installation:

Run [next] ->

Accept the license terms ->

Click [next] ->

Accept the suggested installation directory or change it using [Browse] ->

Set the Tomcat server administrator’s login and password. Here we used [admin / admin] ->

Tomcat 5.x requires JRE 1.5. It should normally locate the version installed on your machine. Above, the specified path is for the JRE 1.5 file downloaded in section 2.1. If no JRE is found, specify its root directory using the [1] button. Once this is done, use the [Install] button to install Tomcat 5.x ->

The [Finish] button completes the installation. The presence of Tomcat is indicated by an icon on the right side of the Windows taskbar:

Right-clicking this icon gives you access to the Start and Stop server commands:

We use option [Stop service] to stop the web server now:

Note the change in the icon’s status. The icon can be removed from the taskbar:

Tomcat was installed in the folder chosen by the user, which we will now refer to as <tomcat>. The directory structure for the downloaded Tomcat 5.5.17 is as follows:

The Tomcat installation added a number of shortcuts to the [Démarrer] menu. We use the [Monitor] link below to launch the Tomcat stop/start tool:

We then see the icon shown earlier:

The Tomcat monitor can be launched by double-clicking this icon:

The [Start - Stop - Pause] - Restart buttons allow us to start, stop, and restart the server. We start the server using [Start], then, using a browser, we navigate to url http://localhost:8080. We should see a page similar to the following:

You can follow the links below to verify that Tomcat has been installed correctly:

All the links on the [http://localhost:8080] page are of interest, and the reader is encouraged to explore them. We will have the opportunity to revisit the links for managing web applications deployed on the server:

2.3. Deploying a web application on the Tomcat server

[ref1] readings: Chapter 1, Chapter 2: 2.3.1, 2.3.2, 2.3.3

2.3.1. Deployment

A web application must follow certain rules to be deployed within a servlet container. Let <webapp> be the directory of a web application. A web application consists of:

`classes`	in the <webapp>\WEB-INF\classes folder
`Java archives`	in the <webapp>\WEB-INF\lib folder
`vues, ressources (.jsp, .html, ...)`	in the <webapp> folder or subfolders

The web application is configured by a XML file: <webapp>\WEB-INF\web.xml.

Let’s build the web application with the following directory structure:

We will create the directory structure above using Windows Explorer. The [classes] and [lib] folders are empty here. The [vues] folder contains a static HTML file:

whose content is as follows:

<html>
    <head>
      <title>Application exemple</title>
  </head>
  <body>
      Application exemple active ....
  </body>
</html>

If you load this file in a browser, you get the following page:

The URL displayed by the browser shows that the page was not served by a web server but loaded directly by the browser. We now want it to be available via the Tomcat web server.

Let’s return to the directory tree of the <tomcat> directory:

Web applications deployed on the Tomcat server are configured using XML files placed in the [<tomcat>\conf\Catalina\localhost] folder:

These XML files can be created manually because their structure is simple. Rather than taking this approach, we will use the web tools provided by Tomcat.

2.3.2. Tomcat Administration

On its login page at http://localhost:8080, the server provides links for administration:

The link [Tomcat Administration] allows us to configure the resources that Tomcat makes available to the web applications deployed within it, such as a database connection pool. Let’s follow the link:

The page that appears indicates that administering Tomcat 5.x requires a specific package called "admin." Let’s return to the Tomcat website:

Let’s download the zip file named [Administration Web Application] and then unzip it. Its contents are as follows:

The [admin] folder must be copied to [<tomcat>\server\webapps], where <tomcat> is the folder where Tomcat 5.x was installed:

The [localhost] folder contains a file named [admin.xml], which must be copied to [<tomcat>\conf\Catalina\localhost]:

Stop and then restart Tomcat if it was running. Then, using a browser, request the web server’s login page again:

Follow the link [Tomcat Administration]. You will see a login page:

Note: In fact, to get the page below, I first had to manually request url [http://localhost:8080/admin/index.jsp]. Only then did the link [Tomcat Administration] above work. I’m not sure if this was a procedural error on my part.

Here, you need to re-enter the information we provided during the Tomcat installation. In our case, we enter the admin / admin credentials. The [Login] button takes us to the following page:

This page allows the Tomcat administrator to define

data sources (Data Sources),
the information required for sending email (Mail Sessions),
environment data accessible to all applications (Environment Entries),
manage Tomcat users/administrators (Users),
manage user groups (Groups),
define roles (= what a user can and cannot do),
define the characteristics of web applications deployed by the server (Catalina Service)

Follow the link [Roles] above:

A role allows you to define what a user or group of users can or cannot do. Certain permissions are associated with a role. Each user is assigned one or more roles and has the permissions associated with them. The role [manager] below grants the right to manage web applications deployed in Tomcat (deployment, start, stop, unload). We will create a user named [manager] and assign them the role [manager] to allow them to manage Tomcat applications. To do this, we follow the [Users] link on the administration page:

We see that a number of users already exist. We use the option [Create New User] to create a new user:

We give the user "manager" the password "manager" and assign them the "manager" role. We use the [Save] button to confirm this addition. The new user appears in the list of users:

This new user will be added to the [<tomcat>\conf\tomcat-users.xml] file:

whose content is as follows:

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="tomcat"/>
  <role rolename="role1"/>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="tomcat" password="tomcat" roles="tomcat"/>
  <user username="role1" password="tomcat" roles="role1"/>
  <user username="both" password="tomcat" roles="tomcat,role1"/>
  <user username="manager" password="manager" fullName="" roles="manager"/>
  <user username="admin" password="admin" roles="admin,manager"/>
</tomcat-users>

line 10: the user [manager] that was created

Another way to add users is to edit this file directly. This is the procedure to follow if, for example, you have forgotten the password for the admin or manager account.

2.3.3. Managing Deployed Web Applications

Now let’s return to the [http://localhost:8080] login page and follow the [Tomcat Manager] link:

This takes us to an authentication page. We log in as manager / manager, c.a.d. the user with the role [manager] that we just created. In fact, only a user with this role can use this link. On line 11 of [tomcat-users.xml], we see that the user [admin] also has the role [manager]. We could therefore also use the authentication [admin / admin].

We get a page listing the applications currently deployed in Tomcat:

We can add a new application using the forms at the bottom of the page:

Here, we want to deploy the sample application we built earlier within Tomcat. We do this as follows:

`Context Path`	/example	the name used to identify the web application to be deployed
`Directory URL`	C:\data\2005-2006\eclipse\dvp-eclipse-tomcat\example	the web application folder

To obtain the [C:\data\2005-2006\eclipse\dvp-eclipse-tomcat\exemple\vues\exemple.html] file, we will ask Tomcat for URL [http://localhost:8080/exemple/vues/exemple.html]. The context is therefore used to name the root of the deployed web application tree. We use the [Deploy] button to deploy the application. If everything goes well, we get the following response page:

and the new application appears in the list of deployed applications:

Let’s comment out the /example context line above:

`/example`	link to [Deploy]://localhost:8080/example
`Start`	starts the application
`Stop`	stops the application
`Reload`	allows you to reload the application. This is necessary, for example, when you have added, modified, or deleted certain classes in the application.
`Undeploy`	deletes the [/exemple] context. The application disappears from the list of available applications.

Now that our /example application is deployed, we can run some tests. We request the [exemple.html] page via the url [http://localhost:8080/exemple/vues/exemple.html]:

Another way to deploy a web application on the Tomcat server is to provide the information we entered via the web interface in a [contexte] file.xml is placed in the [<tomcat>\conf\Catalina\localhost] folder, where [contexte] is the name of the web application.

Let’s go back to the Tomcat administration interface:

Let’s delete the [/exemple] application along with its link [Undeploy]:

The [/exemple] application is no longer part of the list of active applications. Now let’s define the following [exemple.xml] file:

1 2	`<Context docBase="C:/data/2005-2006/eclipse/dvp-eclipse-tomcat/exemple"> </Context>`

The XML file consists of a single <Context> tag, whose docBase attribute defines the folder containing the web application to be deployed. Let’s place this file in <tomcat>\conf\Catalina\localhost:

Stop and restart Tomcat if necessary, then view the list of active applications using the Tomcat administrator:

The [/exemple] application is indeed present. Let’s request the url using a browser:

[http://localhost:8080/exemple/vues/exemple.html]:

A web application deployed in this way can be removed from the list of deployed applications, in the same way as before, using the link [Undeploy]:

In this case, the file [exemple.xml] is automatically removed from the [<tomcat>\conf\Catalina\localhost] folder.

Finally, to deploy a web application within Tomcat, you can also define its context in the [<tomcat>\conf\server.xml] file. We will not elaborate on this point here.

2.3.4. Web application with a home page

When we request url from [http://localhost:8080/exemple/], we get the following response:

This result depends on the Tomcat configuration. With previous versions, we would have received the contents of the physical [/exemple] application directory. It is a good thing that Tomcat now prevents this display by default.

We can configure the system so that, when the context is requested, a so-called home page is displayed. To do this, we create a file named [web.xml] and place it in the <example>\WEB-INF folder, where <example> is the physical directory of the [/exemple] web application. This file is as follows:

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
    version="2.4">

  <display-name>Application Exemple</display-name>
  <description>Application web minimale</description>
    <welcome-file-list>
        <welcome-file>/vues/exemple.html</welcome-file>
    </welcome-file-list>    
</web-app>

lines 2-5: the root <web-app> tag with attributes copied and pasted from the [web.xml] file in the [/admin] application in Tomcat (<tomcat>/server/webapps/admin/WEB-INF/web.xml).
Line 7: the display name of the web application. This is a freely chosen name with fewer constraints than the application context name. For example, you can include spaces, which is not possible with the context name. This name is displayed, for example, by the Tomcat administrator:

line 8: description of the web application. This text can then be retrieved programmatically.
Lines 9–11: the list of welcome files. The <welcome-file-list> tag is used to define the list of views to be presented when a client requests the application context. There can be multiple views. The first one found is presented to the client. Here we have only one: [/vues/exemple.html]. Thus, when a client requests url or [/exemple], it will actually be url or [/exemple/vues/exemple.html] that is delivered to them.

Let’s save this [web.xml] file in <example>\WEB-INF:

If Tomcat is still running, you can force it to reload the [/exemple] web application using the [Recharger] link:

During this "reload" operation, Tomcat re-reads the [web.xml] file contained within [<exemple>\WEB-INF] if it exists. This will be the case here. If Tomcat was stopped, restart it.

Using a browser, let’s request the URL and [http://localhost:8080/exemple/] files:

The host file mechanism worked.

2.4. Installing Eclipse

Eclipse is a multi-language development environment. It is widely used in Java development. It is an extensible tool through the addition of tools called plugins. There are a large number of plugins, and this is what makes Eclipse so powerful.

Eclipse is available at url [http://www.eclipse.org/downloads/]:

We want to use Eclipse for Java web development. There are a number of plugins available for this purpose. They help verify the syntax of JSP pages, XML files, ... and allow you to test a web application within Eclipse. We will use one of these plugins, called the Web Tools Package (WTP). The standard procedure for installing Eclipse is as follows:

Install Eclipse
install the plugins you need

The WTP plugin itself requires other plugins, which makes its installation quite complex. Therefore, the Eclipse website offers a package that includes the Eclipse development platform and the WTP plugin along with all the other plugins it requires. This package is available on the Eclipse website (May 2006) at url [http://download.eclipse.org/webtools/downloads/]:

Follow the link above:

We download the [wtp] package using the link above. The resulting zip file contains the following:

Simply extract this content into a folder. We will refer to this folder as <eclipse> from now on. Its contents are as follows:

[eclipse.exe] is the executable file, and [eclipse.ini] is its configuration file. Let’s look at the contents of the configuration file:

1
2
3

-vmargs
-Xms40m
-Xmx256m

These arguments are used when launching Eclipse as follows:

eclipse.exe -vmargs -Xms40m -Xmx256m

You can achieve the same result as with the .ini file by creating a shortcut that launches Eclipse with these same arguments. Let’s explain them:

-vmargs: indicates that the following arguments are intended for the Java Virtual Machine that will run Eclipse. Indeed, Eclipse is a Java application.
-Xms40m: ?
-Xmx256m: sets the memory size in MB allocated to the Java Virtual Machine (JVM) that runs Eclipse. By default, this size is 256 MB, as shown here. If the machine allows it, 512 MB is preferable.

These arguments are passed to JVM, which will run Eclipse. JVM is represented by a file named [java.exe] or [javaw.exe]. How is this file located? In fact, it is located in different ways:

in the PATH file within the OS directory
in the <JAVA_HOME>/jre/bin folder, where JAVA_HOME is a system variable defining the root folder of a JDK.
to a location passed as an argument to Eclipse in the form -vm <path>\javaw.exe

This last solution is preferable because the other two are subject to the vagaries of subsequent application installations, which may either change the PATH of the OS or change the JAVA_HOME variable.

We therefore create the following shortcut:

`target`	<eclipse>\eclipse.exe -vm "C:\Program Files\Java\jre1.5.0_06\bin\javaw.exe" -vmargs -Xms40m -Xmx512m
`Start in`	Eclipse installation folder <eclipse>

Once this is done, launch Eclipse using this shortcut. A dialog box will appear:

A [workspace] is a workspace. Let’s accept the default values provided. By default, Eclipse projects will be created in the <workspace> folder specified in this dialog box. There is a way to override this behavior. This is what we will do systematically. Therefore, the response given in this dialog box is not important.

Once this step is complete, the Eclipse development environment is displayed:

We close the [Welcome] view as suggested above:

Before creating a Java project, we will configure Eclipse to specify the JDK to be used for compiling Java projects. To do this, we select the option [Window / Preferences / Java / Installed JREs ]:

Normally, the JRE (Java Runtime Environment) that was used to launch Eclipse itself should be present in the list of JRE. This will normally be the only one. You can add JRE entries using the [Add] button. You must then specify the root of the JRE. The [Search] button, on the other hand, will launch a search for JREs on the disk. This is a good way to keep track of the JREs files that you install and then forget to uninstall when upgrading to a newer version. Above, the checked JRE is the one that will be used to compile and run Java projects.

The JRE that will be used in our examples is the one installed in Section 2.1 and also used to launch Eclipse. Double-clicking on it opens its properties:

Now, let’s create a Java project named [File / New / Project]:

Select [Java Project], then [Next] ->

In [2], we specify an empty folder where the Java project will be installed. In [1], we name the project. It does not have to bear the same name as its folder, as the example above might suggest. Once this is done, we use the [Finish] button to finish the creation wizard. This amounts to accepting the default values proposed by the following pages of the wizard.

We now have a Java project skeleton:

Right-click on the [test1] project to create a Java class:

in [1], the folder where the class will be created. By default, Eclipse suggests the current project folder.
in [2], the package in which the class will be placed
In [3], the name of the class
in [4], we specify that the static method [main] should be generated

We confirm the wizard with [Finish]. The project is then enhanced with a class:

Eclipse has generated the class skeleton. This can be accessed by double-clicking on [Test1.java] above:

We modify the code above as follows:

We run the program [Test1.java]: [clic droit sur Test1.java -> Run As -> Java Application]

The result of the execution is displayed in the [Console] window:

2.5. Tomcat - Eclipse Integration

To work with Tomcat while remaining within Eclipse, we need to declare this server in the Eclipse configuration. To do this, we use option [File / New / Other]. We then see the following wizard:

We choose to create a new server. We select the [Server] icon above and then click [Next]:

Adding the server results in a folder appearing in the Eclipse Project Explorer:

To manage Tomcat from Eclipse, we open the view named [Servers] with option and [Window -> Show View -> Other -> Server]:

Select [OK]. The [Servers] view then appears:

All registered servers appear in this view, in this case the Tomcat 5.5 server we just registered. Right-clicking on it gives access to the commands to start, stop, and restart the server:

Above, we are starting the server. During startup, a number of logs are written to the [Console] view:

11 mai 2006 15:31:16 org.apache.catalina.core.AprLifecycleListener lifecycleEvent
INFO: The Apache Tomcat Native library which allows optimal performance in production environments was not found on the java.library.path: C:\Program Files\Java\jre1.5.0_06\bin;.;C:\WINDOWS\system32;...
11 mai 2006 15:31:16 org.apache.coyote.http11.Http11BaseProtocol init
INFO: Initialisation de Coyote HTTP/1.1 sur http-8080
...
INFO: Server startup in 1641 ms

Understanding these logs takes some getting used to. We won’t dwell on them for now. However, it is important to verify that they do not indicate any context loading errors. When launched, the Tomcat/Eclipse server attempts to load the context of the applications it manages. Loading an application’s context involves processing its [web.xml] file and loading one or more classes that initialize it. Several types of errors can occur:

The [web.xml] file contains syntax errors. This is the most common error. It is recommended to use a tool capable of validating a XML document during its creation.
Some classes to be loaded were not found. They are searched for in [WEB-INF/classes] and [WEB-INF/lib]. You should generally verify the presence of the necessary classes and the spelling of those declared in the [web.xml] file.

The server launched from Eclipse does not have the same configuration as the one installed in section 2.2, page 5. To verify this, request url and [http://localhost:8080] using a browser:

This response does not indicate that the server is not working, but rather that the resource / requested from it is not available. With the Tomcat server integrated into Eclipse, these resources will be web projects. We will see this later. For now, let’s stop Tomcat:

The previous operating mode can be changed. Let’s return to the [Servers] view and double-click on the Tomcat server to access its properties:

The [1] checkbox is responsible for the previous behavior. When checked, web applications developed in Eclipse are not declared in the configuration files of the associated Tomcat server but in separate configuration files. As a result, the default applications defined within the Tomcat server—[admin] and [manager], which are two useful applications—are not available. Therefore, we will uncheck [1] and restart Tomcat:

Once this is done, let’s request url and [http://localhost:8080] using a browser:

We see the behavior described in section 2.3.3, page 15.

In our previous examples, we used a browser outside of Eclipse. We can also use a browser within Eclipse:

Above, we select the internal browser. To launch it from Eclipse, you can use the following icon:

The browser that actually launches will be the one selected by the option [Window -> Web Browser]. Here, we get the internal browser:

If necessary, launch Tomcat from Eclipse and request the url [http://localhost:8080] in [1]:

Follow the link [Tomcat Manager]:

The [login / mot de passe] pair required to access the [manager] application is requested. Based on the Tomcat configuration we set up earlier, you can enter [admin / admin] or [manager / manager]. This will display the list of deployed applications:

We see the [personne] application that we created. The associated [Recharger] link will be useful later on.