Raible's Wiki

Raible Designs
Wiki Home
Recent Changes


  - Korean
  - Chinese
  - Italian
  - Japanese

QuickStart Guide
  - Chinese
  - French
  - German
  - Italian
  - Korean
  - Portuguese
  - Spanish
  - Japanese

User Guide
  - Korean
  - Chinese

  - Chinese
  - German
  - Italian
  - Korean
  - Portuguese
  - Spanish

  - Korean

Latest Downloads

Other Applications

Struts Resume
Security Example
Struts Menu

Set your name in

Edit this page

Referenced by

JSPWiki v2.2.33


Hide Menu


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]

After a bit of trial-and-error, I discovered that the *.html mapping didn't seem to work in web.xml. This is strange since it does work in the Struts Portlet. Change the mappings for the FacesServlet and exportFilter to be *.jsf.

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">
        <description>This is a simple portlet</description>
            <title>User List</title>

Deploy the WAR to Jetspeed [#4]

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


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.


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]

Create a equinox-jsf.psml file in $CATALINA_HOME/webapps/jetspeed/WEB-INF/pages with the following contents. The fragment id's must be unique among all .psml files, and the name of the portlet is read from the portlet.xml file.
<?xml version="1.0" encoding="UTF-8"?>
<page id="equinox-jsf">

  <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"/>

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

Go to top   Edit this page   More info...   Attach file...
This page last changed on 06-Nov-2006 13:52:58 MST by MattRaible.