用 Apache Pluto 编写 portlet 并将其部署到 Apache Geronimo 中

2007 年 7 月 23 日

Portlet 是功能强大的工具，可用于从多个位置聚合数据，整合各种应用程序，以及为多组用户提供一致的工作区。Apache Pluto 是 Portlet 规范的参考实现，因此可用来测试正在开发中的 portlet。本文将教您如何在 Apache Geronimo 服务器内安装和配置 Pluto portlet 容器。

Apache Geronimo 是 Java™ Platform, Enterprise Edition (Java EE) 服务器系列的新成员（版本 1.0 是在 2006 年 1 月发布的）。它是若干个其他项目的强大组合，包括 OpenEJB、Axis、Jetty、Tomcat、ActiveMQ 和 ServiceMix。Geronimo 最近受到广泛宣扬，因为它是另一种 Java 2 Platform, Enterprise Edition (J2EE) 认证的服务器。它是使用依赖性注入容器从头构建的。Geronimo 还提供了针对类装入器的精细控制，使您可以指定父子关系，而不只是删除共享 lib 目录中的所有类，并希望不会出现什么问题。

Apache Pluto 是 Portlet 规范的参考实现。Pluto 本身不是功能全面的门户服务器；相反，它是一种轻量级 portlet 容器，适于嵌入到成熟的门户服务器，或测试 portlet。Apache Jetspeed 2、uPortal 和 Jahia 等多个开源门户服务器中目前都使用了 Pluto。现在，Pluto 支持 Portlet 规范的 1.0 版 (JSR 168)；规范的 2.0 版 (JSR 286) 目前正在开发中。

如果要使用 Pluto 开发 portlet 或门户服务器，则将它与 Geronimo 结合使用是十分有意义的。如果门户或 portlet 使用 Geronimo 特有的特性（例如 GBeans），这样做尤为正确。Pluto Web 站点并未解释如何在 Geronimo 上安装 Pluto，但是可以对安装方法做一些调整。

安装 Geronimo 十分简单：只需从 Geronimo Web 站点安装 Jetty-Geronimo 包（有关链接，请参阅 ），并将其解压缩到 GERONIMO_HOME 目录中。像 Apache Tomcat 一样，您可以用位于 GERONIMO_HOME/bin 目录中的启动脚本（或批处理文件）来启动服务器。

注：本文使用了配有 Jetty 的 Geronimo 2.0-M2。没有针对其他版本或 Tomcat-Geronimo 包测试过这些步骤。

从 Pluto 站点下载 Pluto 1.1 包（有关链接，请参阅 ），并将其解压缩到 PLUTO_HOME 目录中。该包是与 Tomcat 绑定在一起的二进制版本的 Pluto 容器，因此需要执行一些额外的工作才能使它在 Geronimo 上运行。

注：本文使用了 Pluto 1.1。没有针对以前的版本测试过这些步骤。

Pluto 要求把一些 JAR 文件放入共享位置中，以便 portlet 应用程序和门户驱动程序本身可以使用这些 JAR 文件。从版本 1.1 开始，Geronimo 支持共享库目录。但是，创建显式依赖性是更好的选择，因为可以进行更精细地控制。

要定义与库之间的依赖性，库必须可用于 Geronimo 存储库。所有 Pluto 依赖性都在 PLUTO_HOME/shared/lib 目录中。但是，由于 Geronimo 已经安装了一些这类库，因此只需将其中的一些库添加到存储库中：

• pluto-container-1.1.0.jar
• pluto-descriptor-api-1.1.0.jar
• pluto-descriptor-impl-1.1.0.jar
• pluto-taglib-1.1.0.jar

通过友好的 Geronimo 管理控制台把一些库添加到存储库中十分简单，如图 1 所示。通过控制台添加上面的每个库，并确保每个库都在 org.apache.pluto 组中。

下一步是为 Pluto 门户驱动程序编写 Geronimo 部署计划，该驱动程序是用于运行 portlet 的 Web 应用程序。计划 是描述其他 Geronimo 特有的属性的 XML 文档；部署计划将替代 Java EE 部署描述符。

Pluto 门户驱动程序驻留在 PLUTO_HOME/webapps/pluto 目录中。在 WEB-INF 目录中创建名为 geronimo-web.xml（这是 Geronimo Web 部署计划的标准名称）的新文件。在此文件中，将指定 Pluto 门户驱动程序要求使用的依赖性及该驱动程序的上下文路径。首先，声明 moduleId，如清单 1 所示：

         org.apache.pluto pluto 1.1.0 war

