WebSphere Portal 中的 URL 生成

需要执行以下操作的 JSR 286 Portlet：

• 生成指向另一个门户网站页面的呈示链接（产生页面导航）。
• 有选择地控制目标 portlet 的方式或窗口状态。
• 有选择地控制门户网站状态。
• 有选择地控制目标 portlet 的呈示参数。
• 有选择地控制已生成请求的语言环境。

从 Portal 8.5 CF05 开始，对所有这些用例等使用 WebSphere Portal 定义的公共呈示参数。这些呈示参数使得当前请求上下文的各个方面在 WebSphere Portal 指定的名称空间中作为普通公共呈示参数可用。

要将导航状态值读取为呈示参数：

可以通过普通 JSR286 API renderResponse.getParameter(<parameter qualified name>) 来访问这些特殊公共呈示参数。

其中，<parameter qualified name> 是 NAMESPACE_URI 和某一个呈示参数名称的并置，如以下部分中所定义。例如，http://www.ibm.com/xmlns/prod/websphere/portal/publicparams 选择。

要使用呈示参数来设置导航状态值：

可以通过普通 JSR286 portlet API baseURL.setParameter(<parameter qualified name>, <value>) 来设置

通过使用普通 JSR286 API 来设置这些特定的呈示参数，系统将正确的导航状态设置编码到新 URL 上的导航状态文档中。该设置使得新值对呈示并单击该新 URL 而产生的下一个请求可用。

WebSphere Portal 指定的公共呈示参数的名称空间为 http://www.ibm.com/xmlns/prod/websphere/portal/publicparams（作为 NAMESPACE_URI 可用）。以下项是 WebSphere Portal 支持的特殊公共呈示参数：

• selection (NAME_SELECTION)
• uri (NAME_URI)
• parameters (NAME_PARAMETERS)
• locale (NAME_LOCALE)
• themeTemplate (NAME_THEME_TEMPLATE)
• labelMappings (NAME_LABEL_MAPPINGS)
• screenTemplate (NAME_SCREEN_TEMPLATE)
• themePolicy (NAME_THEME_POLICY)
• solo (NAME_SOLO)
• showTools (NAME_SHOW_TOOLS)
• hiddenContent (NAME_HIDDEN_CONTENT)
• hiddenPages (NAME_HIDDEN_PAGES)
• statePartition (NAME_STATE_PARTITION)
• path-info (NAME_PATH_INFO)
• focus (NAME_FOCUS)
• deviceClass (NAME_DEVICE_CLASS)
• digest (NAME_DIGEST)
• pageMode (NAME_PAGE_MODE)
• editMode (NAME_PAGE_EDIT_MODE)
• infoMode (NAME_PAGE_INFO_MODE)
• helpMode (NAME_PAGE_HELP_MODE)

还存在门户网站 URL 生成便捷 API。此便捷 API 仅支持呈示 URL。使用此 API 无法生成任何状态更改（操作 URL ）。以下项是此 API 中的关键类：

• com.ibm.portal.portlet.service.url.PortalURLGenerationService
• com.ibm.portal.portlet.service.url.PortalURLWriter

依据 com.ibm.portal.portlet.service.url 包的 javadoc，程序员：

1. 通过 JNDI 查找来获取 PortletServiceHome 的实例。
2. 在该 home 接口上，调用 getPortletService(PortalURLGenerationService.class)。
3. 在该服务上，调用 getPortalURLWriter(request, response)
4. 使用 PortalURLWriter 对象上的方法来创建和操作呈示 URL。

存在针对 URL 生成便捷 API 的同等 JSP 标记集。

<%@ taglib uri="http://www.ibm.com/xmlns/prod/websphere/portal/v8/portlet/ibm-portlet-ext" prefix="portlet-ext" %> 

有关更多信息，请参阅标准 portlet 的 JSP 标记。使用便捷 API 标记创建呈示 URL 的示例为 <portlet-ext:portalRenderURL>。

又称为“友好 URL 名称”的“友好 URL”是门户网站页面的人类可读名称。它被设置为页面属性，每一页最多可以有一个“友好 URL”。

要使用“友好 URL”API，需获取 FriendlyURLFactory 实例。根据您编写的代码的类型，可通过以下两种方式之一来获取 FriendlyURLFactory 实例：

如果您正在编写 portlet：

