Upgrading Liferay

Liferay upgrades are fairly straightforward. A consistent set of steps is all you need to follow to upgrade a standard Liferay installation. Things do get more complicated if your organization has used the extension environment to customize Liferay, as it is possible that API changes in the new version will break your existing code. This, however, is usually fairly straightforward for your developers to fix. Portlet plugins are generally backwards compatible, as they are written to the Java standard. This includes Portlet 1.0 (JSR-168) portlets, as the Portlet 2.0 (JSR-286) standard has also been designed to be backwards-compatible. Theme plugins may require some modifications in order to take advantage of new features. Much effort has been made to make upgrades as painless as possible; however, this is not a guarantee that everything will work without modification. Extension environment changes are the most complicating factor in an upgrade, so it is important to test as much as possible.

As a general rule, you can upgrade from one major release to the next major release. For example, you can upgrade directly from Liferay 4.3.x to 4.4.x, but not from 4.3.x to 5.0.x. If you need to upgrade over several major releases, you will need to run the upgrade procedure for each major release until you reach the release you want. This doesn't mean you need to run the procedure for every point release (i.e., 4.3.5 to 4.3.6 to 4.4.0 to 4.4.1, etc.); you only need to run the procedure for the major releases. A good practice is to use the latest version of each major release to upgrade your system. So if you wanted to upgrade from Liferay 4.3.5 to Liferay 5.1.1, you would first run the upgrade procedure for 4.4.2, then 5.0.1, and then 5.1.1.

Liferay Upgrade Procedure

Liferay 4.3.0 and higher can auto-detect whether the database requires an upgrade the first time the new version is started. When Liferay does this, it will automatically upgrade the database to the format required by the new version. In order to do this, Liferay must be accessing the database with an ID that can create, drop, and modify tables. Make sure that you have granted these permissions to the ID before you attempt to upgrade Liferay. It is also a good idea to backup your database before attempting an upgrade in case something goes wrong during the process.

Tip: Liferay versions prior to 4.3.0 require that you manually run SQL scripts on your database to perform an upgrade. If you need to upgrade from Liferay 4.1.x to 4.2.x, you can find these SQL scripts in the source code archive for the version of Liferay you are running. They will be in the SQL folder of the archive.

Upgrade Steps

It takes only four steps to upgrade a standard Liferay installation:

• Copy your customized portal-ext.properties file to a safe place, and then undeploy the old version of Liferay and shut down your application server.

• Copy the new versions of the dependency .jars to a location on your server's class path, overwriting the ones you already have for the old version of Liferay.

• Deploy the new Liferay .war file to your application server. Follow the deployment instructions in Chapter 1 or in Chapter 5 (if you have customized Liferay).

• Start (or restart) your application server. Watch the console as Liferay starts: it should upgrade the database automatically. Review the portal.properties changes and re-configure your previous customizations as necessary, restarting when customizations are complete.

That's all there is to it. Everything else is handled by Liferay's upgrade procedure. Note that as stated above, if you have to upgrade over several Liferay versions, you will need to repeat these steps for each major release.

What follows are instructions for upgrading for specific versions.

Upgrading Liferay 4.3 to Liferay 4.4

Prerequisite

In order to upgrade to 4.4.x, you must start at 4.3.0 or above. If you are using version 4.2.2 or below, please see the upgrade instructions on Liferay's wiki at http://wiki.liferay.com.

Follow the generic upgrade steps above. Make sure your Liferay .war and dependency .jars are all the same version.

If Your Developers Have Customized Liferay

If you are deploying Liferay from an extension environment, ensure that your developers have:

• Run Service Builder for each custom service.

• Edited their custom {Model}LocalServiceImpl classes and make them extend from {Model}LocalServiceBaseImpl.

• Run Service Builder again for each of the custom services after the previous change.