这段代码片段在 org.apache.pluto 组中声明了名为 pluto 的模块。由于使用的不是共享 lib 目录，因此计划还必须声明依赖性，如清单 2 所示：

... org.apache.pluto pluto-container 1.1.0 jar org.apache.pluto pluto-descriptor-api 1.1.0 jar org.apache.pluto pluto-descriptor-impl 1.1.0 jar org.apache.pluto pluto-taglib 1.1.0 jar ...

这段代码片段包括添加到 Geronimo 存储库中的所有库。但是，Pluto 门户驱动程序要求使用已经在存储库中安装的其他一些库，如清单 3 所示：

xalan xalan 2.7.0 jar xerces xercesImpl 2.8.1 jar castor castor 0.9.5.3 jar commons-logging commons-logging 1.1 jar portlet-api portlet-api 1.0 jar            ...

这些库是随 Geronimo 附带的，因此在将这些库声明为依赖性之前不需要将其添加到存储库中。

如 前述，Geronimo 是若干个开源库的组合。除了诸如 OpenEJB 之类的较大组件之外，它还使用了 Spring 框架和管理控制台，甚至还使用了较早版本的 Pluto。要安装 Pluto 1.1 门户驱动程序，Web 应用程序必须忽略服务器所装入的任何其他 Pluto 或 Spring 库。幸运的是，您可以告诉 Geronimo 忽略那些类以避免任何混乱，如清单 4 所示：

... org.apache.pluto org.springframework

接下来，必须指定 Pluto 的上下文根，如清单 5 所示：

... /pluto    ...

您几乎已经完成了部署计划，但是仍有 “一点” 安全问题。

Pluto 门户驱动程序将使用 Java EE 安全角色，因此必须将 Geronimo 角色映射为门户驱动程序的 web.xml 文件中定义的角色。最简单方法是使用 Geronimo 的默认安全领域 geronimo-admin。需要做的全部操作就是将默认管理角色映射为门户驱动程序使用的 pluto 角色，如清单 6 所示：

... geronimo-admin               class="org.apache.geronimo.security.realm. 	                providers.GeronimoUserPrincipal"/>                       class="org.apache.geronimo.security.realm. 	                         providers.GeronimoUserPrincipal"/>

您可以看到您已经定义了默认的匿名角色并将 pluto 角色映射为用户名 system，这是默认的管理员帐户。

计划现已完成。完整的文件可从 部分下载获得。

最 后一步是修改 castor.properties 文件，该文件将由 Geronimo 和 Pluto 都使用的开源数据绑定框架 Castor 使用。该文件驻留在 PLUTO_HOME/webapps/pluto/WEB-INF/classes 目录中。打开文件，并禁用 parser.validation 和 indent 属性。清单 7 显示了修改后的文件。

org.exolab.castor.parser.validation=false org.exolab.castor.parser.namespaces=false org.exolab.castor.indent=false org.exolab.castor.debug=false

配置现已完成。现在是时候将 Pluto 发布到 Geronimo 实例中了。

现在您已经完成了配置更改，必须把 PLUTO_HOME/webapps/pluto 目录打包成名为 pluto-portal-1.1.0.war 的 WAR 文件。

创建完 .war 文件后，您可以使用 Geronimo 管理工具中的 Deploy New 选项轻松地部署该文件，如图 2 所示（不要忘记用启动脚本启动 Geronimo）。在部署了应用程序之后，您应当能够通过 http://localhost:8080/pluto/ 访问该应用程序（如图 3 所示）。

要成功地运行 Pluto 门户驱动程序，您还必须安装 Pluto TestSuite，它拥有检验门户驱动程序是否正常运行的默认 portlet。安装 TestSuite 类似于安装门户驱动程序：创建部署计划，打包并部署 WAR 文件。

由于您已经添加了所有共享库，因此您可以跳过部署计划。从清单 8 开始，它显示了 Pluto TestSuite 的模块声明。

org.apache.pluto testsuite 1.1.0 war         ...     ...

