You are on page 1of 31

Build portlets with Apache Geronimo and Eclipse

Managing the Liferay portal with the Eclipse Web Tools Platform (WTP)
Skill Level: Intermediate Matthew Scarpino Java Developer Eclipse Engineering, LLC

24 Apr 2007 Web developers can build multifunctional portals by arranging simple, reusable, event-driven components called portlets. Eclipse makes this process even simpler. First, find out how the Eclipse Web Tools Platform (WTP) provides a complete development environment for editing the code and configuration files needed for portlet projects. Then, by integrating the Apache Geronimo Eclipse plug-in, learn how you can deploy and display these portlets inside a full portal by accessing the Geronimo application server.

Section 1. Before you start


About this tutorial
With the right open source tools, you can build a Web portal just as capable and multifunctional as any huge corporate site. This tutorial explores a method of creating such a portal by using three tools: The Eclipse integrated development environment (IDE) to develop the project An Apache Geronimo application server to deploy it

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 1 of 31

developerWorks

ibm.com/developerWorks

The Liferay portal to provide the overall structure It takes some effort to install these components and work out the version incompatibilities. But after configuration, the process of building and deploying the portal is straightforward.

Objectives
This tutorial covers: Organizing and simplifying portal development with the Eclipse WTP. Structuring portlets within the Liferay portal. Deploying a servlet-based portlet application to a Geronimo application server. Deploying a JavaServer Pages (JSP)-based portlet application with a Geronimo application server.

Prerequisites
This tutorial is written for enterprise Java developers whose skills and experience are at a beginning to intermediate level. You should have a general familiarity with Java technology, servlets, and JSP pages as well as a passing familiarity with Eclipse and how it manages projects.

System requirements
To start this tutorial, you need a recent version of Eclipse 3.2 or later on your system. You install the WTP, Geronimo server, Geronimo server run time, and Liferay portal platform during the course of the tutorial.

Section 2. Portals, portlets, and Geronimo


Learn the difference between portals and portlets, and discover the role that Apache Geronimo plays in their creation.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 2 of 31

ibm.com/developerWorks

developerWorks

Introduction to portals and portlets


Java Specification Request (JSR) 168 defines a portal as "a Web application that commonly provides personalization, single sign-on, content aggregation from different sources and hosts the presentation layer of Information Systems." It defines a portlet as a "Web component, managed by a portlet container, that processes requests and generates dynamic content." Functionally speaking, portlets generate fragments of markup in response to requests, and portals manage these fragments and structure them into a framework. Large institutions commonly use portals to provide users with multiple capabilities from a single page. In many cases, these portals also serve as intranet applications for institution-wide communication. Developing these pages would be unbearable with monolithic servlets, so portlets were created as pluggable components that can be dynamically added and modified. Thanks to the common JSR 168 standard, portal developers can mix and match portlets from different vendors without significant changes. So there's no need to rewrite registration applications, stock tickers, and Really Simple Syndication (RSS) feeds simply download and deploy, and you're done. Thankfully, many open source tools are available that make portal development available for everyone. The Apache Jetspeed project, released under the Apache License, provides a large set of features that includes database access, role-based security, and support for the Wireless Markup Language (WML). Apache Pluto is the reference implementation of JSR 168, which means that it can manage and display portlets according to the standard but doesn't provide the additional features that developers have come to expect. The JBoss portal is also very popular and is released under the Lesser GNU Public License (LGPL). This tutorial uses the Liferay portal platform to structure its content. (See the sidebar Liferay vs. Pluto for reasons why I chose this portal.) This platform is released under the MIT License, which means you can use it for proprietary purposes without paying royalties. In addition to providing a framework for displaying portlets, it integrates a large number of capabilities, including: Web-based Distributed Authoring and Versioning (WebDAV). A complete Content Management System (CMS). Directory modification through the Lightweight Directory Access Protocol (LDAP). Language translation. Support for many different application servers, including Geronimo.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 3 of 31

developerWorks

ibm.com/developerWorks

