When you make database changes to your application, you must use a data upgrade process to migrate users’ existing data to the new database schema. While the old framework required several classes, the new framework can orchestrate the upgrade steps from a single class. Managing the steps from one class facilitates developing upgrade processes. The data upgrade framework you use depends on your development framework. This tutorial shows you how to migrate to the new framework.
-
If your upgraded plugin is a traditional WAR, you don’t need to do anything special; existing upgrade processes adapted to Liferay DXP 7.1’s API work as is. The new data upgrade framework is for modules only.
-
If you converted your upgraded plugin to a module or you have an upgraded module, you must migrate any upgrade processes you want to continue using to the new data upgrade framework.
You can migrate any number of old upgrade processes (starting with the most recent ones) to the new framework. For example, if your module has versions 1.0, 1.1, 1.2, and 1.3, but you only expect customers on versions 1.2 and newer to upgrade, you might migrate upgrade processes for versions 1.2 and 1.3 only.
Before beginning, make sure you know how to create an upgrade process that uses the new framework.
First, you’ll review how Liferay Portal 6 upgrade processes work.
Understanding Liferay Portal 6 Upgrade Processes
Before getting started, it’s important to understand how Liferay Portal 6 upgrade processes are structured. As an example, you’ll use the Liferay Portal 6.2 upgrade process for the Knowledge Base Portlet.
In Liferay Portal 6 upgrade processes, the upgrade step classes for each schema
version are in folders named after their schema version. For
example, the Knowledge Base Portlet’s upgrade step classes are in folders named
v1_0_0, v1_1_0, v1_2_0, and so on. Each upgrade step class extends
UpgradeProcess and overrides the doUpgrade method. The code in doUpgrade
performs the upgrade. For example, the Knowledge Base Portlet’s
v1_0_0/UpgradeRatingsEntry upgrade step
extends UpgradeProcess and performs the upgrade via the
updateRatingsEntries() call in its doUpgrade method:
public class UpgradeRatingsEntry extends UpgradeProcess {
@Override
protected void doUpgrade() throws Exception {
updateRatingsEntries();
}
...
protected void updateRatingsEntries() throws Exception {
// Upgrade code
}
...
}
The upgrade process classes are on the same level as the folders containing the
upgrade steps and are also named after their schema version. For
example, the Knowledge Base Portlet’s upgrade process classes are
named UpgradeProcess_1_0_0, UpgradeProcess_1_1_0, UpgradeProcess_1_2_0,
and so on. Each upgrade process class also extends UpgradeProcess and runs the
upgrade process in the doUpgrade method. It runs the upgrade process by
passing the appropriate upgrade step to the upgrade method. For example, the
doUpgrade method in the Knowledge Base Portlet’s
UpgradeProcess_1_0_0 class
runs the upgrade steps UpgradeRatingsEntry and UpgradeRatingsStats via the
upgrade method:
@Override
protected void doUpgrade() throws Exception {
upgrade(UpgradeRatingsEntry.class);
upgrade(UpgradeRatingsStats.class);
}
Now that you know how Liferay Portal 6 upgrade processes are defined, you’ll learn how to convert them to the new upgrade process framework in Liferay DXP 7.1.
Converting your Liferay Portal 6 Upgrade Process to Liferay DXP 7.1
So how do Liferay Portal 6 upgrade processes compare to those that use the new upgrade process framework? First, the upgrade step classes are the same, so you can leave them unchanged. Here are the big changes in the new upgrade processes:
- A single registrator class replaces upgrade process classes.
- Service Builder services require a Bundle Activator.
Start your conversion by creating a registrator class.
Create a Registrator Class
The new data upgrade framework requires using registrator class instead of
upgrade process classes. You must combine your upgrade process classes’
functionality into a single registrator class. Recall from
the data upgrade process tutorial
that registrators define an upgrade process that the upgrade process framework
executes. Each registry.register call in the registrator registers the
appropriate upgrade steps for each schema version. You must therefore transfer
the functionality of your old upgrade process classes’ doUpgrade methods into
a registrator’s registry.register calls.
For example, click here to see the Knowledge Base Portlet’s new Liferay DXP 7.1 upgrade process in GitHub.
Besides some additional upgrade step classes to handle changes made to the
portlet for Liferay DXP 7.1, the only difference in this upgrade process is that
it contains a single registrator class, KnowledgeBaseServiceUpgrade, instead
of multiple upgrade process classes.
The KnowledgeBaseServiceUpgrade class,
like all registrators, calls the appropriate upgrade steps for each schema
version in its registry.register calls. For example, the first
registry.register call registers the upgrade process for the 1.0.0 schema
version:
registry.register(
"com.liferay.knowledge.base.service", "0.0.1", "1.0.0",
new com.liferay.knowledge.base.internal.upgrade.v1_0_0.
UpgradeRatingsEntry(),
new com.liferay.knowledge.base.internal.upgrade.v1_0_0.
UpgradeRatingsStats());
Compare this to the above doUpgrade method from
the corresponding Liferay Portal 6 upgrade process class UpgradeProcess_1_0_0.
Both call the same upgrade steps.
Next, create a Bundle Activator if your modularized plugin uses Service Builder.
Create a Bundle Activator
If your module implements Service Builder services, it needs a Bundle Activator to initialize a record in the release table. Creating a Bundle Activator is straightforward.
That’s it! For instructions on creating new upgrade processes for Liferay DXP 7.1, including complete steps on creating a registrator, click here.
Related Topics
Creating Data Upgrade Processes for Modules