Build portals with Jetspeed

Use Apache Jetspeed to build portals out of Web services

Developers are facing a new application integration challenge: building existing content, server-side Java applications, and Simple Object Access Protocol (SOAP)-based Web services into a coherent frontend application for their users. Most of you are familiar with consumer-oriented Websites -- such as Lycos, AltaVista, and Yahoo! -- that aggregate content and services into portals. Company intranets have used portals for years to make internal systems available to employees. Those intranets tend to be either expensive proprietary solutions or internally supported homegrown portals. If you're looking for an open source way to develop your own portal solution, look no further than the Jetspeed project from the Apache Software Foundation. For Java developers, Jetspeed offers a Portal API for developing small Java applications, known as portlets, that run inside the portal. The IBM WebSphere Portal Server also supports that Portlet API.

What does Jetspeed do?

Jetspeed lets you focus on building connections to outside resources, such as Web services, databases, and content feeds. It features built-in services for user interface customization, caching, persistence, and user authentication. As a portal developer, you don't have to build any of those services yourself; instead, you can concentrate on retrieving external data and displaying it. Jetspeed doesn't place any restrictions on what resources portlets may access.

Each user has individual settings for displaying portlets on his or her portal, for both wireless and Web access. Some portlets may only work on the Web, while some may also work on mobile devices; users can have different portlets for each. User authentication is abstracted through interfaces, and you can implement the authenticate() method on the UserManager interface from Turbine (provided as part of Jetspeed) or you can replace the method with a pluggable authentication module. You could use that module as part of a single sign-on solution, in which your portal handles frontend authentication, or to access an existing database of user information.

To display content, portlets use the Element Construction Set (ECS) API, which generates markup elements from Java objects. ECS supports the Wireless Markup Language (WML) as well as HTML and XML, and is open source under the Apache license. It is available from the Jakarta Apache Project; however, the ECS jar file is bundled with Jetspeed, so no additional downloads are necessary. It may be easier to use a servlet-based template or Web publishing technology, such as JSPs, WebMacro, or Velocity, to generate content for your portlet. ECS can run a servlet and capture the output in an ECS element, which may then be used as the displayed content.

Without any Java programming, you can easily set up Jetspeed to get news headlines and content from other Websites. Jetspeed can use both the RSS (RDF Site Summary) and OCS (Open Content Syndication) formats. RSS is an XML format used for syndicating Web headlines. Websites publish RSS feeds to anyone on the Internet interested in retrieving them. The headlines link back to the publishing Website for the article's full content. The OCS format describes multiple-content channels, including RSS headlines. To configure new content channels for Jetspeed, add them to your WEB-INF/conf/jetspeed-config.jcfg file.

Jetspeed architecture

Jetspeed is built on top of Turbine, an open source application framework from the Jakarta Apache Project. Most Apache projects are either built on Turbine or integrated with it. Some of Jetspeed's concepts, such as screens and user information, are borrowed from Turbine.

Jetspeed can sit on a number of servlet runners and databases. We'll be using the Tomcat 3.2 servlet runner, also from the Jakarta Apache Project. Tomcat also acts as a Web server, so you won't need an additional HTTP server.

Jetspeed is bundled with Thomas Mueller's Hypersonic SQL database. Tables are already created and populated with user data in Hypersonic SQL. Hypersonic SQL runs in process to Jetspeed (and Tomcat), so no additional configuration is necessary. If you want to use a different database, such as Oracle, DB2, Sybase, MySQL, or Postgres, you must set up the database using the SQL scripts included with the Jetspeed source code. In addition, you must configure the file that Jetspeed and Turbine use to point to the new database server.

I recommend that you use the Hypersonic SQL database. The most common complaint on the Jetspeed users mailing list is that configuring a new database, like MySQL, doesn't work. If you do run into problems with another database, first check the Jetspeed and Turbine mailing list archives for other developers' experiences with the software (see Resources). Jetspeed uses Turbine's database connection code. Of course, you can use any database from your portlet; Jetspeed just uses Hypersonic SQL internally.

Install Jetspeed

To install Jetspeed, follow these three steps:

  • Download and install Tomcat 3.2.
  • Download the Jetspeed binary distribution (currently 1.3a1) and place the war file in Tomcat's webapps directory.
  • Download Apache James if you don't already have an SMTP server running on your machine. Configure the mail.server property in Jetspeed's, which resides in the webapps/jetspeed/WEB-INF/conf subdirectory under the directory where you installed Tomcat.

Detailed installation instructions are available on the Jetspeed Webpage; see Resources for a link.

Jetspeed is packaged as a war file, and can be dropped into Tomcat's webapps directory. You'll need to restart Tomcat if it's already running.

The testing URL for Jetspeed is http://localhost:8080/jetspeed/. If you change Tomcat's default port, replace 8080 with your new port number. You can log in using turbine as both your username and password, or just use the default configuration without logging in.

Develop new portlets

When you develop new portlets for Jetspeed, use the AbstractPortlet class as a base. This is in the org.apache.jetspeed.portal.portlets package. By extending AbstractPortlet, you can have a working portlet by implementing the getContent() method. The getContent() method also takes an implementation of the RunData interface from Turbine as a parameter. By accessing get or set methods from the RunData interface, you have access to the runtime information stored in Turbine, including cookies, locale, and user data. Most of this data is actually handled by Jetspeed itself, and isn't needed for portlet development.