• 从 com.ibm.portal.resolver.friendly.service.PortletFriendlySelectionServiceHome 类开始。您需要通过两步获取此类的实例：
  1. 使用常量 PortletFriendlySelectionServiceHome.JNDI_NAME 来执行 JNDI 查找。此 JNDI 查找会返回 PortletServiceHome 的实例。
  2. 在 PortletServiceHome 对象上，调用 getPortletService(PortletFriendlySelectionServiceHome.class)。调用会返回 PortletFriendlySelectionServiceHome 实例。
• 为了提高效率，请在 portlet 的 init(PortletConfig) 方法中执行 JNDI 查找并调用 getPortletService，然后保存将重复使用的 PortletFriendlySelectionsServiceHome 实例。没有必要对每个请求都执行此调用。
• 在调用每个请求（如 portlet 的 doView(RenderRequest,RenderResponse) 方法）时，请使用已保存的 PortletFriendlySelectionServiceHome 来调用 getPortletFriendlySelectionService(request,response)。调用会返回 PortletFriendlySelectionService 实例。
  注： 必须在此实例超出范围前对其调用 dispose() 来进行处理。
• 在返回的 PortletFriendlySelectionService 实例上，调用 getURLFactory()。

如果您正在编写主题代码：

• 从 com.ibm.portal.resolver.friendly.service.PortalFriendlySelectionServiceHome 类开始。使用常量 PortalFriendlySelectionServiceHome.JNDI_NAME 来执行 JNDI 查找。 此查找会返回 PortalFriendlySelectionServiceHome 的实例。
• 为了提高效率，请在您的类的构造方法或其他初始化方法中执行 JNDI 查找，然后保存将重复使用的 PortalFriendlySelectionServiceHome 实例。没有必要对每个请求都执行此调用。
• 在调用每个请求时，请使用已保存的 PortalFriendlySelectionServiceHome 来调用 getPortalFriendlySelectionsService(HttpServletRequest,HttpServletResponse)。 调用会返回 PortalFriendlySelectionService 实例。
  注： 必须在此实例超出范围前对其调用 dispose() 来进行处理。
• 在返回的 PortalFriendlySelectionService 实例上，调用 getURLFactory()。

以下部分描述了如何使用虚 URL API 来获取可用于呈示虚 URL 链接的 VanityURLNode。根据您正在开发的代码包的类型，使用三种不同的方法之一来访问和使用虚 URL API。 必需的接口文档位于 WebSphere Portal SPI javadoc 中。

如果您正在编写 portlet：

• 找到 com.ibm.portal.portlet.service.model 包。
• 从 VanityURLModelProvider 接口开始。您需要获取类的实例，该实例通过两步实现此接口：
  1. 使用名称常量 VanityURLModelProvider.JNDI_NAME，通过 JNDI 查找来获取 PortletServiceHome 的实例。
  2. 在该 PortletServiceHome 对象上，调用 getPortletService(VanityURLModelProvider.class)。
• 在 portlet 的 getPortletService 方法中执行 JNDI 查找并调用 init()。将返回的 VanityURLModelProvider 实例保存在 portlet 类内的静态字段中。可以在各个请求中复用此提供程序实例。
• 对于每个请求，例如，在 portlet 的 doView() 方法的调用中，通过传递当前的 portlet 请求和响应，在已保存的 VanityURLModelProvider 实例上调用 getVanityURLModel。不能在各个请求中复用模型。
• 在 VanityURLModel 对象上，调用 getLocator()。
• 在 VanityURLModelLocator 上，您可以调用任何 findBy 方法，这些方法将返回单个 VanityURLNode 或 IterableListModel<VanityURLNode> 列表。

如果您正在编写主题代码：

• 找到 com.ibm.portal.model 包。
  注： 此指令集中的许多类名与虚 URL API 的数据源用法的类名相同，但包名不同。
• 获取类的实例，该实例通过两步实现 VanityURLModelProvider：
  1. 使用名称常量 VanityURLModelHome.JNDI_NAME，通过 JNDI 查找来获取 VanityURLModelHome 的实例。请参阅 com.ibm.portal.model.VanityURLModelHome javadoc，以获取示例代码。
  2. 在该 VanityURLModelHome 对象上，调用 getVanityURLModelProvider()。