Many free example portlets, including chat clients, calendars, clocks, and RSS feeds. Liferay vs. Pluto
Pluto is included in Geronimo and is released by the Apache Software Foundation, so I feel compelled to explain why I chose Liferay as the portal framework for this tutorial. It comes down to ease of deployment. Liferay provides a Web application that runs immediately within Geronimo. But the Pluto artifact in the Geronimo repository isn't packaged as a Web application and isn't initialized when Geronimo starts. So it would have taken a lot of effort to configure a Pluto application for Geronimo and integrate it within the Apache Tomcat container. Also, according to the documentation on the Pluto site, Maven is the preferred application for accessing Pluto. Maven provides many advantages for large project management, but as I've learned from painful experience, the Maven plug-in doesn't play well with Eclipse and the WTP. The Pluto site also mentions (in bright red letters!) that "to automate the deployment/installation of portlets, you must utilize the source distribution of Pluto." This would mean creating and modifying an Eclipse project with all the Pluto source code and dependent libraries. With Liferay, you never need to touch the source code to deploy portlets. Finally, Liferay provides such a wealth of freely available portlets and functions that I'd feel compelled to mention it even if I'd chosen Pluto as the portlet container. And not only is Liferay's documentation vast compared to Pluto's, but it even provides video tutorials of how to perform common tasks. So far, I've been very impressed with Liferay in fact, my only complaint against it is that it provides too much capability.

In addition, Liferay contains a large-scale framework for deploying intranet applications across dispersed locations. In this way, administrators in a large institution can customize the portal for each branch, location, and community of their institution.

The Geronimo application server


In this tutorial, you deploy the example portal and portlet application to a Geronimo application server. (Geronimo is released under the Apache License by the Apache Software Foundation [ASF].) The Geronimo application server is a fully certified Java 2 Platform, Enterprise Edition (J2EE) 1.4 application server, and despite its youth, stands head-to-head with commercial offerings with regard to features, reliability, and performance. IBM WebSphere Application Server Community Edition is based on Geronimo. Geronimo is structured as a modular set of management objects called Geronimo Beans (GBeans). Every component is wrapped in a GBean and exposes its life cycle
Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved. Trademarks Page 4 of 31

ibm.com/developerWorks

developerWorks

for other components to interact with. Some of the most important components in Geronimo include the following: ActiveMQ Message Broker OpenEJB Enterprise JavaBeans (EJB) container Tomcat or Jetty Web container Remote Method Invocation (RMI)-based naming service Apache Derby Relational Database Management System (RDBMS) Geronimo can use either the Tomcat or Jetty Web container to deploy its applications, but this tutorial relies on Geronimo with Tomcat installed. If you've used Tomcat alone, much of the operation described here will look familiar. However, you can't access Tomcat directly. Instead, you'll need to deploy your applications using one of the three Geronimo deployment methods: The deploy command-line tool The Geronimo Web Console The hot deployer This last option involves sending the Web application to the $(GERONIMO)/deploy directory, where Geronimo detects it. In this tutorial, Eclipse automatically performs hot deployment. During deployment, Geronimo creates a new element in its repository for the application. This element, called an artifact, is identified by a specific directory structure. Any applications that depend on it must know this structure. Here, the example portlet application depends on the Liferay artifact, and I'll show you how to inform Geronimo about this dependency. But first, you must know how to acquire and configure the software for this tutorial.

Section 3. Create the Eclipse environment


Coding portlet applications isn't difficult. The hard part is acquiring and installing all the software you need so that you can code portlets in Eclipse and deploy them with Geronimo.

Required software components


Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved. Trademarks Page 5 of 31

developerWorks

ibm.com/developerWorks

You need the following four main components: WTP 1.5.1: This feature allows you to create and edit Eclipse projects for dynamic Web applications. It also provides for directly deploying these applications using Web or application servers. Geronimo Server Runtime: This Eclipse plug-in enables the WTP feature to access a Geronimo server and use it to deploy applications. Geronimo application server: The Geronimo server deploys the portlet applications within the Liferay portal. Liferay portal: The Liferay Web application provides the structural framework to hold and display your portlets.

Install the Web Tools Platform


The Eclipse WTP serves two important roles in this tutorial: It provides a simple means of organizing Web application projects and exporting them as WAR files. With the right additional features, it acts as a control panel for starting, stopping, and communicating with the Geronimo server. Put simply, the WTP makes it possible to go from source code to application deployment by pointing and clicking. To install the WTP, perform the following steps: 1. 2. 3. Open Eclipse, and click Help > Software Updates. Choose Find and Install, and then select the Search for New Features to Install option. Click Next. The window shown in Figure 1 appears. Figure 1. Selecting the update site

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 6 of 31

