« Back to Upgrade Instructions

Upgrade Instructions from 5.0 to 5.1

This upgrade is recommended to anyone running the 5.0.x branch as well as for those that want to benefit from the New Features in Liferay Portal v5.1

Prerequisite #

It's recommended to upgrade first to 5.0.1. An automatic upgrade from 4.4 might also work (but again is not recommended)

Basic Installation Outline #

  1. Undeploy the old version of Liferay, and then shut down your application server. For Tomcat, you'd delete the ROOT folder from <Tomcat Home>/webapps.
  2. Copy the new versions of the dependency .jars to a location on your server's classpath, overwriting the ones you already have for the old version of Liferay. For Tomcat, these are stored in <Tomcat Home>/common/lib/ext.
  3. Deploy the new Liferay .war file. This is different by application server. For Tomcat, you'd create a ROOT folder in <Tomcat Home>/webapps and unzip the .war file there.
  4. Delete your tomcat class cache ie <Tomcat Home>/work/localhost/ as sometimes tomcat will load class' from the previous version of Liferay instead of the new version
  5. Start (or restart) your application server. Liferay should come up.

Changes in configuration properties #

How to keep the old values #

The default values of some properties has been changed. In order to keep the previous values you have to run Liferay passing the following system property:

 java ... -Dexternal-properties=portal-legacy-5.0.properties

Each application server has different methods to add this system property. In Tomcat modify catalina.sh/catalina.bat or catalina.conf (depending on the exact version you are using).

What has been changed? #

Here is a description of the most significant changes. Check the file portal-legacy-5.0.properties for a full list of properties changed.

  • layout.user.private.layouts.power.user.required: It's no longer required to be Power User to have a personal community. This new property allows falling back to the old behavior. For details about the changes and how to take them into consideration, see the article on personal communities.
  • permissions.user.check.algorithm: the default value is now a new algorithm that is much faster.
  • Company-specific portal.properties files (e.g., portal-liferay.com.properties) can no longer be used. Changes specific to the company can only be done via the GUI.

Changes to the ext environment #

Following is a list of API changes. If you used the ext environment to develop custom code review the following items and adapt your code accordingly:

  • Several classes have been moved from portal-impl to portal-kernel to make them available to plugins. If you were using any of those classes you will have to change the import package.
  • The JSPPortlet class has been moved to util-bridges so that it can be used from plugins. In order to adapt to this change do the following:
    • Any references to com.liferay.portlet.JSPPortlet need to be changed to com.liferay.util.bridges.jsp.JSPPortlet
    • Check that the paths to your JSP files in portlet.xml are absolute paths (from the docroot). For example, if your view.jsp lives in {docroot}/html/, set your view-jsp to "/html/view.jsp"
  • Error handling has been changed (in order to provide a better end-user experience). The following construct:

catch (Exception e) { req.setAttribute(PageContext.EXCEPTION, e); return mapping.findForward(ActionConstants.COMMON_ERROR); } }}} should be replaced with

 catch (Exception e) { PortalUtil.sendError(e, request, response); return null; } }}} Note that you can also optionally include an 
HttpServletResponse
code in the
sendError
method.

Note: this list is not yet complete.

Upgrading Themes #

There were a few changes between the Classic theme in 5.0 and the Classic theme in 5.1. However, these changes were predominantly CSS only changes, but if you built your theme from the plugins directory, and used the _diffs directory and placed your CSS changes in custom.css, you may need to make a few adjustments to your CSS.

New css file #

No matter how you created your theme, you will more than likely need to include a file called application.css. The list of these files is located in /css/main.css. At the top, right after base.css, you would add this line: @import url(application.css);

This file includes all of the styling that is used for application elements, such as dialogs, inline popups, tabs, tags, and other elements.

Some rules were added (that may need to be overwritten for your theme) and some rules were removed (and may need to be readded). If however, your theme is already built, and you edited the files directly, for the most part, you won't be affected. Overall, most changes are minor, but there are a couple that could cause confusion.

The parent element of the Dock may change positioning when upgrading. #

