Download
FAQ
History 		HomeHomeNext 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>/jwstutorial12/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 ("138.78");
    euroRate = new BigDecimal (".0084");
    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>/jwstutorial12/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. For more information on JSP syntax, see Chapter 16.

Here is the source code for index.jsp: 

<%-- index.jsp --%>
<%@ page import="converterApp.ConverterBean,java.math.*" %>
<%@ page contentType="text/html; charset=ISO-8859-5" %>

<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 
</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>
<%
String amount = request.getParameter("amount");

if ( amount != null && amount.length() > 0 ) {

%>
<p><FONT FACE="ARIAL" SIZE=10><%= amount %> dollars are  

<jsp:setProperty name="converter" property="yenAmount" 
value="<%= new BigDecimal(amount)%>" />
<jsp:getProperty name="converter" property="yenAmount"  /> Yen. 

<p><%= amount %> Yen are

<jsp:setProperty name="converter" property="euroAmount" 
value="<%= new BigDecimal(amount)%>" />
<jsp:getProperty name="converter" property="euroAmount"  /> 
Euro. </FONT>

<% 
} 
%>

</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>/jwstutorial12/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>/jwstutorial12/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://www.apache.org). Documentation for the Ant tool can be found in the file index.html from the <JWSDP_HOME>/apache-ant/docs/ directory of your Java WSDP installation.

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>/jwstutorial12/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>
</target>

</project>

To see the common build targets, look at the files in <INSTALL>/jwstutorial12/examples/common/targets.xml and <INSTALL>/jwstutorial12/examples/web/common/targets.xml.

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>/jwstutorial12/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.

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 the Currency Converter Application
  -->
  <display-name>Currency Converter Application</display-name>
    <description>
    This is the Java WSDP 1.2 release of the Getting Started
    with Tomcat application, based on JSP pages technology.
    To run this application, you must first build and deploy
    this application, then enter http://localhost:8080/gs
    in a web browser.  When the application is loaded, enter
    an amount to be converted, then click the Submit button.
    he 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, change to the <INSTALL>/jwstutorial12/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>/jwstutorial12/examples/gs/build
  [mkdir] Created dir:
  <INSTALL>/jwstutorial12/examples/gs/build/WEB-INF
  [mkdir] Created dir:
    <INSTALL>/jwstutorial12/examples/gs/build
    /WEB-INF/classes
  [mkdir] Created dir:
    <INSTALL>/jwstutorial12/examples/gs/build/WEB-INF/lib
  [mkdir] Created dir:
    <INSTALL>/jwstutorial12/examples/gs/build/WEB-INF/tags

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

build:
  [javac] Compiling 1 source file to
    <INSTALL>/jwstutorial12/examples/gs/build/WEB-INF/classes

BUILD SUCCESSFUL

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

Deploying the 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.html retrieves the file index.html from the document root. To install an application to Tomcat, you notify Tomcat that a new context is available.

You notify Tomcat of a new context with the Ant install task. 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.

The Ant install task tells a Tomcat manager application to install an application at the context specified by the path attribute at the location containing the Web application files. Read Installing Web Applications for more information on this procedure.

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>/jwstutorial12/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 Tomcat splash screen displays, you may continue. If the splash screen does not load immediately, wait up to several minutes and then retry. If, after several minutes, the Tomcat splash screen does not display, refer to the troubleshooting tips in "Unable to Locate the Server localhost:8080" Error.

Documentation for Tomcat can be found at <JWSDP_HOME>/docs/tomcat/index.html.

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, change to the <INSTALL>/jwstutorial12/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 - Installed 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 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 application server host and port is localhost:8080. The host localhost refers to the machine on which Tomcat is running.

The application should display in your Web browser. If there are any errors, refer to Common Problems and Their Solutions. If there is a blank screen, you may need to set the encoding on your browser differently. Here's how to do that:

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 		HomeHomeNext 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.