Adapting to Liferay Portal CE 7.1’s API with the Code Upgrade Tool

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

Step Name Description
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:

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

  2. Select Project → Liferay Code Upgrade Tool… to launch the Code Upgrade Tool.

    code-upgrade-invoke-tool.png

    Figure 1: The Code Upgrade Tool is available in the Project menu.

The Welcome screen appears.

Step 1: Welcome to the Liferay Code Upgrade Tool

This screen describes the tool’s navigation and key functions.

code-upgrade-welcome.png

Navigation

Icon Description
icon-code-upgrade-step-gears.png Represents code upgrade steps. Clicking a step’s gear takes you to that step.
icon-code-upgrade-mark-done.png Indicates step completion and takes you to the next step.
icon-code-upgrade-mark-not-done.png Indicates an incomplete step and advances you to the next step.
icon-code-upgrade-prev-step.png Navigate to the previous step.
icon-code-upgrade-next-step.png 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.

code-upgrade-gears-done-and-not-done.png

Figure 3: The Code Upgrade Tool marks steps complete (icon-code-upgrade-mark-done.png) or incomplete (icon-code-upgrade-mark-not-done.png). It also saves its state so you can resume upgrades later.

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 plugins-sdk subfolder.
  • Installs a Liferay Portal CE 7.1 server bundle to a new bundles subfolder.

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:

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

    code-upgrade-configure-project.png

    Figure 4: The Select Projects to Upgrade step imports Plugins SDK projects and integrates them with a Liferay Portal CE 7.1 server.

  2. Click the Import Projects button.

The selected projects are imported to Dev Studio.

To mark the step complete, click the check mark icon (icon-code-upgrade-mark-done.png).

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 liferay-maven-plugin.
  • 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-service dependency elements will be updated to com.liferay.portal.kernel.

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.

upgrade-tool-pom-list.png

Figure 5: Defining a Liferay Portal server is straightforward.

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.

code-upgrade-pom-compare.png

Figure 6: Defining a Liferay Portal server is straightforward.

Select the 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 (icon-bandage.png) to fix easy problems right away automatically (you can fix tougher problems later). Follow these steps to use this option:

  1. Click the Automatically Correct Problems icon (icon-bandage.png) to open the project selection window.

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

  3. Address any remaining problems individually (as described next).

Option 2: Address Problems Individually

This option (icon-code-upgrade-tool-select-project.png) 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:

  1. Click the Find Breaking Changes icon (icon-code-upgrade-tool-select-project.png) to open the project selection window.

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

    code-upgrade-find-breaking-changes.png

    Figure 7: The Finding Breaking Changes step shows users where breaking changes affect plugins. It describes each change and explains how to adapt to it.

  3. In the upper left panel’s Code Problems tree, select a project file. The bottom left panel lists the file’s problems.

  4. Select a problem to view its description in the right side panel.

  5. Right click the problem to show options for handling it.

    code-upgrade-problem-options.png

    Figure 8: The Code Upgrade Tool can correct some problems automatically. There are also options to ignore the problem, ignore problems like it, or mark it done/undone.

  6. 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 (icon-code-upgrade-list-ignored-problems.png) lists ignored problems.
  7. 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….

code-upgrade-upgrade-descriptor-files.png

Figure 9: The Upgrade Descriptor Files screen lists Plugins SDK project descriptor files to upgrade.

code-upgrade-compare-descriptor-files.png

Figure 10: The Upgrade Descriptor File step adapts descriptor files to Liferay Portal CE 7.1. Clicking a descriptor file opens a window that compares proposed updates to the current content.

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.

code-upgrade-build-service.png

Figure 11: The Build Service step re-runs Service Builder on the projects and removes legacy Service Builder files.

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:

  1. Click the Find… button to list Layout Templates that need updates.

  2. To compare a Layout Template’s original code with proposed code updates, double click its name.

  3. Click the Upgrade… button to apply all proposed Layout Template updates.

Finished shows after each upgraded Layout Template.

code-upgrade-upgrade-layout-templates.png

Figure 12: The Upgrade Layout Templates step lists all Layout Templates to upgrade.

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.

code-upgrade-convert-custom-jsp-hooks.png

Figure 13: The Convert Custom JSP Hooks step lets you select JSP hook plugin projects to convert to modules or module fragments. After they’re converted, the originals are available for comparing with the adapted 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:

  1. Set the Converted Project Location to the Workspace’s modules folder.

  2. Click the Select Projects button. The Custom JSP Hook Project window appears.

  3. In the Custom JSP Hook Project window, select projects to convert and click OK.

    code-upgrade-custom-jsp-hook-project-seclector.png

    Figure 14: The Code Upgrade Tool lets you select custom JSP hook projects to upgrade.

The JSP hooks are converted to new modules or module fragments in the Workspace.

code-upgrade-converted-jsp-hooks-in-modules.png

Figure 15: Custom JSP hook projects are converted to module or module fragment projects.

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.

code-upgrade-convert-jsp-hooks.png

Figure 16: The Code Upgrade Tool lets you compare your 6.2 and new 7.x custom JSPs with Liferay Portal 6.2 originals.

code-upgrade-converted-jsp-hooks-compare-6.2-original.png

Figure 17: This view compares an original 6.2 JSP with a 6.2 custom JSP.

code-upgrade-converted-jsp-hooks-compare-6.2-original-to-7.0.png

Figure 18: This view compares the new module’s 7.x custom JSP with the Liferay Portal 6.2 original.

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.

code-upgrade-converted-jsp-hooks-found-unfound.png

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 src/main/java/codeupgrade.corejsphook/ folder.

code-upgrade-converted-core-jsp-hook-module.png

The new upgraded Portal core JSPs are under the module’s src/main/resources/META-INF/resources/html/ folder.

The Code Upgrade Tool converts Liferay Portal 6.2 app custom JSP hooks to module fragments. Here’s a fragment’s bnd.bnd file:

code-upgrade-converted-jsp-hook-fragment-bnd.png

Figure 21: The Fragment-Host header specifies the module on which to apply the fragment.

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:

  1. Delete the converted module project(s).

  2. Click on the Clear Results button in the Convert Custom JSP Hooks view.

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

code-upgrade-build.png

Figure 22: You can build SDK projects any time.

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.

code-upgrade-summary.png

Figure 23: The Summary step lists each step’s status.

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.

Related Topics

Development Reference

Classes Moved from portal-serice.jar

Modularizing an Existing Portlet

Tooling

0 (0 Votes)
Upgrading Plugins to Liferay Portal CE 7.1 Previous