JavaServerTM Faces Technology 1.1_01 FCS
Installation Instructions



Revised: 20040513

For updates to these instructions, please see the online version, JavaServer Faces Technology 1.1_01 Installation Instructions.

Please refer to the Release Notes, located in your download bundle, for information regarding supported operating systems, required software, limitations and bugs.

Table of Contents:

Using JavaServer Faces Technology with the Sun JavaTM System Application Server, Platform Edition 8

Using JavaServer Faces Technology with the JavaTM Web Services Developer Pack (Java WSDP)

Using JavaServer Faces Technology with Other Containers


Installing JavaServer Faces Technology in the Application Server

  1. Download the Application Server.
  2. Follow the installation instructions provided with the Application Server.
  3. Download the JavaServer Faces Technology 1.1_01 ZIP file.
  4. Archive or remove the the old JavaServer Faces Technology release JAR files located in the lib directory of your Application Server installation. These JAR files are jsf-api.jar and jsf-impl.jar.
  5. Unzip the JavaServer Faces Technology 1.1_01 ZIP file and copy the jsf-api.jar and jsf-impl.jar files from the lib directory of your JavaServer Faces Technology FCS 1.1_01 installation to the lib directory of your Application Server installation. If you have paths to these files already set in your environment, make sure to update the paths to point to the new JAR files in the lib directory of the Application Server installation.

Running the Pre-packaged Example WAR Files in the Application Server

The samples directory of your JavaServer Faces Technology FCS 1.1_01 installation contains a set of WAR files that were packaged from the example source, which is provided in the subdirectories of the samples directory. To run the pre-packaged WAR files, you need to deploy them to the server. The Application Server gives you three ways to deploy:
To deploy using autodeploy, start the server and then simply copy the WAR file to the domains/domain1/autodeploy directory of your Application Server installation.

To deploy using asadmin, start the server and run this command:

	asadmin deploy <full path to the WAR file>

You can also deploy a pre-packaged WAR file using deploytool, a tool that also allows you to package an application WAR file. To deploy a pre-packaged WAR file using deploytool:

  1. Start the server.
  2. Launch deploytool. (See the Quick Start Guide located in the docs directory of your Application Server installation for instructions on launching deploytool.)
  3. Go to the File Menu, select Open. Browse for and open your WAR file.
  4. From the tree, select your WAR file.
  5. On the General tabbed-pane for this WAR file, enter a context root in the Context Root field. For example, you could enter /guessNumber as the context root for the guessNumber example.
  6. Go to the Tools menu and select Deploy.

See the J2EE Tutorial for information on using deploytool to package Web applications.

When the server has finished deploying the application, you can run it by specifing the name of the WAR file in your Web browser:

http://localhost:8080/<EXAMPLE NAME>/
For example, to run cardemo, specify this URL in your Web browser:
http://localhost:8080/jsf-cardemo/
If you used deploytool to deploy the example, use the context root that you gave it in the URL. For example, if you entered the context root /guessNumber, enter the following in your Web browser:
http://localhost:8080/guessNumber

Building and Running the Examples Using the Application Server

To build one of the samples, you need to run its build.xml file using the asant tool, which is a make tool included with the Application Server.

When asant builds the application, it copies files to a temporary build directory. This directory contains an exact image of the binary distribution for your JavaServer Faces application. When asant builds the WAR file, it packages all the files from the build directory into the WAR file while preserving the directory structure contained in the build directory

To build the samples you first need to enter some paths in the build.properties file:

  1. Make sure you have the necessary preconditions as listed in the ReleaseNotes.
  2. Copy build.properties.sample to build.properties.
  3. In build.properties, set the tomcat.home property to the location of your Application Server installation.
  4. Set the other properties as shown here:
      	jsf-api.jar=${tomcat.home}/lib/jsf-api.jar
    jsf-impl.jar=${tomcat.home}/lib/jsf-impl.jar
    commons-logging.jar=${tomcat.home}/lib/appserv-rt.jar
    commons-digester.jar=${tomcat.home}/lib/appserv-rt.jar
    commons-beanutils.jar=${tomcat.home}/lib/appserv-rt.jar
    commons-collections.jar=${tomcat.home}/lib/appserv-rt.jar
    jstl.jar=${tomcat.home}/lib/appserv-jstl.jar
    standard.jar=${tomcat.home}/lib/appserv-jstl.jar
    servlet.jar=${tomcat.home}/lib/j2ee.jar
    jsp.jar=${tomcat.home}/lib/j2ee.jar

To build a sample WAR file and deploy it:

  1. Go to the directory of the sample you want to build.
  2. At the command line, run the default target:
    asant
  3. The WAR file of the sample you just built will overwrite the corresponding pre-packaged WAR file in the samples directory of your JavaServer Faces Technology installation
  4. Follow the instructions in Running the Pre-Packaged Example WAR Files in the Application Server to run the application WAR file.

Installing JavaServer Faces Technology in Java WSDP

  1. Download the Java WSDP.
  2. Follow the Installation Instructions for the Java WSDP.
  3. Update your path so that JWSDP_HOME points to the location of your Java WSDP installation.
  4. Download the JavaServer Faces 1.1_01 ZIP file.
  5. Archive or remove the the old JavaServer Faces release located in JWSDP_HOME/jsf
  6. Remove any serialized JavaServer Faces application files from the work directory of Java WSDP.
  7. Unzip the JavaServer Faces 1.1_01 ZIP file into JWSDP_HOME and rename the base directory to "jsf"

Running the Examples in the Java WSDP

