Deploying JSF Portlets on Oracle WebLogic
This tutorial first shows how to install Liferay Portal on WebLogic, then shows how to deploy JSF portlets. Note that this tutorial assumes that you are using Liferay Portal 6.1.
Download Oracle WebLogic Server #
Download wls1036_dev.zip (WebLogic Server 10.3.6.0) from the OTN Downloads page
Install Oracle WebLogic Server #
Step 1: Define the JAVA_HOME environment variable:
# Example Mac syntax export JAVA_HOME=`/usr/libexec/java_home`
Step 2: Define the USER_MEM_ARGS environment variable:
export USER_MEM_ARGS="-Xms512m -Xmx1024m -XX:MaxPermSize=256m"
Step 3: Define the Oracle Middleware MW_HOME environment variable:
Step 4: Create the Oracle Middleware folder:
mkdir -p $MW_HOME
Step 5: Switch to the new folder:
Step 6: Extract wls1036_dev.zip into $HOME/Oracle/Middleware
Step 7: Verify that you have the following folder hierarchy:
Step 8: Execute the WebLogic configuration script:
Step 9: Define additional WebLogic environment variables:
Configure WebLogic Server Domain #
Step 10: Run the WebLogic Configuration Wizard
Step 11: On the Welcome page, accept the default option and click Next
Step 12: On the Select Domain Source page, accept the default options and click Next
Step 13: On the Specify Domain Name and Location page, enter a domain name and location, then click Next.
Step 14: On the Configure Administrator User Name and Password page, enter a password and click Next.
Step 15: On the Configure Server Start Mode and JDK page, select "Development Mode" and click Next.
Step 16: On the Select Optional Configuration page, accept the default options and click Next.
Step 17: On the Configuration Summary Page, click Create.
Step 18: On the Creating Domain page, click Done.
Install Liferay Portal #
In order to install Liferay Portal in WebLogic Server, please follow the instructions in the Liferay documentation titled Installing Liferay on Oracle WebLogic 10.3. However, you must skip the following sections:
"Lastly, you must provide WebLogic a reference to Java Server Faces (JSF) to use that library"
"Select Deployments and click the Install button. Upload jsf-1.2.war from WebLogic’s common files directory and select Install this deployment as a library"
"Lastly, you must provide WebLogic a reference to Java Server Faces (JSF) to use that library. Insert the following deployment descriptor within the <weblogic-web-app> element of WEB-INF/weblogic.xml found in your Liferay Portal .war"
Those sections refer to installation of JSF 1.2 artifacts that prevent console errors in hot deployable portlets. This was necessary for Liferay Portal 6.1 because of some legacy JSF classes that reside in the util-bridges.jar and util-taglib.jar artifacts that are automatically copied into hot deployable portlet WARs.
Since Liferay Faces 3.x requires JSF 2.1, it is not appropriate to install a JSF 1.2 Shared Library. As described Upgrading Mojarra in Oracle WebLogic (Portlets), it is necessary to copy jsf-api-2.1.21.jar to the weblogic /lib folder in order to avoid the ViewExpiredException documented in FACES-1591. This also has the added benefit of providing the JSF API in the global classpath so that the legacy JSF classes that reside in util-bridges.jar and util-taglib.jar will load properly.
Disable Liferay Portal ETagFilter #
In order to avoid a ViewExpiredException with Ajax, the ETagFilter must be disabled in the portal-ext.properties file:
For more information, please refer to FACES-1591.
Environment Variables #
In order for memory settings to be permanently set, they need to be hard-coded in the startWebLogic.sh script. Just above the definition of DOMAIN_HOME, add the following line:
export MW_HOME=$HOME/Oracle/Middleware export USER_MEM_ARGS="-Xms512m -Xmx1024m -XX:CompileThreshold=8000 -XX:PermSize=128m -XX:MaxPermSize=256m"
Note that if you have many portlet WAR modules, you may need to increase memory. Here is an example of reserving 2X memory:
export MW_HOME=$HOME/Oracle/Middleware export USER_MEM_ARGS="-Xms1024m -Xmx2048m -XX:CompileThreshold=8000 -XX:PermSize=256m -XX:MaxPermSize=512m"
Debugger Settings (Optional) #
If you want to start WebLogic in debug mode, then set the following environment variable in the startWebLogic.sh script.
export JAVA_OPTIONS="$JAVA_OPTIONS -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,address=8453,server=y,suspend=n"
For more info, see Using WebLogic Server.
Configure WebLogic Global Class Path #
This section describes how to setup the WebLogic global classpath so that JSF 2.1 portlets can deploy and run correctly. The following screenshot depicts the folder hierarchy that is required:
Liferay Portal Dependencies #
JARs that must be present in the global classpath in order for Liferay Portal to work properly:
Mojarra JSF API and Implementation #
Liferay Faces 3.x requires JSF 2.1. For detailed upgrade instructions, please refer to Upgrading Mojarra in Oracle WebLogic (Portlets).
RichFaces & RichFaces Dependencies #
JARs that must be present in the global classpath in order for RichFaces to work properly:
These can either be copied to weblogic/lib, or deployed as a Shared Library, such as richfaces-shared-library that can be built from the Liferay Faces source. For more information, see Building Liferay Faces From Source and FACES-1594.
JSR 329 Portlet Bridge TCK Dependencies #
JARs that are necessary only for running the JSR 329 Portlet Bridge TCK:
For more information, see FACES-1599.
Configuring WEB-INF/weblogic.xml #
In order for JSF 2.1 portlets to deploy correctly in WebLogic, the WEB-INF/weblogic.xml descriptor must be configured to fine-tune how class loading takes place. For a working example, please refer to the weblogic.xml descriptor from the jsf2-portlet demo source code.
In order to have a portlet WAR utilize the Mojarra Shared Library, it must include the following in WEB-INF/weblogic.xml:
<wls:library-ref> <wls:library-name>jsf</wls:library-name> </wls:library-ref>
Portlet WAR Dependencies #
Mojarra Libraries #
Since the Mojarra API and Implementation JARs are present in the global classpath, jsf-api.jar and jsf-impl.jar must not be included in WEB-INF/lib.
XML Parser #
Due to a deficiency in the XML parser that ships with WebLogic, it is necessary to include a cusom Apache Xerces parser as a dependency. In order to include it in the proper position within the WebLogic classpath, the Xerces jars are included in the Mojarra Shared Library. Therefore, it is not necessary to add Xerces as a dependency in the portlet's WEB-INF/lib folder.
In order to ensure that WebLogic will always invoke the Xerces SAXParser implementation before others, add the following to the top of the startWebLogic.sh script:
export JAVA_OPTIONS="$JAVA_OPTIONS -Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl"
For more information, see: FACES-1726.
In general, ICEfaces JARs may exist in WEB-INF/lib. However, until PUSH-247 is fixed, it will not be possible for icepush.jar to live alongside icefaces.jar in WEB-INF/lib.
For more information, see FACES-1598.
The primefaces.jar dependency may exist in WEB-INF/lib.
Aside from the RichFaces JARs that must live in the global classpath, all other RichFaces dependencies may exist in WEB-INF/lib.
In order to have a portlet WAR utilize the RichFaces Shared Library, it must include the following in WEB-INF/weblogic.xml:
<wls:library-ref> <wls:library-name>richfaces</wls:library-name> </wls:library-ref>