JSF Library Migration

Overview

Moving from JSF Tools version 0.5.0 (WTP 1.5) to 1.0.0 (WTP 2.0) requires an upgrade of the JSF Library Registry. The tool will automatically migrate your workspace when loaded using WTP 2.0, however some manual steps are required to migrate existing dynamic web projects.

Impact

This change impacts users who created dynamic web projects using WTP1.5/JSF 0.5 and use JSF Libraries to manage jar dependencies. Your projects should continue to work without performing these steps, however, you will not be able to create new projects using JSF libraries nor edit existing ones without performing this migration.

Also note that JSF projects created using WTP 2.0 are not backward compatible and should generally not be used in WTP 1.5.

Action

Migrating Existing Projects

• Clean-up old library references for each JSF project:

1. From the J2EE Module Dependencies project property page, de-select any jars related to old JSF Libraries
2. From the Libraries tab of the Java Build Path project property page, remove any jars related to JSF Libraries
3. If you experience build dependency problems, ensure that no jars related to JSF Libraries remain in the WEB-INF/lib folder of the directory or in the .classpath file

• Create new library references for each JSF project:

1. Java Build Path --> Libraries Tab --> Add Libraries --> JSF Libraries --> select libraries
2. J2EE Module Dependencies --> select the libraries to be published and exported

Rolling back to 1.5.x

If you need to recover your old JSF registry because you wish to change back to WTP 1.5.x for any reason, you can do so manually using these steps:

1. Close Eclipse.
2. Go to the directory: <your-workspace-dir>/.metadata/.plugins/org.eclipse.jst.jsf.core.
3. Rename JSFLibraryRegistry.xml.bkp to JSFLibraryRegistry.xml.
4. Save a copy of JSFLibraryRegistryV2.xml (the new registry data file) and remove it.
5. Load the workspace using your old WTP 1.5.x instance.

Note: Projects that are created using JSF libraries in WTP 2.0 or which are migrated using the section "Migrating Existing Projects" above, cannot be rolled back in this way.

Background

In version 1.0.0 (WTP 2.0), JSF Libraries get added to projects as classpath containers, and some changes were required in the EMF model of the registry. Once an instance of the registry has been upgraded, it will no longer be useable in earlier versions of the JSF tools.

In version 1.0.0, references to JSF Libraries are handled as classpath container references. When you add a reference to a JSF Library, you are adding the set of jars contained within the library, as a container reference on the classpath. To control whether or not the library will be published or exported, will depend on whether or not you mark the library (classpath container) as being a J2EE Module Dependency. The JSF Library Reference property page has been removed. You will now use the Java Build Path property page to add, remove and edit references to JSF Libraries for a project.

The tool will automatically upgrade the JSF Library Registry. However, the references cannot be upgraded from 0.5.0. The following manual steps will be required to upgrade an existing JSF Faceted Web project to use the new JSF Library reference mechanism: