Liferay Portal

Liferay Portal
by Brian Kim
Copyright © 2005 bkim@liferay.com

This is a tutorial for Liferay Portal. Liferay Portal is an open source portal that helps
organizations collaborate more efficiently by providing a consolidated view of disparate
applications via a web browser.

Table of Contents
1. Introduction
1.1. Introduction
1.2. Recommended Requirements
2. Installation
2.1. Setting Up Your Development Environment
2.2. Obtaining Liferay Portal’s Source Code
2.3. Installing Your IDE – Eclipse
2.4. Developing with Liferay’s Core Source
2.4.1. Obtaining Orion Application Server
2.4.2. Configuring Eclipse with Orion
2.4.3. Setting Up Orion
2.4.4. Configuring Your Properties
2.4.5. Deploying to Orion
2.5. Creating an Extension Environment
2.5.1. Setting Up Ext
2.5.2. Adding Plugin support
2.5.3. Hooking Up To a Database
2.5.4. Starting Liferay

Chapter 1. Introduction
1.1. Introduction
In this document, my goal is to help you setup your environment so that you can begin
developing your own custom portlets from scratch. This document assumes that you
have some working knowledge of Servlets, JSPs, and web development in general.
Although I’ll be assuming that you are running on a Windows OS, I’ll try to keep my
explanations general enough so that they can be used for any operating system.

This tutorial will cover the setup of a development environment, from using an IDE
such as Eclipse to setting up your database connections. While my focus will be on
using Liferay Professional – the Tomcat Spring framework version – I will briefly touch
on the Enterprise version as well.

1.2. Recommended Requirements

Although you could probably get away with lesser requirements, when developing and
customizing Liferay, we recommend the following hardware requirements:

1 gig of RAM
2.0 ghz Pentium processor

Chapter 2. Installation
2.1. Setting Up Your Development Environment

As with any enterprise Java application, setting up Liferay can be a daunting task.
Liferay leverages several frameworks. Fortunately for you, most of these frameworks
come bundled with Liferay already. What you do need to install, however, are some of
the basic tools that Liferay uses. Let’s first ensure that you’re using the right Java JDK.
You should be using the latest release of J2SE 1.4.2, which may already be installed on
your machine. If not, download the latest version from http://java.sun.com. Since
we’ll be installing several Java technologies, I typically install/unzip my files under a
common folder such as D:\Java. Obviously you can choose to install them into any
directory of your preference, but from here on out I will reference the installation folder
as {Java}. Although you can use Sun’s default Java compiler, we recommend using
IBM’s Jikes compiler – it is generally more descriptive with compile errors. Make sure

you download version 1.21, since version 1.22 is oriented towards J2SE 1.5, which
Liferay Portal does not use due to backwards compatibility reasons. Finally, you’ll need
to download the latest version of Ant, a Java-based build tool, from
http://ant.apache.org. Once you’ve downloaded and installed/unzipped all the files
described above, you’ll need to set your environmental variables to point to them. In
Windows, open your Control Panel, choose System properties, click the Advanced tab,
and click Environmental Variables.

Figure 2.1. Environmental Variables

Choose New, and then add the following three variables: JAVA_HOME,
JIKES_HOME, and ANT_HOME. Each respective variable needs to point to the
directory in which your tools reside. If you look at Figure 2.1, you can see that my
JAVA_HOME variable points to {Java}\j2sdk1.4.2_05. It is recommended that you
remove the CLASSPATH variable to prevent conflicts when compiling. It is generally
good practice to develop without the use of a classpath variable, since doing so creates
a dependency on the developer’s machine. Once you have your three System variables
setup, you need to edit the Path variable by adding the
following: %ANT_HOME%\bin;%JAVA_HOME%\bin;%JIKES_HOME%\bin

2.2. Obtaining Liferay Portal’s Source Code

In order to keep up-to-date with Liferay’s upgrades, you will want to create an extension
environment. To start, go to http://www.liferay.com/web/guest/downloads/portal_source


and download the latest stable Liferay Portal Enterprise source. I would recommend
unzipping the bundle into a directory like D:\cvsroot\liferay (I use CVS as a code
repository), which I will refer to as {Liferay}. Then download the latest stable Liferay
Portal bundle, in particular Liferay Portal Professional (Bundled with Tomcat) for this
tutorial. I’ll explain what to do with the Tomcat bundle later on in this chapter.

2.3. Installing Your IDE – Eclipse

Despite the fact that you could modify and deploy Liferay Portal with as simple as an
editor as Textpad, a good IDE can help speed up the process. I’ll show you how Eclipse
plugins can make life easier for editing, deploying, and running Liferay Portal.
Download the newest version of the Eclipse from
http://www.eclipse.org/downloads/index.php. Install Eclipse into {Java}\eclipse and
then run it. Select File from the menu bar and then choose Switch Workspace…Within
the input box, type the path of {Liferay}, as shown in Figure 2.2.

Figure 2.2. Creating a new Workspace

To setup your project within your workspace, select File from the menu bar, New, then
Project. Select Java Project from the dialogue box and click Next. In the New Java
Project window, enter portal as the Project Name, and then click Finish.


 Figure 2.3. Adding a new java project

If you’ve setup the Workspace correctly, you should be able to see the portal project
within the Navigator pane of the Resource perspective. If you right click on the root
directory of the project, select Properties, choose Java Build Path from the left
navigation, and the Libraries tab from the right, your portal project should have all the
necessary jars loaded already. These jars are loaded via the .classpath file that exists in
{Liferay}\portal.

Adding plugin support for Eclipse is even easier. Since Eclipse comes bundled with Ant,
setting up Ant is as easy as selecting Window from the menu bar, choosing Show View
and then Ant. You should see the Ant tab displayed within your current perspective.
Adding Liferay’s build files is just as easy. Simply select the Ant tab in your
perspective and then click the Ant icon with the + symbol. Note that each directory
within Liferay contains its own build.xml file, which Ant reads. When clicking the Ant
icon, select the build.xml file within the portal directory. Your Ant setup should look
like Figure 2.3.


 Figure 2.3. Adding the Ant plugin

2.4. Developing with Liferay’s Core Source

The following section outlines how to develop and debug Liferay’s core source using
Orion’s application server. It is important to note that working off the core source is not
recommended. If you are trying to extend the functionality of Liferay Portal, it is
suggested that you create an Extension Environment, as outlined in the next section
(2.5). Development of the core portal should only be done for bug fixes or
enhancements that potentially would make it into the next build. Typical developers will
not need to read this section.

2.4.1. Obtaining Orion Application Server

Although Liferay’s core source could be deployed to other application servers, the build
files were written specifically with Orion in mind. An evaluation version of Orion is
available for download at http://www.orionserver.com. Extract the files into your
installation folder (i.e. {Java}\orion-2.0.6), which I will reference as {orion}. To test out
your server, from your Orion home directory, run the command: “java –jar orion.jar”.

2.4.2. Configuring Eclipse with Orion

Running Orion from your Eclipse IDE takes a little more time to setup. First change
your perspective to Debug. Underneath the menu bar, there is a bug-like icon. Click


the small drop down arrow to the right of it and then select “Debug…”, at which point a
dialogue box should appear.

Figure x.1. Debug

If you have any existing configurations under the Java Application group that are no
longer applicable, you can go ahead and delete them. Go ahead and click the New
button, and then make the following changes:

Main Tab
1. change the Name of the configuration to “orion”
2. set the Main class to be “com.evermind.server.ApplicationServer”

Arguments Tab
1. Program arguments: -config {orion}/config/server.xml -userThreads (note that
you need to change the directory path)
2. VM arguments: -Xmx256m -Dfile.encoding=UTF8 -Duser.timezone=GMT


Classpath Tab
1. under the User Entries group, remove the “portal (default classpath)” entry
2. click Add External JARs, and then browse to your orion.jar to add it

