# JavaServerTM Faces Technology 1.1 FCS
Installation Instructions

Revised: 20040513

For updates to these instructions, please see the online version, JavaServer Faces Technology 1.1 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

- Installing Java Server Faces Technology in the Application Server
- Running the Pre-packaged Example WAR Files in the Application Server
- Building and Running the Examples with the Application Server

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

- Installing JavaServer Faces in Java WSDP
- Running the Pre-packaged Example WAR files in Java WSDP
- Building and Running the Examples with the Java WSDP

#### Using JavaServer Faces Technology with Other Containers

- Installing, Building, and Running the Examples in a Different Container

# 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 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 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 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 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:

- Copy the WAR file to the `autodeploy` directory
- Run `asadmin deploy` with the path to the WAR file
- Launch `deploytool` and deploy the WAR file from there

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

- Java WSDP 1.3 includes an XML file for each sample application in the `JWSDP_HOME/conf/Catalina/localhost` directory. This file causes that application to be automatically deployed when you start Tomcat.

- You can manually deploy an application by copying the WAR file you just generated to the `JWSDP_HOME/webapps` directory.

- When manually deploying under Java WSDP 1.3 make sure to remove the corresponding XML file located in the `JWSDP_HOME/conf/Catalina/localhost` directory.

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 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:
   - `tomcat-home`: path to your web container
   - `jsf-api.jar`
   - `jsf-impl.jar`
   - `commons-beanutils.jar`
   - `commons-digester.jar`
   - `commons-logging.jar`
   - `commons-collections.jar`: available in the `lib` directory of your JavaServer Faces unzipped bundle
   - `jsp.jar`: JSP 1.2+ API JAR is available from Jakarta Tomcat
   - `jstl.jar`: JSTL 1.0+ API JAR is available from Jakarta Taglibs. You should use JSTL 1.1 in a container that supports JSP 2.0. If your container does not support JSP 2.0 then use JSTL 1.0.x. The JavaServer Faces standalone samples contain JSTL 1.1 implementation jars.
   - `standard.jar`: JSTL 1.0+ Implementation JAR file is available from Jakarta Taglibs. You should use JSTL 1.1 in a container that supports JSP 2.0. If your container does not support JSP 2.0 then use JSTL 1.0.x. The JavaServer Faces standalone samples contain JSTL 1.1 implementation jars.
   - `servlet.jar`: Servlet 2.3+ API jar available from Jakarta Tomcat
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.