+ All Categories
Home > Documents > Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides...

Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides...

Date post: 01-Feb-2018
Category:
Upload: ngohanh
View: 215 times
Download: 0 times
Share this document with a friend
27
Build portlets with Apache Geronimo and Eclipse Managing the Liferay portal with the Eclipse Web Tools Platform (WTP) Skill Level: Intermediate Matthew Scarpino ([email protected]) 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 The Liferay portal to provide the overall structure It takes some effort to install these components and work out the version Build portlets with Apache Geronimo and Eclipse © Copyright IBM Corporation 1994, 2008. All rights reserved. Page 1 of 27
Transcript
Page 1: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

Build portlets with Apache Geronimo and EclipseManaging the Liferay portal with the Eclipse Web ToolsPlatform (WTP)

Skill Level: Intermediate

Matthew Scarpino ([email protected])Java DeveloperEclipse 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 completedevelopment environment for editing the code and configuration files needed forportlet projects. Then, by integrating the Apache Geronimo Eclipse plug-in, learn howyou can deploy and display these portlets inside a full portal by accessing theGeronimo 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 andmultifunctional as any huge corporate site. This tutorial explores a method ofcreating such a portal by using three tools:

• The Eclipse integrated development environment (IDE) to develop theproject

• An Apache Geronimo application server to deploy it

• The Liferay portal to provide the overall structure

It takes some effort to install these components and work out the version

Build portlets with Apache Geronimo and Eclipse© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 1 of 27

Page 2: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

incompatibilities. But after configuration, the process of building and deploying theportal 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 applicationserver.

• Deploying a Java™Server Pages (JSP)-based portlet application with aGeronimo application server.

Prerequisites

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

System requirements

To start this tutorial, you need a recent version of Eclipse 3.2 or later on yoursystem. You install the WTP, Geronimo server, Geronimo server run time, andLiferay 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 ApacheGeronimo plays in their creation.

Introduction to portals and portlets

Java Specification Request (JSR) 168 defines a portal as "a Web application thatcommonly provides personalization, single sign-on, content aggregation fromdifferent sources and hosts the presentation layer of Information Systems." It definesa portlet as a "Web component, managed by a portlet container, that processesrequests and generates dynamic content." Functionally speaking, portlets generate

developerWorks® ibm.com/developerWorks

Build portlets with Apache Geronimo and EclipsePage 2 of 27 © Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 3: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

fragments of markup in response to requests, and portals manage these fragmentsand structure them into a framework.

Large institutions commonly use portals to provide users with multiple capabilitiesfrom a single page. In many cases, these portals also serve as intranet applicationsfor institution-wide communication. Developing these pages would be unbearablewith monolithic servlets, so portlets were created as pluggable components that canbe dynamically added and modified. Thanks to the common JSR 168 standard,portal developers can mix and match portlets from different vendors withoutsignificant changes. So there's no need to rewrite registration applications, stocktickers, and Really Simple Syndication (RSS) feeds — simply download and deploy,and you're done.

Thankfully, many open source tools are available that make portal developmentavailable for everyone. The Apache Jetspeed project, released under the ApacheLicense, provides a large set of features that includes database access, role-basedsecurity, and support for the Wireless Markup Language (WML). Apache Pluto is thereference implementation of JSR 168, which means that it can manage and displayportlets according to the standard but doesn't provide the additional features thatdevelopers have come to expect. The JBoss portal is also very popular and isreleased under the Lesser GNU Public License (LGPL).

This tutorial uses the Liferay portal platform to structure its content. (See the sidebarLiferay vs. Pluto for reasons why I chose this portal.) This platform is released underthe MIT License, which means you can use it for proprietary purposes withoutpaying royalties. In addition to providing a framework for displaying portlets, itintegrates 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.

• Many free example portlets, including chat clients, calendars, clocks, andRSS feeds.

Liferay vs. PlutoPluto is included in Geronimo and is released by the ApacheSoftware Foundation, so I feel compelled to explain why I choseLiferay as the portal framework for this tutorial. It comes down toease of deployment. Liferay provides a Web application that runsimmediately within Geronimo. But the Pluto artifact in the Geronimorepository isn't packaged as a Web application and isn't initializedwhen Geronimo starts. So it would have taken a lot of effort toconfigure a Pluto application for Geronimo and integrate it within theApache Tomcat container.

Also, according to the documentation on the Pluto site, Maven is the

ibm.com/developerWorks developerWorks®

