Setting up the developer's environment

Many developers want to customize Liferay Portal to fit it to a client's requirements. Also, in this book, there will be a number of examples of code, so the setting environment is an important step to start with. Liferay mentions that there are two types of development and two ways to get sources:

• GitHub: For contributors
• sourceforge.net: For non-contributors

For the purpose of this book, it is enough to use the non-contributors version only.

Getting ready

The minimal requirements to use Liferay Portal are Java Development Kit (JDK), Apache Ant with 1.7 version or later, and Eclipse IDE Indigo or later. Make sure that the installation is successful by typing the following lines of code:

$ ant -version
Apache Ant(TM) version 1.8.2 compiled on May 18 2012

$ java -version
java version "1.7.0_45"
Java(TM) SE Runtime Environment (build 1.7.0_45-b18)
Java HotSpot(TM) 64-Bit Server VM (build 24.45-b08, mixed mode)

How to do it...

This recipe is divided into three sections. The first section contains a description of preparatory activities such as downloading Liferay sources or unpacking them. The second one provides a description about the required configuration. The last section focuses on compiling all Liferay sources and deploying them into Apache Tomcat server.

Import sources to the Eclipse IDE

The first step is importing Liferay sources as a project in our IDE. These steps are based on Eclipse IDE. To achieve this, follow these steps:

1. In ${liferay.home}, create a workspace folder.
2. Go to http://sourceforge.net/projects/lportal/files/Liferay%20Portal/ and choose the folder with the newest 6.x version. Next, find the file with the prefix liferay-portal-src-* and download it.
3. Unpack this file into the workspace folder.
4. Import this project to Eclipse IDE by going to File | Import | General | Existing Projects into Workspace and click on the Next button. On the next screen, select Select root directory and point to the folder with Liferay sources, which is ${liferay.home}/workspace/liferay-portal-src-${VERSION}. To complete this task, click on the Finish button.
5. After this step, it is necessary to create a folder called /portal-web/test/functional in the project. This actions resolves a warning in the Eclipse IDE with the following message: Build path entry is missing: Liferay-portal-src.6.2-ce-ga2/portal-web/test/functional.

Override app.server.properties

To be compatible with the existing Tomcat, which is placed in the ${liferay.home}/tomcat-7.0.42 folder, change the app.server.parent.dir properties. To achieve this, follow these steps:

1. Create app.server.${username}.properties in the main folder of the project, which is ${liferay.home}/workspace/liferay-portal-src-${VERSION}.
2. Override Server directory properties and set a new value:

   app.server.parent.dir=${project.dir}/../../

   It could also be an absolute path to Tomcat's parent folder.

   The ${liferay.home} folder should have the following hierarchy:

     .
     |-data
     |---document_library
     |---hsql
     |---lucene
     |-deploy
     |-license
     |-logs
     |-tomcat-7.0.42
     |---bin
     |---conf
     |---lib
     |---logs
     |---temp
     |---webapps
     |-workspace
     |---liferay-portal-src-6.2-ce-ga2

Compile and deploy

Go to {$liferay.home}/workspace/liferay-portal-src-${VERSION} and compile all Liferay sources using the ant all target in a command line.

Note

In this book, we will use a console approach to compile, deploy, and so on. Liferay provides Eclipse with Liferay IDE. For proper understanding, we will use command line as the main tool.

How it works

It could be a source of criticism that Liferay is managed by Apache Ant instead of Maven, Gradle, or other build-automation tools. As a matter of fact, the Apache Ant tool is sufficient to manage and compile the Liferay core. If someone wants to use Maven, they are free to use it in custom portlets. Liferay offers many archetypes to help create Maven projects for multiple plugins.

Let's take a closer look at the project in Eclipse IDE. There are many folders that contain huge bunches of packages. Let's examine the most important folders with regard to Liferay architecture:

Folder name	Description
Definitions	This contains the dtd and xsd definitions, for instance, the portlet.xml definition or the service.xml definition.
portal-impl	This is the central core of the portal. It implements all the interfaces that are exposed in global lib. Also, it contains model definitions. Never put portal-impl anywhere other than where it came from.
portal-service	This provides the interfaces' definitions, which can be used in custom implementation, for instance hooks, portlets, themes, and so on.
util-bridges	This contains bridges and utilities, which can be helpful to implement custom portlets, such as AlloyPortlet, BSFPortlet, MVCPortlet, and so on.
portal-web	This contains the web application root, which has all the configuration files and view tier.

Let's get back to the compile command, ant all. What exactly happened here? Portal has its own runtime structure. It provides ready-to-use bundles with Tomcat, JBoss, or other application servers. It gives a tool that can build a runtime bundle. In the main build.xml Ant file, there is a definition of Ant target https://ant.apache.org/manual/targets.html:

<target name="all">
  <antcall target="clean" />
  <antcall target="start" />
  <antcall target="deploy" />
</target>

The building process consists of three parts: clean, start, and deploy.

Clean process

The ant clean command performs the following steps:

• It cleans Java classes under the following folders: classes, portal-service, util-bridges, util-java, util-slf4j, util-taglib, portal-impl, portal-pacl, osgi/bootrstap, portal-web and sql
• It deletes files with mask *.ear, *.jar, *.war, and *.zip
• It cleans the work, temp, and logs Tomcat folders and removes the *-hook.xml and *-portlet.xml files from the /conf/Catalina/localhost directory

There are some more steps that clean or delete many configuration files depending on the application server. To understand the processes used in this book, it is not important to know every step and deep cleaning process.

Start process

The ant start target invokes the following tasks:

• It runs the compile target that compiles sources under the portal-service, util-bridges, util-java, util-slf4j, util-taglib, portal-impl, portal-pacl, and osgi/bootstrap folders
• It builds a database and rebuilds the hypersonic database
• It builds themes under the portal-impl folder
• It calls the jar target that generates JAR's and WAR of the Liferay core

Deploy process

This target is strictly dependent on the application server. In general, this build deploys applications into a specific servlet container or application server. Furthermore, this build creates the required folders or files under ${liferay.home}. The folders that this build creates are as follows:

• The deploy folder for the hotdeploy process
• The data folder, which contains binary data, such as document library, Jackrabbit, HSQLDB, or Lucene
• The ROOT.xml context configuration file in ${app.server.dir}/conf/Catalina/localhost/ and many other tasks depending on the application server

There's more...

As mentioned earlier, it is possible to create a full bundle without manually downloading Tomcat or other application server. There are only two steps in order to achieve this goal:

• Invoke the ant -buildfile build-dist.xml unzip-tomcat task
• Invoke the ant all command

It is possible to deploy Liferay on a different application server. There is a whole range of commands that do this:

ant -buildfile build-dist.xml build-dist-geronimo
ant -buildfile build-dist.xml build-dist-glassfish
ant -buildfile build-dist.xml build-dist-jboss
ant -buildfile build-dist.xml build-dist-jboss-eap
ant -buildfile build-dist.xml build-dist-jetty
ant -buildfile build-dist.xml build-dist-jonas
ant -buildfile build-dist.xml build-dist-resin
ant -buildfile build-dist.xml build-dist-tcat
ant -buildfile build-dist.xml build-dist-tomcat