Recently I've been working in some new features regarding to internacionalization the name and description of DLFileEntryType entity. I create all the logic and everithing was fine. Everthing went smoothly.
Due I was changing a DB table I had to create an upgrade process and the things became a litle bit hard (it's my very fist time creating an upgrade)... Why? Because I found an absolute lack of updated documentation about this kind of process.
It's true that I found a few wikis but it was a little messy (It was very funny to see five core engineers in the LA office triying to decode the [obsolete] documentation, true story...) So I've decided to create my fist blog entry regarding this.
But first of all... What is an upgrade process??
What we try to do in a upgrade process is guarantee that Liferay can upgrade from any previous version to any newer version.
We can see this in the following example.
I'm going to explain (based in the develop I made) the whole process, explaining how did I upgrade the DLFileEntryType entity by adding a new column called fileEntryTypeKey and changing the name and the description columns introducing localization properties.
Step 1 - Modify an entity
The first thing to do is to perfome all the required changes in the entity. It will give you the basis for the rest of the process. Not very much to explain, edit the service.xml ...
... and modifiy the Impl classes you need. Nothing special
Step 2 - Change .ftl if needed
If the entity has some default objects (i.e. DLFileentryType has 5 default types) maybe you'll need to change its .ftl file :
Step 3 - Create some UpgradeProcess classes
Go to the proper version UpgradeProcess[XXX].java file (for us it's UpgradeProcess_6_2_0.java) and search for the right Upgrade[XXX].java (in this case is UpgradeDocumentLibrary). In this class (wich extends UpgradeProcess) you must introduce and override the doUpgrade() method like this:
As you can see we are directly using pure sql to perform the database upgrade. This clauses are surrounded by a try…catch that calls the method upgradeTable(few params) if something goes wrong...
Let's see that method deeply:
In there we are creating an UpgradeTable.java instance and we pass some values regarding the table we are modifiying. We get this values from an autogenerated class called XXXTable.java (DLFileEntryTypeTable.java for us).
Step 4 - Create the [XXX]Table class
Create this class is as simple as make its skeleton, modify portlet-model-hints.xml to define the configuraiton of the columns...
...and then run...
This is the generated class:
Step 5 - Create some logic to format and persist the current data
The last method that we can see in doUpgrade() is:
Here we are getting the previous values and we pass them to...
...where we will reuse them in the modified table.
Step 6 - Regenerate all the service and TEST!
This is the final step. All you got to do:
Doing this you could be sure you are not breaking the default data.
And that's all!!!