Liferay 6.x Portal Enterprise Intranets Cookbook

Chapter 1. Installation and Basic Configuration

In this chapter, we will cover the following topics:

Quick running Liferay on a Tomcat bundle
The Liferay setup wizard and first login
Setting up the developer's environment
Creating a custom portlet

Introduction

Liferay is the market's leading provider of open source portal solutions. It provides a solid platform to serve our site to all clients. It is difficult to say what Liferay is. On the one hand, Liferay is a great content-management system, but on the other hand, it provides many tools for collaboration and communication between users. It can also be a social platform with many functionalities, such as wall, message board, chat, and many others. Furthermore, it is a portlet container that is JSR-168 and JSR-286 compliant. Java Specification Requests (JSRs) describes final specifications for the Java platform. A portlet is a small web application that produces fragments of HTML code that are aggregated into a portal. JSR-168 and JSR-286 specifications standardize how portlets interact with portlet containers. These specifications also describe a standard application programming interface for Java portlet development. In other words, Liferay is only responsible for aggregating the set of portlets that are to appear on any particular page. This approach gives users a great tool to organize and customize portlets in order to build whole portals, social platforms, or intranets. Within Liferay, a portal is composed of a number of portlets, which are self-contained interactive elements that are written to a particular standard. A number of publications describe Liferay's advantages. In this book, we will try to delve deeper into Liferay's architecture and its functionalities.

The primary purpose of this chapter is to give you an insight about Liferay's installation and management with basic configuration. We realize that there are many ways to download, compile, install, and run Liferay Portal. Our main purpose is to provide some clear and basic information about the starting package on which we will rely and work. This chapter explains the main processes that are performed on every compiling action or on every startup action.

Liferay Portal is distributed in two different editions:

Liferay Portal Community Edition (CE): This is a free and open source version of Liferay
Liferay Portal Enterprise Edition (EE): This is a commercial offering that has Liferay engineers, support, and services

This book is based on the Liferay Portal Community Edition (CE) version with the newest release, which is 6.2.

To start the journey with Liferay, there are a few starting points that contain a lot of useful information, which are as follows:

URL	Description
http://www.liferay.com/	Official Liferay site
http://www.liferay.com/downloads/liferay-portal/available-releases	Place with available releases
http://www.liferay.com/documentation/liferay-portal/6.2/user-guide and https://dev.liferay.com/	User guides and documentation
http://svn.liferay.com/repos/public/portal	Old-fashion repository of Liferay code. Login: Enter guest in this field Password: This field is to be left empty
https://github.com/liferay/liferay-portal/tree/6.2.x	[Recommended] GitHub repository

Tip

Liferay introduced 7.0 version, which will be released on September 2015. Do not check out Liferay sources from the trunk. There are many changes between 6.2 and the trunk version. In the 7.0 version, Liferay will provide OSGi integration and many new features. These new features help users and developers achieve a whole bunch of out-of-the-box functionalities (for instance, Elasticsearch as a search server based on the Lucene framework).

Quick running Liferay on a Tomcat bundle

The simplest way to run Liferay is to download a specific bundle from the Liferay official site. A Liferay bundle is just a compressed archive that contains all that is needed to host the Liferay Portal. A bundle consists of a Java-based application server and the deployed Liferay Portal core application. Liferay provides these bundle runtimes with different application servers (that is, Tomcat, JBoss, Geronimo, and so on) so that you can use any one based on your choice. This method is recommended for people who just want to run Liferay Portal, look at its functionalities, and configure their site using the GUI. In this recipe, you will learn the art of setting up Liferay on Tomcat and the MySQL database engine.

Getting ready

First, make sure that JRE or JDK is properly installed. Type the following command line:

$ java -version

The result should be similar to this:

$ 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).

Also, check out the Java SDK version. Liferay recommends Java 7 or later.

Moreover, determine whether the MySQL server installation is done:

$ mysql --version

As a result, the actual installed version should be displayed. Here is an example:

mysql  Ver 14.14 Distrib 5.5.34, for debian-linux-gnu (x86_64)

Also, check out the MySQL version. We recommend 5.5 version or later.

How to do it...

In order to run Liferay on a Tomcat bundle, follow these steps:

Create a database with the name lportal:

CREATE DATABASE lportal CHARACTER SET utf8 COLLATE utf8_general_ci;
grant all privileges on lportal.* to '{USERNAME}'@'%' identified by 'PASSWORD';

