One of the first things one wants to do with a new technology is to see it in action. This guide provides information so you can quickly take an existing JSF application, get it packaged with the bridge and deployed and running as a portlet. The procedure for using the Portlet 1.0 Bridge is the same as the Portlet 2.0 Bridge except the Portlet 2.0 Bridge can only run in a Portlet 2.0 container. Its recommended you match the version of the bridge with the version of the portlet container you are running.
If you don't have an existing JSF application, you can use one of the JSF samples that are part of the JSF reference implementation distribution. For information of using one of these samples, read Running_the_Mojarra_Samples.
Before beginning you must have portal/portlet container installed in an application server. If you don't otherwise have one installed, consider using Apache Tomcat 6.x along with either Pluto 1.1 (Portlet 1.0 container) or Pluto 2.0 (Portlet 2.0 container). Consult the install guides on their respective project pages for more information or refer to Setting_up_Portal_Environments_for_Bridge.
Before beginning you must verify whether Faces is installed as part of your server installation or not. In general, JavaEE 5 installations contain a Faces implementation. Tomcat however doesn't. If Faces is not already installed you will need to download it so its libraries can later be packaged directly into your sample .war. If you don't have a preference its recommended you use either the Apache MyFaces implementation or the reference implementation maintained in the Mojarra project. Note: If you are using the Mojarra implementation you will need to download a couple of dependent common libraries:
As many use cases also rely on JSP scripting its best to also check to see if the JSTL (1.2) libraries are installed. If they aren't download the JSTL library.
Finally, you will also need the Portlet Bridge libraries as this will also be packaged directly into your sample .war.
Convert your JSF Web Application into a Portlet Application
- If not already in a suitable desconstructed form, Explode/Unzip your application into the filesystem.
Add a portlet.xml to the application's WEB-INF directory. The version of your portlet.xml should coincide with the version of the portlet container. Within the portlet.xml add a new portlet tag entry for each portlet you want to expose from your application. Use javax.portlet.faces.GenericFacesPortlet as the value for the <portlet-class> tag. Add a portlet <init-param> for each portlet mode that you want bound to a default JSF view. This tells the bridge what JSF target to render for the specific mode when the incoming request isn't already encoded with a JSF target, e.g. the initial render. The <name> value for the <init-param> is javax.portlet.faces.defaultViewId.<portlet-mode> where <portlet-mode> is the name of the mode defining the default JSF target mapping. The <value> value for the <init-param> is the target JSF view. This value has the same form as used/referenced in a faces-config.xml navigation rule. I.e. its not the form that is servlet mapped rather the target result of that mapping.
- Add the portlet bridge jar files to your WEB-INF/lib directory. (Both the -api and -impl jars).
- If your installation doesn't contain a Faces implementation, add the jars for the version you downloaded (plus any dependent libraries) to your WEB-INF/lib directory.
- If pages rely on JSTL and the library isn't already installed, add the jar to your WEB-INF/lib directory.
- Repackage the above into a new .war file.
(re)Deploy the .war in your server. Note: portlet deployment is server dependent. Some servers can deploy a generic Portlet Application (.war) as we constructed above. Other servers require a manual or tool driven process to repackage a generic application for deployment in its environment. Consult the documentation for the portlet container running in your environment. For example, Pluto requires additional deployment information in the web.xml. This can be added manually or by adding rules in build scripts. Specifically, for each portlet in the portlet.xml Pluto requires a corresponding <serlvet> and <servlet-mapping> entry in the web.xml where portlet-name is the name used to identify the portlet in the portlet.xml (<portlet-name> tag):