Portlet 参数选项

以下文字转载自:http://dev2dev.bea.com.cn/techdoc/200403134.html

Portlet 参数选项提供了将应用程序数据与 portlet 关联到一起的首选方式。 这一特性是基于其用途来个性化portlet的关键。在本文中，我们将详细讲述 portlet 参数选项。

Portlet 参数选项提供了将应用程序数据与 portlet 关联到一起的首选方式。 这一特性是基于其用途来个性化portlet的关键。在本文中，我们将详细讲述 portlet 参数选项。

·   什么是 portlet 参数选项？

指定参数选项

修改参数选项

参数选项的 JSP 标签

参数选项－实用注意事项

·   定义 Portlet： 每个 portlet 都有一个用于显示数据/内容的 UI，和一段用于处理用户交互的代码。

使用 Portlet： 一旦创建了portlet ，门户管理员和（或）终端用户就可以在各种门户和桌面的页面中多次添加相同的 portlet 。然后，门户管理员和（或）终端用户可以自定义 portlet 的各种属性（例如，portlet 的标题）。在这种情况下，门户管理员和（或）终端用户要处理 portlet 的特定用途。 就是说，在此过程中，要创建 portlet 实例并定制每一个实例。

正如您从中看出的，portlet 比其他 Web 组件（如 servlet、JSP 或甚至 Java Page Flow）更易重复使用。一旦创建了一个 portlet ，可以将它多次实例化。

由于可为portlet 创建多个实例，我们自然期望每个实例的行为不同，但却使用相同的代码和 UI。 例如，请看一个用于显示“股票投资组合”的常见的 portlet。 指定一个股票代号的列表，该 portlet 定期从股票报价网站检索报价，并在 portlet 窗口中显示这些报价。 通过让每个用户更改股票代号的列表和重新加载报价数据的时间间隔，可以让每个用户自定义这个 portlet。

但是，portlet 需要能够持久存储股票代号的列表和检索的时间间隔，并在用户自定义这些值时更新它们。 特别是，必须持久管理以下数据：

默认值： portlet 可以指定股票代号的默认列表和合理的检索时间间隔。无论用户是谁，这些值都可用于 portlet 的所有用途。用户甚至可以是匿名的。

自定义的值： 用户更新特定 portlet 实例的值时，需要 portlet 也能够存储这些值。 注意，portlet 还应该将这一数据定义在某个实例内，这样该自定义才不会影响 portlet 的其他实例。

Portlet 参数选项提供了将这些数据与 portlet 关联起来的一个框架。除了具有建多个 portlet 实例的能力之外，WebLogic Portal 8.1 还允许用户为 portlet 指定参数选项。

在本文中，我们将分析以下内容：

·   如何关联 portlet 参数选项和 portlet？

·   注意事项

什么是 Portlet 参数选项？

portlet 参数选项是指定的字符串数据。 例如，股票投资组合 portlet 可能具有以下 portlet 参数选项：

并且值为“BEAS, MSFT”的参数选项

并且值为“600” (以秒计算)的参数选项。

可以将多个这种参数选项与 portlet 关联。 portlet 参数选项具有以下属性：

名称： 每个参数选项都有一个名称。 对于特定 portlet，任何两个参数选项不能有相同的名称。

描述： 参数选项的简要描述。

值： 每个参数选项可以有一个（单值参数选项）或多个值（多值参数选项）。每个值都是 java.lang.String 类型的。

只读： 用一个布尔值表示特定参数选项的值是否可以被 portlet 更改。

WebLogic Portal 8.1 提供以下特性来管理 portlet 参数选项：

在开发时指定 portlet 参数选项： 构建 portlet 时，可为每个 portlet的参数选项指定名称和默认值。 默认情况下，从此 portlet 派生出的所有 portlet 实例将使用开发时指定的值。

让管理员修改 portlet 参数选项： WebLogic Portal 8.1 允许门户管理员修改特定实例的参数选项。

让 portlet 在请求时访问和修改参数选项： 请求时，portlet 可以通过 javax.portlet.PortletPreferences 对象使用程序来访问和更新参数选项。 可以为 portlet 创建编辑页，以便让用户更新参数选项，或更新作为部分普通 portlet 应用程序流程的参数选项。

为 Portlet 指定参数选项

参数选项与 portlet 的关联步骤视构建的 portlet 类型而定。 如果使用 Java Portlet API (参见本文结尾的参考部分)，请遵照 Java Portlet 规范中指定的步骤。 对于其他类型的 portlet，如那些使用 Java Page Flow、Struts 或 JSP 的portlet，WebLogic Workshop 将会帮助您把参数选项添加到 portlet。