Note: make sure that within your JRE Tab, your Project JRE points to a SDK as
opposed to just a JRE (i.e. my Project JRE has j2sdk1.4.2_05 next to it in parenthesis.
This may require you to add another entry within Java (from the left navigation)
Installed JREs.

2.4.3. Setting Up Orion

There are three key files when configuring Orion. The first, {orion}\config\server.xml,
let’s you specify which “web-sites” will be accessible when started up. Add a new
website by inserting the element:

<web-site path="./web-sites/portal.liferay.com-web.xml" />

You can also specify for Orion to use another compiler by adding:

<compiler executable="jikes" classpath="{Java}\jre\lib\rt.jar" />

Now that you’ve specified a new website, you need to create a file called
portal.liferay.com-web.xml within {orion}\config\web-sites\. You’re file should look
something like this:

Figure x.2. portal.liferay.com-web.xml


Finally, in {orion}\config\application.xml, you need to add both web-module elements
and ejb-module elements. All web-app elements declared in your portal.liferay.com-
web.xml must be defined in your application.xml:

Figure x.3. application.xml

Add the references to your EJBs as well by inserting the ejb-module elements. Note that
by using the “file:” prefix, you can have Orion look for the direct files. An advantage
of using this prefix is that you don’t have to deploy your files to the server. This can be
particularly useful for quickly debugging JSPs (simply save your JSP and refresh).
Another advantage is that for class files, you can just compile the source files rather
than having to compile and deploy.

Note: When using the “file:” prefix for the portal-ejb module, you need to ensure that
the portal-ejb.jar does not exist within your {orion}\applications\ directory.

Finally, you must edit your {orion}\config\data-sources.xml to allow your application to

access your database. If you are using MySQL, make sure that the mysql.jar gets
deployed to your {orion}\lib\ directory, and configure your data-sources.xml file like so:

<data-sources>
<data-source
class="com.evermind.sql.DriverManagerDataSource"
name="Liferay"
location="jdbc/LiferayCore"
pooled-location="jdbc/LiferayPool"
xa-location="jdbc/xa/LiferayXA"
ejb-location="jdbc/LiferayEJB"


 connection-driver="com.mysql.jdbc.Driver"
url="jdbc:mysql://localhost/lportal"
username="root"
password=""
inactivity-timeout="30"
schema="database-schemas/mysql.xml"
/>
</data-sources>

2.4.4. Configuring Your Properties

Most of Liferay’s configuration is set using a flat file called portal.properties. Similar
to your build.properties, you want to override any property settings within portal-
ext.properties rather than in portal.properties itself. To configure your portal, create a
new file within {Liferay}\portal\util-java\ called portal-ext.properties. Within there,
add the following setting:
portal.ctx=/portal

Again, note that this property setting in portal-ext.properties overrides the property
setting in portal.properties.

2.4.5. Deploying to Orion

In order for your ant scripts to know where to deploy to, you need to create an extension
file named like app.server.{username}.properties. Within the file, add the following
line:

app.server={orion}

Remember that {orion} represents your orion home directory, and for this property,
should also use forward slashes (i.e. app.server=D:/Java/orion-2.0.5). Finally, from your
Ant View in Eclipse, run the start and deploy targets from your portal directory. If
you’ve used the “file:” prefix, don’t forget to delete portal-ejb.jar after deploying!

You’re all set! Go ahead and click the bug icon in your Debug perspective, and within
your console you should see Orion startup.

2.5. Creating an Extension Environment

It is in your best interest to develop your portlets via an Extension Environment. This
would allow you to upgrade your portal without any headaches. Any time a new stable
version of Liferay Portal is released, all you would need to do is drop in the new jars
and you’re set to go. With that said, your development should only be done within the
Extension Environment as well. Meaning, all new classes, JSPs, and all changes in
general, should be within {Liferay}\ext.

2.5.1. Setting Up Ext

Setting up your Extension Environment is simple. Before anything, you will need to
change a property file (.properties) within {Liferay}\portal. Note that you should never
change the values of the default .properties files. Instead, follow the instructions
commented at the top of each .properties file, which states that you should instead create
an extension file named like release.{username}.properties. You can find out what your

${username} value is by opening a command prompt from Start Run and seeing

what name shows up after Documents and Settings (i.e. release.Brian Kim.properties).
Within your new .properties file, add just one line (with {Liferay} being the actual
directory of course):

lp.ext.dir={Liferay}/ext
(Note that it’s a forward slash)

Next, in the Ant View described in 2.3, you should be able to expand portal’s build.xml
target list. Among the targets, you should see clean, start, build-ext. Go ahead and
double click those targets (in that order) while watching the Console View. You should
see a whole lot of text scrolling by – indicating that your Extension Environment is
being built. To double check, quickly skim the Console output for any red errors. You
may find that you might have incorrectly set some of your properties. If all goes well,
you should be able to browse to your new extension directory by going to
{Liferay}\ext!

Remember the Liferay Portal Professional (Bundled with Tomcat) that I had you


download in section 2.2? Well, here’s what you need to do with it. Simply unzip the file
into {Liferay}\ext\servers\tomcat. Like before, you need to create an
app.server.{username}.properties file within {Liferay}\ext that includes only the two
lines:

lp.ext.dir={Liferay}/ext
app.server.type=tomcat

This designates where your Extension Environment is to copy files from, and what
server directory to deploy to.

In order to develop in Eclipse using the Extension Environment, follow the same
instructions for adding a New Java Project (as described earlier for portal). However,
this time, use the name ext as the Project name instead.

2.5.2. Adding Plugin Support

If you are planning on using Liferay Portal Professional, which implements the Spring
framework, it would be a good idea to download the Sysdeo Eclipse Tomcat plugin.
This plugin would allow you to troubleshoot Liferay Portal using Eclipse’s debugger.
Download the latest version (I have version 3.0) of the Sysdeo plugin from
http://www.sysdeo.com/eclipse/tomcatPlugin.html, and then unzip it into the plugins
folder (i.e. {Java}\eclipse\plugins\com.sysdeo.eclipse.tomcat_3.0.0). Close and then
restart Eclipse and you should see the Tomcat icons just below the Search menu.

Let’s configure your Tomcat plugin now. Choose Windows from the menu bar,
Preferences, then select Tomcat from the left navigation. You’ll need to select the
appropriate Tomcat version. If you downloaded Liferay Portal Professional (Bundled
with Tomcat), then check Version 5.x. You’ll also need to set the following variables:

Tomcat home: {Liferay}\ext\servers\tomcat

Configuration file: {Liferay}\ext\servers\tomcat\conf\server.xml

 Figure 2.4. Setting up Tomcat in Eclipse

Since Liferay uses JAAS for authentication, you need to add a JVM parameter. Select
JVM Settings from the left navigation (under the Tomcat node) and click the Add button
respective to the Append to JVM Parameters section. When the small prompt comes up,
add this:

-Djava.security.auth.login.config={Liferay}/ext/servers/tomcat/conf/jaas.config

To allocate enough memory for Tomcat when Liferay is running, you need to add the
following parameter as well (assuming you have at least 512 megs of RAM):

-Xmx512m

Note: make sure that within your JVM Settings your JRE points to a SDK as opposed to
just a JRE (i.e. my JRE has j2sdk1.4.2_05 showing in the dropdown box). This may

require you to add another entry within Java (from the left navigation) Installed

JREs. Otherwise, you’ll find that your Tomcat runs correctly the first time, but not on
successive attempts.

If you’re wondering what port your portal will be running on, check out your
{Liferay}\ext\servers\tomcat\conf\server.xml and search for your “Connector port”


setting. To test to see if you’ve setup Tomcat correctly, click on the cat-like icon at the
upper left of your Eclipse window, and it should start up. Remember that you still have
a database to setup, however.

2.5.3. Hooking Up To a Database

Unfortunately, writing documentation of how to hook up to a database would take too

long (and probably bore you) since there are so many different databases you can use
with Liferay Portal. The best reference for this would be on Liferay’s website,
specifically here:

http://www.liferay.com/web/guest/documentation/development/databases

There it will go in depth into how to setup and connect to your database of choice
depending on your server.

2.5.4. Starting Liferay

Now that you have your environment all configured, go ahead and click the Tomcat
icon to start up your web server. As long as you’ve left the default settings, you should
be able to browse to http://localhost and see Liferay Portal load up!

Note: because of the nature of Hypersonic, the Sysdeo plugin will not work correctly
with our configuration. If you plan on using Hypersonic as your database, you will need
to actually browse to {Liferay}\ext\servers\tomcat\bin in your command prompt, and
manually type in startup to start Tomcat.