Overview

The following information should provide a useful recipe on the necessary steps to migrate portlets developed under GridSphere 2.X to GridSphere 3.X. The most important change in GS 3, is that the old WebSphere-style portlet API is no longer supported. This means you WILL have to first migrate the portlets to use the JSR 168 Portlet API. If you are in this situation, you should probably do this before migrating to GS 3.

Update project from template build script

 If you created your portlet project using the ant new-project target provided by GridSphere, then you will need to update the build.xml file in your project. Please follow the steps below:

1) Place your existing project in the gridsphere/projects directory (where gridsphere is version 3.x) 

2) From the gridsphere directory, issue ant update-project  and enter the project web app name when prompted. After, you will find a backup of your old build.xml has been saved to build.xml.bak.

3) Add the following properties to your build.properties file:

# if there are any dependencies, an integer must be specified here which will  determine the ordering for when this app gets starting from smallest to largest
project.priority=
# if this project provides any portlet services used by another portlet application, then the value should be set to true
project.shared=false

If you've made numerous edits to your existing build.xml, then you should compare the new build.xml file with your backup in build.xml.bak and you will have to sort the differences out by hand

Remove gridlab namespace

The gridlab namespace has been removed! This means that you must do a global search and replace in your codebase for org.gridlab.gridsphere and replace it with  org.gridsphere

Make sure you do this for ALL files in your application! Most IDE's can do this for you pretty effectively.

Remove PortletLog references

The PortletLog class has been removed! Now you must use either Log4J or Jakarta Commons logging. It is recommended that you use Commons logging since it provides an abstraction layer on top of all logging subsystems such that you can still use Log4J. 

Replace all lines of the following:

PortletLog log = SportletLog.getInstance with Log log = LogFactory.getLog

Your IDE should easily allow you to import the new package names, but if it doesn't you will need to add the following to your imports:

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

PersistenceManager is now a service

In GS3, the PersistenceManager is a service which means that you will have to replace these lines:

PersistenceManagerRdbms pm = PersistenceManagerFactory.createPersistenceManagerRdbms("WEB_APP_NAME"); 

with:

PersistenceManagerService persistService = (PersistenceManagerService)PortletServiceFactory.createPortletService(PersistenceManagerService.class, true);
PersistenceManagerRdbms pm = persistService.createPersistenceManagerRdbms("WEB_APP_NAME");

where WEB_APP_NAME is the name of the webapp as it is deployed to the servlet container webapps directory. 

Remove descriptor files that are no longer used

 You can safely remove the following files from your webapp/WEB-INF directory:

gridsphere-portlet.xml
group.xml
roles.xml 
layout.xml 

 Edit web.xml

If you see any lines that look like the following in webapp/WEB_INF/web.xml, please remove them:

<context-param>
    <!-- preferred repository selector. "preferred" because
         if one is already installed, this choice is ignored. -->
    <param-name>log4j-selector</param-name>
    <param-value>org.apache.log4j.selector.ContextJNDISelector</param-value>
</context-param>
<context-param>
    <!-- relative path to config file within current webapp -->
    <param-name>log4j-config</param-name>
    <param-value>WEB-INF/classes/log4j.properties</param-value>
</context-param>

<listener>
    <listener-class>org.apache.log4j.servlet.InitContextListener</listener-class>
</listener>
...

<env-entry>
    <description>JNDI logging context for this app</description>
    <env-entry-name>log4j/logging-context</env-entry-name>
    <env-entry-value>YOUR_WEB_APP_NAME</env-entry-value>
    <env-entry-type>java.lang.String</env-entry-type>
</env-entry>

Update Hibernate version

If you are using the PersistenceManager in your services, then you will also need to update Hibernate to version 3. Here are the necessary steps:

1) In webapp/WEB-INF/persistence directory, edit the hibernate.properties file

Replace any occurrence of net.sf.hibernate with org.hibernate 

2) In webapp/WEB-INF/persistence directory, edit all of your hibernate mapping files e.g. XXX.hbm.xml

replace

<!DOCTYPE hibernate-mapping PUBLIC
    "-//Hibernate/Hibernate Mapping DTD 1.1//EN"
    "http://hibernate.sourceforge.net/hibernate-mapping-2.0.dtd">

with

<!DOCTYPE hibernate-mapping PUBLIC
    "-//Hibernate/Hibernate Mapping DTD 1.1//EN"
    "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

Also make sure that you add default-lazy="false" as an attribute to all of the hibernate-mapping elements like so:

<hibernate-mapping default-lazy="false">

Unfortunately, if you use the PersistenceManager in your portlets, you cannot use the lazy loading features of Hibernate. The reason is that Hibernate core classes expect to find the POJOs in the same classpath. Since the Hibernate classes are in the gridsphere webapp, they cannot create proxy objects  of classes in your portlet  web application. If you have a good understanding of Hibernate and object relational mapping, you are probably better off including all the Hibernate libraries in your webapp and programming to it directly rather than use the PersistenceMangerService.

Passing request attributes in processAction method

Previously GridSphere allowed you to pass parameters as request attributes in your action method e.g.

public void actionMethod(ActionFormEvent event) {
request.setAttribute("foo", "bar");
...
}

1. If the parameter to be passed is a "navigational" parameter and a String, you can use:

   actionResponse.setRenderParameter("foo", "bar");
   

   and use

   request.getParameter("foo"); 
   

   in the corresponding render method to get the value.

2. Place the object to be transferred in a PortletSession.

request.getPortletSession().setAttribute("myObject", Object);

<%
   PortletSession ps = renderRequest.getPortletSession(false);
   Object myObject = ps.getAttribute("myObject");
%>

Furthermore, please have a look at the tag guide on using Action and Render links/buttons. Render links/buttons are a new feature designed to make it easier to create links/buttons that do not affect persisted state and are used only to change the navigation.

 Congratulations!

You should now be able run "ant install" and deploy the migrated web app to GridSphere!