Build portlets with Apache Geronimo and Eclipse© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 3 of 27

Page 4: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

preferred application for accessing Pluto. Maven provides manyadvantages for large project management, but as I've learned frompainful experience, the Maven plug-in doesn't play well with Eclipseand the WTP. The Pluto site also mentions (in bright red letters!)that "to automate the deployment/installation of portlets, you mustutilize the source distribution of Pluto." This would mean creatingand modifying an Eclipse project with all the Pluto source code anddependent libraries. With Liferay, you never need to touch thesource code to deploy portlets.

Finally, Liferay provides such a wealth of freely available portletsand functions that I'd feel compelled to mention it even if I'd chosenPluto as the portlet container. And not only is Liferay'sdocumentation vast compared to Pluto's, but it even provides videotutorials of how to perform common tasks. So far, I've been veryimpressed with Liferay — in fact, my only complaint against it is thatit provides too much capability.

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

The Geronimo application server

In this tutorial, you deploy the example portal and portlet application to a Geronimoapplication server. (Geronimo is released under the Apache License by the ApacheSoftware Foundation [ASF].) The Geronimo application server is a fully certified Java2 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 isbased on Geronimo.

Geronimo is structured as a modular set of management objects called GeronimoBeans (GBeans). Every component is wrapped in a GBean and exposes its life cyclefor other components to interact with. Some of the most important components inGeronimo 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 itsapplications, but this tutorial relies on Geronimo with Tomcat installed. If you've usedTomcat alone, much of the operation described here will look familiar. However, youcan't access Tomcat directly. Instead, you'll need to deploy your applications usingone of the three Geronimo deployment methods:

developerWorks® ibm.com/developerWorks

Build portlets with Apache Geronimo and EclipsePage 4 of 27 © Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 5: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

• The deploy command-line tool

• The Geronimo Web Console

• The hot deployer

This last option involves sending the Web application to the $(GERONIMO)/deploydirectory, where Geronimo detects it. In this tutorial, Eclipse automatically performshot deployment.

During deployment, Geronimo creates a new element in its repository for theapplication. This element, called an artifact, is identified by a specific directorystructure. Any applications that depend on it must know this structure. Here, theexample portlet application depends on the Liferay artifact, and I'll show you how toinform Geronimo about this dependency. But first, you must know how to acquireand 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 allthe software you need so that you can code portlets in Eclipse and deploy them withGeronimo.

Required software components

You need the following four main components:

• WTP 1.5.1: This feature allows you to create and edit Eclipse projects fordynamic Web applications. It also provides for directly deploying theseapplications using Web or application servers.

• Geronimo Server Runtime: This Eclipse plug-in enables the WTPfeature to access a Geronimo server and use it to deploy applications.

• Geronimo application server: The Geronimo server deploys the portletapplications within the Liferay portal.

• Liferay portal: The Liferay Web application provides the structuralframework to hold and display your portlets.

Install the Web Tools Platform

The Eclipse WTP serves two important roles in this tutorial:

ibm.com/developerWorks developerWorks®

Build portlets with Apache Geronimo and Eclipse© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 5 of 27

Page 6: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

• It provides a simple means of organizing Web application projects andexporting 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 applicationdeployment by pointing and clicking.

To install the WTP, perform the following steps:

1. Open Eclipse, and click Help > Software Updates.

2. Choose Find and Install, and then select the Search for New Featuresto Install option.

3. Click Next. The window shown in Figure 1 appears.Figure 1. Selecting the update site

4. Select the Callisto Discovery Site check box, and then click Finish.Note: The Callisto Discovery Site packages large feature projects like theWTP and ensures version compatibility between them.

developerWorks® ibm.com/developerWorks

Build portlets with Apache Geronimo and EclipsePage 6 of 27 © Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 7: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

5. Click OK when the list of mirror sites appears. The page shown in Figure2 appears.Figure 2. Selecting the WTP features

6. Select the Web and J2EE Development check box. This tells themanager to download the features corresponding to the Eclipse WTP.You'll see a warning that this feature requires additional features tofunction. To make sure that you have all the necessary dependencies,such as the Visual Editor, Graphical Editor Framework (GEF), and EclipseModeling Framework (EMF), click Select Required. When the warningdisappears, click Next and accept the license agreement.

7. Click Next, and then click Finish.Note: If you continue to see a dependency warning, even after clickingSelect Required, you may need to acquire a newer, or possibly morestable, version of Eclipse.

