JBoss Portlet Bridge Overview

To get an idea of the JBoss Portlet Bridge community, the developers, and for wiki
information, checkout the project page.

What is the JBoss Portlet Bridge?

The JBoss Portlet Bridge (or JBPB for short) is a non-final draft implementation of the
JSR-301
specification which supports JSF within a
portlet and with added enhancements to support other web frameworks (such as
Seam and
RichFaces). It basically allows any Java
developer to get started quickly with their JSF web application running in a portal environment. The developer
no longer needs to worry about the underlying portlet development, portlet concepts, or the API.

Understanding how JSF works with Portal

The portlet bridge isn't a portlet. It's the mediator between the two environments and allows JSF and Portal
to be completely unaware of each other.
The bridge is used to execute Faces requests on behalf of the portlet. During each request, the Faces
environment is setup and handled by the bridge. Part of this implementation acts as a Faces controller much as
the FacesServlet does in the direct client request world. The other part of this
implementation is provided by implementating a variety of (standard) Faces extensions.

Note

This draft specification for the JSR 301 specification is not final. Any final specification that may be
published will likely contain differences, some of which may be substantial. Publication of this draft
specification is not intended to provide the basis for implementations of the specification. This draft
specification is provided AS IS, with all faults. THERE ARE NO WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING WARRANTIES OF CONDITION OF TITLE OR NONINFRINGEMENT. You may copy and display this draft
specification provided that you include this notice and any existing copyright notice. Except for the
limited copyright license granted above, there are no other licenses granted to any intellectual property
owned or controlled by any of the authors or developers of this material. No other rights are granted by
implication, estoppel or otherwise.

Chapter 1. Getting started with JBoss Portlet Bridge

JBoss Portlet Bridge not only gives you the ability to run JSF web applications in a portlet, but also gives you
the benefit of running supported JBoss frameworks like Seam and RichFaces.

1.1. Bridge Frameworks and Extensions

The JBoss Portlet Bridge currently supports JBoss Portal, JSF 1.2, JBoss Seam, and JBoss Richfaces. There are
configurations that apply to supporting each framework. See section Chapter 2, Bridge Configuration for instructions.

The JBoss Portlet Bridge project is also actively developing extensions, or Bridgelets, that enhance or bring together features of JBoss Portal, Seam, and Richfaces.
For example, the PortalIdentity seam component allows you to drop the jar in your classpath and you instantly have
SSO between Seam and Portal. This extension can also be configured with additional attributes in your Seam application's
components.xml file.

Note

Don't forget that the bridge is still in Beta and so are any extensions. If you would like to contribute to
any part of this project, we encourage you to be active on the user forum and bring issues/enhancements to attention.

Table 1.1. Available Bridgelets

Bridgelet

Command

Single Sign On

By inlcuding the following dependency in your web pom, you will automatically have SSO
between Jboss Portal and your Seam 2.1.1.GA application.

1.2. Before you start

Current version and compatibilty information can be easily located on the
JBPB wiki. Ensure you are using compatible
versions of all integrated frameworks before you begin.

JBoss Portal provides it's latest distribution included in JBoss Application Server. All of the guesswork has been
eliminated so that you can unzip and run Portal with a few clicks.
Get the latest here (ensure you choose
the JBoss Portal + JBoss AS link)

Next, all that's left is to download the JBoss Portlet
Bridge distribution and cofigure your portlet to use the bridge. Or, you can
run a provided archetype Section 1.3, “Maven Archetypes” and deploy the generated war in a few easy steps. This will
also give you an empty project to play around with or start from scratch.

For system requirements and setting up your JBoss Portal environment see the
reference guide.

1.3. Maven Archetypes

The JBPB project utilizes
Maven archetypes
which allow you get up and running with different flavors of the bridge quickly.

1.3.1. Running the Archetypes

JSF 1.2 Basic, RichFaces Basic, Seam Basic, and other demos

Each example application is configured to download the latest versions of JBoss Portal bundled with
JBoss Application Server. After running the archetype Section 1.3, “Maven Archetypes” or
downloading the source code for the
example application that you're interested in, you can run one of the following Maven profiles to save time
and get everything up and running with only 2 commands.
You have 2 options for deploying the generated project using Maven. You can let the project download, run, and deploy
JBoss AS and Portal automatically with the first option . Or you can use your own local install of JBoss AS
and Portal to deploy this project with the second option.

