The first and easiest plugin upgrade step is adapting to Liferay Portal CE 7.1’s API. Liferay Portal CE 7.1’s modular architecture benefits Liferay Portal 6 developers. Modularizing the product, however, required renaming many packages. Of course, we documented each API change (7.0 breaking changes and 7.1 Breaking Changes) to explain what changed, why it changed, and how to adapt to it.
Going above and beyond documentation, Liferay provides the Code Upgrade Tool in Liferay Dev Studio (versions 3.1+). Here’s what the Code Upgrade Tool does:
- Identifies code affected by the API changes.
- Describes each API change related to the code.
- Suggests how to adapt the code.
- Provides options, in some cases, to adapt code automatically.
Even if you prefer tools other than Liferay Dev Studio (which is based on Eclipse), you should upgrade Plugins SDK plugins using the Code Upgrade Tool first–you can use your favorite tools afterward. This tutorial walks you through the steps required to use the Code Upgrade Tool:
Code Upgrade Tool Steps
|1.||Welcome to the Liferay Code Upgrade Tool||Introduces the Code Upgrade Tool.|
|2.||Configure the Project||Imports an existing Maven project or Plugins SDK project, and prepares its plugins for upgrading.|
|Maven only||Upgrade POM Files||Upgrades POM files so they use the latest Maven plugins and Liferay dependencies.|
|3.||Find Breaking Changes||Finds breaking changes, describes them, and prescribes adaptations (some of which can be applied automatically).|
|4.||Upgrade Descriptor Files||Moves descriptor files to their new versions.|
|5.||Build Services||Runs Service Builder on plugins that use it.|
|6.||Upgrade Layout Templates||Upgrades layout templates.|
|7.||Convert Custom JSP Hooks||Converts JSP hooks to modules or module fragments.|
|8.||Build||Compiles the plugins|
|9.||Summary||Lists each upgrade step’s status|
After completing step 2, you can execute the steps in any order. Also, be aware that you may not be presented with all nine steps for your project. For example, if you don’t have a JSP hook in your Plugins SDK, step 7 will not be available. Likewise, if you’re upgrading a 7.0 project already residing in Liferay Workspace, you’ll have fewer upgrade steps since fewer changes are required.
Launch the Code Upgrade Tool now.
Launching the Code Upgrade Tool
Launch the Code Upgrade Tool to start new upgrades or continue previously started upgrades:
Upgrading plugins with the Code Upgrade Tool for the first time requires a new empty Eclipse workspace. Bring up the Workspace Launcher by selecting File → Launch Workspace → New…. Then create a workspace.
Select Project → Liferay Code Upgrade Tool… to launch the Code Upgrade Tool.
The Welcome screen appears.
Step 1: Welcome to the Liferay Code Upgrade Tool
This screen describes the tool’s navigation and key functions.
|Represents code upgrade steps. Clicking a step’s gear takes you to that step.|
|Indicates step completion and takes you to the next step.|
|Indicates an incomplete step and advances you to the next step.|
|Navigate to the previous step.|
|Advance to the next step.|
Liferay Dev Studio tracks each plugin’s state. You can close the Code Upgrade Tool view at any step and re-launch it later to resume upgrading plugins.
Now you’re ready to configure your project.
Step 2: Select Projects to Upgrade
The Code Upgrade Tool can upgrade Liferay 6.2 plugins built with the Plugins SDK, Maven, or an older version of Liferay Workspace. Browse to the Plugins SDK, Maven parent project, or Liferay Workspace root location to proceed with importing your plugin into the workspace.
If you’re upgrading a Plugins SDK plugin, you must integrate its Plugins SDK with a Liferay Portal CE 7.1 server before beginning the upgrade. You can work with plugins in your current Plugins SDK, or in a copy of the Plugins SDK in a new Liferay Workspace. Liferay Workspace offers the best of both worlds: it lets you continue to work with plugins in an SDK while facilitating plugin migration to modules or Workspace WAR projects.
Upgrading a Plugins SDK to Liferay Workspace does these things:
- Converts the SDK root folder to a new Liferay Workspace.
- Upgrades the Liferay Plugins SDK 6.2 to Liferay Plugins SDK 7.0 (if applicable).
- In the Workspace, migrates the Plugins SDK to a new
- Installs a Liferay Portal CE 7.1 server bundle to a new
If you’re upgrading a traditional Maven project or legacy Liferay Workspace, your current project structure will not be reorganized. Only necessary breaking changes and file modifications are suggested. For example, a traditional Maven project will not be converted to a Liferay Workspace.
Use the steps below to import your legacy projects:
Configure the project:
- Project sources: Path to the project to upgrade
- Upgrade to Liferay Version: Version of Liferay Portal to upgrade to
- Server Name: Arbitrary name for the Liferay Portal CE 7.1 server bundle
- Liferay Server Bundle Download URL: Location of a server bundle to download and install
Click the Import Projects button.
The selected projects are imported to Dev Studio.
To mark the step complete, click the check mark icon ().
Upgrade POM Files (Maven Projects Only)
Note: If you are not upgrading a Maven project, please skip this section.
The Code Upgrade Tool scans through all of your Maven project’s POM files. Here is an outline of the types of changes it suggests:
- Remove declarations of the
- Add new Maven plugins like
- CSS Builder
- Service Builder
- Theme Builder
- Find dependency elements that point to old Liferay Portal 6.2 artifacts and update them. For example,
portal-servicedependency elements will be updated to
For more information on the upgrade process for your Maven build, see Upgrading the Liferay Maven Build.
If the tool finds any necessary updates, it lists them in the view.
You can double-click any of the POM files to display a preview of the changes that will be made if you upgrade that file.
pom.xml files you’d like to upgrade and click Upgrade Selected.
Next, you’ll begin updating your project’s descriptor files.
Step 3: Find Breaking Changes
Breaking changes are API changes that affect (and might break) existing API consumers and implementations. The Code Upgrade Tool finds affected plugin code and explains how to adapt it.
Breaking changes documentation contains the following information for each change:
- Date: Date the change was introduced
- JIRA Ticket: Corresponding issue number
- What Changed?: Change summary
- How should I update my code?: Adaptation instructions
- Why was the change made?: Reasons for the change
The tool helps you address problems. It offers to auto-correct problems that are clearly understood and easy to fix (e.g., package imports and Liferay Portal version properties). It facilitates opening affected code in an editor to check and modify it. Lastly, the tool lets you mark progress in resolving the problems.
You can use one or both of the following options to resolve problems.
- Option 1: Correct Problems Automatically First
- Option 2: Address Problems Individually
The following sections explain each option.
Option 1: Correct Problems Automatically First
Use this option () to fix easy problems right away automatically (you can fix tougher problems later). Follow these steps to use this option:
Click the Automatically Correct Problems icon () to open the project selection window.
Select projects in which to correct problems automatically and click the OK button. After addressing those problems, the Find Breaking Changes window appears and lists any remaining problems.
Address any remaining problems individually (as described next).
Option 2: Address Problems Individually
This option () finds and describes all the problems, leaving you to address them on a case-by-case basis. Problems that the tool can auto-fix have the Correct automatically option. Follow these steps to address problems individually:
Click the Find Breaking Changes icon () to open the project selection window.
Select the projects where you want to find upgrading problems and the new Liferay Portal version. You can also select the Combine existing problems list checkbox to have all project issues displayed in one list. Then click the OK button. The Find Breaking Changes window appears:
- Upper-left panel: lists the projects that have outstanding problems. The Code Problems folder holds a tree of projects and project files that have code problems.
- Lower-left panel: lists the currently selected project’s problems.
- Right panel: shows breaking change documentation for selected problems.
In the upper left panel’s Code Problems tree, select a project file. The bottom left panel lists the file’s problems.
Select a problem to view its description in the right side panel.
Right click the problem to show options for handling it.
Based on the problem description, handle it using one of the following options:
Option Instructions Correct automatically (if available) 1. Right click the problem.
2. Select Correct automatically.
3. Mark the problem resolved by checking its checkbox in the Resolved column.
Fix manually 1. Double click the problem to open an editor.
2. Fix the problem based on the instructions in How should I update my code?.
3. Mark the problem resolved by checking its checkbox in the Resolved column.
Ignore 1. Right click the problem.
2. Ignore this problem (Ignore) or all problems like it (Ignore all problems of this type). Ignoring problems marks them for you to revisit. Clicking the Open Ignored List icon () lists ignored problems.
Continue addressing problems individually or try Correcting Problems Automatically (as explained previously).
Congratulations on addressing breaking change problems! Next, you’ll upgrade your descriptor files.
Step 4: Upgrade Descriptor Files
The Upgrade Descriptor Files screen lists plugin descriptor files to upgrade. It proposes updates for them and lets you compare proposed updates with the current content. To compare a descriptor’s proposed update with its current content, click the descriptor entry in the list. To apply all proposed descriptor file updates, click Upgrade…. To find plugins whose descriptor files need upgrading, click Find….
In the next step, you’ll build your project’s services.
Step 5: Build Services
The Build Service step re-runs Service Builder on the projects and deletes legacy Service Builder files. To do this, click Build Services.
Next, you’ll upgrade any layout templates.
Step 6: Upgrade Layout Templates
The Upgrade Layout Templates step proposes Layout Template updates. It lists Layout Templates for you to view and compare proposed updates with original content.
Follow these steps to upgrade your Layout Templates:
Click the Find… button to list Layout Templates that need updates.
To compare a Layout Template’s original code with proposed code updates, double click its name.
Click the Upgrade… button to apply all proposed Layout Template updates.
Finished shows after each upgraded Layout Template.
Next, you’ll convert any custom JSP hooks.
Step 7: Convert Custom JSP Hooks
This step converts custom JSP hooks to modules or module fragments. It lets you compare your custom JSPs with original Liferay Portal 6.2 JSPs, and newly generated module custom JSPs.
Use these steps to convert the Liferay Portal 6.2 custom JSP hooks to new modules or module fragments for Liferay Portal CE 7.1:
Set the Converted Project Location to the Workspace’s
Click the Select Projects button. The Custom JSP Hook Project window appears.
In the Custom JSP Hook Project window, select projects to convert and click OK.
The JSP hooks are converted to new modules or module fragments in the Workspace.
The Code Upgrade Tool helps you review the changes, so you can make any additional changes. It lists the 6.2 custom JSPs and the new converted custom JSPs for you to compare with the 6.2 originals:
- To compare a 6.2 custom JSP with the original, click the custom JSP filename.
- To compare a newly converted 7.x custom JSP with the original, click the 7.x custom JSP filename.
Referring to these comparisons helps you to implement new JSP customizations for Liferay Portal CE 7.1.
If the 6.2 hook plugin’s JSP didn’t customize an existing Liferay Portal 6.2 JSP, there’s no original and the JSP is marked unfound. You must then decide how to implement the customization for Liferay Portal CE 7.1. It might make sense to create a similar new JSP in a new or converted module project.
The Code Upgrade Tool creates a
ConvertedCustomJspBag class in the converted module project. It tells the OSGi container that the module modifies a core JSP. The class resides in the module’s
The new upgraded Portal core JSPs are under the module’s
The Code Upgrade Tool converts Liferay Portal 6.2 app custom JSP hooks to module fragments. Here’s a fragment’s
The Code Upgrade Tool also gives you a great deal of flexibility to convert custom JSPs as needed. For example, if you make a mistake or aren’t fond of the results of converting a custom JSP, you can start over. Follow these steps to do so:
Delete the converted module project(s).
Click on the Clear Results button in the Convert Custom JSP Hooks view.
Select the project(s) again from the Custom JSP Hook Project window and click OK.
The Convert Custom JSP Hooks view lets you upgrade JSP hooks at your leisure. Now you’re ready to rebuild your projects.
Step 8: Build
You must now rebuild any Plugins SDK projects. To do so, click the Build… button.
Great, you’re almost done!
Step 9: Summary
The last screen in the Code Upgrade Tool lists each step’s status. A check mark indicates the step is done, an X indicates it’s not done, and a question mark indicates its status is to be determined. To revisit a step, click its name.
You can always revisit the Liferay Code Upgrade view by selecting Project → Liferay Code Upgrade Tool….
Awesome! You now know how to leverage Liferay’s Code Upgrade Tool to adapt plugins to Liferay Portal CE 7.1. As you continue upgrading your plugins, you can re-open the Code Upgrade Tool to facilitate upgrades.