ibm.com/developerWorks

developerWorks

4.

Select the Callisto Discovery Site check box, and then click Finish. Note: The Callisto Discovery Site packages large feature projects like the WTP and ensures version compatibility between them. Click OK when the list of mirror sites appears. The page shown in Figure 2 appears. Figure 2. Selecting the WTP features

5.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 7 of 31

developerWorks

ibm.com/developerWorks

6.

Select the Web and J2EE Development check box. This tells the manager to download the features corresponding to the Eclipse WTP. You'll see a warning that this feature requires additional features to function. To make sure that you have all the necessary dependencies, such as the Visual Editor, Graphical Editor Framework (GEF), and Eclipse Modeling Framework (EMF), click Select Required. When the warning disappears, click Next and accept the license agreement. Click Next, and then click Finish. Note: If you continue to see a dependency warning, even after clicking Select Required, you may need to acquire a newer, or possibly more stable, version of Eclipse. Choose to install all the features, and restart Eclipse. To verify that the features have been added, go to Help > About Eclipse SDK, and click Feature Details.

7.

8.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 8 of 31

ibm.com/developerWorks

developerWorks

Section 4. Install the Geronimo application server


Now that you've installed the WTP, you'll find many new categories of Eclipse projects, including EJB projects, J2EE projects, and Web projects. Under the Web category, you can create Dynamic Web Projects and Static Web Projects. The portlet project in this tutorial is a Dynamic Web Project, but to deploy the project with Geronimo, you must acquire the Geronimo runtime server.

Add WTP support for the Geronimo application server


To add WTP support for your Geronimo application server, perform the following steps: 1. Select Window > Preferences, open the Server category, and then select Installed Runtimes. The preference page should look similar to the top of Figure 3. Figure 3. Adding a server run time to Eclipse

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 9 of 31

developerWorks

ibm.com/developerWorks

2.

Click Add on the right to add a new server run time. The New Server Runtime window, shown in Figure 4, shows that WTP already supports several servers, including JBoss and Tomcat. But alas, Geronimo isn't listed. Click the Don't see your vendor listed? Click here link to see which additional server run times are available. Figure 4. Available server run times

3.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 10 of 31

ibm.com/developerWorks

developerWorks

4.

In the Install New Server window, select the preferred version of Geronimo (this tutorial uses version 1.1), and then click Next. Remember the version number. Accept the license agreement, click Finish, and then click OK in the window that appears. Eclipse downloads the Geronimo runtime environment and asks whether you want to restart the workbench. Click Yes.

5. 6.

Download Geronimo
So far, you've incorporated the Eclipse WTP into Eclipse and added support for the Geronimo application server. The next task is to download the server itself.
Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved. Trademarks Page 11 of 31

developerWorks

ibm.com/developerWorks

To download the Geronimo application server, perform the following steps: 1. 2. 3. 4. Choose File > New > Other, and then select the Server option under the Server category. Click Next to see the Define a New Server window again. This time, when you open the Apache category, you'll see options for Geronimo. Select the version of Geronimo for which you installed support, and then click Next. In the next window, type a directory location in the Application Server Installation Directory box, and make sure that the Geronimo with Tomcat option is selected. Click Download and Install, and then click OK. When the download is complete, click Finish. To test the server, open the J2EE Perspective by choosing Window > Open Perspective > Other and selecting J2EE. As shown in Figure 5, a new set of tabs appears in the lower view section of the workbench. Figure 5. Starting the Geronimo server

5. 6. 7.

8.

Click the Servers tab, and then click Run (circled in blue).

Watch the Console view to see which Geronimo modules are starting as well as the application modules and Web applications. To see the main Geronimo Administration Console, click the toolbar item that looks like a globe, and type http://localhost:8080/console in the address field. Type system as the user name and manager as the password. The browser view should look something like Figure 6. Figure 6. The Geronimo Administration Console

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 12 of 31

ibm.com/developerWorks

developerWorks

Note: If you don't see the globe item on the toolbar, choose Window > Show View > Other, and then select the Internal Web Browser option under the General category. You'll use this console in the next section, so I recommend that you keep it open. If you need to stop Geronimo, just click the red square to the right of the Run button when the Servers tab is visible.

Section 5. Install the Liferay portal platform


