Since Liferay 6.0 extension environment was moved to plugins, it transformed the way core functionalities can be overridden, but there are some best practices which justifies why ext development was moved to plugins.
The major reason why ext was moved to plugins was that in earlier versions of Liferay code had to be placed on the server to deploy ext, which was a major concern from potential customers. So if the customer uses Liferay 6.x version then best practice is NEVER keep source code on servers.
So one should use SSH for Linux servers or RDC for Windows Server to deploy the war files on the server.
As we all know that ext-plugin is still not 100% hot deployable and just because of this reason developers tend to use ant direct-deploy command to deploy ext on the servers. One more reason this command is used more frequently is that people find un-deploying ext-plugin difficult.
So following are some steps which will help in un-deploying the ext-plugin from the server:
Assuming the name of ext-plugin is "sample-ext"
1. Shut down server
2. Delete the folder sample-ext from "webapps" folder
3. Navigate to /webapps/ROOT/WEB-INF folder and delete the following files only:
a. liferay-display-ext.xml
b. liferay-portlet-ext.xml
c. portlet-ext.xml
d. tiles-defs.xml
e. ext-sample-ext.xml
4. Navigate to following location to delete only those jar files mentioned below:
a. ext-sample-ext-impl.jar
b. ext-sample-ext-util-bridges.jar
c. ext-sample-ext-util-java.jar
d. ext-sample-ext-util-taglib.jar
5. Navigate to following location to delete only the ext-sample-ext-service.jar file
6. Restart the server
By following the steps mentioned the ext changes are reverted back to original state once the server restarts and new version of ext can be re-deployed.
Note:
1. Avoid creating multiple ext-plugin in the same project to facilitate code manageability.
2. Using EXT Plugin should be avoided till its utmost necessary to modify any core features of Liferay.
Tuesday, January 8, 2013
Liferay Development Best Practices
Liferay Development Best Practices
Introduction:
Liferay portal is a portal framework which is an open source platform which can be customized to any level to deliver cross platform solutions. Liferay development has always been a point for discussion as Liferay provides different ways to customize Liferay or add new functionalities into Liferay.
Liferay Development offers following various ways to customize default behaviour of Liferay:
i. Portlets
ii. Themes
iii. Layout Templates
iv. Webs
v. Hooks
In order to use the various ways mentioned above one must follow the best practices to help in organizing and managing the code as well as defining the deployment strategies
This document will provide information about such practices and how to apply these practices.
1. Liferay Installation
Liferay installation involves three zip files such as liferay-portal-tomcat-6.1.0.zip, liferay-plugins-sdk.zip and liferay-portal-src.zip.
One needs to unzip these files and follow the regular installation steps to install Liferay.
2. portal-ext.properties
The file portal-ext.properties is the most important file in the whole Liferay development lifecycle as it holds to various configurations which are utilized within the portal or portlets. Once Liferay 6 was released ext became part of plugins-sdk and keeping portal-ext.properties file within ext is not a good practice.
Best Practice:
Placing the portal-ext.properties file at Liferay tomcat installation root folder is the best practice. For example : If Liferay Tomcat server is installed under the location : D:\\liferay-portal-6.1.0-ee-ga1 then placing the properties file under this location is the best practice.
Also, this file needs to be part of source repository and needs to be updated regularly. Another practice is to avoid using portlet.properties for custom portlets. So if there is need to use properties specific to portlets adding them to portal-ext.properties file is better.
3. Ext Plugin :
Since Liferay 6.0 extension environment was moved to plugins, it transformed the way core functionalities can be overridden, but there are some best practices which justifies why ext development was moved to plugins.
The major reason why ext was moved to plugins was that in earlier versions of Liferay code had to be placed on the server to deploy ext, which was a major concern from potential customers. So if the customer uses Liferay 6.x version then best practice is NEVER keep source code on servers.
So one should use SSH for Linux servers or RDC for Windows Server to deploy the war files on the server.
As we all know that ext-plugin is still not 100% hot deployable and just because of this reason developers tend to use ant direct-deploy command to deploy ext on the servers. One more reason this command is used more frequently is that people find un-deploying ext-plugin difficult.
So following are some steps which will help in un-deploying the ext-plugin from the server:
Assuming the name of ext-plugin is "sample-ext"
1. Shut down server
2. Delete the folder sample-ext from "webapps" folder
3. Navigate to /webapps/ROOT/WEB-INF folder and delete the following files only:
a. liferay-display-ext.xml
b. liferay-portlet-ext.xml
c. portlet-ext.xml
d. tiles-defs.xml
e. ext-sample-ext.xml
4. Navigate to following location to delete only those jar files mentioned below:
a. ext-sample-ext-impl.jar
b. ext-sample-ext-util-bridges.jar
c. ext-sample-ext-util-java.jar
d. ext-sample-ext-util-taglib.jar
5. Navigate to following location to delete only the ext-sample-ext-service.jar file
6. Restart the server
By following the steps mentioned the ext changes are reverted back to original state once the server restarts and new version of ext can be re-deployed.
Note:
1. Avoid creating multiple ext-plugin in the same project to facilitate code manageability.
2. Using EXT Plugin should be avoided till its utmost necessary to modify any core features of Liferay.
3. Hooks Plugin:
Hooks Plugin are the most powerful plugins as compared to any other plugins available within Liferay. One should be careful while using hooks plugin to modify presentation or functionalities of Liferay. Following are some of the best practices to be kept in mind while using hooks plugin:
1. Naming Convention:
Always provide proper naming conventions to hooks plugins. For example, If there is a need to create a hooks plugin for asset publisher then name that plugin as "asset-publisher-hook". This will notify other developers that this particular hook is for asset publisher.
2. Avoid Duplication
Some times developers will create hooks for same portlets more than once which results into conflict and confusion. This can be avoided if Naming convention is followed properly.
4. Portlets Plugin:
These plugin provide freedom to developers to create custom applications which are not part of Liferay OOB features. There are some best practices for such plugins as well which are mentioned as follows:
1. Naming Convention :
Providing proper names based on feature/functionality to the plugin portlets help in identifying the portlets. For example, If one create a portlet providing weather features can be named as weather-portlet.
2. Categorization:
Specifying the categories for the plugin portlets helps in grouping them based on functionality or project. If we consider the above weather-portlet as an example which was developed for customer ABC then mention the portlet categorization in liferay-display.xml as follows:
3. Service Builder
Service Builder tool is used to provide database connectivity to the plugin portlets so that portlet specific information can be persisted in the configured Database. While creating the plugin portlets always consider the bigger picture, like whether this portlet is a standalone portlet or there is a need to share the services of this portlet with another one.
In such scenarios developers will place the service jars in lib/ext folder to make the services global which can be consumed across any portlet. This creates chances of frequent restart of the portal if the service jar gets updated frequently.
The above situation can be avoided if such portlets where services needs to shared are defined under single portlet.xml.
4. CSS/JS/Images
Liferay supports/provides developers to add portlet specific CSS, JS and Images to plugin portlets. One should use this only at the time of development in local machines. When the unit testing is completed whole of the portlet specific CSS, JS and Images should be merged with theme to avoid conflicts with other portlets or theme itself.
For example, if there are two portlets ABC and XYZ and both are using some jQuery plugins. So keeping Jquery Library files in both the portlets separately will end up in either conflicts or performance issue so such common files should be made part of the theme so that they can be accessed globally.
5. Classes Files:
In order to avoid discrepancy between the various components of Liferay, NEVER COMMIT CLASS files to Code Repository. That is the most dangerous activity for the whole project. This can be avoided by configuring classes folder as ignored for check-in.
6. JDK Version
Liferay Portal Server comes with built in JRE and is configured by default. So whenever you are starting the portal server always keep a check of the JRE_HOME Attribute in the command prompt/logs.
Selection of version of JDK entirely depends on the system requirements, though best practice is to configure the JRE_HOME/JAVA_HOME to the installed JDK on the local system. In order to change these settings open up the setenv.bat file (which can be found under bin directory) in a text editor and modify the path of JRE_HOME as follows:
JRE_HOME=%CATALINA_HOME%/jre1.6.0_20/win
to
JRE_HOME=PATH_TO_INSTALLED_JDK
These are some of the best practices which I have learned from my experiences in Liferay Development.
I will keep adding more such best practices to help people work with Liferay the right way.
Introduction:
Liferay portal is a portal framework which is an open source platform which can be customized to any level to deliver cross platform solutions. Liferay development has always been a point for discussion as Liferay provides different ways to customize Liferay or add new functionalities into Liferay.
Liferay Development offers following various ways to customize default behaviour of Liferay:
i. Portlets
ii. Themes
iii. Layout Templates
iv. Webs
v. Hooks
In order to use the various ways mentioned above one must follow the best practices to help in organizing and managing the code as well as defining the deployment strategies
This document will provide information about such practices and how to apply these practices.
1. Liferay Installation
Liferay installation involves three zip files such as liferay-portal-tomcat-6.1.0.zip, liferay-plugins-sdk.zip and liferay-portal-src.zip.
One needs to unzip these files and follow the regular installation steps to install Liferay.
2. portal-ext.properties
The file portal-ext.properties is the most important file in the whole Liferay development lifecycle as it holds to various configurations which are utilized within the portal or portlets. Once Liferay 6 was released ext became part of plugins-sdk and keeping portal-ext.properties file within ext is not a good practice.
Best Practice:
Placing the portal-ext.properties file at Liferay tomcat installation root folder is the best practice. For example : If Liferay Tomcat server is installed under the location : D:\
Also, this file needs to be part of source repository and needs to be updated regularly. Another practice is to avoid using portlet.properties for custom portlets. So if there is need to use properties specific to portlets adding them to portal-ext.properties file is better.
3. Ext Plugin :
Since Liferay 6.0 extension environment was moved to plugins, it transformed the way core functionalities can be overridden, but there are some best practices which justifies why ext development was moved to plugins.
The major reason why ext was moved to plugins was that in earlier versions of Liferay code had to be placed on the server to deploy ext, which was a major concern from potential customers. So if the customer uses Liferay 6.x version then best practice is NEVER keep source code on servers.
So one should use SSH for Linux servers or RDC for Windows Server to deploy the war files on the server.
As we all know that ext-plugin is still not 100% hot deployable and just because of this reason developers tend to use ant direct-deploy command to deploy ext on the servers. One more reason this command is used more frequently is that people find un-deploying ext-plugin difficult.
So following are some steps which will help in un-deploying the ext-plugin from the server:
Assuming the name of ext-plugin is "sample-ext"
1. Shut down server
2. Delete the folder sample-ext from "webapps" folder
3. Navigate to /webapps/ROOT/WEB-INF folder and delete the following files only:
a. liferay-display-ext.xml
b. liferay-portlet-ext.xml
c. portlet-ext.xml
d. tiles-defs.xml
e. ext-sample-ext.xml
4. Navigate to following location to delete only those jar files mentioned below:
a. ext-sample-ext-impl.jar
b. ext-sample-ext-util-bridges.jar
c. ext-sample-ext-util-java.jar
d. ext-sample-ext-util-taglib.jar
5. Navigate to following location to delete only the ext-sample-ext-service.jar file
6. Restart the server
By following the steps mentioned the ext changes are reverted back to original state once the server restarts and new version of ext can be re-deployed.
Note:
1. Avoid creating multiple ext-plugin in the same project to facilitate code manageability.
2. Using EXT Plugin should be avoided till its utmost necessary to modify any core features of Liferay.
3. Hooks Plugin:
Hooks Plugin are the most powerful plugins as compared to any other plugins available within Liferay. One should be careful while using hooks plugin to modify presentation or functionalities of Liferay. Following are some of the best practices to be kept in mind while using hooks plugin:
1. Naming Convention:
Always provide proper naming conventions to hooks plugins. For example, If there is a need to create a hooks plugin for asset publisher then name that plugin as "asset-publisher-hook". This will notify other developers that this particular hook is for asset publisher.
2. Avoid Duplication
Some times developers will create hooks for same portlets more than once which results into conflict and confusion. This can be avoided if Naming convention is followed properly.
4. Portlets Plugin:
These plugin provide freedom to developers to create custom applications which are not part of Liferay OOB features. There are some best practices for such plugins as well which are mentioned as follows:
1. Naming Convention :
Providing proper names based on feature/functionality to the plugin portlets help in identifying the portlets. For example, If one create a portlet providing weather features can be named as weather-portlet.
2. Categorization:
Specifying the categories for the plugin portlets helps in grouping them based on functionality or project. If we consider the above weather-portlet as an example which was developed for customer ABC then mention the portlet categorization in liferay-display.xml as follows:
3. Service Builder
Service Builder tool is used to provide database connectivity to the plugin portlets so that portlet specific information can be persisted in the configured Database. While creating the plugin portlets always consider the bigger picture, like whether this portlet is a standalone portlet or there is a need to share the services of this portlet with another one.
In such scenarios developers will place the service jars in lib/ext folder to make the services global which can be consumed across any portlet. This creates chances of frequent restart of the portal if the service jar gets updated frequently.
The above situation can be avoided if such portlets where services needs to shared are defined under single portlet.xml.
4. CSS/JS/Images
Liferay supports/provides developers to add portlet specific CSS, JS and Images to plugin portlets. One should use this only at the time of development in local machines. When the unit testing is completed whole of the portlet specific CSS, JS and Images should be merged with theme to avoid conflicts with other portlets or theme itself.
For example, if there are two portlets ABC and XYZ and both are using some jQuery plugins. So keeping Jquery Library files in both the portlets separately will end up in either conflicts or performance issue so such common files should be made part of the theme so that they can be accessed globally.
5. Classes Files:
In order to avoid discrepancy between the various components of Liferay, NEVER COMMIT CLASS files to Code Repository. That is the most dangerous activity for the whole project. This can be avoided by configuring classes folder as ignored for check-in.
6. JDK Version
Liferay Portal Server comes with built in JRE and is configured by default. So whenever you are starting the portal server always keep a check of the JRE_HOME Attribute in the command prompt/logs.
Selection of version of JDK entirely depends on the system requirements, though best practice is to configure the JRE_HOME/JAVA_HOME to the installed JDK on the local system. In order to change these settings open up the setenv.bat file (which can be found under bin directory) in a text editor and modify the path of JRE_HOME as follows:
JRE_HOME=%CATALINA_HOME%/jre1.6.0_20/win
to
JRE_HOME=PATH_TO_INSTALLED_JDK
These are some of the best practices which I have learned from my experiences in Liferay Development.
I will keep adding more such best practices to help people work with Liferay the right way.
Liferay Migration Process from 4.x to 6.x
Introduction:
I am considering JBoss bundled Liferay Portal.
Liferay is a portal framework which can be used to create and manage web portals in a much easier way than any other existing portal framework. Liferay has been evolving since they released Liferay 4.2.3 Portal with many user friendly features which soon started getting popular. Today the released version of Liferay is Liferay 6.1 with many more enhancements and new features which makes Liferay the most downloaded open source software of all times.
As Liferay was evolving there was need to support migration from an old version to any other version above this version. So Liferay came up with migration APIs to facilitate the migration process.
This document will describe approach and guidelines of how to understand and perform database migration from Liferay 4.2.3 to Liferay 6.1.
As per the recommendations from Liferay regarding database migration, we need to perform the migration in 3 stages stated below:
Stage I - Migration from Liferay 4.2.3 to Liferay 5.2.3
Stage II - Migration from Liferay 5.2.3 to Liferay 6.0
Stage III - Migration from Liferay 6.0 to Liferay 6.1
Prerequisites:
In order to initiate the migration following are the prerequisites:
1. Liferay 4.2.3 Database Dump
2. Liferay 5.2.3 portal bundled with JBoss
3. Liferay 6.0 portal bundled with JBoss
4. Liferay 6.1 portal bundled with JBoss
5. Access to SQL Query Browser, for example if DB is MySQL then we need MySQL Query Browser
Methodology:
Step I
Take the DB dump and import the dump to another database. For Example , if the database name of Liferay 4.2.3 is "ABC" then take a backup as ABC.sql. Create a database with name "XYZ" and import ABC.sql into this database.
This will create a copy of the LIVE database, this step is very important because doing migration on the Live DB directly is risky and not recommended.
Step II
Once you have the copy of the Database, next we need to set up a vanilla Liferay 5.2.3 bundled with JBoss on the local system. As we know we need to create portal-ext.properties file to configure Liferay with a database., so once the file is created we need to mention the database name of the one which needs to be migrated. In this case it will be XYZ.
Once you have provided the details to connect to the DB, simply start the server. Liferay portal will identify by itself that the database to which is connected right now is of old version and based on the version number respective Upgrade process will be initiated.
Step III
In the upgrade process based on the version schematic changes are initiated on the DB. This will involve temporary back up of tables, then creation of new table structure and inserting the data into the table.
Once the upgrade process is completed then Verification Process is initiated. This process actually verifies that the data which is present in the table is as per the requirements of Liferay 5.2.3.
Once the data gets migrated to desired version try logging into the server and cross check the data which got migrated with original database.
By following the steps mentioned above migration process can be carried out for the other two stages.
Points to Remember:
1. If using a windows machine where the migration will be carried out then start the server within the command prompt using "catalina.bat run" command. This will help you in checking the logs even if there is a System Exception which caused the server to shutdown.
2. During the migration process if any exception occurs resulting into system error leading to shutdown of server, then check from logs to which version Liferay was upgraded to. For example, if in the logs its mentioned that Upgrade successful to 5.0.01 version then execute the following query for "release_" table in the database.
"update XYZ.release_ set build =5001 where releaseId=1"
3. By executing this query we have updated build number of the database to the version its already upgraded. If we do not execute the query and start the server then server will start from 4.2.3 schema only. So by executing this we have saved sometime.
4. During the migration process there may be chances of elevated usage of JVM so make sure that the Perm Size, Heap size are defined properly to avoid any performance issues.
5. Also, If experiencing same problem during migration again and again at the same stage then do check the associated source files, Liferay has some issues in their upgrade process. You may end up coding in ext for making upgrade process proper.
6. Upgrade process never makes any changes to custom tables present within the Database, but if these tables are being used in conjunction with another out of box tables then there will be changes involved at each level.
7. Apart from all the above criteria there will still be issues which may come up during the migration. All such issues will be different from case to case.
I am considering JBoss bundled Liferay Portal.
Liferay is a portal framework which can be used to create and manage web portals in a much easier way than any other existing portal framework. Liferay has been evolving since they released Liferay 4.2.3 Portal with many user friendly features which soon started getting popular. Today the released version of Liferay is Liferay 6.1 with many more enhancements and new features which makes Liferay the most downloaded open source software of all times.
As Liferay was evolving there was need to support migration from an old version to any other version above this version. So Liferay came up with migration APIs to facilitate the migration process.
This document will describe approach and guidelines of how to understand and perform database migration from Liferay 4.2.3 to Liferay 6.1.
As per the recommendations from Liferay regarding database migration, we need to perform the migration in 3 stages stated below:
Stage I - Migration from Liferay 4.2.3 to Liferay 5.2.3
Stage II - Migration from Liferay 5.2.3 to Liferay 6.0
Stage III - Migration from Liferay 6.0 to Liferay 6.1
Prerequisites:
In order to initiate the migration following are the prerequisites:
1. Liferay 4.2.3 Database Dump
2. Liferay 5.2.3 portal bundled with JBoss
3. Liferay 6.0 portal bundled with JBoss
4. Liferay 6.1 portal bundled with JBoss
5. Access to SQL Query Browser, for example if DB is MySQL then we need MySQL Query Browser
Methodology:
Step I
Take the DB dump and import the dump to another database. For Example , if the database name of Liferay 4.2.3 is "ABC" then take a backup as ABC.sql. Create a database with name "XYZ" and import ABC.sql into this database.
This will create a copy of the LIVE database, this step is very important because doing migration on the Live DB directly is risky and not recommended.
Step II
Once you have the copy of the Database, next we need to set up a vanilla Liferay 5.2.3 bundled with JBoss on the local system. As we know we need to create portal-ext.properties file to configure Liferay with a database., so once the file is created we need to mention the database name of the one which needs to be migrated. In this case it will be XYZ.
Once you have provided the details to connect to the DB, simply start the server. Liferay portal will identify by itself that the database to which is connected right now is of old version and based on the version number respective Upgrade process will be initiated.
Step III
In the upgrade process based on the version schematic changes are initiated on the DB. This will involve temporary back up of tables, then creation of new table structure and inserting the data into the table.
Once the upgrade process is completed then Verification Process is initiated. This process actually verifies that the data which is present in the table is as per the requirements of Liferay 5.2.3.
Once the data gets migrated to desired version try logging into the server and cross check the data which got migrated with original database.
By following the steps mentioned above migration process can be carried out for the other two stages.
Points to Remember:
1. If using a windows machine where the migration will be carried out then start the server within the command prompt using "catalina.bat run" command. This will help you in checking the logs even if there is a System Exception which caused the server to shutdown.
2. During the migration process if any exception occurs resulting into system error leading to shutdown of server, then check from logs to which version Liferay was upgraded to. For example, if in the logs its mentioned that Upgrade successful to 5.0.01 version then execute the following query for "release_" table in the database.
"update XYZ.release_ set build =5001 where releaseId=1"
3. By executing this query we have updated build number of the database to the version its already upgraded. If we do not execute the query and start the server then server will start from 4.2.3 schema only. So by executing this we have saved sometime.
4. During the migration process there may be chances of elevated usage of JVM so make sure that the Perm Size, Heap size are defined properly to avoid any performance issues.
5. Also, If experiencing same problem during migration again and again at the same stage then do check the associated source files, Liferay has some issues in their upgrade process. You may end up coding in ext for making upgrade process proper.
6. Upgrade process never makes any changes to custom tables present within the Database, but if these tables are being used in conjunction with another out of box tables then there will be changes involved at each level.
7. Apart from all the above criteria there will still be issues which may come up during the migration. All such issues will be different from case to case.
Subscribe to:
Posts (Atom)