8. Choose to install all the features, and restart Eclipse. To verify that thefeatures have been added, go to Help > About Eclipse SDK, and clickFeature Details.

ibm.com/developerWorks developerWorks®

Build portlets with Apache Geronimo and Eclipse© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 7 of 27

Page 8: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

Section 4. Install the Geronimo application server

Now that you've installed the WTP, you'll find many new categories of Eclipseprojects, including EJB projects, J2EE projects, and Web projects. Under the Webcategory, you can create Dynamic Web Projects and Static Web Projects. Theportlet project in this tutorial is a Dynamic Web Project, but to deploy the project withGeronimo, 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 followingsteps:

1. Select Window > Preferences, open the Server category, and thenselect Installed Runtimes. The preference page should look similar tothe top of Figure 3.Figure 3. Adding a server run time to Eclipse

developerWorks® ibm.com/developerWorks

Build portlets with Apache Geronimo and EclipsePage 8 of 27 © Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 9: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

2. Click Add on the right to add a new server run time. The New ServerRuntime window, shown in Figure 4, shows that WTP already supportsseveral servers, including JBoss and Tomcat. But alas, Geronimo isn'tlisted.

3. Click the Don't see your vendor listed? Click here link to see whichadditional server run times are available.Figure 4. Available server run times

4. In the Install New Server window, select the preferred version ofGeronimo (this tutorial uses version 1.1), and then click Next. Rememberthe version number.

5. Accept the license agreement, click Finish, and then click OK in thewindow that appears.

6. Eclipse downloads the Geronimo runtime environment and asks whetheryou want to restart the workbench. Click Yes.

ibm.com/developerWorks developerWorks®

Build portlets with Apache Geronimo and Eclipse© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 9 of 27

Page 10: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

Download Geronimo

So far, you've incorporated the Eclipse WTP into Eclipse and added support for theGeronimo application server. The next task is to download the server itself.

To download the Geronimo application server, perform the following steps:

1. Choose File > New > Other, and then select the Server option under theServer category.

2. Click Next to see the Define a New Server window again. This time, whenyou open the Apache category, you'll see options for Geronimo.

3. Select the version of Geronimo for which you installed support, and thenclick Next.

4. In the next window, type a directory location in the Application ServerInstallation Directory box, and make sure that the Geronimo withTomcat option is selected.

5. Click Download and Install, and then click OK.

6. When the download is complete, click Finish.

7. To test the server, open the J2EE Perspective by choosing Window >Open Perspective > Other and selecting J2EE. As shown in Figure 5, anew set of tabs appears in the lower view section of the workbench.Figure 5. Starting the Geronimo server

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 theapplication modules and Web applications. To see the main GeronimoAdministration Console, click the toolbar item that looks like a globe, and typehttp://localhost:8080/console in the address field. Type system as theuser name and manager as the password. The browser view should look somethinglike Figure 6.

Figure 6. The Geronimo Administration Console

developerWorks® ibm.com/developerWorks

Build portlets with Apache Geronimo and EclipsePage 10 of 27 © Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 11: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

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 Generalcategory.

You'll use this console in the next section, so I recommend that you keep it open. Ifyou need to stop Geronimo, just click the red square to the right of the Run buttonwhen 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 supportfor Geronimo has only recently been added. Please check the Liferay site fordifferent 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 thetop.

2. Scroll down until you see the Application Server Plugins section. Thereshould be at least two links for downloading Configuration Archive (CAR)files:

ibm.com/developerWorks developerWorks®

Build portlets with Apache Geronimo and Eclipse© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 11 of 27

Page 12: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

• liferay-portal-geronimo-tomcat-a.b.c.car contains the Liferaymodule that plugs into the Geronimo server.

• liferay-portal-geronimo-derby-pool-a.b.c.car contains the filesneeded to interface Liferay with the Derby database module includedin the Geronimo installation.

3. Click these links. After you've downloaded both plug-ins, return to theGeronimo Application Console in the Eclipse Web browser.

4. Because you've downloaded these plug-ins separately instead ofaccessing a plug-in repository, you'll need to use Geronimo's deploycommand from the command line. This file (deploy.bat in Microsoft®Windows® or deploy.sh in UNIX® or Linux®) resides in Geronimo'stop-level bin directory, so add this directory to your PATH environmentalvariable.