• 在您的类的构造方法或 init() 方法中，执行 JNDI 查找并调用 getVanityURLModelProvider()。将返回的 VanityURLModelProvider 实例保存在类内的静态字段中。 可以在各个请求中复用此提供程序实例。
• 对于每个请求，通过传递当前的 servlet 请求和响应，在已保存的 VanityURLModelProvider 实例上调用 getVanityURLModel。不能在各个请求中复用模型。
• 在 VanityURLModel 对象上，调用 getLocator()。
• 在 VanityURLModelLocator 上，您可以调用任何 findBy 方法，这些方法将返回单个 VanityURLNode 或 IterableListModel<VanityURLNode> 列表。

如果您正在编写数据源：

• 找到 com.ibm.portal.cor.service 包。
  注： 此指令集中的许多类名与虚 URL API 的主题代码用法的类名相同，但包名不同。
• 获取类的实例，该实例通过两步实现 VanityURLModelProvider：
  1. 使用名称常量 VanityURLModelHome.JNDI_NAME，通过 JNDI 查找来获取 VanityURLModelHome 的实例。请参阅 com.ibm.portal.cor.service.VanityURLModelHome javadoc，以获取示例代码。
  2. 在该 VanityURLModelHome 对象上，调用 getVanityURLModelProvider()。
• 在您的类的构造方法或 init 方法中，执行 JNDI 查找并调用 getVanityURLModelProvider()，然后将返回的 VanityURLModelProvider 实例保存在类内的静态字段中。 可以在各个请求中复用此提供程序实例。
• 在“数据源”的每个请求方法中，调用 modelProvider.getVanityURLModel(com.ibm.content.operations.registry.api.Context)。

  针对“数据源”的编程详细信息：在大多数情况下，由专用工厂分配“数据源”。向解析器框架注册该工厂，以处理特定 URI 的请求。收到该 URI 的请求后，解析器框架会启动该工厂，并且会向该工厂传递 com.ibm.content.operations.registry.api.Context 对象。确保了解此 COR Context 对象与 JNDI 查找所使用 javax.naming.Context 类之间的差异。该工厂将分配新的“数据源”实例（或者可能会从池中检索一个现有实例），并通过传递 COR Context 对象，在“数据源”上调用 reset()。必须将该对象以及 reset() 的其他参数保存在“数据源”内的实例字段中。可以在随后的方法调用中进行使用，直至调用 dispose() 或重新调用 reset()。调用 getVanityURLModel(com.ibm.content.operations.registry.api.Context) 时，请使用 COR Context 对象。

• 在 VanityURLModel 对象上，调用 getLocator()。
• 在 VanityURLModelLocator 上，您可以调用任何 findBy 方法，这些方法将返回单个 VanityURLNode 或 IterableListModel<VanityURLNode> 列表。

在您通过任何适当的方式具有 VanityURLNode 实例后，可以调用该接口的各种方法来构建虚 URL 的呈示表示：

• VanityURLnode.isSecure() 告知目标协议是 http 还是 https。
• VanityURLnode.isProtected() 告知目标 URL 映射到 /portal 还是 /myportal。
• VanityURLnode.getHost() 将返回与此虚 URL 关联的主机名。
• VanityURLnode.getPort() 将返回与此虚 URL 关联的端口号。
• VanityURLnode.getVpld() 将返回针对此虚 URL 的虚拟门户网站 OID。
• VanityURLnode.getPath() 将返回针对此虚 URL 的路径字符串。该路径字符串被认为是虚 URL 字符串。

如果您正在编写代码，旨在创建、更新或删除虚 URL，而非读取和呈示虚 URL，那么请使用以下 API：

• 找到 com.ibm.portal.model.controller 包。
• 您需要获取类的实例，该实例使用名称常量 VanityURLModelControllerHome.JNDI_Name，通过 JNDI 查找来实现 VanityURLModelControllerHome。请参阅 com.ibm.portal.model.controller.VanityURLModelControllerHome javadoc，以获取示例代码。
• 在该 VanityURLModelControllerHome 对象上，调用 getVanityURLModelControllerProvider()。
• 在您的类的构造方法或 init 方法中，执行 JNDI 查找并调用 getVanityURLModelControllerProvider()，然后将返回的 VanityURLModelControllerProvider 实例保存在类内的静态字段中。可以在各个请求中复用此提供程序实例。
• 您可能还需要使用与编写主题代码中描述的相同代码来获取 VanityURLModelProvider。
• 在每个请求方法中，
  • 在 VanityURLModelProvider 上，调用 getVanityURLModel(request,response)。
  • 在 VanityURLModelControllerProvider 对象上，通过传递从调用 getVanityURLModel 返回的模型来调用 createVanityURLModelController(model)。
