|
http://www-128.ibm.com/developerworks/cn/websphere/library/techarticles/yangjiang/0402_jsr168/jsr168portlet.html?ca=dwcn-newsletter-wsdd#download
楊江
Innovation Center高級信息工程師, IBM
2004 年 2 月
本文以Hello World為例，介紹如何使用JSR 168 API編寫portlet，打包成portlet應(yīng)用，部署portlet應(yīng)用到portlet容器上。最后給出JSR 168的參考實現(xiàn)－Apache pluto的安裝配置。
在過去三年中，企業(yè)面臨著信息、流程的整合問題，"企業(yè)門戶"和"企業(yè)應(yīng)用集成"一時間成了IT業(yè)內(nèi)熱門的課題。國內(nèi)外IT廠商和開源組織順時而動，開發(fā)了各種企業(yè)門戶服務(wù)器。單是Java陣營，IBM公司發(fā)布了WebSphere Portal Server 1.2/2.1/4.x/5.x, Apache Software Foundation推出了JetSpeed、BEA、Oracle、SAP、Sun也推出了各自的Portal服務(wù)器。這些Portal服務(wù)器各自提供不同的Java API給應(yīng)用系統(tǒng)開發(fā)商開發(fā)Portlet，應(yīng)用系統(tǒng)開發(fā)人員不得不為不同的Portal服務(wù)器使用互不通用的API開發(fā)功能相同的Portlet。人們翹首以待，希望有一天能象編寫Java Servlet那樣，使用一種API編寫能運行在大多數(shù)Portal服務(wù)器上的Portlet應(yīng)用。
經(jīng)過近兩年時間的漫長等待，2003年10月7日，Java Community Process(JCP)發(fā)布了JSR168: Portlet Specification 1.0的最終版本。該規(guī)范包含如下內(nèi)容(參見 參考3)
定義了portlet運行環(huán)境 - portlet容器
定義了portlet容器和portlet之間的API
提供了portlet存儲持久性和非持久性數(shù)據(jù)的機制
提供了portlet包含servlet和JSP的機制
定義了portlet打包，方便部署
保證了portlet在JSR 168門戶中的二進制移植
能夠以WSRP協(xié)議把JSR 168 portlet作為遠程portlet運行。
JSR 168規(guī)范獲得了業(yè)內(nèi)的廣泛支持，JSR 168專家組包括主要的Portal廠商，包括Apache、BEA、 IBM、 Oracle、 Sun等公司和組織。IBM在Apache以開放源碼項目的方式提供了該規(guī)范的參考實現(xiàn)pluto，并在WebSphere Portal Server 5.0.2中提供了JSR 168的支持。
本文以Hello World為例，介紹如何使用JSR 168 API編寫portlet，打包成portlet應(yīng)用 源碼包下載，部署portlet應(yīng)用到portlet容器上。最后給出JSR 168的參考實現(xiàn)－Apache pluto的安裝配置。
現(xiàn)在讓我們開始吧。
一、 創(chuàng)建項目的目錄結(jié)構(gòu)
portlet項目的最基本的幾個目錄是：
HelloWorld\JavaSource 放置Java源代碼
HelloWorld\WebContent\Web-INF\classes 放置Java Class文件
HelloWorld\WebContent\Web-INF\lib放置jar文件，比如jstl.jar 、standard.jar (JSTL - JSP Standard Tag Library及Apache的JSTL的實現(xiàn))
HelloWorld\WebContent\Web-INF\tld 放置taglib定義文件，比如portlet.tld或者portlet.tld(portlet JSP tag)這些目錄下面的jar文件和tld文件可以從安裝好的pluto中找到。
二、創(chuàng)建Portlet Java代碼
下面是HelloWorldPortlet.java的代碼。相關(guān)連的另外兩個Java源文件，在本文末尾有 源碼包下載的鏈接。
注意：
1.import語句，這里使用的全部是java或者javax標(biāo)準(zhǔn)類庫，說明這個portlet代碼應(yīng)該是可以運行在支持相應(yīng)標(biāo)準(zhǔn)的服務(wù)器上面。
2.對于一些常量，使用了public static final修飾符。有助于提供java代碼的性能。
3.processAction方法是Portlet的核心方法之一，例子代碼在這里處理jsp中FORM表單提交的數(shù)據(jù)，并把得到的數(shù)據(jù)放到一個Java Bean中，該Java Bean又被放到PortletSession中供jsp文件調(diào)用。
proccessAction處理完畢后，portlet引擎會運行portlet的doView方法。doView方法根據(jù)邏輯、輸入數(shù)據(jù)或者配置，調(diào)用不同的jsp文件進行數(shù)據(jù)展示。
package com.ibm.spc;
import java.io.*;
import javax.portlet.*;
/**
*
* A sample portlet based on GenericPortlet
*
*/
public class HelloWorldPortlet extends GenericPortlet {
public static final String JSP_FOLDER = "/com_ibm_spc/jsp/"; // JSP folder name
public static final String VIEW_JSP = "HelloWorldPortletView"; // JSP file name to be rendered on the view mode
public static final String VIEW_BEAN = "HelloWorldPortletBean"; // Bean name for the view mode request
public static final String SAY_HELLO_ACTION = "Say_Hellow_Action"; // Action name for submit form
public static final String YOUR_NAME = "YourName"; // Parameter name for the text input
/**
* Serve up the <code>view</code> mode.
*
* @see javax.portlet.GenericPortlet#doView(javax.portlet.RenderRequest, javax.portlet.RenderResponse)
*/
public void doView(RenderRequest request, RenderResponse response) throws PortletException, IOException {
// Set the MIME type for the render response
response.setContentType(request.getResponseContentType());
// Invoke the JSP to render
PortletRequestDispatcher rd = getPortletContext().getRequestDispatcher(getJspFilePath(request, VIEW_JSP));
rd.include(request,response);
}
/**
* Process an action request.
*
* @see javax.portlet.Portlet#processAction(javax.portlet.ActionRequest, javax.portlet.ActionResponse)
*/
public void processAction(ActionRequest request, ActionResponse response) throws PortletException, java.io.IOException {
if( request.getParameter(SAY_HELLO_ACTION) != null ) {
// Make a session bean
PortletSession session = request.getPortletSession();
HelloWorldPortletBean viewBean = new HelloWorldPortletBean();
session.setAttribute(VIEW_BEAN, viewBean);
System.out.println("debug HelloWorld " + request.getParameter(YOUR_NAME));
// Set form text in the view bean
viewBean.setFormText(request.getParameter(YOUR_NAME));
}
}
/**
* Returns JSP file path.
*
* @param request Render request
* @param jspFile JSP file name
* @return JSP file path
*/
private static String getJspFilePath(RenderRequest request, String jspFile) {
String markup = request.getProperty("wps.markup");
if( markup == null )
markup = getMarkup(request.getResponseContentType());
return JSP_FOLDER+markup+"/"+jspFile+"."+getJspExtension(markup);
}
/**
* Convert MIME type to markup name.
*
* @param contentType MIME type
* @return Markup name
*/
private static String getMarkup(String contentType) {
if( "text/vnd.wap.wml".equals(contentType) )
return "wml";
return "html";
}
/**
* Returns the file extension for the JSP file
*
* @param markupName Markup name
* @return JSP extension
*/
private static String getJspExtension(String markupName) {
return "jsp";
}
}
|
三、創(chuàng)建JSP
jsp文件中首先聲明它不需要創(chuàng)建新的HTTP Session，返回頁面的內(nèi)容是html頁面。然后import聲明需要引用標(biāo)準(zhǔn)java類庫java.util，javax.portlet，以及我們自己的類庫com.ibm.spc。接著聲明使用portlet標(biāo)記庫。<portlet:defineObjects/>使用portlet標(biāo)記庫的標(biāo)記defineObjects，定義了jsp中要使用3個變量：
RenderRequest renderRequest
RenderResponse renderResponse
PortletConfig portletConfig
|
<%@ page session="false" import="java.util.*,javax.portlet.*,com.ibm.spc.*" %>
<%@taglib uri="http://java.sun.com/portlet" prefix="portlet" %>
<portlet:defineObjects/>
|
接下來，從<portlet:defineObjects/>語句定義的變量renderRequest當(dāng)中獲取PortletSession，進而得到session當(dāng)中保存的數(shù)據(jù)并顯示在JSP頁面上。
<%
PortletSession session = renderRequest.getPortletSession();
HelloWorldPortletBean bean = (HelloWorldPortletBean)session.getAttribute(HelloWorldPortlet.VIEW_BEAN);
%>
if (bean != null) {
String formText = bean.getFormText();
if( formText.length()>0 ) {
%>
Hello <%=formText%>.
<%
}
}
%>
|
最后部分是使用portlet標(biāo)記庫的另一個標(biāo)記actionURL產(chǎn)生一個URL指向當(dāng)前頁面中的這個portlet，生成的URL能夠觸發(fā)當(dāng)前portlet的action請求，或者說這個URL能夠觸發(fā)當(dāng)前portlet的processAction方法。
<FORM method="POST" action="<portlet:actionURL/>">
<LABEL for="<%=HelloWorldPortlet.YOUR_NAME%>">Please input your name here, </LABEL><BR>
<INPUT name="<%=HelloWorldPortlet.YOUR_NAME%>" type="text"/>
<INPUT name="<%=HelloWorldPortlet.SAY_HELLO_ACTION%>" type="submit" value="Submit"/>
</FORM>
|
四、編譯portlet
編寫好portlet的java代碼，現(xiàn)在我們可以把它編譯成二進制class文件。
下面的腳本中使用JAVA_HOME環(huán)境變量指向WebSphere Application Server 5.0.2中的IBM JDK 1.3.1。
腳本中使用CP變量指向Tomcat 4.1中帶的Servlet 2.3類庫，以及pluto的JSR 168 portlet類庫。腳本最后的動作是編譯HelloWorld portlet，并把編譯好的class文件放到WebContent\WEB-INF\classes目錄。
注意：
WebSphere Portal Server 5.0.2中使用的WebSphere Application Server 企業(yè)版5.0.2；Tomcat 4.1使用的JDK 1.3.1。
WebSphere Application Server 5.1中的JDK是1.4.1版本。
set JAVA_HOME=C:\WebSphere\AppServer\java
set PATH=%JAVA_HOME%\bin
set tomcat.home.pluto=e:\ApacheSoftwareFoundation\Tomcat4.1
set CP=.
rem Servlet 2.3 API jar file
set CP=%CP%;%tomcat.home.pluto%\common\lib\servlet.jar
rem JSR 168 API jar file
set CP=%CP%;%tomcat.home.pluto%\shared\lib\portlet-api.jar
rem Specify where to place generated class files
set target_path=..\WebContent\WEB-INF\classes
cd JavaSource
javac -classpath %CP% -d %target_path% com\ibm\spc\*.java
|
五、 創(chuàng)建Web應(yīng)用的部署描述文件
Portlet應(yīng)用也是一個J2EE Web應(yīng)用，擁有一個Web應(yīng)用部署描述文件web.xml。web.xml文件中taglib標(biāo)記部分是關(guān)于Portlet Tag Library的定義，在Portlet 應(yīng)用的jsp文件中可以使用這種Tag Lib。
下面代碼片斷聲明使用uri是 http://java.sun.com/portlet的tag lib，tag lib的前綴是portlet。關(guān)于Portlet Tag Library請參考Java Portlet Specification。
注意：2004年2月的pluto中portlet部署程序中不能分析處理web.xml文件中welcome-file的標(biāo)記，相信Apache會在后繼的版本中修正這個問題。解決辦法是，或者從web.xml文件中去除有關(guān)的tag；或者修改pluto代碼，為servletdefinitionmapping.xml文件添加welcome-file標(biāo)記，為org.apache.pluto.portalImpl.om.servlet.impl. WebApplicationDefinitionImpl java類添加一個字段來解決這個問題。
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app id="WebApp">
<display-name>HelloWorld Web Application</display-name>
<taglib id="PortletTLD">
<taglib-uri>http://java.sun.com/portlet</taglib-uri>
<taglib-location>/WEB-INF/tld/portlet.tld</taglib-location>
</taglib>
</web-app>
|
六、 創(chuàng)建Portlet部署描述文件
每個Portlet應(yīng)用除了Web應(yīng)用部署描述文件web.xml外，還有一個Portlet部署描述文件 - portlet.xml。該文件中包括該Portlet Application中一個或者多個portlet的定義。
下面的portlet.xml文件中首先是<portlet-app/>，其中引用了sun公司的關(guān)于portlet描述文件的名字空間的定義文件portlet-app_1_0.xsd。然后是各個<portlet/>定義，包括名字和描述信息，國際化的名字和描述信息，portlet的class類名，portlet的初始化參數(shù)、國際化用戶界面中使用的資源文件。HelloWorld Portlet有一個初始化參數(shù)wps.markup，在我們的portlet代碼中使用renderRequest.getProperty("wps.markup")獲得這個初始化參數(shù)的值。
七、 創(chuàng)建war文件
我們使用JDK的命令jar把class文件、jsp文件、jar包、JSP標(biāo)記庫、web部署描述文件web.xml、portlet部署描述文件portlet.xml等打包成web archive文件。
set JAVA_HOME=C:\WebSphere\AppServer\java
set PATH=%JAVA_HOME%\bin
cd WebContent
jar cf ..\build\HelloWorld.war .
|
八、 在pluto上面部署portlet應(yīng)用
pluto提供了部署打包成war格式portlet應(yīng)用的命令行工具。名叫Deploy的部署工具會做兩件事情：
1. 分析portlet應(yīng)用war文件中的web.xml文件和portlet.xml文件，修改web.xml以添加和pluto運行環(huán)境相關(guān)的servlet定義和servlet運行參數(shù)
2. 把portlet作為Web應(yīng)用部署到Tomcat服務(wù)器上面
在我們的例子中，Deploy工具修改web.xml文件，添加一個名叫HelloWorldPortlet的servlet定義，并為這個servlet添加了portlet-guid的參數(shù)，參數(shù)值HelloWorld.HelloWorldPortlet。其中<servlet-name>值來源于portlet.xml文件中<portlet-name>標(biāo)記，portlet-guid參數(shù)的值是war文件的前面部分和portlet.xml文件中<portlet-name>標(biāo)記的值的組合。
<servlet>
<servlet-name>HelloWorldPortlet</servlet-name>
<display-name>HelloWorldPortlet Wrapper</display-name>
<description>Automated generated Portlet Wrapper</description>
<servlet-class>org.apache.pluto.core.PortletServlet</servlet-class>
<init-param>
<param-name>portlet-guid</param-name>
<param-value>HelloWorld.HelloWorldPortlet</param-value>
</init-param>
<init-param>
<param-name>portlet-class</param-name>
<param-value>com.ibm.spc.HelloWorldPortlet</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>HelloWorldPortlet</servlet-name>
<url-pattern>/HelloWorldPortlet/*</url-pattern>
</servlet-mapping>
|
Deploy的語法是：
deploy <TOMCAT-webapps-directory> <TOMCAT-pluto-webmodule-name> <web-archive>
<build-container-dir> [-debug] [-addToEntityReg <app-id> [<portlet-id>:<portlet-name>]+]
|
下面的例子腳本中，Tomcat所有Web應(yīng)用都部署在TOMCAT-webapps-directory目錄下面，比如%tomcat.home%/webapps；<TOMCAT-pluto-webmodule-name>參數(shù)是pluto web應(yīng)用的名稱，比如 pluto；web-archive參數(shù)是我們要部署的portlet應(yīng)用打包文件， D:/workspace/JSR168Portlet/HelloWorld/build/HelloWorld.war；<build-container-dir>是portlet部署工具的工作路徑，比如當(dāng)前路徑，Deploy工具會在相對于工作路徑的路徑下面找尋相關(guān)文件。
set JAVA_HOME=C:\WebSphere\AppServer\java
set PATH=%JAVA_HOME%\bin
set tomcat.home.pluto=e:\ApacheSoftwareFoundation\Tomcat4.1
set CP=.
set CP=%CP%;%tomcat.home.pluto%\common\lib\servlet.jar
set CP=%CP%;%tomcat.home.pluto%\shared\lib\portlet-api.jar
set CP=%CP%;%tomcat.home.pluto%\common\endorsed\xercesImpl.jar
set CP=%CP%;%tomcat.home.pluto%\webapps\pluto\WEB-INF\lib\castor-0.9.5.jar;
set CP=%CP%;%tomcat.home.pluto%\common\endorsed\xmlParserAPIs.jar
set CP=%CP%;%tomcat.home.pluto%\shared\lib\pluto-1.0.jar
cd %tomcat.home.pluto%\webapps\pluto\WEB-INF\classes
set tomcat.home=e:/ApacheSoftwareFoundation/Tomcat4.1
java -classpath %CP% org.apache.pluto.portalImpl.Deploy %tomcat.home%/webapps pluto
D:/workspace/JSR168Portlet/HelloWorld/build/HelloWorld.war . -debug
|
注意：2004年2月份的pluto部署以后，可能缺少一個文件，具體路徑和文件名稱是tomcat.home\webapps\pluto\WEB-INF\portal\src\webapp\WEB-INF\tld\portlet.tld。
九、 注冊portlet到pluto容器中
修改%tomcat.home.pluto%\webapps\pluto\WEB-INF\data\portletentityregistry.xml文件，加入我們的portlet的注冊信息。其中application屬性<definition-id>指向HelloWorld應(yīng)用的war文件名稱的前半部分，portlet屬性definition-id指向HelloWorld應(yīng)用的web.xml文件中portlet-guid的值。這樣，portlet容器pluto就能夠根據(jù)這個注冊文件找到相應(yīng)web應(yīng)用的servlet了。
<application id="5">
<definition-id>HelloWorld</definition-id>
<portlet id="1">
<definition-id>HelloWorld.HelloWorldPortlet</definition-id>
<preferences>
<pref-name>TestName4</pref-name>
<pref-value>TestValue4</pref-value>
<read-only>true</read-only>
</preferences>
</portlet>
</application>
|
十、 把portlet放到我們的測試頁面中
修改%tomcat.home.pluto%\webapps\pluto\WEB-INF\data\ pageregistry.xml文件，添加一段fragment，把我們的portlet注冊到頁面上。其中名為portlet的參數(shù)的值是portletentityregistry.xml文件中注冊的portlet的應(yīng)用id和portlet id的組合。
<fragment name="col1" type="column">
<fragment name="p3" type="portlet">
<property name="portlet" value="5.1"/>
</fragment>
</fragment>
|
現(xiàn)在重新啟動Tomcat，我們終于看到盼望已久的JSR 168 portlet了。
在頁面中輸入IBM Innovation Center，你將看到
十一、 pluto的安裝
根據(jù)JSR 168 Request，IBM在Apache以開放源碼的方式提供了JSR 168的參考實現(xiàn)。
安裝Apache pluto，我們需要
1)Maven 1.0-beta-10或者更高版本，下載網(wǎng)址 http://maven.apache.org/start/download.html
2)JDK 1.3或者更高
3)Servlet 2.3引擎
Tomcat 4.1.18-LE w/JDK 1.4
或者
Tomcat 4.1.24 w/ JDK 1.3
4)CVS Client for windows
本人使用的測試環(huán)境是IBM JDK 1.3.1， jakarta-tomcat-4.1.29， v. 1.0-rc1-SNAPSHOT。
我們需要使用cvs客戶端以匿名方式下載pluto代碼。注意：cvs客戶端不能使用代理，必須用直接的internet連接。
cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login
password: anoncvs
cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout jakarta-pluto
|
安裝好JDK、maven、Tomcat以后，進入pluto源碼目錄，拷貝build.properties.sample 文件為build.properties文件。在build.properties文件中指定tomcat安裝路徑，注意windows平臺上面或者使用/或者是\\作為路徑的分割符。如果你在公司防火墻的后面或者其他原因必須通過代理服務(wù)器訪問internet的話，那么需要指定代理服務(wù)器參數(shù)maven.proxy.host和maven.proxy.port。
tomcat.home.pluto=e:\\ApacheSoftwareFoundation\\Tomcat4.1
maven.proxy.host = proxyhostname
maven.proxy.port = 8080
|
現(xiàn)在，我們執(zhí)行maven命令就可以開始pluto的安裝了。Maven將安裝pluto到Tomcat服務(wù)器上面，安裝名為testsuite的測試用portlet應(yīng)用到Tomcat上，配置pluto以運行testsuite中的例子portlet。
啟動tomcat以后，通過http://localhost:8080/pluto/portal/就可以訪問到pluto的演示頁面了。
MAVEN_HOME=E:\ApacheSoftwareFoundation\Maven1.0-rc1
Set PATH=%MAVEN_HOME%\bin;%path%
maven fullDeployment
|
后記
相信JSR 168標(biāo)準(zhǔn)會象Servlet標(biāo)準(zhǔn)那樣得到應(yīng)用服務(wù)器廠商和廣大應(yīng)用開發(fā)商的大力支持。上面的HelloWorld portlet現(xiàn)在可以運行在Apache pluto上面和IBM WebSphere Portal Server 5.0.2上面，相信也能運行在其他支持該標(biāo)準(zhǔn)的Portal服務(wù)器上。
參考資料
1) JSR(Java Standardization Request) 168
2)Pluto reference implementation: http://jakarta.apache.org/pluto
3)"Introducing the Portlet Specification," Stefan Hepper and Stephan Hesmer (JavaWorld):
Part 1: Get your feet wet with the specification's underlying terms and concepts (August 2003)
Part 2: The Portlet API's reference implementation reveals its secrets (September 2003)
4) IBM JSR 168 Tech preview
5) IBM Portal Toolkit 5.0.2：IBM WebSphere Studio 5.0的plugin， 支持JSR 168 portlet的開發(fā)環(huán)境
6) 比較JSR 168 Java Portlet 規(guī)范和IBM Portlet API
下載
|
Name |
|
 |
|
Size |
|
|
|
Download method |
|
|
|
HelloWorld.zip |
|
|
|
21 KB |
|
|
|
HTTP |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
關(guān)于作者
楊江， IBM Innovation Center高級信息工程師，主要從事WebSphere Portal Server和WebSphere Application Server的技術(shù)支持工作，對Linux、Web Service和Web安全有濃厚興趣。Email: yjiang@cn.ibm.com. | |