使用 Application Developer V7 来创建和部署 JSR 168 协作 portlet

协作 portlet 是如何工作的

协作 portlet 就是可以通过发送消息与其它 portlet 相互联系的 portlet。它们以下面任何一种方式进行工作：

• 一个 portlet 可以是 一个协作 源，意思是它能够向其它 portlet 发送数据。

• 它可以是 一个协作目标， 意思是它可以从其它 portlet 接收数据。

• 一个 portlet 还可以同时是 协作源和协作目标 。Application Developer Version 7 提供了一套工具来详细说明协作源和目标，并在它们之间传递数据。

IBM® WebSphere® Portal 使之间的通信通过两种机制变得十分方便：属性代理和 Click-to-Action。 属性代理机制可以通过 Java™ Specification Request (JSR) 168 和 IBM API portlet 来使用。 Click-to-Action 目前只能对 IBM API portlet 使用。这篇文中重点强调的是属性代理机制。

属性代理机制是由 WebSphere Portal 提供的服务，它像一个中心集线器按照一系列详细定义的导线从源 portlet 接收数据并将它传递到目标 portlet。每一根导线都是一个源行为导目标行为一对一的映射。当一个 portlet 为协作被激活后，就会创建一个 WSDL 文档（Web Services Description Language），这个文档定义了可以共享数据的类型，这个数据如何被共享，以及将要激发属性转换的行为。

创建一个协作 portlet 应用软件包含三个主要步骤：

1. 定义数据转换，无论是引入的（对于目标）还是外出的（对于源）。

1. 实施操作过程，如果它是一个协作源，就使这个数据对于这个属性代理是可利用的，或者如果它是一个协作目标，就使这个数据通过属性代理传递进来。

1. 将它部署到服务器上，并用这个配线工具将这些 portlet 连接起来。

紧接着后面的练习可以让您贯穿这些步骤，并产生一个您可以部署到 WebSphere Portal 服务器上的一个有效的协作应用软件。

Rational Application Developer 中的协作 portlet 工具

在进入这个例子之前，让我们先来快速浏览一下 Rational Application Developer V7 中可应用的 JSR 168 portlet 协作工具。

Cooperative Source 向导

目的： 使用这个向导(图 1)来激活一个 portlet，使它能够成为一个协作源。点击 Finish 以后，就会创建一个 WSDL 文档，这个文档定义了可以共享数据的类型，这个数据如何被共享，以及将要激发属性转换的行为。您可以在一个 portlet 上多次运行这个向导来定义附加的属性和转换。

访问这个向导：

1. 在 Project Explorer 中展开 Portlet Deployment Descriptor 节点，然后右键点击一个 portlet。
2. 选择 Cooperative > Enable this Portlet to Send Data (Source)。

它创建或者更新的文档：

• WebContent/wsdl/[portletName].wsdl： 这个文档定义了可以共享数据的类型，这个数据如何被共享，以及将要激发属性转换的行为。
• WebContent/WEB-INF/portlet.xml： 向导更新了这个包含一个涉及 WSDL 文件的 portlet 优先文档。
• 属性文档： 两个可选择的功能值被添加到这个 portlet 的属性文件。

The Cooperative Target 向导

目的： 使用这个向导 (图 2) 来激活一个 portlet 作为协作目标。在点击 Finish 之后，就会创建一个 WSDL 文件，这个文件定义了接收数据的类型，如何从属性代理接收数据，以及当接收数据时将要执行什么样的行为。

访问这个向导：

1. 展开 Project Explorer 中的 Portlet Deployment Descriptor 节点，然后右键点击一个 portlet。
2. 选择 Cooperative > Enable this Portlet to Receive Data (Target)。

它创建或者更新的文件：

• WebContent/wsdl/[portletName].wsdl： 这个文件定义了接收数据的类型，如何接收，以及当它接受数据以后执行什么样的行为。
• WebContent/WEB-INF/portlet.xml： 向导更新了这个包含一个涉及 WSDL 文件的 portlet 优先文档。当激活一个 JavaServer™ Faces (JSF) portlet 时，两个涉及到输入属性名称和目标行为名称的初始化值(init params)都会被添加。
• 属性文件： 两个可选择的功能值被添加到这个 portlet 的属性文件。