WebLogic Portal 还允许您通过Portal管理工具创建新的参数选项。 但是，由于 portlet 开发人员更易注意 portlet 是如何使用 portlet 参数选项的，所以在开发时创建 portlet 参数选项更合适。

为 Java Portlet 指定参数选项
对于使用 Java Portlet API 的 portlet，可以在 portlet 部署描述符中指定参数选项。 对于 web 应用程序中的所有 portlet，部署描述符是portlet.xml，它位于 web 应用程序的目录WEB-INF中。 下面是一个示例。

    <portlet>

  <description>

      This portlet displays a stock portfolio.</description>

  <portlet-name>portfolioPortlet</portlet-name>

  <portlet-class>portlets.stock.PortfolioPortlet </portlet-class>

  <supports>

      <mime-type>text/html</mime-type>

      <portlet-mode>edit</portlet-mode>

  </supports>

  <portlet-info>

      <title>My Portfolio</title>

  </portlet-info>

  <portlet-preferences>

      <preference>

    <name>stockSymbols</name>

    <value>BEAS, MSFT</value>

      </preference>

      <preference>

    <name>refreshInterval</name>

    <value>600</value>

      </preference>

  </portlet-preferences>

    </portlet>

这个代码片断使用两个参数选项部署股票投资组合 portlet： 一个名为 BEAS, MSFT, 的参数选项，另一个参数选项是 refreshInterval 且值为 600。不用为 以粗体显示的值元素)。 

    <portlet>

  <description>

      This portlet displays a stock portfolio.

  </description>

  <portlet-name>portfolioPortlet</portlet-name>

  <portlet-class>portlets.stock.PortfolioPortlet </portlet-class>

  <supports>

      <mime-type>text/html</mime-type>

      <portlet-mode>edit</portlet-mode>

  </supports>

  <portlet-info>

      <title>My Portfolio</title>

  </portlet-info>

  <portlet-preferences>

      <preference>

    <name>stockSymbols</name>

    <value>BEAS</value>

          <value>MSFT</value>

      </preference>

      <preference>

    <name>refreshInterval</name>

    <value>600</value>

      </preference>

  </portlet-preferences>

    </portlet>

如果不允许 portlets 使用程序来更新任何给定参数选项，可以将参数选项标记为只读。 例如，如果要防止 portlets 更改

    <portlet>

  <description>

      This portlet displays a stock portfolio.

  </description>

  <portlet-name>portfolioPortlet

  <portlet-class>portlets.stock.PortfolioPortlet

  <supports>

      <mime-type>text/html</mime-type>

      <portlet-mode>edit</portlet-mode>

  </supports>

  <portlet-info>

      <title>My Portfolio</title>

  </portlet-info>

  <portlet-preferences>

      <preference>

    <name>stockSymbols</name>

    <value>BEAS</value>

    <value>MSFT</value>

      </preference>

      <preference>

    <name>refreshInterval</name>

    <value>600</value>

    <read-only>true</read-only>

      </preference>

  </portlet-preferences>

    </portlet>

注意，通过将参数选项标记为只读，只能防止 portlet 在请求时更改当前值。 门户管理员始终可以更改参数选项的值。

为其他类型的 Portlets 指定参数选项
如果构建其他类型的 portlet (如那些使用 Java Page Flow、或 Strut、或简单 JSP 的portlet)，WebLogic Workshop 可以帮助您添加参数选项。

以下步骤显示了如何给portlet添加参数选项。 这些步骤上标记有 [1]、[2] 和 [3]。

步骤 1： 将“New Preference”控件拖到 portlet 窗口中。

步骤 2： 通过展开“Portlet Preferences”选项卡选择参数选项。

步骤 3： 在Property Editor中更新参数选项的属性。

要为参数选项指定多个值，用相同的名称创建多个参数选项即可。 要将参数选项标记为只读， 可将Modifiable属性标记为false。

使用参数选项 API 访问或修改参数选项

在请求时，对于特定的 portlet， portlet 参数选项可表示成 javax.portlet.PortletPreferences 接口的实例。 这个接口是Java Portlet API的组成部分。 该接口指定了访问和修改 portlet 参数选项的方法。

获取参数选项： portlet 可以使用以下方法访问它的参数选项。

String getValue(String name、String default)	使用该方法获取参数选项的第一个值。
String[] getValues(String name, String[] defaults)	使用该方法获取参数选项的所有值。
boolean isReadOnly(String name)	使用该方法确认是否一个特定的参数选项是只读的。
Enumeration getNames()	使用该方法获取一个所有参数选项名称的目录。
Map getMap()	使用该方法获取参数选项的镜像。 此镜像中的键是所有参数选项的名称，其值与getValues(String name, String[] defaults)返回的值相同。