For more commands, view the README.txt in each project.
If you plan on using the cargo profiles to do active development, you can save alot of time by not downloading the
bundle each time you do a clean install. To use a locally configured server bundled with portal, use the following command line parameters.
The variable for JBOSS_HOME_DIR is related to how you zip the server directory. If you zip the files
under JBOSS_HOME/* then it will only be the name of your archive. But if you zip the actual folder JBOSS_HOME then
JBOSS_HOME_DIR must be defined as 'zip file name/JBOSS_HOME folder name'.
So basically, just zip up your local install of JBoss AS and portal (or download the bundle from sourceforge) if
you want to use this option.

The 301 specification is aimed at making the developers life as easy as possible with JSF+Portlet development.
You
will see below that there are minimal settings to getting any JSF web application up and running in the Portal
environment.

When preserveActionParams is set to TRUE, the bridge must maintain any request parameters assigned during
the portlet's action request. The request parameters are maintained in the"bridge
request scope". When this
attribute isn't present or is FALSE the action's request parameters are only maintained for the duration of
theportlet request scope.

2.1.3. Facelets Configuration

The following web.xml setting is only for Facelets based applications

2.1.3.1. web.xml

<web-appxmlns="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"version="2.4"> ...<!-- This is optional parameters for a facelets based application --><context-param><param-name>org.ajax4jsf.VIEW_HANDLERS</param-name><param-value>org.jboss.portletbridge.application.FaceletPortletViewHandler</param-value></context-param>

RenderPolicy Options

ALWAYS_DELEGATE
Indicates the bridge should not render the view itself but rather always delegate the rendering.

NEVER_DELEGATE
Indicates the bridge should always render the view itself and never delegate.

DEFAULT
Directs the bridge to first delegate the render and if and only if an Exception is thrown then
render the view based on its own logic. If the configuration parameter is not present or has an
invalid value the bridge renders using default behavior. I.e. as if DEFAULT is set.

2.1.4. JSP Only Configuration

The following web.xml setting is only for JSP based applications. Download the demo application here.

2.2. RichFaces Setup and Configuration Options

2.2.1. web.xml

The following configuration is designated for portlets using the RichFaces library. These settings
will vary based on your individual needs. See
this section
of the RichFaces documentation for more details.

Earlier 2.0.x versions of Seam portlets must have the LIFECYCLE_ID set to SEAM_PORTLET in the web.xml. This setting allows the bridge
to replace the original Seam phase listener during the faces lifecycle addPhaseListeners. This setting is not needed for
Seam portlets version 2.1.x and up.

Chapter 3. Developing Portlets with the Bridge

This chapter demonstrates common development tasks described by the 301 specification.

3.1. Excluding Attributes from the Bridge Request Scope

When your application uses request attributes on a per request basis and you do not want that particular
attribute to be managed in the extended bridge request scope, you must use the following configuration in
your faces-config.xml. Below you will see that any attribute namespaced as foo.bar or any attribute beginning
with foo.baz(wildcard) will be excluded from the bridge request scope and only be used per that application's request.

3.2. Supporting PortletMode Changes

A PortletMode represents a distinct render path within an application. There are three standard modes: view,
edit, and help. The bridge's ExternalContext.encodeActionURL recognizes the query string parameter
javax.portlet.faces.PortletMode and uses this parameter's value to set the portlet mode on the underlying
portlet actionURL or response. Once processed it then removes this parameter from the query string. This means
the following navigation rule causes one to render the \edit.jspx viewId in the portlet edit mode:

3.3. Navigating to a mode's last viewId

By default a mode change will start in the mode's default view without any (prior) existing state. One common
portlet pattern when returning to the mode one left after entering another mode (e.g.. view -> edit -> view)
is to return to the last view (and state) of this origin mode. The bridge will explicitly encode the necessary
information so that when returning to a prior mode it can target the appropriate view and restore the appropriate state.
The session attributes maintained by the bridge are intended to be used by developers to navigate back from a
mode to the last location and state of a prior mode. As such a developer needs to describe a dynamic navigation:
"from view X return to the last view of mode y". This is most easily expressed via an EL expression. E.g.

Note to Portlet Developers

Depending on the bridge implementation, when using values from these session scoped attributes or any
viewIds which may contain query string parameters it may be necessary to use the wildcard syntax when
identifying the rule target. For example, the above

<to-view-id>

expression returns a viewId of the
form

/viewId?javax.portlet.faces.PortletMode=view&....

Without wildcarding, when a subsequent navigation
occurs from this new view, the navigation rules wouldn't resolve because there wouldn't be an exact match.
Likewise, the above edit.jspx

<from-view-id>

is wildcarded because there are navigation rules that target
it that use a query string (