• 用于创建新的虚 URL 和设置其属性的后续调用记录在 VanityURLModelController 和 ModifiableVanityURLNode 的 javadoc 中。

要使用部分内容 URL，请获取 com.ibm.portal.resolver.acessors.url.PocURLFactory 的实例。与其他 URL API 极为类似，获取 URLFactory 的实例的代码取决于您是否正在编写 portlet 或主题代码，或者是否已在解析器框架内运行代码。

如果您正在编写 portlet：

• 在 Portal javadoc 中，找到 com.ibm.portal.resolver.servicer.service 包。
• 通过两步获取 PortletPocServiceHome 实例：
  1. 使用名称常量 PortletPocServiceHome.JNDI_NAME，为 PorletServiceHome 实例执行 JNDI 查找。请参阅 PortletPocServiceHome 的 javadoc，以获取样本代码。
  2. 在返回的 PortletServiceHome 对象上，调用 getPortletService(PortletPocServiceHome.class)。
• 在 portlet 的 init(PortletContig) 方法中，执行 JNDI 查找并调用 getPortletService，然后将生成的 PortletPocServiceHome 实例保存在类实例变量中。没有必要对 portlet 服务的每个请求都重新执行此调用。
• 在每个请求方法（如 render(RenderRequest,RenderResponse)）中，根据所实施的特定方法以及所传递的请求和响应的类型来调用适当的 PortletPocServiceHome.getPortletPocService() 方法。针对“操作”、“事件”、“呈示”、“资源”以及普通的 PortletRequest 和 PortletResponse，此方法有多个版本。
  注： 必须在返回的服务实例超出范围前对其调用 dispose()。
• 在 PortletPocService 或适当的子类上，调用 getURLFactory()。

如果您正在编写主题代码：

• 在 Portal javadoc 中，找到 com.ibm.portal.resolver.service 包。
• 使用名称常量 PortalPocServiceHome.JNDI_NAME，为 PortalPocServiceHome 执行 JNDI 查找。
• 将生成的 PortalPocServiceHome 实例保存在类实例字段中。没有必要对每个请求都执行 JNDI 查找。
• 在您的类的每个请求方法中，在已保存的 PortalPocServiceHome 实例上，通过传递 HttpServletRequest 和 HttpServletResponse 来调用 getPortalPocService。
  注： 必须在返回的服务实例超出范围前对其调用 dispose()。
• 在生成的 PortalPocService 实例上，调用 getURLFactory()。

如果您正在编写作为数据源或解析服务运行的代码：

• 在 Portal javadoc 中，找到 com.ibm.portal.resolver.service 包。
• 使用名称常量 CorPocServiceHome.JNDI_NAME，为 CorPocServiceHome 执行 JNDI 查找。
• 将生成的 CorPocServiceHome 实例保存在类实例字段中。没有必要对每个请求都执行 JNDI 查找。
• 在您的类的每个请求方法中，在已保存的 CorPocServiceHome 实例上，调用 getCorPocService(com.ibm.content.operations. registry.api.Context)。
  注： 必须在返回的服务实例超出范围前对其调用 dispose()。

  针对“数据源”的编程详细信息：在大多数情况下，由专用工厂分配“数据源”。向解析器框架注册该工厂，以处理特定 URI 的请求。收到该 URI 的请求后，解析器框架会启动该工厂，并且会向该工厂传递 com.ibm.content.operations.registry.api.Context 对象。确保了解此 COR Context 对象与 JNDI 查找所使用 javax.naming.Context 类之间的差异。该工厂将分配新的“数据源”实例（或者可能会从池中检索一个现有实例），并通过传递 COR Context 对象，在“数据源”上调用 reset()。必须将该对象以及 reset() 的其他参数保存在“数据源”内的实例字段中。可以在随后的方法调用中进行使用，直至调用 dispose() 或重新调用 reset()。调用 getCorPocService (com.ibm.content.operations.registry.api.Context) 时，请使用 COR Context 对象。

• 在生成的 CorPocService 实例上，调用 getURLFactory()。

在获取 PocURLFactory 后：

• 调用某一项 newURL 方法，将期望类型的 PocURL 实例化。
• 在生成的 PocURL 实例上，调用 setXXX 方法来定义 URL 属性。
• 调用 writeDispose() 来让 URL 指向响应并处理 PocURL 实例。必须从 writeDispose 方法的响应参数获取供其使用的“写程序”实例。