5. Open a command prompt, change to the directory containing the twoCAR files, and type the following commands in order (remember that thedefault user name is system, and the password is manager):deploy install-pluginliferay-portal-geronimo-derby-pool-a.b.c.cardeploy install-pluginliferay-portal-geronimo-tomcat-a.b.c.carDon't be concerned if you receive an error during the second installation.It probably means that the second plug-in was installed correctly butcouldn't be started.

6. To take care of the problem, go to the Geronimo Administration Console,and click the Web App Wars link under the Applications heading. Thenew window, which displays Geronimo's Web applications, should looksimilar to Figure 7.Figure 7. Starting the Liferay Console in Geronimo

You can see the context of each application in the URL column. Thetop-most application uses the /remote-deploy context, and theconsole for the Tomcat server uses the root context, or /.

developerWorks® ibm.com/developerWorks

Build portlets with Apache Geronimo and EclipsePage 12 of 27 © Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 13: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

7. But the last application, the Liferay portal, also wants this root context, souninstall the Tomcat Console by clicking Uninstall in the same row asgeronimo/welcome-tomcat/a.b.c/car. Then, start the Liferay portal byclicking Start.Note: Neither of these actions affects the Geronimo Console.

8. It may take some time, but after Geronimo starts the Liferay portalapplication, go to http://localhost:8080/ in the Eclipse Web browser. Thepage that appears looks similar to the Liferay home page; to see theportal, click the Sign in link in the upper right. Then, in the text boxes thatappear, type [email protected] as your user name and test as yourpassword. If all goes well, you'll see the page shown in Figure 8.Figure 8. The Liferay portal

Before continuing, take a moment to look through the Liferay portal. Explore theportlets and click the different links and tabs. All these capabilities, from the clock tothe 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 addportlets. This example shows how to create a simple portlet that displays all of its

ibm.com/developerWorks developerWorks®

Build portlets with Apache Geronimo and Eclipse© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 13 of 27

Page 14: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

available attributes. It starts with the Eclipse setup and deployment descriptors andfinishes by adding servlet and JSP applications.

Note: If you'd rather not type every line of code, you can get the complete Eclipseproject (see Downloads). After you download the code samples, choose File >Import, and then select the Existing Projects into Workspace option under theGeneral heading.

Create web.xml

To create the web.xml and geronimo-web.xml files you need, perform the followingsteps:

1. Within Eclipse, choose File > New > Project.

2. Select Dynamic Web Project under the Web option.

3. Name the project simpleportlet, then click Finish. When you openthe folders in the project, the project should look similar to Figure 9.Figure 9. Initial structure of the Portlet project

developerWorks® ibm.com/developerWorks

Build portlets with Apache Geronimo and EclipsePage 14 of 27 © Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 15: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

Two important deployment descriptors appear at the bottom of the project: web.xmland geronimo-web.xml. The first describes the Web component in general, and thesecond tells Geronimo how the application should be packaged and deployed. In theproject, modify web.xml so that its content matches that shown in Listing 1. Thismeans removing the welcome-file-list element and adding context-param,listener, servlet, servlet-mapping, and taglib elements, each shown inbold in the listing.

Listing 1. The web.xml deployment descriptor

<?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/j2eehttp://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, accomplishestwo tasks:

• It tells Geronimo where and how to store the application within itsrepository.

• It specifies that your portlet application depends on the Liferay portalmodule.

Add the bold text in Listing 2 to your file.

Listing 2. The geronimo-web.xml deployment descriptor

ibm.com/developerWorks developerWorks®

Build portlets with Apache Geronimo and Eclipse© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 15 of 27

Page 16: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

<?xml version="1.0" encoding="UTF-8"?><web-appxmlns="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>

<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 theproject'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 identifyonly the groupId and artifactId subelements of the Liferay portal. To see howthese parameters relate to the file location, open the repository directory underGeronimo's top-level directory. Each repository subdirectory takes its name from amodule'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 orJSP-based application, but you need a third deployment descriptor, portlet.xml, forportlet applications. Then, because this portlet must be integrated into the Liferayportal, 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 thecontent in Listing 3 to it. The elements here have the same names and functions asthose of servlets in web.xml, so this looks familiar. One interesting difference about

developerWorks® ibm.com/developerWorks

Build portlets with Apache Geronimo and EclipsePage 16 of 27 © Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 17: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

portlet descriptors is that they describe what modes of operation are available for aportlet. JSR 168 introduces the basic View, Edit, and Help modes, but you cancreate 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-appxmlns="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.xsdhttp://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 thecontent shown in Listing 4. This file matches the security roles of portlet.xml with thespecific and similarly named roles in Liferay. If the instanceable element is set totrue, 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 PortletApplication 4.2.0//EN""http://www.liferay.com/dtd/liferay-portlet-app_4_2_0.dtd"><liferay-portlet-app>