In 5.1 we made a change to the Dock javascript which is a fix, but older themes may rely on the "buggy" behavior. Essentially, the css positioning of the Dock's parent was always set to "relative", however, there are often times when a theme requires that it uses a different positioning. The script now looks to see what the theme developer has specified, and uses that. There is, however, one caveat. Sometimes, you absolutely must not have a positioned parent at all. The script, however, needs a positioned parent in most cases, and will apply one whenever the css position is set to "position: static;", since that is what the browser will return if no positioning is applied. So the problem in that sitation is that if you must have "position: static" the script will always overwrite it. In order to account for this, we've added checking so that if your CSS selector has these two rules: "position: static; top: 0;" then it will use static positioning. The thinking is that because setting top: 0 on a statically positioned item has no effect visually, we use it as a trigger to say that you really want to use static positioning. However, it now will allow you to define other positioning (absolute, relative, or fixed) without worrying about your defined styling being overwritten.

The class names for different UI components have changed #

One of the only changes that will have a real impact is that we've changed from ".popup" for the inline popups, to instead using ".ui-dialog". We've also made other class name changes, but left them on the elements for now so that breakages will be kept to a minimum. However, default styling for those class names have been removed from classic.

The class names that have been changed are as follows:

  • .portlet-section-header is now .results-header
  • .portlet-section-body is now .results-row
  • .portlet-section-body-hover is now .results-row.hover
  • .portlet-section-alternate is now .results-row.alt
  • .portlet-section-alternate-hover is now .results-row.alt.hover
  • .popup is now .ui-dialog
  • .tabs is now .ui-tabs
  • .tag is now .ui-tag
  • .autocomplete-box is now .ui-autocomplete-results
  • .drag-indicator is now .ui-proxy

Change in Theme CSS Fast Load#

In 5.0.1, the default setting for

theme.css.fast.load
was
false
which means that when you edited the deployed css files, the changes would take effect immediately on the next page load. Now, for the sake of better out of the box performance, the default in 5.1 has been changed to
true
. Of course this means that when you edit the deployed css files directly, you would NOT see the changes take effect immediately on the next page load, but rather you would have to make the change in the pre-deployed theme and run the deploy process on the theme for the changes to be bundled and packed into the
everything_packed.css
file.

This of course might make it harder for theme developers to do real-time testing. So, the solution to get the old behavior is simply to revert

theme.css.fast.load
to
false
and restart the portal.

Change in Javascript Fast Load#

For the same reasons as described in Change in Theme CSS Fast Load, a change was made to

javascript.fast.load
from
false
to
true
.

You may want to revert it to

false
for the same reason.

Upgrading PHP Portlets #