The Liferay portal has been in development for more than six years, but full support for Geronimo has only recently been added. Please check the Liferay site for different installation directions should these instructions become obsolete. To install the Liferay portal, perform the following steps: 1. From the Liferay site (see Resources), click the Downloads link at the top.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 13 of 31

developerWorks

ibm.com/developerWorks

2.

Scroll down until you see the Application Server Plugins section. There should be at least two links for downloading Configuration Archive (CAR) files: liferay-portal-geronimo-tomcat-a.b.c.car contains the Liferay module that plugs into the Geronimo server. liferay-portal-geronimo-derby-pool-a.b.c.car contains the files needed to interface Liferay with the Derby database module included in the Geronimo installation.

3. 4.

Click these links. After you've downloaded both plug-ins, return to the Geronimo Application Console in the Eclipse Web browser. Because you've downloaded these plug-ins separately instead of accessing a plug-in repository, you'll need to use Geronimo's deploy command from the command line. This file (deploy.bat in Microsoft Windows or deploy.sh in UNIX or Linux) resides in Geronimo's top-level bin directory, so add this directory to your PATH environmental variable. Open a command prompt, change to the directory containing the two CAR files, and type the following commands in order (remember that the default user name is system, and the password is manager): deploy install-plugin liferay-portal-geronimo-derby-pool-a.b.c.car deploy install-plugin liferay-portal-geronimo-tomcat-a.b.c.car Don't be concerned if you receive an error during the second installation. It probably means that the second plug-in was installed correctly but couldn't be started. To take care of the problem, go to the Geronimo Administration Console, and click the Web App Wars link under the Applications heading. The new window, which displays Geronimo's Web applications, should look similar to Figure 7. Figure 7. Starting the Liferay Console in Geronimo

5.

6.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 14 of 31

ibm.com/developerWorks

developerWorks

You can see the context of each application in the URL column. The top-most application uses the /remote-deploy context, and the console for the Tomcat server uses the root context, or /. 7. But the last application, the Liferay portal, also wants this root context, so uninstall the Tomcat Console by clicking Uninstall in the same row as geronimo/welcome-tomcat/a.b.c/car. Then, start the Liferay portal by clicking Start. Note: Neither of these actions affects the Geronimo Console. It may take some time, but after Geronimo starts the Liferay portal application, go to http://localhost:8080/ in the Eclipse Web browser. The page that appears looks similar to the Liferay home page; to see the portal, click the Sign in link in the upper right. Then, in the text boxes that appear, type test@liferay.com as your user name and test as your password. If all goes well, you'll see the page shown in Figure 8. Figure 8. The Liferay portal

8.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 15 of 31

developerWorks

ibm.com/developerWorks

Before continuing, take a moment to look through the Liferay portal. Explore the portlets and click the different links and tabs. All these capabilities, from the clock to the calendar, are freely available when you start creating your own applications.

Section 6. The deployment descriptors


Now that you've deployed the Liferay portal with Geronimo, you're ready to add portlets. This example shows how to create a simple portlet that displays all of its available attributes. It starts with the Eclipse setup and deployment descriptors and finishes by adding servlet and JSP applications. Note: If you'd rather not type every line of code, you can get the complete Eclipse project (see Downloads). After you download the code samples, choose File > Import, and then select the Existing Projects into Workspace option under the General heading.

Create web.xml
To create the web.xml and geronimo-web.xml files you need, perform the following
Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved. Trademarks Page 16 of 31

ibm.com/developerWorks

developerWorks

steps: 1. 2. 3. Within Eclipse, choose File > New > Project. Select Dynamic Web Project under the Web option. Name the project simpleportlet, then click Finish. When you open the folders in the project, the project should look similar to Figure 9. Figure 9. Initial structure of the Portlet project

Two important deployment descriptors appear at the bottom of the project: web.xml and geronimo-web.xml. The first describes the Web component in general, and the second tells Geronimo how the application should be packaged and deployed. In the project, modify web.xml so that its content matches that shown in Listing 1. This means removing the welcome-file-list element and adding context-param, listener, servlet, servlet-mapping, and taglib elements, each shown in bold in the listing. Listing 1. The web.xml deployment descriptor
Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved. Trademarks Page 17 of 31

developerWorks

ibm.com/developerWorks