Many of the DTD references in the various -ext.xml files have changed (liferay-portlet-ext.xml in particular). Be sure to compare your <!DOCTYPE references with the main file to insure they reference the same DTD.

Example:

Liferay 4.3.x:

<!DOCTYPE liferay-portlet-app PUBLIC "-LiferayDTD Portlet Application 4.3.0EN" "http://www.liferay.com/dtd/liferay-portlet-app_4_3_0.dtd">

Liferay 4.4.x:

<!DOCTYPE liferay-portlet-app PUBLIC "-LiferayDTD Portlet Application 4.4.0EN" "http://www.liferay.com/dtd/liferay-portlet-app_4_4_0.dtd">

Upgrading Liferay 4.4 to Liferay 5.0

Prerequisite

In order to upgrade to 5.0.x, you must start at 4.4.0 or above.

Follow the generic upgrade steps above. Make sure your Liferay .war and dependency .jars are all the same version.

If Your Developers Have Customized Liferay

If you are deploying Liferay from an extension environment, ensure that your developers have upgraded their Service Builder .xml files to the new DTDs.

The generated code is slightly different, and custom written finders and LocalServiceImpl methods need to be adopted. The system-ext.properties and portal-ext.properties files have moved from ext-impl/classes to ext-impl/src.

Converting wiki pages (optional)

If you were using the wiki portlet, you will be happy to find many new features and improvements in 5.0—and everything is backwards compatible.

You may wish to convert your existing pages from the old Classic Wiki syntax to the new Creole (http://www.wikicreole.org) syntax because it's more powerful and easier to learn and use. It may also be more familiar to your users if they have experience with other popular wikis like MediaWiki or Confluence. To that end, Liferay 5.0 includes an automatic translator that will convert all of the pages in the database to Creole. To run it, edit portal-ext.properties and set:

verify.processes=com.liferay.portal.verify.VerifyWikiCreole
verify.frequency=-1

Start the server and let the process do the whole translation for you automatically. Remember to change those properties back to their original state before the next startup; otherwise the process will run every time you start Liferay.

Upgrade Troubleshooting

• The parameter p_p_action is now called p_p_lifecycle. This has to be adapted for example in the FriendlyURLMappers if you want them to trigger a processAction().

• You need to copy parent-build.xml in ext-impl from our Subversion repository; otherwise, some files will be missing when deploying.

• Upload in Struts portlets is broken. See http://support.liferay.com/browse/LEP-6412 and http://support.liferay.com/browse/LEP-6479.

Upgrading Liferay 5.0 to Liferay 5.1

Changes in configuration properties

Because of changes in the default configuration, Liferay now comes with several configuration files containing the defaults for previous versions. If the portal is not operating the way you are used to, it is likely that this is because a default value has been changed. You can revert to the previous behavior by following the process below.

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 pass the following system property when running Liferay:

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

Each application server has different methods to add this system property. In Tomcat, you would 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 changed properties.

• 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.

• permissions.user.check.algorithm: the default value is now a new algorithm that is much faster.

If Your Developers Have Customized Liferay

Following is a list of API changes. If your developers used the extension 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.

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

There is a new file which your developers will 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 re-added). 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. These are covered below.

The Parent Element of the Dock May Change Positioning When Upgrading

In 5.1 a change was made 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 use a different positioning mechanism. 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 situation is that if you must have position: static, the script will always overwrite it. In order to account for this, checking has been added 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 the style .popup for the inline popups has been changed to .ui-dialog. Other class name changes have been made, but have been left 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 the Classic theme.

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 developers 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 developers edit the deployed CSS files directly, they will not see the changes take effect immediately on the next page load. Instead, developers should 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 above, a change was made to javascript.fast.load from false to true.

Developers 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, developers should first make a back-up of the existing portlet. Then the PHP portions (including HTML, images, CSS, javascript), should be zipped and re-deployed 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 your developers 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 the parts that need to be changed can be manually updated in the 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 name space and/or were 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.

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), or 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]);