Cooperative Source Trigger

目的： 使用这个向导 (图 3) 来为 JavaServer Faces 或者 Basic 协作源 portlet 来执行行为过程的步骤。它将必要的输入元素插入 JavaServer Pages™ (JSPs) 来激发一个属性转换，并产生行为过程代码使数据能够被属性代理所使用。您可能需要修改产生的代码来满足您应用软件的准确需要。

访问这个工具：

1. 打开 Palette 视图中的 Portlet drawer 。
2. 拖拽 Cooperative Source Trigger 条目到 JSP 页面。

它所更新的文件：

• JSP：适当的 UI 数据将会被添加到 JavaServer Pages 文件。无论添加的是一个链接还是一个按钮。当点击它的时候，它就会触发这个属性转换。
• 页面代码文件 (JavaServer Faces， 或者仅仅是 JSF)： 在页面代码中将会创建一个行为方法，这将使共享数据能够被属性代理使用。
• portlet 类（仅仅是 Basic）： 向导更新了 processAction() 方法使得共享数据能够被属性代理使用。

Project Explorer

目的： 协作行为何数据类型都显示在 Project Explorer (Figure 4) 中，像 portlet 的小孩一样，因此您可以获得一个被激活的源和目标 portlet 的综合高级视图。

访问这个信息：

1. 展开 Project Explorer 中的 Portlet Deployment Descriptor 节点。
2. 展开 portlet 节点。

Edit Data Type 向导

目的： 这个向导(图 5) 的功能与用来激活源或者目标 portlet 的向导功能是一样的。当您选择一个数据从 Project Explorer 中进行编辑时，它的值将会提前迁移到这个向导。您所做的任何变动都会对 WSDL 文件中现存的值进行编辑，而不是创建一个新的条目。

访问这个向导：

1. 展开 Project Explorer 中的Portlet Deployment Descriptor 节点，然后展开包含您想编辑的数据类型的 portlet。
2. Expand the action that the data type is associated with, and right-click on it.
3. 选择 Edit Data Type。

它更新的文件：

• WebContent/wsdl/[portletName].wsdl： 更新了 WSDL 文件中现有的值。
• WebContent/WEB-INF/portlet.xml： 当编辑一个 Faces portlet 时，在必要的情况下，涉及输入属性名称和目标行为名称的两个初始值将会被更新。

Delete Action 和 Delete Data Type 对话框

目的： 这两个对话框可以使您自动清除 WSDL 文件中的行为或者数据类型。(请看 图 6 和 图 7。)

访问这些工具：

1. 右键点击 Project Explorer 中的一个协作行为或者一个数据类型阶段。
2. 选择 Delete。

这些工具更新的文件：

• WebContent/wsdl/[portletName].wsdl： 清除 WSDL 文件中的行为或者数据类型。
• WebContent/WEB-INF/portlet.xml： 当编辑一个 Faces portlet 时，如果需要的话，涉及输入属性名称和目标行为名称的两个初始值可能被删除。

Disable Cooperative 行为对话框

目的： 这个对话框 (图 8) 能够联合一个 portlet 从而清除所有的共同程序相关的工件，并使它恢复到非协作 portlet 的状态。

访问这个工具：

1. 右键点击 Project Explorer 中的 portlet 节点。
2. 选择 Disable Cooperative。

清除或者更新的文件：

• WebContent/wsdl/[portletName].wsdl： 删除这个文件。
• WebContent/WEB-INF/portlet.xml： 清除 WSDL 文件的索引和创建的所有初始值。

让我们开始进入这个

步骤 1. 定义数据传输类型

现在您将创建一个只含有一个单向源和一个单向目标 portlet 的简单 JSR 168 Faces portlet 应用软件。在您的源代码中，您将允许您的用户键入一个名称并将这个值显示在目标 portlet 中。