<?xml version="1.0" encoding="UTF-8"?> <web-app id="WebApp_ID" version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"> <display-name>simpleportlet</display-name> <context-param> <param-name>company_id</param-name> <param-value>liferay.com</param-value> </context-param> <listener> <listener-class> com.liferay.portal.kernel.servlet.PortletContextListener </listener-class> </listener> <servlet> <servlet-name>simpleportlet</servlet-name> <servlet-class> com.liferay.portal.kernel.servlet.PortletServlet </servlet-class> <init-param> <param-name>portlet-class</param-name> <param-value>org.dworks.SimplePortlet</param-value> </init-param> <load-on-startup>0</load-on-startup> </servlet> <servlet-mapping> <servlet-name>simpleportlet</servlet-name> <url-pattern>/simpleportlet/*</url-pattern> </servlet-mapping> </web-app>

Create geronimo-web.xml
The second deployment descriptor for this tutorial, geronimo-web.xml, accomplishes two tasks: It tells Geronimo where and how to store the application within its repository. It specifies that your portlet application depends on the Liferay portal module. Add the bold text in Listing 2 to your file. Listing 2. The geronimo-web.xml deployment descriptor
<?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1" xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.1" xmlns:sec="http://geronimo.apache.org/xml/ns/security-1.1" xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1"> <sys:environment> <sys:moduleId>

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 18 of 31

ibm.com/developerWorks

developerWorks

<sys:groupId>default</sys:groupId> <sys:artifactId>simpleportlet</sys:artifactId> <sys:version>1.0</sys:version> <sys:type>car</sys:type> </sys:moduleId> <sys:dependencies> <sys:dependency> <sys:groupId>liferay</sys:groupId> <sys:artifactId>liferay-portal-tomcat</sys:artifactId> </sys:dependency> </sys:dependencies> </sys:environment> </web-app>

The <moduleId> element contains four subelements that specify where the project's deployed module should be placed in Geronimo's repository: groupId: The entity that created the file (for example, Apache) artifactId: The name of the file version: The file version type: The format of the file (for example, JAR) But to declare the application's module dependency, the descriptor needs to identify only the groupId and artifactId subelements of the Liferay portal. To see how these parameters relate to the file location, open the repository directory under Geronimo's top-level directory. Each repository subdirectory takes its name from a module's groupId, and each module file can be found in the $(GERONIMO)/repository/groupId/artifactId/version folder.

Section 7. Create the portlet descriptors


The web.xml and geronimo-web.xml files are sufficient to deploy a servlet or JSP-based application, but you need a third deployment descriptor, portlet.xml, for portlet applications. Then, because this portlet must be integrated into the Liferay portal, you need two more files: liferay-portlet.xml and liferay-display.xml.

Create portlet.xml
Create a file called portlet.xml in the project's WEB-INF directory, and add the content in Listing 3 to it. The elements here have the same names and functions as those of servlets in web.xml, so this looks familiar. One interesting difference about portlet descriptors is that they describe what modes of operation are available for a

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 19 of 31

developerWorks

ibm.com/developerWorks

portlet. JSR 168 introduces the basic View, Edit, and Help modes, but you can create custom modes as needed. Only the view mode is required for a portlet; because there are no <portlet-mode> subelements beneath the <supports> element in Listing 3, the View mode is the only one this simple portlet supports. Listing 3. The portlet.xml deployment descriptor
<?xml version="1.0"?> <portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"> <portlet> <portlet-name>simpleportlet</portlet-name> <display-name>Simple Portlet</display-name> <portlet-class>org.dworks.SimplePortlet</portlet-class> <expiration-cache>0</expiration-cache> <supports> <mime-type>text/html</mime-type> </supports> <portlet-info> <title>Simple Portlet</title> <short-title>Simple Portlet</short-title> <keywords>Simple Portlet</keywords> </portlet-info> <security-role-ref> <role-name>administrator</role-name> </security-role-ref> <security-role-ref> <role-name>guest</role-name> </security-role-ref> <security-role-ref> <role-name>power-user</role-name> </security-role-ref> <security-role-ref> <role-name>user</role-name> </security-role-ref> </portlet> </portlet-app>