To run one of the samples,
  1. Go to the  JWSDP_HOME/bin directory.

  2. In a terminal window start the web server.

    If you are on a Unix platform, invoke the following command to start the web server:

    catalina.sh run 

    If you are running Windows, invoke the following command to start the web server:

    catalina run


  3. Wait for the copyright license to display in your terminal window.

  4. Launch your browser.

  5. You can find a page containing links to the JavaServer Faces sample programs on your default server port:
http://localhost:8080

You can also run each sample individually by specifing the name of the WAR file in your web browser:

http://localhost:8080/<EXAMPLE NAME>/ 


For example, this is the address you enter if you are running the cardemo:

http://localhost:8080/jsf-cardemo/

Please note that the samples are provided as a proof-of-concept rather than a best-practices guide for writing JavaServer Faces applications.

Building and Running the Examples With the Java WSDP

To build one of the samples, you need to run its build.xml file using Ant, which is a portable make tool.

Like the asant tool, when Ant builds the application it copies files to a temporary build directory. When Ant builds the WAR file, it packages all the files from the build directory into the WAR file.

To build the samples you first need to enter some paths in the build.properties file:

  1. Make sure you have the necessary preconditions as listed in the ReleaseNotes.
  2. Make sure you have Ant version 1.5.1 installed and working on your machine.
  3. Copy build.properties.sample to build.properties and edit accordingly for your system.
  4. Go to the directory of the sample you want to build.

To build a sample WAR file and deploy it:

  1. Go to the directory of the sample you want to build.
  2. At the command line, run the default target:
    ant
  3. The WAR file of the sample you just built will be placed in the JWSDP_HOME/jsf/samples directory.
  4. Your application will be automatically deployed in Java WSDP 1.3.
  5. Start the server by either running catalina.sh run if you are using UNIX or catalina run if your are using Windows.
  6. When the server has started, open your browser and enter this URL:
    	http://localhost:8080/<EXAMPLE NAME>

    In Java WSDP, you can also find a page containing links to the JavaServer Faces samples on your default server port:
    	http://localhost:8080

Installing, Building and Running the Examples in Other Containers

  1. Download the JavaServer Faces 1.0_01 ZIP file.
  2. Unzip the file.
  3. Copy the build.properties.sample file to build.properties and edit it according to your system configuration. Be sure to uncomment the build.standalone property in the build.properties file.
  4. Make sure the following properties in your customized build.properties file point to the correct JAR file location according to your system configuration:
  5. If you have previously run JavaServer Faces applications, you should remove your web server's cached files before running the new release. For instance, the cached files in a Java WSDP container will be located in JWSDP_HOME/work/Catalina/localhost/jsf-*. It is safe to remove all these files before restarting your server. Read your container's documentation to find out where the cached files are located in your specific container.
  6. Follow the Building and Running the Examples With Java WSDP section
    You will need to rebuild each of the JavaServer Faces sample applications with the build.standalone property set to "true" so that each sample's web archive includes all of the jar file dependencies. This step is not necessary in a JWSDP container since all the jar dependencies that JavaServer Faces requires are already part of the container.

    Note: the Building and Running the Examples With Java WSDP section makes reference to JWSDP_HOME, substitute your container's home directory for JWSDP_HOME. You will also need to manually deploy the sample WAR files into your container's webapps directory

Copyright © 2004 Sun Microsystems, Inc., 4150 Network Circle, Santa
Clara, California 95054, U.S.A. All rights reserved.

Sun Microsystems, Inc. has intellectual property rights relating to
technology embodied in this product. In particular, and without
limitation, these intellectual property rights may include one or more
of the U.S. patents listed at http://www.sun.com/patents and one or more
additional patents or pending patent applications in the U.S. and other
countries.

This product is distributed under licenses restricting its use, copying
distribution, and decompilation. No part of this product may be
reproduced in any form by any means without prior written authorization
of Sun and its licensors, if any.

Third-party software, including font technology, is copyrighted and
licensed from Sun suppliers.

Sun, Sun Microsystems, the Sun logo, the Java Coffee Cup logo,
JavaServer, and Java are trademarks or registered trademarks of Sun
Microsystems, Inc. in the U.S. and other countries.

Federal Acquisitions: Commercial Software - Government Users Subject to
Standard License Terms and Conditions.


Copyright © 2004 Sun Microsystems, Inc., 4150 Network Circle,
Santa Clara, California 95054, Etats-Unis. Tous droits réservés.

Sun Microsystems, Inc. a les droits de propriété intellectuels relatants
à la technologie incorporée dans ce produit. En particulier, et sans la
limitation, ces droits de propriété intellectuels peuvent inclure un ou
plus des brevets américains énumérés à http://www.sun.com/patents et un
ou les brevets plus supplémentaires ou les applications de brevet en
attente dans les Etats - Unis et les autres pays.

Ce produit ou document est protégé par un copyright et distribué avec
des licences qui en restreignent l'utilisation, la copie, la
distribution, et la décompilation. Aucune partie de ce produit ou
document ne peut être reproduite sous aucune forme, par quelque moyen
que ce soit, sans l'autorisation préalable et écrite de Sun et de ses
bailleurs de licence, s'il y ena.

Le logiciel détenu par des tiers, et qui comprend la technologie
relative aux polices de caractères, est protégé par un copyright et
licencié par des fournisseurs de Sun.

Sun, Sun Microsystems, le logo Sun, le logo Java Coffee Cup, JavaServer,
et Java sont des marques de fabrique ou des marques déposées de Sun
Microsystems, Inc. aux Etats-Unis et dans d'autres pays.