创建一个 portlet 项目

由创建一个新的 JSR 168 Faces Portlet 项目开始：

1. 在 Rational Application Developer V7 中选择 File > New > Project。
2. 选择 Portlet Project 并点击 Next。 (如果被询问是否激活 Portal Development， 点击 OK。)
3. 键入 JSRFacesCooperative 作为 Project 名称。
4. 确保 WebSphere Portal V6.0 已经作为 Target Runtime 被选择，Add project to an EAR 复选框也被选择。
5. 确保 Portlet API 的设置为 JSR 168 Portlet 以及 Portlet type 的设置为 Faces Portlet。
6. 键入 JSRFacesCooperativeSource 作为 Portlet name。
7. 点击 Next，然后点击 Finish。（如果有提示就转向 Web Perspective 。）

现在，添加第二个 portlet 到我们的项目作为目标。

1. 右键点击这个称作 JSRFacesCooperative 的项目并选择 New > Portlet。
2. 在 New Portlet wizard中，将 portlet 的名称设置为 JSRFacesCooperativeTarget。
3. 点击 Next，然后点击 Finish。

激活这个 portlet 来共享数据

现在您可以通过使用 Cooperative Source 向导来激活这个源 portlet 来共享数据。

1. 展开 Project Explorer 中的 Portlet Deployment Descriptor 节点(图 9)。
2. 右键点击 JSRFacesCooperativeSource portlet，选择 Cooperative > Enable this Portlet to Send Data (Source)。

在这个向导的首页（图 10），您应该详细定义您共享的数据类型。

注意： 
您必须详细指定一个 URL 和一个 Java 类型 (屏幕显示的是 URI，而不是 URL)。 两个只在定义相同的 Data Type URL 时才能连接在一起共享数据。

1. 将 Data Type URL 变更为 http://jsrfacescooperative#name。
2. 在这个例子中您仅仅共享了简单的字符串数据，因此您可以将 java.lang.String 保留为 Java™ 类型。但是您可以在这里放置一个更复杂的目标，比如一个 Java bean。

1. 点击 Next。

步骤 2. 执行这个操作过程

这个向导的第二页（图 11），您要详细说明触发这个属性转换的源行为。在 JSR 168 portlet 中，当您在这里详细说明的带有名称和数值的参数出现在这个行为需求中时，属性转换才会被触发。

1. 保留 Action Parameter 的状态不变，但是要将 Action Value 更改为 SendName。

同样在这个页面，您要对这个包含着正从源 portlet 发送的数据的名称和具体位置进行详细说明。当您刚刚具体说明的这个源行为发生后，属性代理就会查找这个位置，检索输出属性，从而使它稍后能够将数据发送到目标 portlet。

1. 将 Request attribute 用作 Location。

提示： 
如果您拉下这个组合框，您将会发现您能够把输出属性存储在几个不同的领域，比如参数或者话路领域。

1. 将 Property Name 更改为 outputName。

1. 点击 Next。

键入标题名称（可选的）

这个向导的下一页（图 12）描述的是输入可选择的标题名称。 配线工具中的标题用作一个简单的名称，以此访问属性和行为名称。这些值将不会显示在用户的 portlet 应用软件中。

1. 使用 Resource Bundle 域中的默认设置。
2. 保留 Property 和 Action 的标题名称， 点击 Next。

这个向导的最后页 (图 13) 展示了配置协作软件的下面的步骤。您可以保存这些文档为将来作为参考。

1. 现在，可以点击 Finish。

您现在已经激活了第一个 portlet 作为您的源。打开 WebContent/wsdl/JSRFacesCooperativeSource.wsdl 文件，您将会发现它增加了您在这个向导中输入的各种条目。同样值得注意的是，在 Project Explorer 中，您的 portlet 图标已经更改，现在您打开它将会看到您刚才定义的行为和数据类型。

插入触发属性转换的 UI 控件