设置参数选项： portlet 可以使用以下方法更改参数选项的值。

void setValue(String name, String value)	使用该方法设置参数选项的值。
void setValues(String name, String[] values)	使用该方法为参数选项设置多个值。
void store()	使用该方法提交对 portlet 参数选项所作的更改。
void reset(String name)	使用该方法将参数选项的值重新设置为默认值，或者在没有默认值时将参数选项删除。

通过调用 setValue()、setValues() 和 reset() 方法更改参数选项后，必须调用 store() 明确地将这些更改保存为永久的。 否则，更改将不是永久的。

为 Java Portlet 获取或设置 Portlet 参数选项
对于使用 Java Portlet API 编写的 portlet，可以从传入 portlet 的请求——processAction() 方法内的 javax.portlet.RenderRequest 或 render() 方法内的 javax.portlet.ActionRequest获得 doEdit() 方法中。

<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet"%>

<%@ page import="javax.portlet.PortletPreferences" %>

<portlet:defineObjects/>

<%

   PortletPreferences prefs = renderRequest.getPreferences();

   String refreshInterval = prefs.getValue("refreshInterval", "600");

   String symbols = prefs.getValue("stockSymbols", "BEAS, MSFT");

%>

<form method="POST" action="">

   <table>

     <tr>

<td>Symbols</td><td><input name="symbols" value="<%=symbols>"/></td>

     </tr>

     <tr>

<td>Refresh Interval</td><td><input name="refreshInterval"

      value="<%=refreshInterval>"/></td>

     </tr>

     <tr>

<td></td>

<td><input type="submit" value="Submit"/></td>

     </tr>

   </table>

 </form>

portlet 在它的processAction() 方法中更新这些参数选项。

public class PortfolioPortlet extends GenericPortlet  {

{

    public void doEdit(RenderRequest renderRequest, RenderResponse renderResponse)

  throws IOException, PortletException 

    {

...

    }

    public void processAction(ActionRequest actionRequest, ActionResponse actionResponse)

  throws PortletException

