Getting Started

Getting Started

This section describes where to get ICEfaces 2.0, how to run the examples, and how to get started using ICEfaces 2.0 to develop your own applications.

Downloading ICEfaces 2.0

The latest official release of all ICEfaces products, including ICEfaces 2.0, can be found on the ICEfaces Downloads page.

Supported Platforms

The current release (Alpha 3) of ICEfaces 2.0 has been tested to run on the following application servers:

• Glassfish 3
• Tomcat 6 (by including the JSF 2.0 runtime libraries in the project)

Note that ICEfaces 2.0 should work on any JEE 6 Web Profile compliant platform.

ICEfaces Libraries

ICEfaces 2.0 provides the following libraries:

icefaces.jar

This is the ICEfaces 2.0 core framework and is required for all applications.

icepush.jar

Provides Ajax Push functionality for ICEfaces 2.0. This library is only required if Ajax Push functionality is required in the application.

icefaces-compat.jar, icefaces-compat-components.jar

These libraries contain the ICEfaces 1.8 compatibility APIs (icefaces-compat.jar), and the ICEfaces 1.8.x Component Suite that is compatible with ICEfaces 2.0 (icefaces-compat-components.jar). You should include these libraries if you want to use the ICEfaces 1.8 Component Suite "ice" components in your application, or if you are porting an existing ICEfaces 1.8.x application to ICEfaces 2.0. See the [Compatibility] section for more information.

Building ICEfaces

If you have downloaded the Source distribution bundle of ICEfaces 2.0 (icefaces-2.0.0-alpha3-src.zip), you will need to compile and build the ICEfaces libraries before using them.

The ICEfaces 2.0 Binary distribution bundle (icefaces-2.0.0-alpha3-bin.zip) comes with prebuilt ICEfaces libraries so building is not necessary.

To build ICEfaces, open a console or shell and navigate to the "icefaces" directory where you unzipped the ICEfaces distribution. Then, in the console, type the following and press Enter:

ant allclean world

This builds all of the ICEfaces libraries and sample applications suitable for deployment to any JEE 6 Web Profile platform, such as Glassfish 3.

Running the Examples

The ICEfaces 2.0 distribution comes with example applications that illustrate the key features of ICEfaces 2.0 as well as providing source code and guidance about configuration and library dependencies.

JSF 2.0 Examples

The examples under [icefaces2.install.dir]/icefaces/samples do not use the compatibility layer or the compatible component suite. These applications use only standard JSF 2.0 components enhanced with ICEfaces. As such, they require far fewer library dependencies.

The main example is Auction - a version of the original ICEfaces 1.8 Auction Monitor application ported to run on ICEfaces 2.0 but modified to use only JSF standard components and ICEpush. To run any of the pure JSF 2.0 examples, open a console or shell and navigate to the directory (e.g. [icefaces2.install.dir]/icefaces/samples/auction), type:

ant -p

and press Enter. This will show a list of build targets for various platforms. Since there are far fewer library dependencies involved, the build targets are relatively simple.

The default build target, "ant ", is mapped to the "war.ice.push" build target, which will build a version of the sample application suitable for deployment to any JEE 6 Web Profile platform, such as Glassfish 3, and includes both the icefaces.jar and the icepush.jar for Ajax Push support.

The default build behavior can be modified using either the convenience targets in the build file or the properties as follows:

ant war.jsf

This includes jsf-*.jar files only.

ant war.jsf.ice

This includes jsf-* and icefaces.jar.

ant war.jsf.ice.push

This includes jsf-*, icefaces.jar, and icepush.jar

The properties can also be used directly with the ant command to add the related .jar files to the .war file:

ant -Djsf='true' -Dice='true' -Dpush='true'

Compatibility Examples

The examples under the [icefaces2.install.dir]/icefaces/compat/samples directory use the compatible version of the ICEfaces 1.8.x Component Suite and the compatibility APIs to allow them to work with ICEfaces 2.0.

The main example is the Component Showcase - a version of the original ICEfaces 1.8 Component Showcase ported to run on ICEfaces 2.0. To run any of the compatibility examples, open a console or shell and navigate to the directory (e.g. [icefaces2.install.dir]/icefaces/compat/samples/component-showcase), and type:

ant -p

And press Enter. This will show a list of build targets for various platforms. To build a version of the compatible Component Showcase for Tomcat 6, you would then type:

ant clean tomcat6.0

The default build (e.g. "ant") is equivalent to "ant glassfishv3", suitable for deployment to Glassfish 3.

Configuring a JSF 2.0 Application to Use ICEfaces

If you're just starting to build a JSF 2.0 application, or you've already started building one and you'd like to add ICEfaces, it's simple to do:

Add h:head and h:body tags

JSF 2 includes head and body components that can be added to the page by using the h:head and h:body tags. ICEfaces 2.0 makes use of these components to automatically add certain scripts and other elements to the page so it the h:head and h:body tags are required on any pages of your application that use ICEfaces.

Include the necessary libraries

• icefaces.jar is always required.
• icepush.jar you are using Ajax Push.
• icefaces-compat-component.jar and icefaces-compat.jar if you are using the compatible ICEfaces 1.x Component Suite.
  • If you are using the ICEfaces 1.8 compatible components you will also require additional 3rd party libraries. See Appendix A - ICEfaces Library/App. Server Dependencies in the ICEfaces 1.8 Developer's Guide for details.
• jsf-api.jar and jsf-impl.jar if the platform you plan to run on does not already supply them. For example, Glassfish 3 already has the JSF 2.0 libraries provided, but Tomcat 6 does not.

Configuration

ICEfaces 2.0 does not require any additional configuration beyond what JSF 2.0 requires. Simply ensure you have the FacesServlet declared appropriately in your web.xml file:

    <servlet>
        <servlet-name>Faces Servlet</servlet-name>
        <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>
        <url-pattern>*.jsf</url-pattern>
    </servlet-mapping>

Advanced Configuration

ICEfaces 2.0 provides a number of configuration parameters that need not be adjusted for typical applications, but may be useful for diagnostic purposes or in special cases. These parameters are fully documented in the Configuration section.