Create liferay-portlet.xml
Create another file called liferay-portlet.xml in the WEB-INF directory, and add the content shown in Listing 4. This file matches the security roles of portlet.xml with the specific and similarly named roles in Liferay. If the instanceable element is set to true, the portlet can be added multiple times to the layout of the Liferay portal. Listing 4. The liferay-portlet.xml deployment descriptor
<?xml version="1.0"?> <!DOCTYPE liferay-portlet-app PUBLIC "-//Liferay//DTD Portlet Application 4.2.0//EN" "http://www.liferay.com/dtd/liferay-portlet-app_4_2_0.dtd"> <liferay-portlet-app>

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 20 of 31

ibm.com/developerWorks

developerWorks

<portlet> <portlet-name>simpleportlet</portlet-name> <instanceable>true</instanceable> </portlet> <role-mapper> <role-name>administrator</role-name> <role-link>Administrator</role-link> </role-mapper> <role-mapper> <role-name>guest</role-name> <role-link>Guest</role-link> </role-mapper> <role-mapper> <role-name>power-user</role-name> <role-link>Power User</role-link> </role-mapper> <role-mapper> <role-name>user</role-name> <role-link>User</role-link> </role-mapper> </liferay-portlet-app>

Create liferay-display.xml
Create one last .xml file, liferay-display.xml, in the WEB-INF directory, and add the content shown in Listing 5. This file tells the portal which category the portlet will be listed in. I'll cover the Liferay categories when I explain the process of deploying and viewing Liferay portlets. For now, all you need to know is that the simple portlet application will fall under the Test category. Listing 5. The liferay-display.xml descriptor
<?xml version="1.0"?> <!DOCTYPE display PUBLIC "-//Liferay//DTD Display 4.0.0//EN" "http://www.liferay.com/dtd/liferay-display_4_0_0.dtd"> <display> <category name="category.test"> <portlet id="simpleportlet" /> </category> </display>

With the five descriptors (web.xml, geronimo-web.xml, portlet.xml, liferay-portlet.xml, and liferay-display.xml) completed, you've taken care of interfacing the server and the portal. Next, you code the portlet's actual operation.

Section 8. Build and deploy the servlet-based portlet


Create the SimplePortlet class, and deploy the application to the Geronimo application server.
Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved. Trademarks Page 21 of 31

developerWorks

ibm.com/developerWorks

The GenericPortlet superclass


Before you look at the code for the SimplePortlet class, I want to briefly mention its superclass, GenericPortlet. This class's two main operational methods are: processAction(ActionRequest request, ActionResponse response): Changes the mode or state information of the portlet render(RenderRequest request, RenderResponse response): Displays the portlet according to the current mode and state information By default, the render() method calls one of the three methods corresponding to the built-in portlet modes: doView(), doEdit(), or doHelp(). As mentioned earlier, the View method is the only required mode, so the SimplePortlet class consists of only the doView() method. The Eclipse WTP adds many libraries to your project's CLASSPATH, but none of them contains the portlet classes. Thankfully, Geronimo includes the necessary library (portlet-api-1.0.jar, as of this writing) in the $(GERONIMO)/repository/portlet-api/portlet-api/1.0 directory. You can paste this file into the Eclipse project, create a CLASSPATH variable to this location, or copy it into the $(GERONIMO)/lib/ext directory, but you must make this file available for the project to compile properly.

Create the SimplePortlet class


To create the SimplePortlet class, perform the following steps: 1. 2. Right-click the project name, and then choose New > Class. In the window that appears, type org.dworks as the name of the package and SimpleProject as the name of the class. The upper half of the window should look similar to Figure 10. Figure 10. The new portlet class

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 22 of 31

ibm.com/developerWorks

developerWorks

3. 4.

Click Finish. Type or paste the code shown in Listing 6. Listing 6. SimplePortlet.java

package org.dworks; import import import import import import java.io.IOException; java.io.PrintWriter; javax.portlet.GenericPortlet; javax.portlet.RenderRequest; javax.portlet.RenderResponse; javax.portlet.PortletException;

public class SimplePortlet extends GenericPortlet { protected void doView(RenderRequest request, RenderResponse response) throws PortletException, IOException { String portletName = "Portlet Name: " + getPortletConfig().getPortletName(); String companyName = "Company Name: " + getPortletConfig().getPortletContext() .getInitParameter("company_id"); response.setContentType("text/html"); PrintWriter out = response.getWriter(); out.println(portletName+"<br />"+companyName); } }

