JBoss Portlet Bridge

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, “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.

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.5, “Public Render Parmaeters” for details and examples.

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>

               

The basic JSR-329 portlet configuration.

      <portlet>

         <portlet-name>yourPortletName</portlet-name>

         <portlet-class>

            javax.portlet.faces.GenericFacesPortlet

         </portlet-class>



         <init-param>

            <name>javax.portlet.faces.defaultViewId.view</name>

            <value>/welcome.xhtml</value>

         </init-param>



         <init-param>

            <name>javax.portlet.faces.defaultViewId.edit</name>

            <value>/jsf/edit.xhtml</value>

         </init-param>



         <init-param>

            <name>javax.portlet.faces.defaultViewId.help</name>

            <value>/jsf/help.xhtml</value>

         </init-param>

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 the portlet request scope.

      <init-param>

         <name>javax.portlet.faces.preserveActionParams</name>

         <value>true</value>

      </init-param>

The PortletViewHandler ensures that each JSF portlet instance is properly namespaced.

        <faces-config>

            <application>

               <view-handler>

                  org.jboss.portletbridge.application.PortletViewHandler

               </view-handler>

               <state-manager>org.jboss.portletbridge.application.PortletStateManager</state-manager>

            </application>

            ...

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

        <web-app xmlns="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>

             <context-param>

                <param-name>javax.portlet.faces.RENDER_POLICY</param-name>

                <param-value>

                    ALWAYS_DELEGATE

                </param-value>

            </context-param>

            ...

        </web-app>

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

        <web-app xmlns="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">



             <context-param>

                <param-name>javax.portlet.faces.renderPolicy</param-name>

                <param-value>

                    NEVER_DELEGATE

                </param-value>

            </context-param>

            ...

        </web-app>

The Jboss Portlet Bridge can be used with a any compatible implementation ( for example, MyFaces implementation). Simply put the following into web.xml :

    <context-param>

        <param-name>javax.portlet.faces.BridgeImplClass</param-name>

        <param-value>org.apache.myfaces.portlet.faces.bridge.BridgeImpl</param-value>

    </context-param>

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.

Sometimes it is better to use the "ALL" load strategy in portlets so you do not need to worry about loading the "framework.pack.js" and "ui.pack.js" files manually in your portlet header.

            <context-param>

                <param-name>org.richfaces.LoadStyleStrategy</param-name>

                <param-value>ALL</param-value>

            </context-param>

            <context-param>

                <param-name>org.richfaces.LoadScriptStrategy</param-name>

                <param-value>ALL</param-value>

            </context-param>

            

The org.ajax4jsf.RESOURCE_URI_PREFIX configuration cross references the path to your scripts below. These settings are required for RichFaces using the "NONE" strategy.

    <script src="/faces/rfRes/org/ajax4jsf/framework.pack.js" type="text/javascript"></script>

    <script src="/faces/rfRes/org/richfaces/ui.pack.js" type="text/javascript"></script>

    <link rel="stylesheet" type="text/css" href="/faces/rfRes/org/richfaces/skin.xcss"/>

    

Seam automatically configures your Ajax4JSF Filter, so if you are running a Seam portlet, you do not need the following Filter config. (But you do need the RESOURCE_URI_PREFIX no matter what)

            <context-param>

                <param-name>org.ajax4jsf.RESOURCE_URI_PREFIX</param-name>

                <param-value>rfRes</param-value>

            </context-param>



            <filter>

                <display-name>Ajax4jsf Filter</display-name>

                <filter-name>ajax4jsf</filter-name>

                <filter-class>org.ajax4jsf.Filter</filter-class>

            </filter>



            <filter-mapping>

                <filter-name>ajax4jsf</filter-name>

                <servlet-name>FacesServlet</servlet-name>

                <dispatcher>FORWARD</dispatcher>

                <dispatcher>REQUEST</dispatcher>

                <dispatcher>INCLUDE</dispatcher>

            </filter-mapping>

            ...

        </web-app>

        

The ExceptionHandler is used to clean Seam contexts and transactions after errors.

      <context-param>

         <param-name>org.jboss.portletbridge.ExceptionHandler</param-name>

         <param-value>

            org.jboss.portletbridge.SeamExceptionHandlerImpl

         </param-value>

      </context-param>

      

For this 2.0.0.BETA release, you must define the following web.xml parameter to use the JBoss Portlet Bridge provided Seam Phase Listener.

      <context-param>

        <param-name>javax.faces.LIFECYCLE_ID</param-name>

        <param-value>SEAM_PORTLET</param-value>

      </context-param>

   

Just like with any portlet 2.0 event consumer and receiver, you must define them in the portlet.xml. To see a working example, checkout the Seam Booking Demo portlet. http://anonsvn.jboss.org/repos/portletbridge/tags/2.0.0.BETA/examples/seam/booking/

You must also define the following init params in your portlet.xml.

    </init-param>

      <init-param>

      <name>javax.portlet.faces.autoDispatchEvents</name>

      <value>true</value>

    </init-param>

      <init-param>

      <name>javax.portlet.faces.bridgeEventHandler</name>

      <value>org.foo.eventhandler</value>

    </init-param>



      

For now, you must dipatch the event in the JSF or Seam backing bean. Future versions on the 2.0 bridge will automate the dispatching and consuming of events.

   if (response instanceof StateAwareResponse) {

        StateAwareResponse stateResponse = (StateAwareResponse) response;

        stateResponse.setEvent(Foo.QNAME, new Bar());

    }

      

Then you must also create the event handler class by implementing the BridgeEventHandler interface to process the event payload.

   public class BookingEventHandler implements BridgeEventHandler

    {

       public EventNavigationResult handleEvent(FacesContext context, Event event)

       {

            //process event payload here

       }



    }

      

Public Render Parameters (or PRP) are one of the most powerful and simple Portlet 2.0 features. Several portlets (JSF or not) can share the same render parameters. This feature can be use to present a cohesive UI to the user across all portlets on the page (i.e. using an employee ID to display relative data).

The bridge maps a render parameter to a backing bean using settings in your faces-config.xml and portlet.xml. A clear and working example can be found in the Seam Booking Demo portlet. http://anonsvn.jboss.org/repos/portletbridge/tags/2.0.0.BETA/examples/seam/booking/

You must define the following init params in your portlet.xml.

    <init-param>

      <name>javax.portlet.faces.bridgePublicRenderParameterHandler</name>

      <value>org.foo.PRPHandler</value>

    </init-param>

    ...

    <supported-public-render-parameter>myCoolPRP</supported-public-render-parameter>

      

You must set the parameter in the JSF or Seam backing bean, if you are providing one from your portlet.

   if (response instanceof StateAwareResponse) {

        StateAwareResponse stateResponse = (StateAwareResponse) response;

        stateResponse.setRenderParameter("hotelName",selectedHotel.getName());

    }

      

Then you must also implement the BridgePublicRenderParameterHandler interface to process and updates from the received parameter.

   public void processUpdates(FacesContext context)

   {

      ELContext elContext = context.getELContext();

      BookingPRPBean bean = (BookingPRPBean) elContext.getELResolver().getValue(elContext, null, "bookingPRP");



    if(null != bean){

       //Do something with bean.getHotelName());

    } else {



    }

   }