The getContent() method returns a ConcreteElement from the ECS. The ECS objects that represent HTML or WML tags extend either MultiPartElement or SinglePartElement, both of which extend ConcreteElement. You can use plain old strings in the StringElement without markup. The StringElement also subclasses ConcreteElement.

Our first portlet is fairly simple and demonstrates the use of ECS to build an HTML table. Our usage of ECS is fairly straightforward: elements may have set attributes, or you may include additional elements; tags, such as <table>, <tr>, and <td>, are nested. ECS can look strange at first, but the advantage of using it is the flexibility it provides in moving content around. Your tags will always be properly nested when you cut and paste your HTML markup.

When you compile the portlet, be sure that ecs.jar, turbine.jar, and jetspeed-1.3a1.jar are in your classpath. Move the class file into webapps/jetspeed/WEB-INF/classes under your Tomcat home directory.

import org.apache.ecs.*;
import org.apache.ecs.html.*;
import org.apache.jetspeed.portal.portlets.AbstractPortlet;
import org.apache.turbine.util.RunData;
public class FirstPortlet extends AbstractPortlet {
   public ConcreteElement getContent (RunData aRunData) {
      Table table = new Table()
                               .addElement(new TR()
                                  .addElement(new TD()
                                     .addElement(new B()
                                       .addElement("I am bold."))))
                               .addElement(new TR()
                                  .addElement(new TD()
                                     .addElement("I'm the lower table row.")));
      return table;

Here is the HTML this portlet displays:

<table border="0">
                I am bold.
            I'm the lower table row.

Portal Structure Markup Language

You must register your new portlet with Jetspeed manually, using an XML dialect called Portal Structure Markup Language (PSML). Jetspeed uses PSML to describe internal configuration, available portlets, and user configurations. The available portlets are stored in the portlet registry. Each portlet is described in PSML as a portlet-entry element, which tells Jetspeed how to instantiate the portlet. Each portlet entry must have an inheritance type associated with it:

  • instance: This is a standalone portlet. The instance entry holds all information needed to run the portlet.
  • abstract: This portlet entry does not have all the information needed, so a ref type portlet must provide additional entry data. The RSS portlet included with Jetspeed is an abstract portlet. To be used, you must create another entry of type ref with a URL pointing to the RSS content.
  • ref: A ref portlet entry builds upon another portlet entry; you can build a chain of ref portlet entries. The Mozilla portlet bundled with Jetspeed is a ref entry and refers to the abstract RSS portlet.

The portlets we'll build here all have the type instance, since they are self-contained.

The configuration file for portlets is jetspeed-config.jcfg in the WEB-INF/conf directory. Each user has two configuration files: homeHTML.psml and homeWML.psml. These files are stored in a different subdirectory -- WEB-INF/psml/<username> -- for each user. If you aren't logged into Jetspeed, you'll see the default user configuration. These default files, called default.psml and defaultWML.psml, are in WEB-INF/psml.

Let's add our new portlet to jetspeed-config.jcfg and then to the default user configuration file, default.psml.

In jetspeed-config.jcfg, there is a portlet registry section. You add a portlet entry to the end of the registry. The portlet has an instance type, and the class name is FirstPortlet. You can also add additional information, like any title and description you'd like; Jetspeed uses the title in the customization screen shown to the user.

The default configuration file contains the layout of all the portlets. They are organized under portlet controllers, which determine how the portlets appear on the page. Portlets may also have controls that modify the portlet's look and feel. Our portlet belongs to a RowColumnPortletController, which is similar to an HTML table, except that it can be either row- or column-oriented. We won't use any portlet controls, because Jetspeed's default control works fine.

Add <entry type="ref" parent="FirstPortlet" /> to the RowColumnPortletController that contains the JetspeedContent portlet entry. I added mine under JetspeedContent, which is how it will display to the user.

Restart Tomcat and go to http://localhost:8080/jetspeed in your Web browser. You should see your first portlet display under the Jetspeed links. If it doesn't appear, check your Tomcat console for error messages. When Tomcat can't find your portlet in the classpath, it puts an error on the console.

Wireless support

Jetspeed supports WML 1.1 and 1.2. To access Jetspeed from a Wireless Access Protocol (WAP) device, such as a mobile phone, you must set up a separate WAP gateway server, such as Nokia's Activ Server.

Jetspeed's WML support comes from the Apache ECS Project. A Java object in the org.apache.ecs.wml package represents each WML element, such as <card> or <p>. You'll have to write separate display code for HTML and WML if you intend to support both in your portlet; Jetspeed unfortunately doesn't have a built-in Web-to-wireless translator yet.

I did my wireless development with Nokia's WAP Toolkit (see Resources). This is one of two toolkits that has been tested with Jetspeed, the other being OpenWave's (formerly Software Developer Kit. Nokia's toolkit comes with a WAP gateway and a mobile phone simulator for running WAP/WML applications on your desktop computer.

Once you've installed the Nokia software, start Tomcat and the Nokia WAP Toolkit. For development purposes, you don't need the Nokia WAP gateway running. Log into Jetspeed running on your local machine at http://localhost:8080/jetspeed and play around with the portal on the simulated mobile phone. Anyone with a Web browser on his or her cell phone can access our first portlet.

1 2 Page 1
Page 1 of 2