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

April 20, 2009

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.

Introduction

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.

Including:

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.

run$ mkdir /tmp/jboss; cd /tmp/jboss
run$ mvn archetype:generate -DarchetypeGroupId=org.jboss.portletbridge.archetypes -DarchetypeArtifactId=seam-basic -DarchetypeVersion=1.0.0.B6 -DgroupId=eu.ibacz.seamtutorial2 -DartifactId=seamproject -DarchetypeRepository=http://repository.jboss.org/maven2/ (accept all defaults)
cd /tmp/jbossrun/seamproject
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
run$ mvn install This will create a WAR package and install it into the local maven repository.
run$ cd /tmp/jboss/seamproject/ear
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.
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
```
<cargo.java.home>/path/to/jdk1.5.0_17/jre</cargo.java.home>
```
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.

Output: [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

(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.)

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 >

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 >
Page Web Modules: keep the defaults.
Page JBoss Portlet Capabilities: keep the defaults (Enable implementation library, Libraries provided by server runtime).
Page JSF Capabilities: keep the defaults (Server supplied JSF implementation, ...).
Page Seam Facet: set the Seam runtime and Database as we did in the other projects of my Seam/RichFaces tutorials (TODO link).
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:

Missing portletbridge class:

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

&l t;li>Missing datasource.

Solution:

Copy portletbridge-impl.jar and portletbridge-api.jar to the WAR's WEB-INF/lib/.
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(PortletContainerImpl.java:254)

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 :-(

Tags: java library tool