现在您可以使用 Cooperative Source Trigger 来添加一个用户界面 (UI) 到您的 JSP 文件中，创建这个行为，使这些数据能被这个属性代理所用。

1. 打开这个源 portlet JSP 文件， JSRFacesCooperativeSourceView.jsp，然后更改 Place content here 文本为 Enter Name: （包括冒号）。
2. 将 JSF Input 组件从 Palette 拖拽到 JSP 页面， 在建立 Enter Name: 文本后再将它作废。
3. 在 Page Data View 中右键点击，并创建一个新的 Param Scope 变量。称它为 nameParam。
4. 通过将 参数 拖拽到 JSP上的组件，从而将新的 Param Scope 变量绑定到 输入组件中。
5. 转到 Palette 并打开这个 Portlet 抽屉。
6. 选择 Cooperative Source Trigger， 并将它拖到 JSP 上，紧邻着 Input 组件。
7. 当 Insert Cooperative Source Trigger 向导 显示 (图 14)时，选择 JSRFacesCooperativeSource 作为 Source portlet。
8. 拉下 Action Value 组合框，并选择您在 Cooperative Source 向导中定义的行为。
9. 拉下 Property Name 组合框，并选择您在 Cooperative Source 向导中定义的属性名称。
10. 选择仅靠着 Value to Send 字段的 Browse 按钮， 展开这个参数节点，并选择您刚才创建的 nameParam 参数。
11. 点击 OK。

1. 将 UI 类型 作为 Link 保留，点击 Finish。
2. 一个链接将会出现在 JavaServer Page 上，或者 JSP (图 15)。 将这个文本变更为 Send Name，如果您希望的话。

源 portlet 现在已经准备好可以共享数据了。如果您转到这个源视图 Page Designer，您将看到您创建的一个传令线路包含一个单一参数。这个参数保存有您在这个向导中详细说明的 Action Parameter (ACTION_NAME_PARAM) 和 Action Value (SendName)。当用户点击这个链接时，哪些值就会被迁移到一个行为请求，因而就触发了这个属性转换。

1. 现在，您可以右键点击 Source 页面并选择 Edit Page Code。
2. 向下滑动，直到您找到 doCooperativeLinkAction() 程序。您将在这里存储数据，这些数据将会与您在 Cooperative Source 向导中详细说明的 Property Name (outputName) 一起发送到请求领域。

使目标 portlet 能够接收数据

下一步，您要通过使用 Cooperative Target 向导来使目标 portlet 接收数据。

1. 展开 Project Explorer 中的 Portlet Deployment Descriptor 节点(图 16)。
2. 右键点击 JSRFacesCooperativeTarget portlet 并选择 Cooperative > Enable this Portlet to Receive Data (Target)。
3. 拉下 Data Type URI (URL) 组合框，选择与您在这个源 portlet 中相同的数据类型。

重点： 
这些值必须与两个 portlet 之间的属性转换相匹配。

1. 保留 Java type 不变，然后点击 Next。

Faces portlet 选项 有了 Faces portlet，您可以对 JSP 页面本身详细定义目标行为。这意味着这个属性代理将只需询问这个目标 portlet 来重新交付 JSP 页面。 Faces portlet 支持的另一个选项是，将按钮作为这个目标。 如果已经指定一个按钮，然后与这个按钮(通过Action 属性)联合的行为程序就会被调用。Faces portlet 得支持还可以允许这个属性名称直接指向目标 JSP 页面上的一个输入栏。Faces portlet 会自动使用包含在这个属性中的值来设置这个输入栏。这可以与一个按钮一起作为目标行为，因为它允许用户对这个按钮重复使用现存的行为，并会很自然地从这个输入栏中努力获取数值。 第三个选项仅仅只是详细指定一个自定义行为名称，以及处理 portlet 的 processAction() 中的行为。这需要使用一个自定义 portlet 类。注意它必须展开 FacesPortlet。 对于这个练习，您可以使用 JSP 作为目标行为。