<portlet><portlet-name>simpleportlet</portlet-name><instanceable>true</instanceable>

</portlet><role-mapper>

ibm.com/developerWorks developerWorks®

Build portlets with Apache Geronimo and Eclipse© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 17 of 27

Page 18: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

<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 thecontent shown in Listing 5. This file tells the portal which category the portlet will belisted in. I'll cover the Liferay categories when I explain the process of deploying andviewing Liferay portlets. For now, all you need to know is that the simple portletapplication 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 andthe 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 Geronimoapplication server.

The GenericPortlet superclass

Before you look at the code for the SimplePortlet class, I want to briefly mentionits superclass, GenericPortlet. This class's two main operational methods are:

developerWorks® ibm.com/developerWorks

Build portlets with Apache Geronimo and EclipsePage 18 of 27 © Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 19: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

• processAction(ActionRequest request, ActionResponseresponse): 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 tothe built-in portlet modes: doView(), doEdit(), or doHelp(). As mentionedearlier, the View method is the only required mode, so the SimplePortlet classconsists of only the doView() method.

The Eclipse WTP adds many libraries to your project's CLASSPATH, but none ofthem contains the portlet classes. Thankfully, Geronimo includes the necessarylibrary (portlet-api-1.0.jar, as of this writing) in the$(GERONIMO)/repository/portlet-api/portlet-api/1.0 directory. You can paste this fileinto the Eclipse project, create a CLASSPATH variable to this location, or copy it intothe $(GERONIMO)/lib/ext directory, but you must make this file available for theproject to compile properly.

Create the SimplePortlet class

To create the SimplePortlet class, perform the following steps:

1. Right-click the project name, and then choose New > Class.

2. In the window that appears, type org.dworks as the name of thepackage and SimpleProject as the name of the class. The upper halfof the window should look similar to Figure 10.Figure 10. The new portlet class

3. Click Finish.

ibm.com/developerWorks developerWorks®

Build portlets with Apache Geronimo and Eclipse© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 19 of 27

Page 20: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

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

package org.dworks;

import java.io.IOException;import java.io.PrintWriter;import javax.portlet.GenericPortlet;import javax.portlet.RenderRequest;import javax.portlet.RenderResponse;import 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 theconfiguration object (PortletConfig) to get the portlet's name. Then it uses itscontext object (PortletContext) to get the initial parameter specified in web.xml.Like a regular servlet, it displays both pieces of information by acquiring thePrintWriter of the response object.

By default, Eclipse sets the context of your application to the project name. But for aportlet project, you must set the context equal to that of its portal, which for Liferay issimply the root directory. To change this:

1. Right-click the project name in the Navigator, then choose Properties.

2. Select the Web Project Settings option on the right.

3. Delete all text in the Context Root box.

Figure 11 shows my project structure. Yours may differ, but you should make surethat the project files are in the right folders.

Figure 11. Structure of the completed Portlet project

developerWorks® ibm.com/developerWorks

Build portlets with Apache Geronimo and EclipsePage 20 of 27 © Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 21: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

Deploy the application to Geronimo

1. Start the Geronimo server if it isn't started already, and make sure that itloads the Liferay portal module.

2. To deploy your application, right-click the project name, then choose RunAs > Run on Server.

3. If a window appears, click Finish. The Eclipse browser should display theLiferay portal at http://localhost:8080/.

4. You won't see any immediate change in the portal because you haven'tadded 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

ibm.com/developerWorks developerWorks®

Build portlets with Apache Geronimo and Eclipse© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 21 of 27

Page 22: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

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 takethe HTML out of the Java class and add it to a JSP page. Making this possiblerequires four steps:

1. Add the Tag Library Descriptor (TLD) and its JAR file to the project.

2. Update the web.xml deployment descriptor to identify the TLD.

3. Modify the servlet class to dispatch processing to the JSP page.

4. Create the JSP page within the project.

This process won't change the project name or its deployment within Geronimo andLiferay, so there's no need to change any of the deployment descriptors exceptweb.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 directoriesreside here: lib and tld.

2. In the lib directory, copy the util-taglib.jar file to the corresponding libdirectory in the WEB-INF folder in your Eclipse project. It disappears from

developerWorks® ibm.com/developerWorks

