Sun Java System Portal Server 7.1 Developer's Guide

Chapter 12 Deploying Struts Application as a Portlet in Portal Server

This chapter describes how to deploy any existing struts application as a JSR 168 portlet in Portal Server. Using the steps mentioned in this document, the entire Struts application can be deployed within a channel on the portal server desktop. This chapter contains the following sections:

Preparing the Struts Application

This section explains how to prepare the Struts application.

Introduction

The extended struts framework shipped with Portal Server is an extension of Struts version 1.2.4. This requires that you must download Standard Struts binary, version 1.2.4, from the struts archive page, and the application must be tested as a standalone application, using standard struts.jar file. This is to ensure that you have the proper version of all the supporting JARs required by the struts framework.

Install Portal Server 7.1 for extended struts framework (struts.jar file) and supporting components (strutssupport.jar, portlet.jar) required to deploy Struts application as JSR 168 portlet.

Modify Struts Application

To deploy any struts application as a portlet, the struts application is required to follow these guidelines:

The Struts application must abide by the restrictions applicable to any application running in the Portal Server. For example, the request parameters in the struts application can not use keywords reserved by the portal server. The list of reserved words include action, provider, targetprovider, containerName, last, page", error, container, selected, editChannelName, targetPortletChannel, and currentChannelMode.
All the forms and links must be created using struts tag library. Struts tag library provide <html:form> and <html:link> for this purpose.
JSP and HTML must not have HTML title, body, frame and base tags. JSP must not use forward and/or redirect.

Obtain Portlet Objects in Struts Application

It is possible for struts application to get hold of portlet objects such as ActionRequest and ActionResponse. This may be required, for example, to implement EDIT functionality. However, if portlet objects are not used properly, the use of portlet objects in struts application may make it portal dependent and result in the struts application unusable as a standalone application.

The struts Action class can obtain javax.portlet.ActionRequest and javax.portlet.ActionResponse objects using the following calls:

ActionRequest aReq = (ActionRequest) request.getAttribute("javax.portlet.request");
ActionResponse aRes = (ActionResponse) request.getAttribute("javax.portlet.response");

The above two statements return javax.portlet.RenderRequest and javax.portlet.RenderResponse respectively, when called from a JSP page.

Session Information

If any struts application, deployed as a portlet, is invalidating the session using session.invalidate(), the session obtained by the struts-portlet bridge becomes the invalid one. Because of this, the bridge is unable to store rendering related information. In application server, struts application, deployed as a portlet, must not use session.invalidate() as the same session is used by struts portlet bridge.

Creating and Modifying XML Files

This section explains how to create and modify XML files.

Modifying `struts-config.xml` File

Change the RequestProcessor to org.apache.struts.action.PortletRequestProcessor or org.apache.struts.tiles.PortletTilesRequestProcessor, if the application is using Tiles.

For example:

<controller 
contentType="text/html;charset=UTF-8"
debug="3"
locale="true"
processorClass="org.apahce.struts.action.PortletRequestProcessor">
<!-- The "input" parameter on "action" elements is the name of a
local or global "forward" rather than a module-relative path -->
<set-property property="inputForward" value="true"/>
</controller>

Creating `portlet.xml` File

Every portlet WAR must have one portlet.xml file in the WEB-INF directory of the web application. When creating the portlet.xml file, note that:

The Portlet class must be org.apache.struts.action.StrutsPortlet.
The initPage init parameter is mandatory and its value must be the welcome page of the struts application. This can be a direct reference to a JSP file (such as /index.jsp) or it can be a reference of Action Mapping Definition (such as /welcome.do).
The editPage init parameter is not mandatory. If specified, portlet mode EDIT must also be specified in <supports> tag and vice-versa.
The helpPage init parameter is not mandatory. If specified, portlet mode HELP must also be specified in <supports> tag and vice-versa. Note that the help page support is limited to a single page and it can not provide navigation to any other page within struts application.
The factoryName init parameter is mandatory and must be set to com.sun.portal.struts.wrapper.PSServletObjectsFactory.
All the init parameters associated with the ActionServlet as defined in web.xml file must also be configured as init parameter in portlet.xml file.
The URL mapping used for ActionServlet as defined in web.xml file must be configured as an init parameter of the portlet.

Here is a sample portlet.xml file for struts-portlet application:

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns="http://java.sun.com/xml/ns/
portlet/portlet-app_1_0.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://java.sun.com/xml/ns/portlet
/porlet-app_1_0.xsd" version="1.0">

<portlet>
	<portlet-name>StrutsPortlet</portlet-name>
	<portlet-class>org.apache.struts.action.
	StrutsPortlet</portlet-class>
	<init-param>
		<name>initPage</name>
		<value>/index.jsp</value>
	</init-param>
	<init-param>
		<name>helpPage</name>
		<value>/tour.htm</value>
	</init-param>
	<init-param>
		<name>editPage</name>
		<value>/edit.jsp</value>
	</init-param>
	<init-param>
		<name>factoryPage</name>
		<value>com.sun.portal.struts.wrapper.
		PSServletObjectsFactory</value>
	</init-param>
	<init-param>
		<name>config</name>
		<value>/WEB-INF/struts-config.xml,/WEB-INF/
		struts-config-registration.xml</value>
	</init-param>
	<init-param>
		<name>servletPage</name>
		<value>*.do</value>
	</init-param>
		<expiration-cache>0</expiration-cache>
		<supports>
			<mime-type>text/html</mime-type>
			<portlet-mode>HELP</portlet-mode>
			<portlet-mode>EDIT</portlet-mode>
		</supports>
	<portlet-info>
		<title>StrutsPortlet</title>
	</portlet-info>
	</portlet>
</portlet-app>

Building and Deploying the Web Application as a Portlet Application

Follow the procedure to deploy the struts application as a portlet.

To Deploy the Struts Application as a Portlet

Replace standard struts.jar file, in the WEB-INF/lib directory, with the extended struts.jar file shipped Portal Server.

Add strutssupport.jar file and portlet.jar file shipped with Portal Server in the WEB-INF/lib directory.

Copy the newly created portlet.xml file and modified struts-config.xml file to the WEB-INF directory.

Create the .war file for the application.

Deploy the newly created WAR file using the psadmin deploy-portlet command. For example, type ./psadmin deploy-portlet -u amadmin -f passwordfile -p portalId -i portalinstance -g warfile.