Sakai tools use a legacy unsupported version of JSF (1.2) and the goal is to get to a more recently released version (2.3).
This migration guide has been built under the SVCfunds 2017 project, inside the Chat JSF Upgrade (Phase 1), which is the first tool that has been migrated to JSF 2.3 from 1.1_02.
The first steps in the migration process was to find the dependencies between the Chat tool and Sakai’s JSF component, check the versions and predict the consequences. The plan was to modify as little code from the Chat tool as possible, but also it was important to save efforts in making changes that could be overridden in future migrations.
The modification flow we followed could be something like this:
pom.xml files (JSF&CHAT)
-> taglib (xml and tld files at JSF)
-> faces-config.xml files (JSF&CHAT)
-> web.xml files (JSF&CHAT)
-> jsp files (CHAT)
This process was re-evaluated several times as we were finding and solving issues and detecting compatibility problems.
See the README-JSF2.md file to get more details about the JSF2 project migration, project which this guide relies on.
First of all, open all the pom.xml files from the VIEW layer (Usually called tool or app).
Replace all the JSF project dependencies, under the groupId org.sakaiproject.jsf, to use the JSF2 dependencies. Before:
<dependency>
<groupId>org.sakaiproject.jsf</groupId>
<artifactId>jsf-tool</artifactId>
</dependency>
<dependency>
<groupId>org.sakaiproject.jsf</groupId>
<artifactId>jsf-widgets-sun-depend</artifactId>
<type>pom</type>
</dependency>
After:
<dependency>
<groupId>org.sakaiproject.jsf2</groupId>
<artifactId>jsf2-tool</artifactId>
</dependency>
<dependency>
<groupId>org.sakaiproject.jsf2</groupId>
<artifactId>jsf2-widgets-sun-depend</artifactId>
<type>pom</type>
</dependency>
Before:
<dependency>
<groupId>org.apache.myfaces.tomahawk</groupId>
<artifactId>tomahawk</artifactId>
<version>1.1.14</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>taglibs</groupId>
<artifactId>standard</artifactId>
<version>1.0.4</version>
</dependency>
After:
<!--JSF 2.3 dependencies-->
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>jstl</artifactId>
<version>${sakai.jstl.version}</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.jboss</groupId>
<artifactId>jandex</artifactId>
<version>2.0.5.Final</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.jboss.weld.servlet</groupId>
<artifactId>weld-servlet-shaded</artifactId>
<version>3.0.4.Final</version>
</dependency>
New file webapp/META-INF/context.xml
<Context>
<Resource name="BeanManager"
auth="Container"
type="javax.enterprise.inject.spi.BeanManager"
factory="org.jboss.weld.resources.ManagerObjectFactory" />
</Context>
New file webapp/WEB-INF/beans.xml
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/beans_2_0.xsd"
bean-discovery-mode="all" version="2.0">
</beans>
Before:
<!DOCTYPE faces-config PUBLIC
"-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
"dtd/web-facesconfig_1_0.dtd">
<faces-config>
After:
<faces-config xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
http://xmlns.jcp.org/xml/ns/javaee/web-facesconfig_2_3.xsd"
version="2.3">
Before:
<web-app id="WebApp_9" version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
After:
<web-app
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<context-param>
<param-name>com.sun.faces.verifyObjects</param-name>
<param-value>true</param-value>
</context-param>
- Replace "sakai:messages" by "h:messages"
- Replace "sakai:button_bar_item" by "h:commandButton"
Before:
<%@ taglib uri="http://java.sun.com/jstl/core_rt" prefix="c" %>
After:
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
Before:
org.sakaiproject.jsf.util.HelperAwareJsfTool
After:
org.sakaiproject.jsf2.util.HelperAwareJsfTool
Before:
<%@ taglib uri="http://sakaiproject.org/jsf/sakai" prefix="sakai" %>
After:
<%@ taglib uri="http://sakaiproject.org/jsf2/sakai" prefix="sakai" %>
Compile and deploy the JSF2 project first, then compile the migrated tool. Startup the application server (Tomcat), you'll notice some lines like this that reflects that Mojarra JSF has been loaded succesfully:
org.apache.catalina.startup.HostConfig.deployWAR Deploying web application archive [D:\opt\sakai\webapps\sakai-chat-tool.war]
com.sun.faces.config.ConfigureListener.contextInitialized Initializing Mojarra 2.3.5 ( 20180516-1910 bf35b0f6c540c69e80e6da962a2b62756838ac41) for context '/sakai-chat-tool'
com.sun.faces.spi.InjectionProviderFactory.createInstance JSF1048: PostConstruct/PreDestroy annotations present. ManagedBeans methods marked with these annotations will have said annotations processed.
org.apache.catalina.startup.HostConfig.deployWAR Deployment of web application archive [D:\opt\sakai\webapps\sakai-chat-tool.war] has finished in [17,674] ms
Test, if possible, all the options and features of the migrated tool, checking every screen and every tag.
You're welcome to receive help about the migration in the Sakai DEV list