Build portlets with Apache Geronimo and EclipsePage 22 of 27 © Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 23: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

this folder and reappears as one of the Web App Libraries associated withyour project.

3. Create a folder called tags beneath the WEB-INF folder in your Eclipseproject.

4. Go to the tld directory and copy the liferay-portlet.tld file into the new tagsfolder that you created.

5. To tell Geronimo where to find the TLD you added, create a UniformReference Identifier (URI) that identifies it. Add the <jsp-config>element shown in Listing 7 to the end of your web.xml file, and leave therest of the descriptor intact.Listing 7. Updated web.xml

<?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/j2eehttp://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>

</web-app>

6. The new servlet doesn't access the RenderResponse directly, but itdispatches processing to the JSP page. Change the doView method tothe 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'sconfiguration object. It provides the same output as the earlier servlet, but the HTMLstructure makes it easier to read and change.

Note: Eclipse may give you an error about not resolving the portletConfigobject, but it should still deploy and display properly.

ibm.com/developerWorks developerWorks®

Build portlets with Apache Geronimo and Eclipse© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 23 of 27

Page 24: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

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, andportletConfig objects accessible within the JSP page. Then theportletConfig object provides access to the portlet's name and context object.

Other available tags include the actionURL tag, which tells the portlet to perform anaction, and the renderURL tag, which sends a render request to the portlet. Thenamespace tag sets aside a section of the code to use only the identifiersassociated with the portlet.

Section 10. Summary

This tutorial has focused on coding and deploying basic JSR 168 portlet applicationswith Eclipse, Geronimo, and the Liferay portal platform. This nuts-and-boltsdiscussion covered how to acquire these necessary components and unite theminside 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 hopethat 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 andportlets. But because the subject is so fascinating, I'd like to finish with a briefdescription of the new portlet standard, JSR 286, and what it has to offer. One of themain goals is to provide improved communication and coordination among portlets,such as event sharing and dispersal of session data. Another goal is to standardizeasynchronous rendering of portlets, thereby providing developers with a commonmeans of creating Asynchronous JavaScript + XML (Ajax)-based portals.

With such tight integration of dynamic portlets, it might be possible to build anEclipse-like Web application based on portlets instead of plug-ins. That is, a uservisiting 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. Ofcourse, the user would need a fast connection, and the server would need to runquickly. Still, the possibilities for such portals and portlets are astounding.

developerWorks® ibm.com/developerWorks

Build portlets with Apache Geronimo and EclipsePage 24 of 27 © Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 25: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

Downloads

Description Name Size Download method

Servlet-based portal application1 simpleportlet-servlet.war.zip4KB HTTP

JSP-based portal application2 simpleportlet-jsp.war.zip91KB 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 beimported into the Eclipse workspace at the same time.

ibm.com/developerWorks developerWorks®

Build portlets with Apache Geronimo and Eclipse© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 25 of 27

Page 26: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

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 projectresources area.

• Visit the developerWorks Open source zone for extensive how-to information,tools, and project updates to help you develop with open source technologiesand 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 Geronimotoday.

• Find helpful resources for beginners and experienced users at the Get startednow with Apache Geronimo section of developerWorks.

• Check out the IBM Support for Apache Geronimo offering, which lets youdevelop 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 thedeveloperWorks 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 CommunityEdition -- a lightweight J2EE application server built on Apache Geronimo opensource technology that is designed to help you accelerate your developmentand deployment efforts.

• Innovate your next open source development project with IBM trial software,available for download or on DVD.

Discuss

• Participate in the discussion forum for this content.

developerWorks® ibm.com/developerWorks

Build portlets with Apache Geronimo and EclipsePage 26 of 27 © Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 27: Build portlets with Apache Geronimo and Eclipse - IBM · PDF fileFinally, Liferay provides such a wealth of freely available portlets ... and performance. IBM® WebSphere® Application

• Stay up to date on Geronimo developments at the Apache Geronimo blog.

• Get involved in the developerWorks community by participating indeveloperWorks blogs.

About the author

Matthew ScarpinoMatthew Scarpino is a project manager and Java developer at Eclipse EngineeringLLC. He is the lead author of SWT/JFace in Action and made a minor but importantcontribution 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 UnitedStates, other countries or both.Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc., in theUnited 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 othercountries.Linux is a registered trademark of Linus Torvalds in the United States, othercountries, or both.

ibm.com/developerWorks developerWorks®

Build portlets with Apache Geronimo and Eclipse© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 27 of 27


Recommended