Download
FAQ
History
PrevHomeNext API
Search
Feedback
Divider

Creating a Simple Web Application

The example application contains the following pieces:

For this example, we will create a top-level project source directory named /gs. All of the files in this example application are created from this root directory.

Creating the JavaBeans Component

The ConverterBean component used in the example application is used in conjunction with a JSP page. The resulting application runs in a Web browser and enables you to convert American dollars to Yen, and convert Yen to Euros. The source code for the ConverterBean component is in <INSTALL>/jwstutorial13/examples/gs/src/converterApp/ConverterBean.java.

The ConverterBean class for this example contains two properties, yenAmount and euroAmount, and the set and get methods for these properties. The source code for ConverterBean follows.

//ConverterBean.java
package converterApp;

import java.math.*;

public class ConverterBean{

  private BigDecimal yenRate;
  private BigDecimal euroRate;
  private BigDecimal yenAmount;
  private BigDecimal euroAmount; 

  /** Creates new ConverterBean */
  public ConverterBean() {
    yenRate = new BigDecimal ("110.97");
    euroRate = new BigDecimal (".0078");
    yenAmount = new BigDecimal("0.0");
    euroAmount = new BigDecimal("0.0");
  }
  public BigDecimal getYenAmount () {
    return yenAmount;
  }
  public void setYenAmount(BigDecimal amount) {
    yenAmount = amount.multiply(yenRate);
    yenAmount =  yenAmount.setScale(2,BigDecimal.ROUND_UP);
  }
  public BigDecimal getEuroAmount () {
    return euroAmount;
  }
  public void setEuroAmount (BigDecimal amount) {
    euroAmount = amount.multiply(euroRate);
    euroAmount = 
      euroAmount.setScale(2,BigDecimal.ROUND_UP);
  }
} 

Creating a Web Client

The Web client is contained in the JSP page <INSTALL>/jwstutorial13/examples/gs/web/index.jsp. A JSP page is a text-based document that contains both static and dynamic content. The static content is the template data that can be expressed in any text-based format, such as HTML, WML, or XML. JSP elements construct the dynamic content.

The JSP page is used to create the form that will appear in the Web browser when the application client is running. This JSP page is a typical mixture of static HTML markup and JSP elements. This example has been updated for this release to use JSP 2.0, JSTL, and expression language expressions instead of scripting expressions. For more information on JSP syntax, see Chapter 16, "JavaServer Pages Technology".

Here is the source code for index.jsp:

<%-- index.jsp --%>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" 
prefix="c" %>
<%@ taglib uri="http://java.sun.com/jsp/jstl/functions"
prefix="fn" %>

<%@ page import="converterApp.ConverterBean" %>
<%@ page contentType="text/html" %>

<html>
<head>
   <title>Currency Conversion Application</title>
</head>
<body bgcolor="white">
<jsp:useBean id="converter"
class="converterApp.ConverterBean"/> 

<h1><FONT FACE="ARIAL" SIZE=12>Currency Conversion 
Application JSP page</FONT></h1>
<hr>
<p><FONT FACE="ARIAL" SIZE=10>Enter an amount to convert:</p></
FONT>
<form method="get">
   <input type="text" name="amount" size="25">
   <br>
   <p>
   <input type="submit" value="Submit">
   <input type="reset" value="Reset">
</form>

<c:if test="${!empty param.amount && 
fn:length(param.amount) > 0}" >
   <p><FONT FACE="ARIAL" SIZE=10>${param.amount} dollars are
   <jsp:setProperty name="converter" property="yenAmount"
   value="${param.amount}" />
   ${converter.yenAmount} Yen. 
   <p>${param.amount} Yen are
   <jsp:setProperty name="converter" property="euroAmount"
   value="${param.amount}" />
   ${converter.euroAmount} Euro. </FONT>
</c:if>
</body>
</html> 

Creating the Build Properties File

In this release of the Java WSDP, this tutorial uses two build properties files. One of the build properties files contains properties that will be used by the Ant targets for many of the example applications included with this tutorial. Rather than reproduce this information in every application, a common build.properties file is used. This file can be found at <INSTALL>/jwstutorial13/examples/common/build.properties. As discussed in Modifying the Build Properties File, you must edit this file and provide information regarding your user name and password and the directory from which you've installed the tutorial.

The other build.properties file, <INSTALL>/jwstutorial13/examples/gs/build.properties, is in the application directory. This file contains properties specific to this application that will be passed to the Ant targets. This file does not require modification. The build.properties file for the Converter application looks like this:

context.path=${example}
example.path=${tutorial.install}/examples/${example}
build=${tutorial.install}/examples/${example}/build 

The variable example is defined in the build.xml file. The variable tutorial.install is defined in the common/build.properties file.

Creating the Build File

This release of the Java Web Services Developer Pack includes Ant, a make tool that is portable across platforms, and which is developed by the Apache Software Foundation (http://apache.org). Documentation for the Ant tool can be found at http://ant.apache.org/manual/index.html.

The version of Ant shipped with the Java WSDP sets the jwsdp.home environment variable, which is required by the example build files. To ensure that you use this version of Ant, rather than other installations, make sure you add <JWSDP_HOME>/apache-ant/bin/ to the front of your PATH.

This example uses the Ant tool to manage the compilation of our Java source code files and creation of the deployment hierarchy. Ant operates under the control of a build file, normally called build.xml, that defines the processing steps required. This file is stored in the top-level directory of your source code hierarchy.

Like a Makefile, the build.xml file provides several targets that support optional development activities (such as erasing the deployment home directory so you can build your project from scratch). This build file includes targets for compiling the application, installing the application on a running server, reloading the modified application onto the running server, and removing old copies of the application to regenerate their content.

When we use the build.xml file in this example application to compile the source files, a temporary /build directory is created beneath the root. This directory contains an exact image of the binary distribution for your Web application. This directory is deleted and recreated as needed during development, so don't edit the files in this directory.

Many of the example applications shipped with this release of the Java WSDP Tutorial use the same Ant targets. To simplify development, each application has its own build.xml file in its project source directory. The build.xml file in the project source directory is fairly simple. It sets some properties specific to this example and includes only one target, which is the target for building the Java source code and copying it to the correct location for deployment. It also tells Ant where to find the properties used in the build files and points to other files that contain common Ant targets.

The <INSTALL>/jwstutorial13/examples/gs/build.xml file looks like this:

<!DOCTYPE project [
  <!ENTITY targets SYSTEM "../common/targets.xml">
  <!ENTITY webtargets SYSTEM "../web/common/targets.xml">
]>

<project name="gs-example" default="build" basedir=".">
  <target name="init">
    <tstamp/>
  </target>

  <!-- Configure the context path for this application -->
    <property name="example" value="gs" />

  <!-- Configure properties -->
    <property file="../common/build.properties"/>
    <property file="build.properties"/>

  &targets;
  &webtargets;

  <!-- Application-Specific Targets -->

  <target name="build" depends="copy" 
      description="Compile app Java files and copy HTML
      and JSP pages" >
    <javac srcdir="src" destdir="${build}/WEB-INF/classes">
      <include name="**/*.java" />
      <classpath refid="classpath"/>
    </javac>
    <copy todir="${build}/WEB-INF/lib">
      <fileset dir="${jwsdp.home}/jstl/lib">
      <include name="*.jar" />
      </fileset>
    </copy>
  </target>

</project> 

To see the common build targets, you can do either of these options:

  1. Look at the files in <INSTALL>/jwstutorial13/examples/common/targets.xml and <INSTALL>/jwstutorial13/examples/web/common/targets.xml.
  2. In the project directory, run the command ant -projecthelp.

Creating the Deployment Descriptor

Certain aspects of Web application behavior can be configured when the application is installed or deployed to the Web container. The configuration information is maintained in a text file in XML format called a Web application deployment descriptor. A Web application deployment descriptor (DD) must conform to the schema described in the Java Servlet specification. For this simple application, the deployment descriptor, <INSTALL>/jwstutorial13/examples/gs/web/WEB-INF/web.xml, simply includes a description of the application. For more information on deployment descriptors, refer to Configuring Web Applications and Security in the Web-Tier.

The deployment descriptor for this application looks like this:

<?xml version="1.0" ?>
<web-app version="2.4" 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">

<!-- General description of Currency Converter Application -->
<description>
  This is the Java WSDP 1.3 release of the Getting Started
  with Tomcat application, based on JSP pages technology. 
  To run this application, read the instructions in the Getting
  Started with Tomcat chapter of the Java WSDP Tutorial v.1.3,
  which explains which enviroment variables need to be set,
  which properties need to be set, which Ant commands to run,
  and how to run the application in a web browser.  When the
  application is loaded, enter an amount to be converted, then
  click the Submit button. The resulting conversion displays
  below the button.
</description>
</web-app> 

Building the Example Application

To compile the JavaBeans component (ConverterBean.java), copy the generated class file to the appropriate location for deployment as an unpacked WAR, and copy the other files needed for deployment to their appropriate locations, we will use the Ant tool and run the build target in the build.xml file. The steps for doing this follow.

  1. In a terminal window or command prompt, change to the <INSTALL>/jwstutorial13/examples/gs/ directory.
  2. Type the following command to build the Java files (this and the following steps that use Ant assume that you have the executable for Ant in your path: if not, you will need to provide the fully-qualified path to the Ant executable):
  3. ant build

If successful, the following message will echo to your screen:

Buildfile: build.xml
init:
prepare:
  [mkdir] Created dir:
      <INSTALL>/jwstutorial13/examples/gs/build
  [mkdir] Created dir:
  <INSTALL>/jwstutorial13/examples/gs/build/WEB-INF
  [mkdir] Created dir:
    <INSTALL>/jwstutorial13/examples/gs/build
    /WEB-INF/classes
  [mkdir] Created dir:
    <INSTALL>/jwstutorial13/examples/gs/build/WEB-INF/lib
  [mkdir] Created dir:
    <INSTALL>/jwstutorial13/examples/gs/build/WEB-INF/tags

copy:
  [copy] Copying 1 file to
    <INSTALL>/jwstutorial13/examples/gs/build
  [copy] Copying 1 file to
    <INSTALL>/jwstutorial13/examples/gs/build/WEB-INF

build:
  [javac] Compiling 1 source file to
    <INSTALL>/jwstutorial13/examples/gs/build/WEB-INF/
  classes
  [copy] Copying 2 files to <INSTALL>/jwstutorial13/
    examples/gs/build/WEB-INF/lib


BUILD SUCCESSFUL

As you can see from the message above, when we run the Ant build target, the following steps are performed:

Installing the Web Application

A Web application is defined as a hierarchy of directories and files in a standard layout. In this example, the hierarchy is accessed in an unpacked form, where each directory and file exists in the file system separately. This section discusses deploying your application using the Ant targets discussed in Creating the Build File.

A context is a name that gets mapped to the document root of a Web application. The context of the Getting Started application is /gs. The request URL http://localhost:8080/gs/index.jsp retrieves the file index.jsp from the document root. To install an application to Tomcat, you notify Tomcat that a new context is available.

You install an application at a specified context and notify Tomcat of this new context with the Ant install task. Read Installing Web Applications for more information on this procedure. The Ant install task does not require Tomcat to be restarted, but an installed application is also not remembered after Tomcat is restarted. To permanently deploy an application, use the Ant deploy task as discussed in Deploying Web Applications.

In this example, we are installing the application into an unpacked directory. The Ant install task used by this application can be found in <INSTALL>/jwstutorial13/examples/common/targets.xml, and looks like this:

<target name="install" description="Install web application"
    depends="build">
  <install url="${url}" username="${username}"
    password="${password}" path="/${context.path}"
    war="file:${build}"/>
</target> 

Starting Tomcat

You must start Tomcat before you can install this application using the Ant tool. To start Tomcat, select the method that is appropriate for your platform:


Note: The startup script for Tomcat can take several minutes to complete. To verify that Tomcat is running, point your browser to http://localhost:8080. When the Java WSDP index page displays, you may continue. If the index page does not load immediately, wait up to several minutes and then retry. If, after several minutes, the index page does not display, refer to the troubleshooting tips in "Unable to Locate the Server localhost:8080" Error.


Documentation for Tomcat can be found at http://jakarta.apache.org/tomcat/tomcat-5.0-doc/index.html. Information on errors commonly occurring during Tomcat startup, see Errors Starting Tomcat.

Installing the Application

The Ant install task tells the manager running at the location specified by the url attribute to install an application at the context specified by the path attribute and the location containing the Web application files specified with the war attribute. The value of the war attribute in this example is an unpacked directory. To install this application, follow these steps:

  1. In a terminal window or command prompt, change to the <INSTALL>/jwstutorial13/examples/gs directory.
  2. Type the following command to install the application on Tomcat (this step assumes that you have the executable for Ant in your path: if not, you will need to provide the fully-qualified path to the Ant executable):
  3. ant install

    If the installation is successful, the following message will echo to your screen:

    [install] OK - Deployed application at context path /gs

Running the Getting Started Application

A Web application is executed when a Web browser references a URL that is mapped to a component. Once you have installed or deployed the /gs application using the context /gs, you can run it by pointing a browser at the URL:

http://localhost:8080/gs 

The examples in this tutorial assume that you are running the default implementation of Tomcat and thus the server host and port are localhost:8080. The host localhost refers to the machine on which Tomcat is running. The localhost in this example assumes you are running the example on your local machine as part of the development process. The 8080 in this example is the port where Tomcat was installed during installation. If you are using a different server or port, modify this value accordingly.

The application should display in your Web browser. If there are any errors, refer to Common Problems and Their Solutions. To test the application,

  1. Enter 1000 in the "Enter an amount to convert" field.
  2. Click Submit.

Figure 3-1 shows the running application.

Image of the ConverterBean Web Client.  This image shows the title of the page, and displays a box for the user to enter a value.  When Submit is clicked, this value is translated to Yen and Euro and the resulting value is displayed on the screen.

Figure 3-1 ConverterBean Web Client

Shutting Down Tomcat

When you are finished testing and developing your application, you should shut down Tomcat. Shut down Tomcat by one of the following methods, depending on which platform you are running:

Divider
Download
FAQ
History
PrevHomeNext API
Search
Feedback
Divider

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.