JSFPortlet

This page documents the steps necessary to migrate an existing JSF application for use as a Jetspeed portlet. See the installing Jetspeed page if you don't have Jetspeed installed.

The application used for testing and figuring out these steps was the JSF version of Equinox. The jsf-demo app that's included in Jetspeed-2 was used as a reference. For this tutorial, Equinox 1.2 was used - and this change was made to build.xml. To begin, I created an equinox-jsf project by downloading/extracting Equinox and then cd-ing into its extras/jsf folder and running "ant test". Make sure Tomcat is stopped when you run this command since this command will actually start Tomcat and run some tests in it.

Table of Contents

• [1] Add the portals-bridges-jsf-0.1.jar to your project
• [2] Modify web.xml to use *.jsf instead of *.html
• [3] Create a portlet.xml file in the WEB-INF directory
• [4] Deploy the WAR to Jetspeed
• [5] Create a .psml file so the portlet will show up in Jetspeed
• [6] Known Issues

Add the portals-bridges-jsf-0.1.jar to your project [#1]

Once you have equinox-jsf and jetspeed setup, copy the portals-bridges-jsf-0.1.jar from your local Maven repository into the web/WEB-INF/lib directory.

cp ~/.maven/repository/portals-bridges/jars/portals-bridges-myfaces-0.1.jar web/WEB-INF/lib

Modify web.xml to use *.jsf instead of *.html [#2]

    <filter-mapping>
        <filter-name>exportFilter</filter-name>
        <url-pattern>*.jsf</url-pattern>
    </filter-mapping>

    <servlet-mapping>
        <servlet-name>faces</servlet-name>
        <url-pattern>*.jsf</url-pattern>
    </servlet-mapping>

Create a portlet.xml file in the WEB-INF directory [#3]

Copy and paste the following XML into a portlet.xml file in the web/WEB-INF directory.

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app id="equinox-jsf" version="1.0">
    <portlet id="Equinox-JSF">
        <init-param>
            <name>ViewPage</name>
            <value>/userList.jsf</value>
        </init-param>
        <portlet-name>Equinox-JSF</portlet-name>
        <display-name>Equinox</display-name>
        <description>This is a simple portlet</description>
        <portlet-class>org.apache.portals.bridges.myfaces.FacesPortlet</portlet-class>
        <expiration-cache>-1</expiration-cache>
        <supports>
            <mime-type>text/html</mime-type>
            <portlet-mode>VIEW</portlet-mode>
            <portlet-mode>EDIT</portlet-mode>
            <portlet-mode>HELP</portlet-mode>
        </supports>
        
        <portlet-info>
            <title>User List</title>
            <short-title>users</short-title>
        </portlet-info>
    </portlet>
</portlet-app>

Deploy the WAR to Jetspeed [#4]

In build.properties, add a "deploy.dir" property so you can deploy to Jetspeed's deployer.

deploy.dir=/opt/dev/tools/tomcat/webapps/jetspeed/WEB-INF/deploy

Edit web/WEB-INF/classes/jdbc.properties and change the "jdbc.url" to use an absolute path. This is necessary so you can populate the HSQL database from the equinox-jsf directory.

jdbc.url=jdbc:hsqldb:/Users/mraible/dev/equinox-jsf/db/equinox

Start Tomcat and run "ant deploywar" to deploy your portlet. If you're watching Tomcat's log files ($CATALINA_HOME/logs/catalina.out) - and you don't see your WAR getting deployed, make sure the portlet.xml is in your web/WEB-INF directory.

To update the WAR in Jetspeed, just run "ant deploywar" after you've modified files. To undeploy the WAR, delete the equinox-jsf.war file from $CATALINA_HOME/webapps/jetspeed/WEB-INF/deploy.

NOTE: These deployment instructions are based on this wiki page.

Create a .psml file so the portlet will show up in Jetspeed [#5]

<?xml version="1.0" encoding="UTF-8"?>
<page id="equinox-jsf">
  <defaults
     skin="orange"
     layout-decorator="tigris"
     portlet-decorator="tigris"/>

  <title>Equinox-JSF</title>
  <fragment id="equinox-jsf-layout" type="layout" name="jetspeed::VelocityTwoColumns">
    <fragment id="equinox-jsf-portlet" type="portlet" name="equinox-jsf::Equinox-JSF">
      <property layout="TwoColumns" name="row" value="0"/>
      <property layout="TwoColumns" name="column" value="0"/>
    </fragment>
  </fragment>
</page>

Open http://localhost:8080/jetspeed. You should see a "Equinox-JSF" tab on the opening screen. To populate the values in the HSQL database, run "ant populate" and you should see a list of users when you click on the tab.

Known Issues [#6]

• The equinox-jsf app is a JSF application that is not modified at all to be used as a portlet. Because of this, most of the app's functionality does not work. In fact, I experienced very intermittent behavior with Jetspeed. Sometimes I would click the Equinox-JSF tab and it would work, and the next time it wouldn't.
• Having the portals-bridges-myfaces-0.1.jar in the classpath when running tests on managed beans causes them to fail. At first, when I tried to run "ant test -Dtestcase=UserList", I received an error about missing classes. I copied ~/.maven/repository/portlet-api/jars/portlet-api-1.0.jar to web/WEB-INF/lib to fix that problem. Then when I tried to run the unit tests, I ended up with "javax.faces.FacesException: Unsupported context type org.springframework.mock.web.MockServletContext".