Getting Started

Version 7 by Deryk Sinotte
on Jan 14, 2010 11:37.

<< Changes from 6 to 7

compared with

Version 8 by Deryk Sinotte
on Jan 14, 2010 11:38.

Changes from 8 to 9 >>

Key

These lines were removed. This word was removed.

These lines were added. This word was added.

View page history

There are 3 changes. View first change.

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

		h3. Downloading ICEfaces 2.0
		The latest official release of all ICEfaces products, including ICEfaces 2.0, can be found on the [ICEfaces Downloads\|http://www.icefaces.org/main/downloads/os-downloads.iface\|ICEfaces Downloads] page.

		h3. Supported Platforms

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

		* Glassfish 3
		* Tomcat 6

		h3. ICEfaces Libraries

		ICEfaces 2.0 provides the following libraries:

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

		h5. icefaces-compat-components.jar, icefaces-compat.jar
		These libraries contain the ICEfaces 1.8.x version of the component suite and the compatibility layer that is compatible with ICEfaces 2.0. You should include these libraries if you want to use components other than the standard components or if you are porting an existing ICEfaces 1.8.x application to ICEfaces 2.0. See the [Compatibility] section for more information.

		h5. icepush.jar
		This is the library that provides Ajax Push functionality for ICEfaces 2.0.


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

		h5. Build ICEfaces Libraries

		The ICEfaces binary libraries come pre-built in the distribution. If you need to build them again (e.g. perhaps you've tweaked the source code), open a console or shell and navigate to the directory where you unzipped the ICEfaces distribution. Then, in the console, type the following and press Enter:

		{code}ant cleanall world{code}

		This builds all of the ICEfaces libraries and sample applications for the default platform.

		{note}I think the default for the compat examples is Tomcat but the default for the stock samples is Glassfish{note}

		h5. Compatibility Examples

		The examples under the \[icefaces2.install.dir\]/compat/samples directory use the compatible version of the ICEfaces 1.8.x component suite and the compatibility layer that allows them to operate under 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\]/compat/samples/component-showcase), type:

		{code}ant -p{code}

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

		{code}ant clean glassfishv3{code}

		{note}The build shows more platforms than we officially support. How to reconcile?{note}

		h5. JSF 2.0 Examples

		The examples under \[icefaces2.install.dir\]/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 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\]/samples/auction), type:

		{code}ant -p{code}

		and press Enter. This will show a list of build targets for various platforms. To build a version of the Auction for Glassfish 3, you would then type:

		{code}ant{code}

		and press Enter. Since there are far fewer library dependencies involved, the build targets are relatively simple. The default build (i.e. just using 'ant') builds a Glassfish 3 compatible .war. This will include icefaces.jar and icepush.jar. This can be modified using either the convenience targets in the build file or the properties as follows:

		{code}ant war.jsf{code} //includes jsf-*.jar files only
		{code}war.jsf.ice{code} //includes jsf-* and icefaces.jar
		{code}war.jsf.ice.push{code} //includes jsf-* and icefaces.jar and icepush.jar
		{code}ant war.jsf{code}
		This includes jsf-*.jar files only.

		Or the properties can be used like this in whatever combination to add the related .jar files to the .war file:
		{code}ant war.jsf.ice{code}
		This includes jsf-* and icefaces.jar.

		{code}ant war.jsf.ice.push{code}
		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:
		{code}ant -Djsf='true' -Dice='true' -Dpush='true'{code}

		h3. Configuring an ICEfaces Application

		h5. Include the necessary libraries

		* icefaces.jar is always required.
		* icefaces-compat-component.jar and icefaces-compat.jar if you are using more than the standard components.
		* icepush.jar you are using Ajax Push.
		* jsf-api.jar and jsf-impl.jar if the platform does not already supply them

		h5. Configuration

		ICEfaces 2.0 does not require an additional configuration beyond what JSF 2.0 requires. Simply ensure you have the FacesServlet declared appropriately in your web.xml file:
		{code:xml}
		<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>
		{code}