The portlet's operation is straightforward. The doView() method accesses the configuration object (PortletConfig) to get the portlet's name. Then it uses its context object (PortletContext) to get the initial parameter specified in web.xml. Like a regular servlet, it displays both pieces of information by acquiring the PrintWriter of the response object.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 23 of 31

developerWorks

ibm.com/developerWorks

By default, Eclipse sets the context of your application to the project name. But for a portlet project, you must set the context equal to that of its portal, which for Liferay is simply the root directory. To change this: 1. 2. 3. Right-click the project name in the Navigator, then choose Properties. Select the Web Project Settings option on the right. Delete all text in the Context Root box.

Figure 11 shows my project structure. Yours may differ, but you should make sure that the project files are in the right folders. Figure 11. Structure of the completed Portlet project

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 24 of 31

ibm.com/developerWorks

developerWorks

Deploy the application to Geronimo


1. 2. 3. 4. Start the Geronimo server if it isn't started already, and make sure that it loads the Liferay portal module. To deploy your application, right-click the project name, then choose Run As > Run on Server. If a window appears, click Finish. The Eclipse browser should display the Liferay portal at http://localhost:8080/. You won't see any immediate change in the portal because you haven't added the portlet content. To add the portlet, click the Add Content link, circled in Figure 12. Figure 12. Adding a new portlet to the Liferay portal

5.

Open the Test category, and click Add next to the Simple Portlet option. You should see a new window in the portal that looks like Figure 13. Figure 13. The Simple Portlet window

Section 9. Build a JSP-based portlet


The SimplePortlet servlet is indeed simple, but it would be more convenient to take the HTML out of the Java class and add it to a JSP page. Making this possible requires four steps: 1. 2. Add the Tag Library Descriptor (TLD) and its JAR file to the project. Update the web.xml deployment descriptor to identify the TLD.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 25 of 31

developerWorks

ibm.com/developerWorks

3. 4.

Modify the servlet class to dispatch processing to the JSP page. Create the JSP page within the project.

This process won't change the project name or its deployment within Geronimo and Liferay, so there's no need to change any of the deployment descriptors except web.xml.

Point Geronimo to the TLD


To point your Geronimo application server to the TLD: 1. Open the $(GERONIMO)/repository/liferay/liferay-portal-tomcat/x.y.z/ liferay-portal-tomcat-x.y.z.car/WEB-INF folder. Two important directories reside here: lib and tld. In the lib directory, copy the util-taglib.jar file to the corresponding lib directory in the WEB-INF folder in your Eclipse project. It disappears from this folder and reappears as one of the Web App Libraries associated with your project. Create a folder called tags beneath the WEB-INF folder in your Eclipse project. Go to the tld directory and copy the liferay-portlet.tld file into the new tags folder that you created. To tell Geronimo where to find the TLD you added, create a Uniform Reference Identifier (URI) that identifies it. Add the <jsp-config> element shown in Listing 7 to the end of your web.xml file, and leave the rest of the descriptor intact. Listing 7. Updated web.xml

2.

3. 4. 5.

<?xml version="1.0" encoding="UTF-8"?> <web-app id="WebApp_ID" version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"> ... <jsp-config> <taglib> <taglib-uri>http://java.sun.com/portlet</taglib-uri> <taglib-location>/WEB-INF/tags/liferay-portlet.tld</taglib-location> </taglib> </jsp-config>

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 26 of 31

ibm.com/developerWorks

developerWorks

</web-app>

6.

The new servlet doesn't access the RenderResponse directly, but it dispatches processing to the JSP page. Change the doView method to the code shown in Listing 8. Listing 8. Updated doView() method of SimplePortlet.java

protected void doView(RenderRequest request, RenderResponse response) throws PortletException, IOException { PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher("/view.jsp"); prd.include(request, response); }

The JSP code, shown in Listing 9, uses portlet-specific tags to access the portlet's configuration object. It provides the same output as the earlier servlet, but the HTML structure makes it easier to read and change. Note: Eclipse may give you an error about not resolving the portletConfig object, but it should still deploy and display properly. Listing 9. View.jsp
<%@ taglib prefix="portlet" uri="http://java.sun.com/portlet" %> <portlet:defineObjects /> Portlet Name: <%= portletConfig.getPortletName() %> Company Name: <%= portletConfig.getPortletContext().getInitParameter("company_id") %>

