Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
Setting Up
Note: Before you start developing the example applications, follow the instructions in About the Examples, then continue with this section.
Getting the Example Code
Once you've installed the tutorial, you'll find the source code for this example in
<INSTALL>
/jwstutorial13/examples/gs/
, a directory that is created when you unzip the tutorial bundle. If you are viewing this tutorial online, you can download the tutorial bundle from:
http://java.sun.com/webservices/downloads/webservicestutorial.html
The example application contains a JavaBeans component, a Web component, a file to build and run the application, a build properties file, and a deployment descriptor. 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.Organizing Web Applications
In this example application, the source code directories are organized in a way that reflects good programming practices for Web services programming. This method of organization is described in more detail in the document at
http://jakarta.apache.org/tomcat/tomcat-5.0-doc/appdev/deployment.html
. Basically, the document explains that it is useful to examine the runtime organization of a Web application when creating the application. A Web application is defined as a hierarchy of directories and files in a standard layout. Such a hierarchy can be accessed in its unpacked form, where each directory and file exists in the file system separately, or in a packed form known as a Web Application Archive, or WAR file. The former format is more useful during development, while the latter is used when you distribute your application.To facilitate creation of a WAR file in the required format, it is convenient to arrange the files that Tomcat uses when executing your application in the same organization as required by the WAR format itself. In the example application,
<INSTALL>
/jwstutorial13/examples/gs/
is the root directory for the source code for this application.The application consists of the following files that are either in the
/gs
directory or a subdirectory of/gs
.
src/converterApp/ConverterBean.java
--The JavaBeans component that contains theget
andset
methods for theyenAmount
andeuroAmount
properties used to convert U.S. dollars to Yen and convert Yen to Euros.web/index.jsp
--The Web client, which is a JSP page that contains components that enable you to enter the value to be converted, click the button to submit the value, and display the result of the conversion.web/WEB-INF/web.xml
--The deployment descriptor for this application. In this simple example, it contains a description of the example application.build.xml
--The build file that theAnt
tool uses to build and deploy the Web application. This build file calls targets common to many of the example applications from a build file named<INSTALL>
/jwstutorial13/examples/common/targets.xml
.build.properties
--The file that contains properties unique to this application. There is also an<INSTALL>
/jwstutorial13/examples/common/build.properties
file that contains properties unique to your installation.A key recommendation of the Tomcat Application Developer's Manual is to separate the directory hierarchy containing the source code from the directory hierarchy containing the deployable application. Maintaining this separation has the following advantages:
- The contents of the source directories can be more easily administered, moved, and backed up if the executable version of the application is not intermixed.
- Source code control is easier to manage on directories that contain only source files.
- The files that make up an installable distribution of your application are much easier to select when the deployment hierarchy is separate.
As discussed in Creating the Build File, the
Ant
development tool makes the creation and processing of this type of directory hierarchies relatively simple. In this example, when we run theant
build
target, the target creates a directory structure that is separate from the source code and is organized in the directory hierarchy required by Tomcat for unpacked applications. In this example, thebuild
directory contains the following files and directories:The rest of this document shows how this example application is created, built, deployed, and run.
Note: The sections Setting the PATH Variable and Modifying the Build Properties File discuss getting your environment setup for running this example. Whether you want to work through creating the example or just run the existing example application, you must follow the steps in these sections first.
Setting the PATH Variable
Most of the tutorial examples are distributed with a configuration file for
Ant
, a portable build tool included with the Java WSDP. The version ofAnt
shipped with the Java WSDP sets thejwsdp.home
environment variable to the location of your Java WSDP installation. This variable is used by the example build files.It is very important that you add the
bin
directories of the Java WSDP, J2SE SDK, andAnt
installations to the front of yourPATH
environment variable so that the Java WSDP startup scripts forAnt
and Tomcat override other installations. The path to theAnt
installation that ships with the Java WSDP is<JWSDP_HOME>
/apache-ant/bin/
.Modifying the Build Properties File
In order to invoke many of the
Ant
tasks, you need to edit a file namedbuild.properties
in the<INSTALL>
/jwstutorial13/examples/common/
directory.The
build.properties
file must contain a user name and password in plain text format that matches either the user name and password set up during installation or a name added subsequent to installation that is assigned the role ofmanager
. In case you've forgotten, the user name and password that you entered during installation of the Java WSDP are stored in<JWSDP_HOME>
/conf/tomcat-users.xml
. Information on adding users is provided in Managing Roles and Users.The
tomcat-users.xml
file, which is created by the installer, looks like this:<?xml version='1.0'?> <tomcat-users> <role rolename="manager"/> <role rolename="admin"/> <user username="<your_username>
" password="<your_password>
" roles="admin,manager"/> </tomcat-users>For security purposes, the Tomcat Manager application verifies that you (as defined in the
build.properties
file) are a user who is authorized to install and reload applications (as determined by the roles assigned to you intomcat-users.xml
) before granting you access to the server.In addition to specifying your user name and password in the
build.properties
file, you also need to specify the directory location where the tutorial is installed. Define the variabletutorial.home
by entering the fully-qualified path to the directory into which you installed the tutorial, for example,/home/your_name/jwsdp-1.3/docs
orc:/jwsdp-1.3/docs
. Note that the direction of the slash character is important in this file. The slash must be the "/" character for the build files to work properly. This is true on both the Windows and Unix platforms.You must edit the
build.properties
file to deploy any of the example applications onto Tomcat. Open the<INSTALL>
/jwstutorial13/examples/common/build.properties
file and modify the following lines:username=<your_username> password=<your_password> tutorial.home=<path_to_dir_into_which_tutorial_was_installed>If you are running on a different Web server and/or port, modify the default tutorial settings for those in this file as well.
Running the Application
Now that you've downloaded the application and gotten your environment set up for running the example application, this section gives you a quick overview of the steps needed to run the application. Each step is discussed in more detail on the pages referenced.
- Download the tutorial examples and set up your environment as discussed in Getting the Example Code, Setting the PATH Variable, and Modifying the Build Properties File.
- From a terminal window or command prompt, change to the root directory for this application, which is
<INSTALL>
/jwstutorial13/examples/gs/
(see Creating a Simple Web Application).- Compile the source files by typing the following at the terminal window or command prompt (see Building the Example Application):
ant build
Compile errors are listed in Compilation Errors.
- Start Tomcat. If you need help doing this, see Starting Tomcat. Tomcat startup errors are discussed in Errors Starting Tomcat.
- Install the Web application on Tomcat using
Ant
by typing the following at the terminal window or command prompt (see Installing the Web Application).
ant install
Installation and deployment errors are discussed in Installation and Deployment Errors.
- Start a Web browser. Enter the following URL to run the example application (see Running the Getting Started Application):
http://localhost:8080/gs
- Shutdown Tomcat. See Shutting Down Tomcat if you need assistance with this.
Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
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.