1. 紧邻 Action Value (图 17)，点击 Browse ，从这个对话框中选择 JSRFacesCooperativeTargetView.jsp，然后点击OK。
2. 保留 Location 为 Request Param ，更改 Property Name 为 inputName。

注意： 
当这个属性代理对于一个目标 portlet 来说已经是可利用的，它就可以调用这个目标行为，使它在 Property Name 特定的参数中可利用，然后将它置于一个具体的位置。接下来就是 portlet 的职责，重新获得这些在行为处理阶段使用的数据。

1. 点击 Next。
2. 将 Action 标题名称改为更易读的名称，比如 Name Target Action。这将帮助您理解在稍后的配线工具中您要操作哪个行为。
3. 点击 Finish。

现在，您可以在这个目标 JSP 上创建一些 UI 数据来显示引入的数据。

1. 打开目标 JSP， JSRFacesCooperativeTargetView.jsp。
2. 将 Place content here 文本更改为 Display Name: （包括冒号）。
3. 从选项板中选择一个 JSF Output 组件到 JSP 上。
4. 在 Page Data View 中创建一个 Param 领域 变量 (这个属性的位置是根据这向个协作模版导设置来定的)，名称为 inputName (属性的名称是根据这向个协作模版导设置来定的)，然后将它绑定到这个 Output 组件。

回页首

步骤 3. 将您的项目部署到这个 portal 服务器

现在您可以将您的项目部署到 WebSphere Portal 服务器上了。

1. 右键点击您的项目， JSRFacesCooperative，选择 Run As… > Run on Server。
2. 填充必要的信息，点击 Finish。
3. 对于 WebSphere Portal 6.0 的测试细节，选取 Rational Application Developer V7 中的 Help。

当 portlet 页面已经下载到 Web 浏览器，您就可以看到 Figure 18 所显示的内容了。

在您开始传输数据之前，您必须将这些 portlet 配置到一起。

1. 点击左边栏中您的页面名称，选择 Edit Page Layout （图 19）。

1. 然后选择 Wires 键，顺着这个页面的顶端启用这个配线工具 （图 20）。

1. 使用这个组合框使您穿过这个页面，填充可用的值。
2. 当您完成之后，点击 + （加号）按钮，然后选择 Done。这将让您回到您的 portlet。
3. 现在，您可以在 Enter Name 栏中键入（图 21），然后点击这个链接。

您将会看到您在这个源 portlet 中键入的文本现在显示在这个目标 portlet 中。

怎样使用一个命令按钮而不是一个链接

这里描述的应用软件使用了一个 传令线路 来触发这个属性转换，但是它还可能使用一个 命令按钮。这两者之间最大的不同在于行为参数和值传送到行为请求的方式不同。

现在让我们来比较一下使用命令链接的 JSP 源代码和使用命令按钮的源代码。注意，对于一个命令链接，参数 (<f:param>) 是嵌入在子元素（列表 1）中的。当点击这个命令链接时， JavaServer Faces 框架就会将这个参数作为一个请求参数置入这个行为请求中。

            <h:form id="form1" styleClass="form">
            Enter Name: <h:inputText id="text1" styleClass="inputText"
            value="#{param.nameParam}"></h:inputText>
            <h:commandLink id="link1" styleClass="commandLink"
            action="#{pc_JSRFacesCooperativeSourceView.doCooperativeLinkAction}">
            <f:param id="parameter1" name="ACTION_NAME_PARAM" value="SendName"></f:param>
            <h:outputText id="text2" styleClass="outputText" value="Send Name"></h:outputText>
            </h:commandLink>
            </h:form>
            

现在，再看看使用命令按钮的类似代码，更换为（列表 2）。主要区别在于，行为参数是通过使用一个 HTML 隐藏域元素来传递的，而不是在 Faces 参数中。这是因为当它们还是命令按钮的子元素时， JavaServer Faces 框架没有将 Faces 参数（<f:param>）添加到这个行为请求中。

            <h:form id="form1" styleClass="form">
            Enter Name: <h:inputText id="text1" styleClass="inputText"
            value="#{param.nameParam}"></h:inputText>
            <INPUT type="hidden" name="ACTION_NAME_PARAM" value="SendName"> 	<hx:commandExButton type="submit" value="Submit" id="button1"
            styleClass="commandExButton" action="#{pc_JSRFacesCooperativeSourceView.doButton1Action}">
            </hx:commandExButton>
            </h:form>
            