    {

  String refreshInterval = actionRequest.getParameter(“refreshInterval”);

  String symbols = actionRequest.getParameter(“stockSymbols”);

  PortletPreferences prefs = actionRequest.getPreferences();

  prefs.setValue(“refreshInterval”, refreshInterval);

  prefs.setValue(“stockSymbols”, symbols);

  try {

      prefs.store();

  }

  catch(SecurityException se) {

      // Thrown when the user does not have enough privileges to store preferences.

      // Make sure that the user logged into the portal.

      ...

  }

  catch(catch(IOException ioe) {

      // There is an error storing preferences

      ...   

  }

    }

}

在 processAction() 中，此 portlet 使用 javax.portlet.ActionRequest 对象获取参数选项。

为其他 Portlet 获取/设置 Portlet 参数选项
也可以从其他类型的 Portlet 访问和更新 portlet 参数选项。 主要的不同是获取 javax.portlet.PortletPreferences 对象的实例的方法。

提交阶段： 在 portlet 的提交阶段 (例如，在与 Page Flow 关联的 JSP 中，或在与 portlet 关联的备份文件的 preRender() 方法中)，portlet 可以使用 com.bea.netuix.servlets.controls.portlet.PorteltPresentationContext 获取 portlet 参数选项。

操作阶段： 在 portlet 的操作阶段 (例如，在 Page Flow 操作中，或在与 portlet 关联的备份文件的 handlePostbackData() 方法中)，portlets 可以使用 com.bea.netuix.servlets.controls.portlet.PortletBackingContext 获取 portlet 参数选项。

这些类都提供了方法 getPreferences()，它接受 javax.portlet.PortletPreferences 类型的对象。

用于获取 Portlet 参数选项的 JSP 标签

WebLogic Portal 8.1 提供了用于访问 portlet 参数选项的 JSP 标签库。 这个标签库包括以下 JSP 标签：

getPreference	使用该标签获取 portlet 参数选项的值。
getPreferences	使用该标签获取 portlet 参数选项的所有值。 该标签还可编辑多个值以便用分隔符分开输出。
forEachPreference	使用该标签可从头到尾重复 portlet 的所有参数选项。可以将其他标签 (getPreference,、getPreferences、 ifModifiable 等) 嵌套在该标签中。
ifModifible	如果指定的 portlet 参数选项不为只读，使用该标签包括该标签的正文。
其他	如果指定的 portlet 参数选项为只读，将该标签与 ifModifiable 标签一起使用以包括该标签的正文。

有关这些标签的更多信息，请在 http://edocs.bea.com/workshop/docs81/doc/en/portal/taglib/JspWlpOverview.html?skipReload=true#portlet 上参阅有关这些标签的 WLW 文档。

Portlet 参数选项 – 实用注意事项

允许用户存储 Portlet 参数选项
使用 Portlet 参数选项 API 和 JSP 标签，可以构建 UI以允许门户用户查看和更新 portlet 参数选项。但是，要允许用户成功更新参数选项，必须满足以下条件：

必须通过桌面访问 Portlet： 必须通过将要更新的桌面访问 portlet，以设置 portlet 参数选项。 从 .portal 文件访问 Portlets 不能存储参数选项。 如果通过 .portal 文件访问 portlet，portlet 将遇到 java.lang.UnsupportedOperationException。

用户必须通过验证： 访问 portlet 的用户必须通过验证。如果用户是匿名的，portlet 将遇到 java.lang.SecurityException。

注意，无论用户是否为匿名，或是否通过 .portal 文件访问 portlet，portlet 始终可以获得 portlet 参数选项。

存储任意数据作为参数选项
要尝试存储任意应用程序数据作为 portlet 参数选项。 例如，考虑一个允许用户在服务器上加载并存储文档的 portlet。 我们是否可以将那些文档存储为 portlet 参数选项？

回答是否定的。portlet 参数选项的用途是为 portlet 实例关联一些属性的设定，而无需考虑任何实现特定的 portlet 实例 ID。 这些属性可帮助自定义 portlet 的行为。 portlet 参数选项的基本实现不是为存储任意应用程序数据设计的。

另一种可选方案也很简单。以下步骤概述了这个过程：

设置：

该参数选项将作为 portlet 应用程序数据的主键。 为该参数选项指派默认值。

·   在 portlet 中：

例如，使用序列号生成器)，并设置它为参数选项的值，然后存储参数选项。

o  现在使用参数选项的值作为主键来存储应用程序数据。

这个步骤将确保应用程序数据始终在 portlet 实例范围内。

您可能想知道是否可以通过直接存储应用程序数据，而不是 portlet 实例 ID 解决相同的问题。现在让我们分析这个方法。

使用实例 ID 代替参数选项
门户框架通过在内部生成实例 ID 来维护实例标识。 Portlet 可以通过 com.bea.netuix.servlets.controls.portlet.PorteltPresentationContext 和com.bea.netuix.servlets.controls.portlet.PorteltBackingContext 上的 getInstanceId() 方法访问其实例 ID。

为什么不在数据库中直接存储这样的数据，而是它们的实例 ID？ 以下原因导致这个方法无效。

首先，门户框架生成了实例 ID，而portlets 没有控制何时及如何生成哪些实例 ID。 其次，无需 portlet 知识就可随时更改实例 ID。 例如，用户/管理员通过访问者/管理工具自定义桌面时，框架可以创建新实例或更改 portlet 的实例 ID。 实例 ID 更改后，portlet 将不能从数据库加载数据。主键已经更改，而 portlet 并不能察觉！

而用以上描述的参数选项机制是可以避免这个问题的。

更多参考资料

1. 下载 WebLogic Platform 的最新版本。 检验 samplePortal 和 tutorialPortal Web 应用程序以查找有关 portlet 参数选项的示例。

2. 有关 Java Portlet API 和 API 文档的信息，请参考 http://jcp.org/aboutJava/communityprocess/final/jsr168/index.html。 Java Portlet API 也同样指定了 portlet 参数选项。

3. 有关 WebLogic Portal API 文档的信息，请参考 http://edocs.bea.com/wlp/docs81/index.html。

·   什么是 portlet 参数选项？

指定参数选项

修改参数选项

参数选项的 JSP 标签

参数选项－实用注意事项

·   定义 Portlet： 每个 portlet 都有一个用于显示数据/内容的 UI，和一段用于处理用户交互的代码。

使用 Portlet： 一旦创建了portlet ，门户管理员和（或）终端用户就可以在各种门户和桌面的页面中多次添加相同的 portlet 。然后，门户管理员和（或）终端用户可以自定义 portlet 的各种属性（例如，portlet 的标题）。在这种情况下，门户管理员和（或）终端用户要处理 portlet 的特定用途。 就是说，在此过程中，要创建 portlet 实例并定制每一个实例。

正如您从中看出的，portlet 比其他 Web 组件（如 servlet、JSP