Make sure that the MySQL user has permissions to create tables.

Download the correct Liferay version on the Tomcat bundle from http://www.liferay.com/downloads/liferay-portal/available-releases.
Unzip the downloaded archive.
Go to the extracted folder liferay-portal-6.2-ce-ga2. This path will be called ${liferay.home} folder.
Go to the ${liferay.home} folder and create a file called portal-ext.properties.

Edit portal-ext.properties and set the database properties:

jdbc.default.driverClassName=com.mysql.jdbc.Driver
jdbc.default.url=jdbc:mysql://localhost/lportal?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false
jdbc.default.username={USERNAME}
jdbc.default.password={PASSWORD}

Find the Tomcat folder and go to the tomcat-7.0.42/bin/ location.
Run the ./startup.sh script (startup.bat for Windows OS) and look into the tomcat-7.0.42/logs/catalina.out log.
In a browser, type http://localhost:8080 location. By default, Tomcat listens on port 8080. It should render the Liferay setup wizard by default. This wizard will ask for basic information, such as, portal name, default language, and administrator user details.

How it works...

Running the Liferay Portal from a prepared bundle is quite an easy task to accomplish. However, it is worth knowing what exactly happens when Tomcat is being started. Take a brief look at the catalina.out log and try to examine it line by line.

Loading the configuration descriptor

The first thing is to deploy ROOT.xml. In our catalina.out file, there is a line present, which is shown as follows:

INFO: Deploying configuration descriptor /home/piotr/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/conf/Catalina/localhost/ROOT.xml

It means that the configuration file turns on the crossContext attribute in Tomcat 7. This setting is required because Liferay is a portlet container. Hence, it is an application that should have access to other applications called portlets. The Apache Tomcat documentation says:

"Set to true if you want calls within this application to ServletContext.getContext() to successfully return a request dispatcher for other web applications running on this virtual host."

Loading system properties and portal properties

The next few lines of the logfile show portal properties and system properties that are loaded from specific locations:

Loading jar:file:/home/piotr/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/webapps/ROOT/WEB-INF/lib/portal-impl.jar!/system.properties
Loading jar:file:/home/piotr/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/webapps/ROOT/WEB-INF/lib/portal-impl.jar!/system.properties
Loading jar:file:/home/piotr/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/webapps/ROOT/WEB-INF/lib/portal-impl.jar!/portal.properties
Loading file:/home/piotr/liferay-portal-6.2-ce-ga2/portal-ext.properties

The main configuration file for Liferay Portal is portal.properties, which contains a detailed explanation about the properties that it defines. There are at least three possible ways to override portal.properties. There is a functionality to put portal-ext.properties in the ext plugin, in the ${liferay.home} directory, or in portal-setup-wizard.properties. But which file is the most important? The answer is placed in portal.properties file. The default read order is portal.properties, portal-bundle.properties, portal-ext.properties, and then portal-setup-wizard.properties:

    include-and-override=portal-bundle.properties
    include-and-override=${liferay.home}/portal-bundle.properties
    include-and-override=portal-ext.properties
    include-and-override=${liferay.home}/portal-ext.properties
    include-and-override=portal-setup-wizard.properties
    include-and-override=${liferay.home}/portal-setup-wizard.properties

Detecting the database and database dialect

The next step is to recognize the database's dialect:

12:35:47,469 INFO  [localhost-startStop-1][DialectDetector:71] Determine dialect for MySQL 5
12:35:47,504 INFO  [localhost-startStop-1][DialectDetector:136] Found dialect org.hibernate.dialect.MySQLDialect

Liferay supports many database engines, such as DB2, Derby, Hypersonic, Ingres, MySQL, Oracle, P6Spy, PostgreSQL, and Sybase. The default database is Hypersonic, which stores all data in the ${liferay.home}/data/hsql/lportal directory. This is a good option for developers who want to run JUnit tests, which modify data by testing the persistence layer or business process.

On every restart, Liferay tries to get the build number (Liferay version) from the Release_ table. If this table doesn't exist, it calls ReleaseLocalService.createTablesAndPopulate().

If it is not possible to get the build number, Liferay logs the following information:

WARN  [localhost-startStop-1][ReleaseLocalServiceImpl:171] Table 'lportal.Release_' doesn't exist

The createTablesAndPopulate method runs following scripts:

liferay-portal/sql/portal-tables.sql: This creates the required tables
liferay-portal/sql/portal-data-common.sql: This adds the default data
liferay-portal/sql/portal-data-counter.sql: This inits the unique key generator
liferay-portal/sql/portal-data-release.sql: This sets the release date
liferay-portal/sql/indexes.sql: This adds database indexes
liferay-portal/sql/sequences.sql: By default, this file is empty.

Apart from creating tables and populating data, Liferay triggers the VerifyProcess mechanism. This process will run on every startup to verify and fix any integrity problems found in the database. This is the perfect place for developers to add custom code to check the integrity of specific cases.

Starting the autodeploy scanner and deploying plugins

The last step is initializing the autodeploy and the hotdeploy listeners. In general, these mechanisms install all the plugins into the Tomcat container and register them as portlets, hooks, themes, and so on. In particular, there are at least three deploying approaches: sandbox deploy, autodeploy, and hotdeploy.

Note

By default, Liferay uses the autodeploy and hotdeploy listeners. In fact, sandbox can currently deploy only themes and portlets.

The autodeploy mechanism is responsible for listening on a specific directory to install on-the-fly new plugins and copying them into the Tomcat hotdeploy process. A definition of that directory is placed in portal.properties, and by default, it is in the deploy folder:

auto.deploy.deploy.dir=${liferay.home}/deploy

Every type of plugin has its own autodeploy mechanism. This mechanism runs all the necessary steps to install it correctly in the Liferay container. In simple terms, the autodeploy mechanism generates the web.xml file and adds the required libraries to specific plugins. Definitions of these classes are placed in the portal.properties file with an auto.deploy.* prefix. Each class extends BaseAutoDeployListener.

The second process, hotdeploy, is responsible for registering plugins in Liferay. There are many steps, such as creating database tables, setting preferences, registering Spring application contexts, and so on. Of course, each step depends on the type of plugin. In portal.properties, there are definitions for each type of class:

hot.deploy.listeners=
com.liferay.portal.deploy.hot.PluginPackageHotDeployListener,
com.liferay.portal.deploy.hot.SpringHotDeployListener,
com.liferay.portal.deploy.hot.ServletContextListenerHotDeployListener,
com.liferay.portal.deploy.hot.ExtHotDeployListener,
com.liferay.portal.deploy.hot.HookHotDeployListener,
com.liferay.portal.deploy.hot.JSONWebServiceHotDeployListener,
com.liferay.portal.deploy.hot.LayoutTemplateHotDeployListener,
com.liferay.portal.deploy.hot.PortletHotDeployListener,
com.liferay.portal.deploy.hot.SocialHotDeployListener,
com.liferay.portal.deploy.hot.ThemeHotDeployListener,
com.liferay.portal.deploy.hot.ThemeLoaderHotDeployListener,
com.liferay.portal.deploy.hot.MessagingHotDeployListener

Tip

In the deployment process, the Liferay deployer modifies the web.xml file, adds specific dependencies, and packs it again. Ensure that you do not copy the WAR file directly to the Tomcat webapps folder. If you do so, the plugin will not work.

There's more...

Often, enterprises have an established Java EE infrastructure upon which they would like to install Liferay. You must consider also the enterprise's security policies. These policies sometimes prevent the download and installation of the Tomcat bundle into a location of your choice. In this situation, a bundle will not suffice, and you have to manually install Liferay from its WAR archive into an already existing Apache Tomcat application server.

There are six steps to achieve this goal. They are as follows:

Copy specific JAR files and dependencies to the Tomcat global lib folder, $TOMCAT_HOME/lib/ext.
Enable crossContext by adding the ROOT.xml file to the $TOMCAT_HOME/conf/Catalina/localhost folder.

Set custom $JAVA_OPTS parameters in the $TOMCAT_HOME/bin/setenv.sh file:

JAVA_OPTS="$JAVA_OPTS -Dfile.encoding=UTF8 -Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false -Duser.timezone=GMT -Xmx1024m -XX:MaxPermSize=256m"

Update the common.loader property located in $TOMCAT_HOME/conf/catalina.properties with the following lines of code:

