How I managed to deploy a JSF/Seam portlet to JBoss after all

Deploying a custom JSF/Seam portlet to JBoss Portal Server isn’t as easy as you’d expect, either manually or using Eclipse with JBoss Tools. I’ll share with you what I learned about this.


See the previous Seam Tutorial 1.1 and 1.2 to learn what SW versions I use, how to configure a server in Eclipse etc. The issues with JBoss Tools, JBoss Portal, and Seam/RichFaces depend pretty much on their respective version and can change significantly even with a minor version change.


  • jboss-portlet-bridge-1.0.0.B6

In the blog JBoss Portlet support in Eclipse you may learn more about creating portlets for JBoss in Eclipse and issues with various versions of JBoss Tools.

Deploying a portlet via Maven 2

JBoss provides Maven archetypes for creating Seam portlets and also tasks for deploying them to a portal server, either an existing one or a newly downloaded one. This is described in the development guide but not sufficiently.

Note: You need maven 2.0.9 or higher.

  1. run$ mkdir /tmp/jboss; cd /tmp/jboss
  2. run$ mvn archetype:generate

    (accept all defaults)
  3. cd /tmp/jbossrun/seamproject
  4. edit /tmp/jboss/seamproject/web/pom.xml
    • Running mvn install would fail because of missing org.jboss.portletbridge:portletbridge-api:jar:1.0-SNAPSHOT for  eu.ibacz.seamtutorial2.web:seamproject:war:1.0-SNAPSHOT.
    • => replace <version>${project.version}</version> with <version>${portletbridge.version}</version> for artifactId portletbridge-api in /tmp/jboss/seamproject/web/pom.xml
  5. run$  mvn install
    This will create a WAR package and install it into the local maven repository.
  6. run$ cd /tmp/jboss/seamproject/ear
  7. run$  mvn -Plocal-portal cargo:start
    This uses the Maven plugin cargo to start a local JBoss Portal. It must be run from the ear/ folder because ear/pom.xml defines the necessary settings.
  8. Set the JDK to use if needed – JBoss requires JRE 1.5. and has troubles under 1.6. You may define the JRE to use by adding a property like

    to the other cargo properties in ear/pom.xml
    Indication of the problem: an error like below in jboss startup log:
    [INFO] [talledLocalContainer] Caused by: java.lang.UnsupportedOperationException: setProperty must be overridden by all subclasses of SOAPMessage
    – Strangely jboss still reports jre 1.6 after setting this property but the error disappears:
    [INFO] [talledLocalContainer] 10:14:54,415 INFO  [ServerInfo] Java version: 1.6.0_07,Sun Microsystems Inc.

    [INFO] [cargo:start]
    [INFO] [talledLocalContainer] Parsed JBoss version = [4.2.3]
    [INFO] [talledLocalContainer] JBoss 4.2.3 starting…

    [INFO] [talledLocalContainer] 10:01:34,211 INFO [Server] JBoss (MX MicroKernel) [4.2.3.GA (build: SVNTag=JBoss_4_2_3_GA date=200807181417)] Started in 2m:34s:75ms

  9. (in new window) run$ mvn cargo:deploy -Plocal-portal
    [INFO] [cargo:deploy]
    [INFO] [talledLocalContainer] Parsed JBoss version = [4.2.3]
    [INFO] [stalledLocalDeployer] Deploying [/POWEROLAP/jboss/seamproject/ear/target/seamproject-1.0-SNAPSHOT.ear] to [/POWEROLAP/jboss/seamproject/ear/target/installs/jboss-portal-2.7.0.GA-bundled/jboss-portal-2.7.0.GA/server/default/deploy]...
    (Some related logs are added also to the window where we started jboss.)
  10. Go to http://localhost:8080/portal You should see a tab called “seamproject” in the portal.

The bug report DOC-13317 describes the shortcomings of the documentation for this.

Manual deployement of a Seam portlet created with Eclipse/JBoss Tools

How to create a Seam portlet in Eclipse with JBoss Tools and deploy it to JBoss Portal.

Create a new Seam portlet project

Note> There are multiple ways to create a Seam Portlet project.