The defineObjects tag makes the renderRequest, renderResponse, and portletConfig objects accessible within the JSP page. Then the portletConfig object provides access to the portlet's name and context object. Other available tags include the actionURL tag, which tells the portlet to perform an action, and the renderURL tag, which sends a render request to the portlet. The namespace tag sets aside a section of the code to use only the identifiers associated with the portlet.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 27 of 31

developerWorks

ibm.com/developerWorks

Section 10. Summary


This tutorial has focused on coding and deploying basic JSR 168 portlet applications with Eclipse, Geronimo, and the Liferay portal platform. This nuts-and-bolts discussion covered how to acquire these necessary components and unite them inside Eclipse projects. Specifically, you learned about two basic portlet projects: one that uses a servlet to generate markup and one that uses a JSP page. I hope that you'll be able to build upon these for your own modular applications. One thing this tutorial hasn't covered in depth is the theory underlying portals and portlets. But because the subject is so fascinating, I'd like to finish with a brief description of the new portlet standard, JSR 286, and what it has to offer. One of the main goals is to provide improved communication and coordination among portlets, such as event sharing and dispersal of session data. Another goal is to standardize asynchronous rendering of portlets, thereby providing developers with a common means of creating Asynchronous JavaScript + XML (Ajax)-based portals. With such tight integration of dynamic portlets, it might be possible to build an Eclipse-like Web application based on portlets instead of plug-ins. That is, a user visiting the site would find the same type of GUI that we associate with Eclipse -different views interacting with a common editor and displaying its information. Of course, the user would need a fast connection, and the server would need to run quickly. Still, the possibilities for such portals and portlets are astounding.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 28 of 31

ibm.com/developerWorks

developerWorks

Downloads
Description
Servlet-based portal application1 JSP-based portal application
2

Name
simpleportlet-servlet.war.zip simpleportlet-jsp.war.zip

Size
4KB 91KB

Download method
HTTP HTTP

Information about download methods

More downloads Demo: Liferay home page Demo: JSR 286 standard site Notes
1 Example portlet project using a servlet 2 Example portlet project using a JSP page. Both projects have the same name, so they can't be imported into the Eclipse workspace at the same time.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 29 of 31

developerWorks

ibm.com/developerWorks

Resources
Learn Learn about the Apache Pluto portal project. Visit the Liferay Web site. Investigate the Apache Jetspeed server. See what all the fuss concerning JBoss is about. Stay current regarding Eclipse happenings by visiting Planet Eclipse. Learn more about the Eclipse Foundation. Expand your Eclipse skills by visiting the IBM developerWorks Eclipse project resources area. Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products. Check out the developerWorks Apache Geronimo project area for articles, tutorials, and other resources to help you get started developing with Geronimo today. Find helpful resources for beginners and experienced users at the Get started now with Apache Geronimo section of developerWorks. Check out the IBM Support for Apache Geronimo offering, which lets you develop Geronimo applications backed by world-class IBM support. Stay current with developerWorks technical events and webcasts. Browse all the Apache articles and free Apache tutorials available in the developerWorks Open source zone. Browse for books on these and other technical topics at the Safari bookstore. Get products and technologies See the latest Eclipse technology downloads at IBM alphaWorks. Download the latest version of Apache Geronimo. Download your free copy of IBM WebSphere Application Server Community Edition -- a lightweight J2EE application server built on Apache Geronimo open source technology that is designed to help you accelerate your development and deployment efforts. Innovate your next open source development project with IBM trial software, available for download or on DVD.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 30 of 31

ibm.com/developerWorks

developerWorks

Discuss Participate in the discussion forum for this content. Stay up to date on Geronimo developments at the Apache Geronimo blog. Get involved in the developerWorks community by participating in developerWorks blogs.

About the author


Matthew Scarpino Matthew Scarpino is a project manager and Java developer at Eclipse Engineering LLC. He is the lead author of SWT/JFace in Action and made a minor but important contribution to the Standard Widget Toolkit (SWT). He enjoys Irish folk music, marathon running, the poetry of William Blake, and the Graphical Editing Framework (GEF).

Trademarks
IBM, the IBM logo, and WebSphere are registered trademarks of IBM in the United States, other countries or both. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc., in the United States, other countries, or both. Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.

Build portlets with Apache Geronimo and Eclipse Copyright IBM Corporation 2007. All rights reserved.

Trademarks Page 31 of 31