Some changes were made to the handling of PHP portlets, including the addition of new init-param values (see: http://support.liferay.com/browse/LEP-6465 ). Also, major changes to util-java classes (such as the elimination of StringMaker, for example) requires that some of the JARs in WEB-INF/lib be updated.

To upgrade an old PHP portlet, first make a back-up of your existing portlet. Then take the PHP portions (including HTML, images, CSS, javascript), create a ZIP, and re-deploy through the Plug-In Installer. Liferay, as usual, will inject the needed files, including everything in the WEB-INF directory, the Quercus libraries, and so forth.

If you are uneasy about this approach, you can also deploy an empty index.php file in a ZIP through the Plug-In Installer and then use the result to do a "DIFF" of your existing portlet with the injected portions of the new portlet. Then you can manually update just the parts that need to be changed in your existing portlet. This might useful, for example if you want to make sure the ID of your portlet does not change (especially if you have many instances scattered throughout your site), or if you've been using the liferay-plugin-package.xml file to keep track of versions and compatibility.

Javascript changes #

The Javascript in Liferay has undergone a refactoring to use the jQuery UI engine, upgrading jQuery to the latest version (version 1.2.6 in Liferay 5.1), and removing the Interface library. We've also removed and changed many of our methods that were polluting the global namespace and/or not being used anymore.

Changed methods #

addPortlet, addPortletHTML These have now been changed to Liferay.Portlet.add() and Liferay.Portlet.addHTML(), respectively.

showLayoutTemplates This is now Liferay.Layout.showTemplates().

StarRating, ThumbnailRating, Tooltip, Tabs These are now Liferay.Portal.StarRating(), Liferay.Portal.ThumbnailRating(), Liferay.Portal.Tooltip, and Liferay.Portal.Tabs respectively.

Element.disable Please use Liferay.Util.disableElements()

Element.remove Please use jQuery(selector).remove();

Viewport.frame, Viewport.scroll, Viewport.page These are now Liferay.Util.viewport.frame(), Liferay.Util.viewport.scroll(), and Liferay.Util.viewport.page(), respectively.

Removed Javascript methods #

AjaxUtil, AjaxRequest, and loadPage Please use jQuery.ajax or any of the other jQuery AJAX methods (see Liferay UI Guidelines).

LinkedList, NavFlyout, DragLink, PhotoSlider, PortletHeaderBar No longer needed.

Coordinates, Coordinate, MousePos No longer needed. If you need mouse coordinates during an event (such as onMousemove, onMouseover, if you're attaching events with jQuery, you can reliably use the event.pageX and event.pageY properties, like so: jQuery(window).mousemove( function(event){ var x = event.pageX; var y = event.pageY; } ); )

Liferay.Util.toJSONString, Liferay.Util.toJSONObject No longer needed. You can use jQuery.parseJSON(str) and jQuery.toJSON(obj) respectively.

Liferay.Util.getSelectedIndex No longer needed, as it was being used to select the "checked" item in a group of radio buttons. To do the same thing, you would do something like: jQuery(Element|Selector).filter(':checked');

If you absolutely must have the actual numerical index of the selected item, you could do: var radioGroup = jQuery(Element|Selector); var index = radioGroup.index(radioGroup.filter(':checked')[0]);

Upgrade Troubleshooting #

There are no known issues so far, if the above instructions are followed appropriately

0 Attachments
38733 Views
Average (0 Votes)
The average rating is 0.0 stars out of 5.
Comments
Threaded Replies Author Date
I'm getting a table error from 5.0.1 RC to... Ryan McKeel July 22, 2008 1:22 PM
I've got the same error The above upgrade... Elvin Wong November 13, 2008 10:10 PM
What happened to the mail portlet and the... Asai Vanson July 22, 2008 2:45 PM
Would really help if the changes to default... sameer danthurthy July 24, 2008 8:23 AM
updradation form 5.0 to 5.1 what is the version... siva sankar March 16, 2011 3:53 AM

I'm getting a table error from 5.0.1 RC to 5.1.0. Does this make sense to the developers? Should this be part of the migration instructions?

20:18:21,025 ERROR [QuartzSchedulerEngineImpl:84] Unable to initialize engine
org.quartz.SchedulerConfigException: Failure occured during job recovery. [See nested exception: org.quartz.JobPersistenceException: Couldn't clean volatile data: Table 'l_portal.QUARTZ_TRIGGERS' doesn't exist [See nested exception: com.mysql.jdbc.exceptions.MySQLSyntaxErrorException: Table 'l_portal.QUARTZ_TRIGGERS' doesn't exist]]
at org.quartz.impl.jdbcjobstore.JobStoreSupport.initialize(JobStoreSupport.java:557­)
at org.quartz.impl.jdbcjobstore.JobStoreTX.initialize(JobStoreTX.java:59)
at org.quartz.impl.StdSchedulerFactory.instantiate(StdSchedulerFactory.java:1204)
at org.quartz.impl.StdSchedulerFactory.getScheduler(StdSchedulerFactory.java:1355)
at com.liferay.portal.scheduler.quartz.QuartzSchedulerEngineImpl.<init>(QuartzSched­ulerEngineImpl.java:81)
at com.liferay.portal.scheduler.quartz.QuartzSchedulerEngineUtil.init(QuartzSchedul­erEngineUtil.java:56)
at com.liferay.portal.events.GlobalStartupAction.run(GlobalStartupAction.java:225)
at com.liferay.portal.events.EventsProcessor._processEvent(EventsProcessor.java:167­)
at com.liferay.portal.events.EventsProcessor._process(EventsProcessor.java:119)
at com.liferay.portal.events.EventsProcessor.process(EventsProcessor.java:55)
at com.liferay.portal.servlet.MainServlet.init(MainServlet.java:422)
at javax.servlet.GenericServlet.init(GenericServlet.java:212)
at org.apache.catalina.core.StandardWrapper.loadServlet(StandardWrapper.java:1139)
at org.apache.catalina.core.StandardWrapper.load(StandardWrapper.java:966)
at org.apache.catalina.core.StandardContext.loadOnStartup(StandardContext.java:3956­)
at org.apache.catalina.core.StandardContext.start(StandardContext.java:4230)
at org.apache.catalina.core.ContainerBase.addChildInternal(ContainerBase.java:760)
at org.apache.catalina.core.ContainerBase.addChild(ContainerBase.java:740)
at org.apache.catalina.core.StandardHost.addChild(StandardHost.java:544)
at org.apache.catalina.startup.HostConfig.deployDescriptor(HostConfig.java:626)
at org.apache.catalina.startup.HostConfig.deployDescriptors(HostConfig.java:553)
at org.apache.catalina.startup.HostConfig.deployApps(HostConfig.java:488)
at org.apache.catalina.startup.HostConfig.start(HostConfig.java:1149)
at org.apache.catalina.startup.HostConfig.lifecycleEvent(HostConfig.java:311)
at org.apache.catalina.util.LifecycleSupport.fireLifecycleEvent(LifecycleSupport.ja­va:120)
at org.apache.catalina.core.ContainerBase.start(ContainerBase.java:1022)
at org.apache.catalina.core.StandardHost.start(StandardHost.java:736)
at org.apache.catalina.core.ContainerBase.start(ContainerBase.java:1014)
at org.apache.catalina.core.StandardEngine.start(StandardEngine.java:443)
at org.apache.catalina.core.StandardService.start(StandardService.java:448)
at org.apache.catalina.core.StandardServer.start(StandardServer.java:700)
at org.apache.catalina.startup.Catalina.start(Catalina.java:552)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.jav­a:25)
at java.lang.reflect.Method.invoke(Method.java:597)
at org.apache.catalina.startup.Bootstrap.start(Bootstrap.java:295)
at org.apache.catalina.startup.Bootstrap.main(Bootstrap.java:433)
Caused by: org.quartz.JobPersistenceException: Couldn't clean volatile data: Table 'l_portal.QUARTZ_TRIGGERS' doesn't exist [See nested exception: com.mysql.jdbc.exceptions.MySQLSyntaxErrorException: Table 'l_portal.QUARTZ_TRIGGERS' doesn't exist]
at org.quartz.impl.jdbcjobstore.JobStoreSupport.cleanVolatileTriggerAndJobs(JobStor­eSupport.java:736)
at org.quartz.impl.jdbcjobstore.JobStoreSupport$1.execute(JobStoreSupport.java:697)­
at org.quartz.impl.jdbcjobstore.JobStoreSupport$40.execute(JobStoreSupport.java:362­8)
at org.quartz.impl.jdbcjobstore.JobStoreSupport.executeInNonManagedTXLock(JobStoreS­upport.java:3662)
at org.quartz.impl.jdbcjobstore.JobStoreSupport.executeInNonManagedTXLock(JobStoreS­upport.java:3624)
at org.quartz.impl.jdbcjobstore.JobStoreSupport.cleanVolatileTriggerAndJobs(JobStor­eSupport.java:693)
at org.quartz.impl.jdbcjobstore.JobStoreSupport.initialize(JobStoreSupport.java:555­)
... 37 more
Caused by: com.mysql.jdbc.exceptions.MySQLSyntaxErrorException: Table 'l_portal.QUARTZ_TRIGGERS' doesn't exist
at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:936)
at com.mysql.jdbc.MysqlIO.checkErrorPacket(MysqlIO.java:2985)
at com.mysql.jdbc.MysqlIO.sendCommand(MysqlIO.java:1631)
at com.mysql.jdbc.MysqlIO.sqlQueryDirect(MysqlIO.java:1723)
at com.mysql.jdbc.Connection.execSQL(Connection.java:3256)
at com.mysql.jdbc.PreparedStatement.executeInternal(PreparedStatement.java:1313)
at com.mysql.jdbc.PreparedStatement.executeQuery(PreparedStatement.java:1448)
at org.apache.tomcat.dbcp.dbcp.DelegatingPreparedStatement.executeQuery(DelegatingP­reparedStatement.java:93)
at org.quartz.impl.jdbcjobstore.StdJDBCDelegate.selectVolatileTriggers(StdJDBCDeleg­ate.java:3491)
at com.liferay.portal.scheduler.quartz.DynamicDriverDelegate.selectVolatileTriggers­(DynamicDriverDelegate.java:567)
at org.quartz.impl.jdbcjobstore.JobStoreSupport.cleanVolatileTriggerAndJobs(JobStor­eSupport.java:714)
... 43 more
20:18:21,027 ERROR [GlobalStartupAction:228] java.lang.NullPointerException
java.lang.NullPointerException
at com.liferay.portal.scheduler.quartz.QuartzSchedulerEngineImpl.start(QuartzSchedu­lerEngineImpl.java:193)
at com.liferay.portal.scheduler.quartz.QuartzSchedulerEngineUtil.init(QuartzSchedul­erEngineUtil.java:58)
at com.liferay.portal.events.GlobalStartupAction.run(GlobalStartupAction.java:225)
at com.liferay.portal.events.EventsProcessor._processEvent(EventsProcessor.java:167­)
at com.liferay.portal.events.EventsProcessor._process(EventsProcessor.java:119)
at com.liferay.portal.events.EventsProcessor.process(EventsProcessor.java:55)
at com.liferay.portal.servlet.MainServlet.init(MainServlet.java:422)
at javax.servlet.GenericServlet.init(GenericServlet.java:212)
at org.apache.catalina.core.StandardWrapper.loadServlet(StandardWrapper.java:1139)
at org.apache.catalina.core.StandardWrapper.load(StandardWrapper.java:966)
at org.apache.catalina.core.StandardContext.loadOnStartup(StandardContext.java:3956­)
at org.apache.catalina.core.StandardContext.start(StandardContext.java:4230)
at org.apache.catalina.core.ContainerBase.addChildInternal(ContainerBase.java:760)
at org.apache.catalina.core.ContainerBase.addChild(ContainerBase.java:740)
at org.apache.catalina.core.StandardHost.addChild(StandardHost.java:544)
at org.apache.catalina.startup.HostConfig.deployDescriptor(HostConfig.java:626)
at org.apache.catalina.startup.HostConfig.deployDescriptors(HostConfig.java:553)
at org.apache.catalina.startup.HostConfig.deployApps(HostConfig.java:488)
at org.apache.catalina.startup.HostConfig.start(HostConfig.java:1149)
at org.apache.catalina.startup.HostConfig.lifecycleEvent(HostConfig.java:311)
at org.apache.catalina.util.LifecycleSupport.fireLifecycleEvent(LifecycleSupport.ja­va:120)
at org.apache.catalina.core.ContainerBase.start(ContainerBase.java:1022)
at org.apache.catalina.core.StandardHost.start(StandardHost.java:736)
at org.apache.catalina.core.ContainerBase.start(ContainerBase.java:1014)
at org.apache.catalina.core.StandardEngine.start(StandardEngine.java:443)
at org.apache.catalina.core.StandardService.start(StandardService.java:448)
at org.apache.catalina.core.StandardServer.start(StandardServer.java:700)
at org.apache.catalina.startup.Catalina.start(Catalina.java:552)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.jav­a:25)
at java.lang.reflect.Method.invoke(Method.java:597)
at org.apache.catalina.startup.Bootstrap.start(Bootstrap.java:295)
at org.apache.catalina.startup.Bootstrap.main(Bootstrap.java:433)

Thanks,

Ryan
Posted on 7/22/08 1:22 PM.
What happened to the mail portlet and the workflow portlet and the chat portlet? Can you please post where to find these things now?
Posted on 7/22/08 2:45 PM.
Would really help if the changes to default settings are published.
Posted on 7/24/08 8:23 AM.
I've got the same error

The above upgrade guide seems need quite an effort to improve.
Posted on 11/13/08 10:10 PM in reply to Ryan McKeel.
updradation form 5.0 to 5.1 what is the version I need to take for new Liferay .war?

what is the liferay.war?
Is it ext environment for 5.1?
If I take the 5.1 ext environment war file my old files where i need to place it?
Posted on 3/16/11 3:53 AM.