New > Project > Dynamic Web Project >

  1. Page Dynamic Web Project:
    • Target runtime: jboss 4.3.2 portal 2.7.1,
    • Dynamic Web Module version: 2.5
    • Configuration “JBoss Seam Portlet Project v2.0”; if you haven’t it on the selection list, click [Modify…] and select the facets Seam, JBoss Portlets and all under it (JBoss Core Portlet, JBoss JSF Portlet, JBoss Seam Portlet), Java, Dynamic Web Module.
    • Click Next >
  2. Page Web Modules: keep the defaults.
  3. Page JBoss Portlet Capabilities: keep the defaults (Enable implementation library, Libraries provided by server runtime).
  4. Page JSF Capabilities: keep the defaults (Server supplied JSF implementation, …).
  5. Page Seam Facet: set the Seam runtime and Database as we did in the other projects of my Seam/RichFaces tutorials (TODO link).
  6. Page JBoss Portlet Capabilities: Portletbridge Runtime: select e.g. jboss-portal-2.7.1/server/default/deploy/jboss-portal.sar/lib .

Add a portlet to the project

New > Other… > JBoss Tools Web > Portlet > JBoss JSF/Seam Portlet (there is also a plain Java Portlet).

Accept all defaults. This will create a portlet called seamPortlet that will display the page home.xhtrml.

Deploy the portlet

One we have created s Seam portlet we would like to be able to deploy it to JBoss Portal. Here we will learn how to deploy it manually, that means by exporting it from Eclipse as a WAR file and installing that to the server. If you try that you will fail. Below I describe the necessary steps to get the exported WAR working under JBoss.

By comparing the SeamBooking example portlet that you can find in the portlet bridge download package and my Seam portlet exported from Eclipse I’ve discovered the following differences.

  • SeamBooking’s META-INF/ contains a persistence.xml (likely some JPA stuff).
  • SeamBooking’s jboss-portlet.xml defines links to 2 RichFaces JavaScript files and 1 CSS file.
  • SeamBooking’s jboss-object.xml has the property theme.renderSetId=emptyRenderer .
  • My portlet exported from Eclipse contains many libraries in WEB-INF/lib/ but not e.g. any portletbridge stuff.

Deploy the exporeted WAR to JBoss and start it.

Attempt I – failure:

  1. Missing portletbridge class:
    Cause: Unable to find class 'org.jboss.portletbridge.application.PortletViewHandler'

    t;li>Missing datasource.


  1. Copy portletbridge-impl.jar and portletbridge-api.jar to the WAR’s WEB-INF/lib/.
  2. Copy
    /resources/*-ds.xml to deploy/.

Attempt II – failure:

ERROR [LifeCycle] Cannot start objectorg.jboss.portal.portlet.container.PortletInitializationException: The portlet seamPortlet threw a runtime exception during init
Caused by: java.lang.ClassCastException: javax.portlet.faces.GenericFacesPortlet cannot be cast to javax.portlet.Portlet
    at org.jboss.portal.portlet.impl.jsr168.PortletContainerImpl.start(

Solution: Remove all portal*, portlet*.jar including portlet-api.jar (contains javax.portlet.Portlet.class), excluding. portletbridge.

Attempt III – portlet running:

No there are no more exceptions and when JBoss Portal starts, you will see there the tab “seamPortlet” with your portlet.

However when you go to the tab to see your portlet there will be another exception:

ERROR [InternalPortletContentProvider] Portlet invoker exception during portlet window renderingorg.jboss.portal.portlet.PortletInvokerException: javax.servlet.ServletException
Caused by: java.lang.NoSuchMethodError: org.ajax4jsf.context.ViewResources.processHeadResources(Ljavax/faces/context/FacesContext;)V

Solution: Replace libs with richfaces-api-3.3.0.GA.jar richfaces-impl-3.3.0.GA.jar richfaces-ui-3.3.0.GA.jar

Attempt VI – everything finally works.

Seam portlet deployment from Eclipse with JBoss Tools

This is something I haven’t managed so far 😦

Published by Jakub Holý

I’m a JVM-based developer since 2005, consultant, and occasionally a project manager, working currently with Iterate AS in Norway.

2 thoughts on “How I managed to deploy a JSF/Seam portlet to JBoss after all

  1. Hi Holy,
    This is really a great site for portlet developers.
    And when i try to enter your blog, I thought I would find a simple jsf portlet. But unfortunately I can’t.
    So I’m requesting you write a simple jsf portlet and explain how to submit an action,form, url in that tutorial. So that it will be a lot helful for the new guys like me.


  2. Hello Ganesh,

    I’m sorry but I haven’t played with JSF in portal that much. But if you read the post “Seam Tutorial 1.1” mentioned above (and I suppose you already have), you will learn how to create a simple JSF portletu (using RichFaces). In the part 1.2 of the tutorial you can also see an action – namely h:commandButton – this should all you need. Adding a form or anything should be equally simple, you may only want to check some JSF tutorial – and there are certainly lots of them – or examples on the RichFaces site.

    Good luck!

Comments are closed.