common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar,${catalina.home}/lib/ext,${catalina.home}/lib/ext/*.jar

Specify the URI encoding as UTF-8 in $TOMCAT_HOME/conf/server.xml as follows:

<Connector port="8080" protocol="HTTP/1.1"
  connectionTimeout="20000"
  redirectPort="8443" URIEncoding="UTF-8" />

Deploy Liferay Portal using Tomcat manager or manually put the WAR archive into the $TOMCAT_HOME/webapps folder. The WAR file is available at http://www.liferay.com/downloads/liferay-portal/available-releases#additional-versions.

Note

More detailed instructions of how to install Liferay on the Tomcat server are available on the official Liferay documentation at https://www.liferay.com/documentation/liferay-portal/6.2/user-guide/-/ai/installing-liferay-on-tomcat-3.

The Liferay setup wizard and first login

After successfully running Liferay on the Apache Tomcat server, the system asks users to fill some necessary information to complete the setup wizard. This is only a single screen with basic fields, such as administrator name or portal name.

How to do it…

After running Liferay for the first time, the Liferay platform displays the basic configuration form, which looks like this:

To finish installation, it is necessary to fill in the preceding form as follows:

Provide details about Portal:
- Portal Name: This is the name of the website, for instance, Enterprise Intranets
- Default Language: This helps in choosing the default language of the portal
- Add Sample Date: This decides to populate the portal with default data
Provide details about Administrator User:
- First Name and Last Name
- E-mail address
Choose the database engine (optional). In the previous recipe, we set properties with a MySql connection.
Confirm the form.
Click on the Go to My Portal button.
Click on the I agree button on the Terms of Use screen.
Fill in the Password Reminder form and confirm the form.
After confirming the Password Reminder form, you will be able to see and use the main Liferay navigation tools.

Follow these steps to navigate to Control Panel:

Click on the Admin button located on the dockbar menu.
Click on the Control Panel link.

How it works…

After running Liferay for the first time, Liferay needs basic information about the portal, database, and administrator. The database connection was set in portal-ext.properties, and it was described in the previous recipe.

All data which was provided on the portal wizard was stored in the ${liferay.home}/portal-setup-wizard.properties file. The most important settings are described in the following table:

Property name	Description
`admin.email.from.name`	This describes the name of the administrator.
`admin.email.from.address`	This is the e-mail address of the administrator.
`liferay.home`	This is the path to the `${liferay.home}` directory. This property is very important and must be set.
`setup.wizard.enabled`	This flag disables the setup wizard.

After logging in, the user is able to see navigation tools available for authorized users only. Here are the navigation tools:

The dockbar menu is located under the top screen edge. The dockbar consist of three buttons:
- The Admin button that allows us to navigate to the Site Administration and Control Panel sections
- The My Sites button that lists links to sites that the user is a member of
- The button with user name and surname that allows us to navigate to user's profile (My Profile), user's dashboard (My Dashboard), user's account (My Account), and also allows the user to log out
The fast edition menu is located near the left edge of the screen. The menu consists of the following icons:
- The Add icon that allows us to add a new page, a new application to the page, or new content
- The Edit icon that allows us to edit the settings of the currently viewed page
- The Preview icon that allows us to view the currently viewed page in different resolutions and devices
- The Edit Controls icon that allows us to hide or show controls of portlets

There's more…

In internal projects such as intranets, user accounts most often are created and managed in external systems, for instance, LDAP. Therefore, it is unnecessary (and sometimes even unacceptable) to allow users to manage their authentication data (for instance, to set a password-reminder query) or ask them to agree to terms of use directly within Liferay. In Liferay, there are many properties that can help customize the first login action, a few of which are as follows:

Property name	Description
`terms.of.use.required=false`	This turns off the terms of use
`terms.of.use.journal.article.group.id` and `terms.of.use.journal.article.id`	This specifies the group ID and article ID that will be displayed as the terms of use
`users.reminder.queries.enabled=false`	This disables the reminder query functionality

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:

In ${liferay.home}, create a workspace folder.
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.
Unpack this file into the workspace folder.
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.
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:

Create app.server.${username}.properties in the main folder of the project, which is ${liferay.home}/workspace/liferay-portal-src-${VERSION}.

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

Creating a custom portlet

This recipe is very specific, because it shows how to generate a new portlet, install it on Liferay, and import it to the Eclipse IDE. Many recipes from this book assume that the user knows how to generate a new plugin, such as portlet, hook, or web. We will show you how to generate a new portlet using Apache Maven archetypes. The whole book assumes that you use Apache Maven to compile and deploy new portlets.

Getting ready

In order to correctly generate a new portlet, you need to have the following software stack:

Java SDK 1.7 or later
Apache Maven, we use 3.0.5 version
Eclipse IDE (Kepler or later)

We also assume that you properly set the developer's environment, which was described in the previous recipe.

How to do it…

There are three phases to achieve our goal: generating a new portlet, compiling it, and deploying and importing it to the Eclipse IDE.

Generating a new portlet

The first thing we need to do is to create a Maven project. In order to generate it, follow these steps:

Go to the ${liferay.home}/workspace folder.
Execute mvn archetype:generate -Dfilter=liferay-portlet-archetype.
Choose a number for com.liferay.maven.archetypes:liferay-portlet-archetype. In our list, it is number 1:
```
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 1
```
Choose the correct Liferay version. In our example, it will be 6.2.2, with the number 24.

Provide all the required Maven project information as follows:

Define value for property 'groupId': : com.packtpub.portlet
Define value for property 'artifactId': : first-portlet
Define value for property 'version':  1.0-SNAPSHOT: : 
Define value for property 'package':  com.packtpub.portlet: : 
Confirm properties configuration:
groupId: com.packtpub.portlet
artifactId: first-portlet
version: 1.0-SNAPSHOT
package: com.packtpub.portlet
Y: : y

In our workspace folder, a portlet called first-portlet should be generated.

Compiling the portlet and deploying it

With Apache Maven, it is easy to compile and deploy a portlet. Before invoking the Maven command, users have to set specific properties in the pom.xml file.

Go to the ${liferay.home}/workspace/first-portlet folder and edit the pom.xml file.

Under the <build> section, add the following properties definition:

<properties>
  <liferay.version>6.2.2</liferay.version>
  <liferay.maven.plugin.version>6.2.2</liferay.maven.plugin.version>
  <liferay.auto.deploy.dir>${liferay.home}/deploy</liferay.auto.deploy.dir>
  <liferay.app.server.deploy.dir>${liferay.home}/tomcat-7.0.42/webapps</liferay.app.server.deploy.dir>
  <liferay.app.server.lib.global.dir>${liferay.home}/tomcat-7.0.42/lib/ext</liferay.app.server.lib.global.dir>
  <liferay.app.server.portal.dir>${liferay.home}/tomcat-7.0.42/webapps/ROOT</liferay.app.server.portal.dir>
</properties>

Tip

Replace ${liferay.home} with the real path to your folders.

Save the pom.xml file.
Build a new project by executing the following command:
```
mvn clean install
```
Make sure that your Apache Tomcat is running with Liferay.

Invoke the mvn liferay:deploy command and follow the catalina.out logfile. You should see a similar message:

[PortletHotDeployListener:343] Registering portlets for first-portlet
[PortletHotDeployListener:490] 1 portlet for first-portlet is available for use

Importing the portlet to the Eclipse IDE

After successfully generating sources by the Maven archetype plugin, the sources of our portlet can be imported to our Eclipse IDE. To import them, follow these steps:

Make sure that you are in the ${liferay.home}/workspace/first-portlet folder.
Run the mvn eclipse:clean eclipse:eclipse command.
Open your IDE and import first-portlet as a project by going to File | Import | General | Existing Projects into Workspace.

How it works…

A portlet project created from com.liferay.maven.archetypes:liferay-portlet-archetype has ready-to-use portlet implementation. In fact, it is very basic, but the entire folder's structure and configuration files are correctly created. Each portlet has four configuration files: portlet.xml, liferay-portlet.xml, liferay-display.xml, and liferay-plugin-package.properties. All of these files are placed in the first-portlet/src/main/webapp/WEB-INF folder.

The portlet.xml file is a portlet descriptor. It contains a portlet definition, such as name, portlet class, and so on.

The liferay-portlet.xml file is a kind of extension of portlet.xml. It is only understood by Liferay Portal. It gives additional information such as portlet's icon, path to the css and js files, and so on.

The liferay-display.xml file tells us in which section our portlet will be available. We will describe it later in the book.

The liferay-plugin-package.properties file is a metric of our portlet. This is a good place to specify version, tags, page URL, author, and license.

Detailed information on portlets is available in the JSR-168 and JSR-286 specification. There are many examples on how to use portlets, how to establish communication between portlets, or what is a portlet request lifecycle.