在这里已经在 org.apache.pluto 组中定义了一个名为 testsuite 的模块。TestSuite 是一个 portlet 应用程序，这意味着它的运行依赖于与 Pluto 相关的库。您无需定义若干个显式依赖性，只需告诉 Geronimo TestSuite 依赖于 Pluto WAR 文件，如清单 9 所示：

... org.apache.pluto pluto 1.1.0 war classes            ...      ...

元素将告诉服务器先装入父类（在本例中，为 Pluto 门户驱动程序及其依赖性）。

为了确保 Web 应用程序类装入器获得 portlet TLD 文件，您还必须直接声明 portlet taglib，如清单 10 所示：

... org.apache.pluto pluto-taglib 1.1.0 jar

最后，使用 元素，该元素将告诉 Geronimo 先在 Web 应用程序的 CLASSPATH (WEB-INF/lib and WEB-INF/classes) 中装入类（参见清单 11）。

...

计划的其余部分类似于 Pluto 门户驱动程序的计划，除了 TestSuite 要求名为 tomcat 而不是 pluto 的角色。

还 有一个额外步骤。在 Pluto 1.1 发行版的早期版本中，PLUTO_HOME/testsuite/WEB-INF 目录中的 web.xml 文件缺少文档类型定义（Document Type Definition，DTD）声明，这是 Geronimo 不满意的地方。您必须将此声明添加到顶部的 XML 声明之后，如清单 12 所示：

         br />        "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"         "http://java.sun.com/dtd/web-app_2_3.dtd">

最新版本的 Pluto 可能已经解决了这个问题（它已经被归档到问题跟踪程序中）。

最 后一步是打包和部署 TestSuite。将 PLUTO_HOME/webapps/testsuite 目录打包成名为 pluto-testsuite-1.1.0.war 的 WAR 文件。就像 Pluto 门户驱动程序一样，您可以使用 Geronimo 管理工具中的 Deploy New 选项轻松地部署 TestSuite。在部署了应用程序之后，您应当能够通过 http://localhost:8080/testsuite/ 直接访问该应用程序。您应当会看到文本 “Hello world!”（参见图 4）。

现在 TestSuite 将独立运行，现在可以在 Pluto 中查看它。返回到 http://localhost:8080/pluto/ 中的 Pluto 门户驱动程序，并使用 Geronimo system 用户帐户登录。您应当会看到与来自 TestSuite 的 Test Portlet 1 和 Test Portlet 2 一起运行的门户驱动程序，如图 5 所示：

祝贺您！您已经成功地在 Geronimo 上安装了 Pluto。将来有可能通过 Ant 任务自动执行这其中的一些步骤。现在让我们浏览一下编写和部署简单的 portlet 的过程。

编 写 portlet 类似于编写 servlet。如果集成开发环境 (IDE) 支持 portlet 开发，则创建一个新的 portlet 项目；否则，一个普通的 Web 应用程序项目就足够了。在此示例中，您将使用原始的 Portlet 应用程序编程接口 (API)，但是在实际的应用程序中，您应当使用诸如 JavaServer Faces (JSF)、Struts 或 Spring MVC 之类的 Web 框架（要获得含有本示例的完整 Eclipse 项目，请参阅 部分）。

编写 portlet 与编写 servlet 之间的主要差别在于存在特定 portlet 模式的方法（例如 help、edit 或 view）和处理 portlet 操作的方法。这个简单的 Hello, World! portlet 应当是 GenericPortlet 类的子类，并实现 doHelp()、doEdit() 和 doView() 方法，如清单 13 所示：

package com.virtua.examples.portlet; import java.io.IOException; import java.io.PrintWriter; import javax.portlet.GenericPortlet; import javax.portlet.PortletException; import javax.portlet.RenderRequest; import javax.portlet.RenderResponse; public class HelloWorldPortlet extends GenericPortlet {
      	protected void doEdit(RenderRequest request, RenderResponse response)           throws PortletException, IOException 	{
               response.setContentType("text/html");		          PrintWriter writer = new PrintWriter(response.getWriter());          writer.println("You're now in Edit mode.");  	} 	protected void doHelp(RenderRequest request, RenderResponse response)           throws PortletException, IOException 	{
               response.setContentType("text/html");		          PrintWriter writer = new PrintWriter(response.getWriter());          writer.println("You're now in Help mode."); 	} 	protected void doView(RenderRequest request, RenderResponse response)           throws PortletException, IOException 	{
               response.setContentType("text/html");          PrintWriter writer = new PrintWriter(response.getWriter());          writer.println("Hello world! You're in View mode.");     } }

