JBoss.orgCommunity Documentation
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.
The bridge considers a portlet event a model event. I.e. the event is targeted to the applications data model not its view. As JSF events primarily concern its view, the bridge processes the portlet events manually, however provisions are made to make sure that any model changes that result from processing the event are updated in the view. Since event payloads are arbitrarily complex, the manual processing of the data, though managed by the bridge, is left to the (portlet) application to support.
See Section 2.4.1, “Sending and Receiving Events” for details and examples.
The bridge deals with portlet served resources in one of two ways. If the request is for a non-JSF resource, the bridge handles the request by acquiring a request dispatcher and forwarding the request to the named resource. If the request is for a JSF resource, the bridge runs the full JSF lifecycle ensuring that data is processed and the resource (markup) is rendered.
See Section 2.4.3, “Serving Your JSF Resources in a Portlet” for details and examples.
The bridge automates the processing of public render parameters. A public render parameter can be mapped to an object's accessor (get/set method) designed to handle a String representation of the value via a Faces ValueExpression. When a new public render parameter value is received in a request, the bridge sets the value by calling the ValueExpression's setValue(). At the end of a request, if the current value of any mapped public render parameter doesn't match the current incoming value, the bridge sets the new value in an outgoing public render parameter (if feasible in the given phase).
See Section 2.4.2, “Public Render Parmaeters” for details and examples.
The JBoss Portlet Bridge currently supports JBoss Portal, GateIn, 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, and to differentiate from just another "project" that has boring ol' "extensions" we coined the term "Bridgelets" - because what would a project with Java and JSF be without having "*let" on the end of it? Not very cool in my opinion ;) With that said, in this current release we decided to bring all of our bridgelets into the impl code base since they are critical in most JSF portlet applications. Now it only takes a single line of configuration to utilize these features.
For example, the PortalIdentity seam component allows you to instantly have SSO between Seam and GateIn or JBoss Portal. This extension is configured in your Seam application's components.xml file as follows.
<security:portal-identity authenticate-method="#{authenticator.authenticate}"/>
Richfaces does not account for multiple components on the same portal page by default. This following web.xml renders all RichFaces component javascript to be portal friendly.
<context-param>
<param-name>org.jboss.portletbridge.WRAP_SCRIPTS</param-name>
<param-value>true</param-value>
</context-param>
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.
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 and GateIn provides it's latest distribution included in JBoss Application Server. All of the guesswork has been eliminated so that you can unzip and run the Portal with a few clicks. Get the latest here (ensure you choose the 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.4, “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.
This project utilizes Maven archetypes which allow you get up and running with different flavors of the bridge quickly.
Table 1.1. Available Archetypes
| Archetype | Command | |||
|---|---|---|---|---|
| JSF 1.2 Basic | mvn archetype:generate -DarchetypeGroupId=org.jboss.portletbridge.archetypes -DarchetypeArtifactId=1.2-basic -DarchetypeVersion=2.0.0.CR1 -DgroupId=org.whatever.project -DartifactId=myprojectname -DarchetypeRepository=http://repository.jboss.org/maven2/ | |||
| RichFaces Basic | mvn archetype:generate -DarchetypeGroupId=org.jboss.portletbridge.archetypes -DarchetypeArtifactId=richfaces-basic -DarchetypeVersion=2.0.0.CR1 -DgroupId=org.whatever.project -DartifactId=myprojectname -DarchetypeRepository=http://repository.jboss.org/maven2/ | |||
| Seam Basic (Modular EAR) | mvn archetype:generate -DarchetypeGroupId=org.jboss.portletbridge.archetypes -DarchetypeArtifactId=seam-basic -DarchetypeVersion=2.0.0.CR1 -DgroupId=org.whatever.project -DartifactId=seamproject -DarchetypeRepository=http://repository.jboss.org/maven2/ | |||
The Maven-Cargo setup mentioned below is completely optional. It gives users who are new to the bridge or ones who may have problems running the bridge in their current setup, a completely fresh install of both JBoss AS and JBoss Portal to run against - with only a few commands. This setup only requires that the latest versions of Java and Maven be installed on your machine, and the following 3 commands will take care of the rest.
To see a step-by-step tutorial of this setup in action, follow along here:
Lesson 1: Getting Started With The BridgeEach example application is configured to download the latest versions of JBoss Portal bundled with JBoss Application Server. After running the archetype Section 1.4, “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.
JBoss Portal 2.7.2.GA + JBoss AS 4.2.3 (Bundled download)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.
1. mvn install -Plocal-portal cargo:start
2. mvn cargo:deploy -Plocal-portal
3. visit http://localhost:8080/portal
1. mvn install cargo:start -Dlocal -Plocal-portal -DJBOSS_ZIP_HOME=/{path to zipped portal + JBoss AS}/jboss-portal-2.7.2-bundled.zip -DJBOSS_HOME_DIR=jboss-portal-2.7.2-bundled/jboss-portal-2.7.2
2. mvn cargo:deploy -Plocal-portal
3. visit http://localhost:8080/portal