除了这个不同，命令链接与命令按钮的执行方式几乎是一样的。

JSR 168 Basic 和 Struts portlet 与 Faces portlet 有着怎样的区别

Faces、 Basic 和 Struts 协作应用软件的主要区别是它们行为处理的方式，以及数据传递到属性代理的方式。在三个 portlet 类型中，当带有 Cooperative Source 向导中特定名称和值的请求参数出现在行为请求中时，属性转换就会触发。

• 这个名称和值可以使任何字符串，除 JSR 168 Struts portlet 以外，这种类型的参数名称必须为 spf_strutsAction。这是所有 Struts 行为默认的参数名称，不能更改。Struts portlet 使用一个 Struts 行为来触发这个属性转换。当一个 Struts 行为发生以后，它的行为类就会将数据传递给这个属性代理。
• Faces portlet 主要是使用 JSP 中的参数将行为名称和值传递到这个行为请求中。他们然后将使用一个 Faces 行为将数据传递给属性代理。您将在一个贯穿整篇文章的例子中看到这个情况。
• Basic portlet 也是从 JSP 中将行为名称和值传递到这个行为请求中。他们通常使用一个参数 (<portlet:param>，一个行为 URL (<portlet:actionURL>)，或者一个表格中的隐藏域来执行。这些数据然后会使用 portlet 类的 processAction() 程序被传递给属性代理。

您可以通过点击 Next 直到您到达 Next Steps page ，在 Cooperative Source 或者 Cooperative Target 向导中可以看到这些步骤的例子。在那里，您将会看到在 JSP 中触发这个行为的步骤，以及怎样将这些数据传递给属性代理。

参考资料

• 您可以参阅本文在 developerWorks 全球网站上的 英文原文。
  
  
• "IBM Rational Application Developer V7.0 新特性" 这是一篇 IBM developerWorks® 文章（2007 年 2 月），提出对 IBM Rational Application Developer V7.0 新特性的概览，这是开发软件解决方案和应用软件的主要工具。 
  
  
• 浏览 技术书店 寻找关于一些关于技术话题的书籍。 
  
  
• 订阅 developerWorks 时事通讯。时刻关注 developerWorks Rational 最新内容。每隔一周，您将收到关于 Rational 软件交付平台最新技术资源和最佳实践。 
  
  
• 订阅 Rational Edge 电子月刊中文版 ，查找有关有效软件开发背后概念的文章。
  
  
• 时刻关注 developerWorks 技术事件和网络广播。
  
  

• 下载 IBM 产品评估版本，并从 DB2®、 Lotus®、 Rational®、 Tivoli®， 以及 WebSphere® 获得应用开发工具和中间产品。
  
  
• 下载一个 Rational Application Developer的免费试用版。

• 查看 developerWorks blogs 并加入到 developerWorks 社区中去。 
  
  
• Rational Software Architect，Data Architect， Software Modeler， Application Developer 以及 Web Developer 论坛：询问关于 Rational Application Developer 的问题。
  
  

注释:红色部分很重要!没有看清这一点,搞了我整整一天时间!
       一定要注意

作者简介

		Christopher 是 IBM 软件组中 IBM Rational 品牌的一名软件工程师。他主要从事于 Web 开发工具，在这之前他是从事 Rational Application Developer 的 Portlet Development 的一名开发人员。

		Jim 是在 IBM Rational 品牌工作的一名咨询软件工程师。他目前带领开发小组从事 Rational Application Developer 产品中关于 Web Rapid Development Tools 组件研究的工作。在这之前他是 Rational Application Developer 的 Portlet Development Tools 的技术领导。