这是简单的只读 portlet，它将根据 portlet 的当前模式显示不同的文本字符串。有两点需要注意：

• 在 portlet 输出任何数据之前，必须先设定内容类型。
• portlet 将从 javax.portlet 包导入类。要访问这个包，必须在构建路径中包括 portlet-api-1.0.jar；您可以从 PLUTO_HOME/shared/lib 获得此文件。

在编写了 Hello, World! portlet 之后，您必须编写三个简短的部署描述符：web.xml、portlet.xml 和 geronimo-web.xml（这其中的一些文件可能已经由 IDE 生成）。所有这些文件都应当位于 portlet 应用程序的 WEB-INF 目录中。

第一个文件 web.xml 只要求引用 Pluto 的 PortletServlet，它用于帮助门户驱动程序处理 portlet（对于大多数门户服务器，此类都是不同的）。清单 14 显示了该文件。

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"> HelloWorldPortlet HelloWorldPortlet 			org.apache.pluto.core.PortletServlet portlet-name HelloWorldPortlet 1 HelloWorldPortlet /PlutoInvoker/HelloWorldPortlet

正如您所见，部署描述符指定使用 org.apache.pluto.core.PortletServlet 类并被配置为装入 HelloWorldPortlet 的单个 servlet。此外请注意：该 servlet 被映射为 Pluto 所要求的以 /PlutoInvoker/ 开头的 URL 模式。

portlet 应用程序描述符 portlet.xml 将提供一些特定于 portlet 的详细信息，如清单 15 所示：

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"> Hello, world! portlet HelloWorldPortlet HelloWorldPortlet        com.virtua.examples.portlet.HelloWorldPortlet text/html VIEW EDIT HELP Hello, Pluto on Geronimo!

在这里，描述符将定义 HelloWorldPortlet，提供描述、显示名称、类名和标题。Portlet.xml 还将指定此 portlet 支持的 portlet 模式，在本例中为 VIEW、edit 和 HELP。

就像先前的 Web 应用程序一样，Geronimo 部署计划驻留在 WEB-INF/geronimo-web.xml 中。此文件（如清单 16 所示）类似于 TestSuite 计划，但是不要求使用安全角色。

         com.virtua.examples.portlet HelloWorldPortlet 1.0 war org.apache.pluto pluto 1.1.0 war classes org.apache.pluto pluto-taglib 1.1.0 jar /HelloWorldPortlet

正如您所见，您将定义 portlet 应用程序的模块以及对 Pluto 门户驱动程序与 pluto-taglib 库的依赖性。请注意，这一次并未包括 元素，因为没必要使用它。

现在所有工件都已经准备好，让我们构建 portlet！

在 IDE 内构建 portlet 应用程序应当是一个简单的过程；记住，惟一的依赖性是 portlet-api-1.0.jar。但是，您必须确保这个 .jar 文件不与 .war 文件一起部署，因为它已经位于 Geronimo 存储库中。打包也十分简单：整个 Web 目录应当被打包成名为 HelloWorldPortlet.war 的 WAR 文件（如果需要节省时间，Eclipse 项目包括了 Ant 脚本；请参阅 部分）。

现 在 .war 文件已经完成，您可以使用 Geronimo 控制台部署它，就像您为 Pluto 门户驱动程序和 TestSuite 应用程序所做的操作一样。此外，您可以使用 Geronimo 的热部署机制并将 .war 文件放入 GERONIMO_HOME/deploy 目录中。

在部署了 HelloWorldPortlet 之后，您可以通过 Pluto Admin portlet 将其添加到 Pluto 门户驱动程序页面中：

1. 正常登录到 Pluto，并从 Navigation 菜单选择 Pluto Admin 选项。
2. 在 Admin portlet 内，选择 Secondary Page，然后选择 HelloWorldPortlet portlet 应用程序，如图 6 所示：
   
3. 单击 Add Portlet 完成操作。

祝贺您！您已经在 Geronimo 上部署了第一个自定义 portlet。您可以通过从 Navigation 菜单中选择 Secondary Page 来查看 portlet。HelloWorldPortlet 应当显示在两个测试 portlet 的下方。图 7 显示了目前已部署的内容，其中两个测试 portlet 被最小化。