JSR168 PORLET标准手册汉化整理

JSR168 PORLET标准手册汉化整理

本规范汉化资源搜集整理于网上并由我作了些修改和添加，主要为适应大陆的语辞、用语及其他未译之处。

由于本人于水平有限，如有错误，请各位高手指正；若有高见，希望不吝言辞，同为中国开源作项献。

特此严重感谢翻译此规范的原译者：

第一、第二章节台湾省Jini

第三章节上海市风之舞

第四章~最后章节台湾省koji lin

许多大型企业的网站, 渐渐采用了portal server 作为开发的基础. 至于什么是portal 呢, 中文翻译为"门户网站"。有人可能想.. 天杀的.. 门户网站不是就像yahoo, pchome, yam 等等。不过, 我们现在讨论的portal server, 不是那么地简单, 基本上yahoo, pchome, yam 那些只能称为搜索引擎的门户网站。

如果你从来沒有用过portal server 或是似懂非懂.. 大家可以连结到MyNetscape或MyYahoo去注册一个帐号。因为MyNetscape 的样式比较好看, 所以我接下来就以MyNetscape 为介绍的范例。

如果你第一次接触到portal，你会惊讶的发现... 哇.. 为何一个网站里面充满了这么多小窗口. 我们称这些小窗口叫做"portlet"，而且每个小窗口都存在着独立的信息与内容，可以放到最大化，缩小，还原，关闭等等。当你登陆之后，可以选择及调整自己portlet 的配置，也可以设置自己喜爱的风格与样式，更可以设置每个portlet 的资料配置。

这种以客户为上帝的系统，就是我们将要介绍的portal。

Portal 的组成可以分为三部份 (1) Portal Server (2) Portlet Container (3) Portlet

1)Portal Server 的定义是

一个 Portal（门户网站）就是指一个 Web-based 的系统，通常都会提供个人化设置、单一登陆、以及由各种不同来源或不同网站取得各式各样的信息，并且将这些信息放在网页之中组合而成的呈现平台，门户网站会有精巧的个人化设置去提供定制的网页，当不同等级的使用者来浏览该页面将获得不同的信息内容。

2) Portlet Container 的定义是

portlet container 是提供 portlets 执行的环境，包含了许多 portlets 并且管理他们的生命周期，他也

求传递给存在 container 的 portlet 执行。portlet container 没有义务去组合 portlets 产生的信息內容，这个工作必须由 portal 来处理。portal 和 portlet container 可以放在一起视为同一个系统的组件，或者分开成为两个独立的组件。

一个 Portlet 是以 Java 技术为技术的 Web 组件，由 Portlet Container 所管理，专门处理客户的request 以及产生各种动态的信息内容。Portlets 为可插式 ( pluggable ) 的客户界面组件，提供呈现层成为一个信息系统。

这些由 portlet 产生的内容也被称为片段 (fragment)，而片段是具有一些规则的Markup( HTML、XHTML、WML )，而且可以和其他的片段组合而成一个复杂的文件。而 Portlet 中的内容正常来说是与其他 Portlet 的内容聚合而成为一个 Portal 网页。而 Portlet 的生命周期是被 Portlet Container 所管理控制的。

客户端和 portlets 的互动是由 portal 通过典型的 request/response 方式实现，正常来说，客户会和portlets 所产生的内容互动，举例来说，根据下一步的连接或者是确认送出的表单，结果 portal 将会接收到portlet 的动作，将这个处理状况转向到目标 portlet。这些 portlet 内容的产生可能会因为不同的使用者而有不同的变化，完全是根据客户对于这个 portlet 的设置。

Portlet 和 Servlet 算是兄弟有那么一点点相似却又有那么一点点不同，因为 Servlet 和 Portlet 不尽然相同，所以研究小組決定将 portlets 定义成为一个新的组件，因此定义了 portlets 一个新的并且明确的界面与行为。为了尽可能与现有的 servlet 结合达到重复使用的目的，portlet 的规范利用了 servlet 的规范，许多观念都很相似的，结合 portlets、servlets 及 jsp 在同一个网站系统中，我们称为 portlet application 。在同一个 portlet application 中，他们将分享同一个 classloader，context 及 session。

1)Portlet 和 Servlet 的相似之处

@ portlets 也是 Java 技术的 web 组件

@ portlets 也是有特定的 container 在管理

@ portlets 可以动态产生各种内容

@ portlets 的生命周期由 container 所管理

@ portlets 和客户端的互动是通过 request/response 的机制

2)Portlet 和 Servlet 也有一些不同

@ portlets 只产生 markup 信息片段，不是完整的网页文件。而 Portal 会将所有的 Portlet markup 信息片段放到一个完整的 Portal 网页。

@ portlets 不会和 URL 有直接的关系

@ 客户端必须通过 portal 系统才能和 portlets 互动

@ portlets 默认定义 portlet modes 及窗口状态可以指出在网页中该 portlet 的哪个功能正在执行及现在的状态。

@ portlets 可以在同一个 portal 网页之中存在多个。

3)Portlet 有一些附加的功能是 Servlet 所没有的

@ Portlets 能够存取及储存永久配置文件及定制资料。

@ portlets 可以存取使用者数据

@ portlets 具有 URL 的重写功能在文件中去动态建立连结，允许 portal server 不用去知道如何在网页的片段之中建立连结及动作。

@ portlets 可以储存临时性的数据在 portlet session 之中，拥有两个不同的范围：

application-wide scope 及 portlet private scope 。

4)Portlet 不具有一些功能，但是 Servlet 却有提供

@ servlet 具有设置输出的文字编码( character set encoding)方式

@ servlet 可以设置 HTTP 输出的 header

@ servlet 才能够接收客户对于 portal 发出的 URL 请求

Portlets 可以调用 servlets ， JSPs 和 JSPs 标签库来产生内容。

一个 portlet 可以使用请求发送者来调用 servlets 和 JSPs ，就像 servlet 使用调用其它 servlets 和JSPs 一样。为了使portlets和servlets之间整合得天衣无缝，Portlet规范允许调用更多的servlet对象。

当servlet或JSP在portlet中被调用时，传给servlet或JSP的request是以portlet request为基础的。同样，传给servlet或JSP的response是以portlet response为基础的。

被包括的servlet request可使用portlet request的Attributes设置。

portlet和被包括的servle或JSP分享同一个的输出流。

portlet 会话中的Attributes设置可以来自于servlet会话，反之亦然。

portlet容器是servlet容器的扩展，所以一个portlet容器可以构建于一个已存在的servlet容器之上或者可能实现servlet容器的全部功能。无论portlet容器如何实现，它的运行环境总是假定它支持Servlet 2.3规范。

一个portlet能产生标记片段。portal通常在portlet产生的标记片段中加上标题，控制按钮及其它修饰。这个新的标记片段称为portlet窗口。然后portal合并这些portlet窗口为一个完整的文档，即portal页面

修饰和控件

标题 portlet片段

portlet窗口

portal页面

portlets 在 portlet container 内执行，portlet container 接收 portlets产生的内容。通常 portlet container 将这些内容提交给 portal server，portal server 从这些内容建立 portal page 然后将它传给客户端。（参考 Spec Figure 4-2）

使用者经由客户端设备（例如浏览器）存取 portal，portal 根据接收到的 request 决定哪些 portlets 需要被执行以满足需求。portal 通过 portlet container 呼叫 portlets，然后由 portlets 产生的片段建立portal page，再传回客户端呈现给使用者。

Portlet interface 是Portlet API 中主要的抽象接口，所有的portlet 不是直接操作这个接口，就是继承了

这个接口类。

Portlet API包含GenericPortlet 类，此类提供了一些预设的功能；开发人员应该继承、直接或间接地拓展GenericPortlet类，以写出自己的portlet。

Portlet Container如何产生portlet instances 是被布署描述(deployment descriptor)中portlet 的定义所控制的。在没有分布式的环境中（默认情况），portlet container 必须实例化一个并且只能使用一个portlet 物件来对应一个portlet 定义。

另一方面，在某种情况下，portlet在web.xml部署描述文件中被部署为分布式环境下的portlet应用程序的

一部份。那么，在同一虚拟机（VM）中，同一部署描述文件内，同一portlet定义下，一个portlet容器只能实例该portlet一次。

一个portlet有着良好的生命周期管理，定义了怎样装载，实例化和初始化，怎样握持来自客户端的请求及怎样送出服务。这个portlet生命周期由portlet接口的init，processAction，render和destroy方法来表达。

portlet container负责载入和实例化portlet。当portlet container 运行portlet application 或者延迟至portlet 需要服务使用者请求时，portlet 就会被载入和实例化。

在Web application下的portlet application中，portlet container用来载入portlet 的ClassLoader 和Servlet container 的ClassLoder 是相同的。载入portlet class 后，portlet class 就被实例化。

portlet物件实例化后，portlet container还必须初始化portlet，以调用portlet 去处理客户端要求。

Protlet经由初始化完成初始高代价的资源(例如在背景扫行的连结)，和执行其他只要执行一次的初始工作。

portlet container呼叫Portlet 接口中init 方法来初始化portlet，init 方法中portlet 的定义由拓展PortletConfig 接口的物件来提供。此configuration 物件可取出定义在部署描述的初始化参数(initialization parameter)及Resource Bundle 。此configuration 物件亦提供存取描述portlet runtime 环境的上下文(context)物件。

要了解PortletConfig 接口的详细信息，请参考PLT.6 Portlet Config 章节。

要了解PortletContex接口的详细信息，请参考PLT.10 Portlet Context 章节。

在portlet 初始化期间，portlet 物件可能会丟出UnavailableException 或PortletException 异常。此时，portlet container 不能把portlet 物件置入已启动的服务，并且portlet container 必需释放这个portlet 物件。destory方法不能被呼叫，因为初始化被认为执行失败。

发生failure 后，portlet container 会尝试着重新实例化及初始化portlet。这个异常处理的规则是：由一个UnavailableException 指定一个不能执行的最小时间，当此异常发生时，portlet container 必需等到指定时间过去后才产生并且初始化一个新的portlet 物件。

在初始化过程中所丟出的Runtime Exception异常，必需当作PortletException 来处理。

PortletConfig 物件，提供了在初始化一个 portlet 时所需要的信息。同时可以通过此物件取得 portlet context 和提供 portlet title-bar 信息的 resource bundle。

译者注：这里提到的“信息”指的是 title， short-title， keyword。

通过 PortletConfig 这个 interface 所提供的 getInitParameterNames 和 getInitParameter 这两个方法，可以得知在 portlets 部署描述文件中所定义的 portlet 初始参数及初始值。

在 Portlets 的部署描述文件中，可以设定 portlet 的基本信息如 portlet title-bar 的名称及portlet 在 portal 中的分类名称。为了显示这些信息， Portlet Spec.定义了一些 resource elements 让 title，short-title， keyword 可以根据 Locale 来显示。 (see the PLT.21.10 Resource Bundles Section)

在 portlets 部署描述文件中，这些 resource elements 可以直接放在 portlet 的定义中，亦或是写在resource bundle(*.properties) 里。

以下是一个定义 portlet 信息的例子：

假如这些信息的定义是写在 resource bundle 中的话，此时这个 portlet 必须提供一个 resource bundle 的名字。

示例如下：

假如 portlet 定义提供了一个resource bundle 的话， portlet-container 则必须通过 ResourceBundle 来 look up 这些设定值。

假如 root resource bundle 没有设定这些信息，且同时这些信息是写在的话， portlet container必须把他们都设到 root resource bundle 里。

TCK PORTLET：SPEC:24提到:

假如使用 ResourceBundle 资源文件来定义，则Portlet container 必须先 look up 在ResourceBundle 里定义的信息。若是 ResourceBundle 没有这些信息，或是没有使用 ResourceBundle来定，则 portlet container 必须 look up 写在定义文件里的信息。

假如 ResourceBundle 和定义文件里都没有定义这些信息，则 portlet container 必须以空字符串来回传。

假如在定义portlet时，没有定义resource bundle，而是把信息定义在部署定义文件中，此时 portlet container 则必须产生一个 ResourceBundle ，并且把这些信息放进来。

而使用的key值必须遵照PLT.21.10 Resource Bundles Section所定义的。

GenericPortlet的 render method 在取得 portlet 的 title 名称时，就是使用 PortletConfig 的ResourceBundle 物件，通过相关的ResourceBundle 设定或是直接写在portlet部署描述文件中的资料而来。

Portlet 也许会在自己的内容里出现 URL link，同时这个URL link 是参考到自己本身。比如说，当 User 在操作一个 portlet 里面的 URL 时(也就是说点选一个链接或是 submit 一张表单)。对 portal 而言，此时是一个新的请求，而这个请求的目标就是那一个 portlet。那些 URLs 就称作为 portlet URLs。

Portlet API定义了一个 PortletURL 的接口。Portlets 必须用这个 PortletURL 物件来产生 portlet URLs。在产生 PortletURL 的同时， PortletURL 也会呼叫 RenderResponse 接口定义的两个方法：createActionURL 和 createRenderURL。

createActionURL 用来生成 action URLs。

createRenderURL 用来生成 render URLs。

由于一些 portal/portlet-containers 在实际操作时可能会附加一些 query string 在 url link 上，以期提供这些 container 所需要的一些内部状态的参数等等，所以 portlet 开发者不应指定表单的传送方法为HTTP GET。

ex: WebLogic会对url link 加上一些参数的例子。

一个render URL 是对某些特殊类型action URLS 的一种优化。在 render portlet URL 的过程中Portal/portlet-container 不允许调用目标 portlet 的 processAction方法。 Portal/portlet-container必须确保当在建构 render URL 时所设定的参数，也能变成是在请求这个 portlet 时的参数。

Render URLs should not be used for tasks that are not idempotent from the portlet perspective。

点击 render 过的 URL发出的请求， portlet所产生的结果有可能会因为错误状况，缓存失效，外部资料的改变等等，而有所影响。 Render URLs 不应放在form表单里，因为 portal/portlet-container 有可能因此而忽略form表单的参数。

Portlets可以通过 PortletURL 所提供的 setParameter 和 setParameters 两个方法，对 PortletURL 物件设定一些应用程序的特殊参数。 setParameter 这个方法必须把以前所设定的同名参数给取代掉。所有portlet 所加到 PortletURL 物件上的参数都必须为该 portlet 的可用请求参数。 Portlet 开发者必须注意到render request 的请求参数并非在产生 PortletURL 时就被使用到。

portlet-container必须把加到portletURL物件上的参数名和值以“x-www-form-urlencoded“方式编码。在这些参数名和值被添加到portletUR物件上之前，portlet开发人员不可以编码它们。

如果 protal/portlet-container 输入一些额外的信息来当作参数，它必须适当地输入这些参数，以避免这些由 portlet 所设定和使用的参数产生碰撞或冲突。

运用 toString 这个方法， portlet 可以获得 PortletURL在该 portlet 里所表示的字符串。

以下是个产生 portlet URI 的例子:

Portlet 开发者应该知道 PortletURL 所表现的字符串并不是个很好看的表单URLS，但却是一个portlet 在此时生成内容的的特別象征。 Portlet servers 通常用一种URL重写的技术来对真正的 URL 进行处理加工。

Portlet URL可以包含一个特定的portlet mode (参考PLT.8 Portlet Modes Chapter) 或window state (参考PLT.9 Window States Chapter). 这个PortletURL 接口提供setWindowState 和setPortletMode 方法，在URL 里加入一些参数来设定portlet mode 和window state。

因为 portlet mode 并不是定义来支持 Portlet 的，且 user 是不能使用 portlet mode 的，所以不能用 portlet mdoe 来产生 portlet URL。若执意如此使用的话，在这种状况下 setPortletMode 方法必须丟出PortletModeException异常。当 portlet URL 的一个请求被调用时， portlet mode 的改变必须做出有效地回应。但还是有一些例外的状况，比如说改变存取控制权就有可能让portlet mode改变不会发生。

Portlet container并不支持winodw state，所以portlet 不能运用window state 来产生portlet URL。假如执意如此使用的话，此时setWindowState 必须丟出WindowStateException异常。Window state 的改变必须有效的反应一个portlet URL 的请求。 The portlet should not assume that the request triggered by the portlet URL will be in the window state set as the portal/portlet-container could override the window state because of implementation dependencies between portlet modes and window states.。

PortletURL接口的setSecure 方法允许portlet 来定义portlet URL 是否必须为一个安全的URL(即HTTPs 或HTTP)。假若没有运用setSecure 方法，portlet URL 必须与当前的请求是同样的安全等级(也就是维持请求时的安全等级)。

Portlet mode 指出portlet 正处于什么模式，Portlet 通常会根据所处的模式而执行不同的工作并产生不同的内容。

Portlet模式让portlet 决定它该显示什么内容和执行什么动作。调用一个portlet 的时候，portlet container 会提供一个portlet 模式给那个portlet。当在处理一个请求动作时，portlet 的模式是可以用程序来改变的。

Portlet规格定义了三个portlet 模式：VIEW，EDIT，and HELP。于是PortletMode 类就为这三个模式定义了常数。

同时Portal是可以根据使用者的角色，来决定是要提供(显示)哪几个portlet 模式给使用者操作。

例如，匿名使用者可以操作VIEW 和HELP等portlet 模式的内容，而只有授权过的使用者可以操作EDIT 这个portlet 模式所提供的内容或动作。

在VIEW 这个portlet 模式里，所被期望要提供的功能是产生markup 语言来表现此时portlet 的状态。举例来说，portlet 的VIEW 模式可以包含一个或多个画面让使用者可以浏览与互动，或是一些不需要与使用者互动的静态内容。

Portlet开发者应该重写doView 这个被定义在GenericPortlet 类別里的方法，来执行VIEW 模式的功能。所有的Portlet 都必须支持VIEW模式。

在EDIT 这个portlet 模式里，protlet 需要提供内容和逻辑来让使用者定制portlet 的行为。portlet 的VIEW 模式可以包含一个或多个画面让使用者可以浏览并输入一些定制的资料。典型的说，EDIT 模式的portlet 会设定或更新portlet 的参数设定值。

参考PLT.14 Portlet Preferences Chapter 可以得到更多有关portlet 参数设定的信息。

Portlet开发者应该重写doEdit 这个被定义在GenericPortlet 类別里的方法，来执行EDIT 模式的功能。所有的portlet 并不需要都提供EDIT 这个模式。

在HELP 这个模式里，portlet 应该提供有关这个portlet 的help 讯息。这个help 讯息可以是有关这个portlet 的简单且条理清楚的视窗说明或是详细的说明整个来龙去脉。

Portlet开发者应该重写doHelp 这个被定义在GenericPortlet 类別里的方法，来执行HELP 模式的功能。

所有的portlet 并不需要都提供HELP 这个模式.

为了特別的功能，Portlet 提供者可以定义一些定制的portlet 模式，所有的portlet 可以使用portal 所定义的portlet 模式。Portlets 必须用 这个tag 在部署描述文件中定义其所要使用的定制的portlet 模式。在部署阶段，这些在部署描述文件中定义的定制的portlet 模式必须对应到portal 所支持的模式。

假若没有这样做的话，portlets 将不会在该portlet 模式里被调用。

举个例子，一个支持clipboard 和config 这两个定制的portlet 模式的portlet，必须在部署描述档里写下这些设定：

在附录 PLT.A Extended Portlet Modes 里定义了一连串的 portlet 模式的名称，和可以利用在哪些方面的建议。

在执行的时候，若有在部署描述文件中定义到这几个预先定义的定制化的 portlet 模式的名字时Portals 可以自动把这几个定义给 mapping 起来。

GenericPortlet类別在执行render 方法时，会根据在doDispatch 方法里所指定的portlet 模式，而把请求分配给doView，doEdit，doHelp 这几个方法。

portlet 可以重载GenericPortlet 的doDispatch 这个方法来达到将请求分配给另外定制的portlet 模式。

在部署描述文件中里，Portlets 必须定义其对任何markup 语言所支持的portlet 模式。正因为所有的portlet 都必须支持VIEW 模式，所以 VIEW 模式是不需定义的。

假如某个portlet 模式并没有被定义来支持某个markup 形态的时候，则portlet 在该portlet 模式里是不能被驱动的。

下面的例子显示在部署描述档里定义一个portlet 模式的片段语法：

对HTML 的markup 来说，portlet 支持EDIT 和HELP 和一定要的VIEW 这三种portlet 模式。就WML markup 来说，portlet 仅支持VIEW 和HELP 两种portlet 模式。至于portal 在执行上没有支持的的其他定制的portlet 模式，或是portal 不支持的portlet 模式，Portlet container 都必须忽略

一个portlet 可以根据视窗状态来决定在一个页面里该占多少大小。当调用一个portlet 时，portlet-container 需要告诉该portlet 目前的视窗状态。此时portlet 可以根据视窗状态来决定它该对多少信息来作处理。在处理请求的过程中，portlet 可以通过程序的方式来改变视窗状态。

Portlet规格里定义了三个视窗状态：NORMAL，MAXMIZED，MINIMIZED。WindowState 这个类定义了这三个状态的常量值。

NORMAL 表示：

?portlet 可以与其他portlet 一起共用一个页面。

?读取的此页面的客户端设备(ex: PDA，手机，etc.) 有受限的显示功能。因此在这此视窗状态下，portlet 必须限制其本身画面可以显示的大小，以符合读取设备的显示功能。

MAXIMIZED 表示：

?portlet 可以把整个画面都占掉，也就是说在整个portal 页面里只有一个portlet。

?当然，在此状态下，portlet 可以产生更丰富的资料。

MINIMIZED 表示：

?在此状态下，portlet 必须处理产生最小化的资料，亦或是都不输出任何内容。

Portal的提供者可以定义定制的视窗状态。

Portlets只能使用portal 所定义的视窗状态。也就是说portlets 必须在其部署描述文件中定义其可以使用的视窗状态。在部署的时候，部署描述文件中所定义的定制化的视窗状态必须符合portal 执行所支持的视窗状态。否则，在此状态下portlet 是不会被调用的。

假设要做到half_page 这个视窗状态时，要如何定义，以下例子说明在部署描述文件中该如何定义所支持的视窗状态：

PortletContext 接口定义了一个 portlet 在portlet application 里执行时的概览。也就是说，通过PortletContext 物件，portlet 可以记录事件，或取得portlet application 的资源，设定和储存一些其他portlet 和servlet 可以取得的属性值。

任何部署在portlet container 里的portlet application 都有一个PortletContext 实例。假使container 是分散在不同的VM 上，一个portlet application 在每个VM 上都会有一个PortletContext

通过PortletContext 接口，我们可以得知context 的起始设定参数，并获得和储存context 属性，从portlet application 取得静态的资源，和取得一个request dispatcher 来作include servlets 和JSPs 的动作。

一个portlet application 是一个web application 的延伸。就延伸自一个web application 而言，portlet 也有一个servlet context。同时portlet context 支持大多数的portlet application 的servlet context 的功能。

Context层级的初始参数就如同servlet context 的初始参数，同时context 属性值是存在于servlet context中，且是可以互相分享的。因此，这些初始参数是必须定义在部署描述文件中的(web.xml 文件)。用PortletContext 来取得的初始参数值，就如同用portlet application 的servlet context 来取得是一样的。

用PortletContext 提供的方法来储存context 的属性值，这些值必须储存在portlet application

的ServletContext 里。

这样做的直接的影响是：用servlets 或JSPs 来存在ServletContext 里的资料，都可以通过PortletContext 来取得，反之亦然。

?PortletContext 必须提供方法来取得 ServletContext 所公开的资源。

?PortletContext 必须处理 ServletContext 处理的缓存目录。而PorteltContext 可以把这个缓存目录的信息当作是context 属性值一样，通过Servlet 2.3 规格第SVR 3章所定义的常量

(javax.servlet.context.tempdir) 来取得。

?在virtual hosting 和reloading considerations 这方面，portlet context 必须遵照servlet context 所定义的行为与功能。(参考Servlet Specification 2.3 SVR 3 Servlet Context Chapter) PLT.10.3.1 Correspondence between ServletContext and PortletContext methods

以下的方法为ServletContext 所提供的，且PortletContext 必须提供相同的功能：

?getAttribute

?getMimeType

?getRealPath

?getResource

?getResourcePaths

?getResourceAsStream

?log

?removeAttribute

?setAttribute

Request 物件封装了所有有关client 的请求，参数，请求内容，portlet mode，portlet state等等的信息。

Portlet的request 物件是交由processAction 和render method 来处理。

PortletRequest接口定义了一些一般的功能，并且由ActionRequest 和RenderRequest 两个接口来继承。

假若portlet 收到一个client 对其发出的请求的时候，其中的请求参数必须是被encode 在URL字符串里(在产生PortetURL 的时候已经处理好了)，而且是对该portlet 发出的请求。这些请求参数经由

"x-www-formurlencoded" 的方式被decode 回name value pairs。(在PortletURL 接口里定义了serParameter(s) 方法就是用"x-www-formurlencoded" 的方式来encode 参数的name 和value。) Portlet-container不能把在action request 得到的参数传递到后续的render request。假如portlet 要这样做，可以通过render URL 或是在processAction 的时候，利用ActionResponse 物件的setRenderParameter or serRenderParameters 方法来做。

假如在portal page 里的一个portlet 收到一个是要给其他portlet 的render request 时，这个request 的参数必须与前一个render reuqest 的参数一样。

假如portlet 在同一个client request 里收到一个跟在action request 后的render request，这时的参数必须与在action request 时的一样。

一般来说，portals 可以控制portlet 的portlet mode 和window state。在操作的这些URLs 是由portal 所产生的。Client 经由触发URLs 来对portlet 发出的请求，必须被视作是render URLs，而且所发出的请求参数是必须被保存的。

一个portlet 不能收到要给別的portlet 的请求参数。

参数是以name-value pairs 的方式被储存着。重复的参数也可已被储存。可以通过以下PortletRequest 接口所提供的方法来取得参数资料。

?getParameter

?getParameterNames

?getParameterValues

?getParameterMap

getParameterValues 方法回传一个String 物件的阵列包含全部相同名字的参数的值。用getParameter 方法所得到的值，是在这些同名参数里的第一个的值，也就是用getParameterValues 回传的阵列里的的第一个的值。假如只有一个参数符合getParameterValues(https://www.360docs.net/doc/ef8578557.html,ng.String name) 所用的name，则必须回传一个size=1 的String 阵列。getParameterMap 方法必须回传一个不能被修改的Map 物件。假如request 没有任何参数，则getParameterMap 必须回传一个空的Map 物件(non null)。这Map 物件里的key 是type String ，而value 是String array(String[])。

Portal/portlet-container执行时可能在portlet URLs 里加一些额外的参数来做整体的routing 和处理client requests。Portal/portlet-container 所用的额外参数必须不被正在接收请求的portlet 所见。如果portal/portlet-container 用的参数的命名有可能与portlet 所定义的参数冲突，这些问题必须由portal/ portlet-container 负责避免。

当然Portlet Spec. 就有规定一些名字是保留字：“javax.portlet.”。

Request attributes是在一个独立的portlet request 里的物件。Portlet 或是portlet container 可以设定request attributes 来表示一些无法通过API 表示的信息。通过request attributes 可以与经由PortletRequestDispatcher 所include 的servlet or JSP 来共用信息。

Attributes可以经由下述PortletRequest 接口所提供的方法来设定，取得和移除:

?getAttribute

?getAttributeNames

?setAttribute

?removeAttribute

不像parameter，一个attribute name 只有一个value。

同样的attribute 的命名也不能是“javax.portlet.”开头的字。

建议依据Java Programming Language Sepcification 1 所提的naming convention 来做attribute 的命名。

Portlet可以得到portal/portlet-container 的属性，假如可已的话，连HTTP client request 的headers 信息都可以通过下列PortletRequest 接口提供的方法得到.

?getProperty

?getProperties

?getPropertyNames

这里可能有同名的属性值。同名的属性值在用getProperty 方法取得时，会回传第一个的值。用getProperties(String name) 方法可以回传一个Enumeration object 包含这个name 的全部属性值(of type String)。

依靠底层不同的web-server/servlet-container 和portal/portlet-container 所执行的，client request HTTP headers 也许不一定都可以正确取得。所以portlets 不行依靠headers 的信息来动作。

PortletRequest接口有提供一些特定的方法来取得一些常见的Header 信息：content-length，content-type，accept-language。

虽然portal/portlet-container 在执行上可能会用其他方法来决定这些header 信息，不过portlet 仍可利用这些特定的方法来取的这些信息。

在request 物件里就可以看到context path。Context path 是所部署的portlet application 的前缀字。

假若portlet application 在web server URL namespace 里是root 的话(也就是"default" context)，此时的context path 必是一个空字串。否则context path 就是这个portlet application 的root 路径。这个path 必须是"/"开头，且结尾不能是"/"。

PortletRequest接口提供一组方法来提供有关User 和User 与Portal 间的关系的"Security" 信息。

方法如下：

?getAuthType

?getRemoteUser

?getUserPrincipal

?isUserInRole

?isSecure

getAuthType方法，指出了User 与Portal 之间所用的authentication scheme。此方法回传所定的（BASIC_AUTH，DIGEST_AUTH，CERT_AUTH and FORM_AUTH）或是由开发商所提供的authentication type 的字符串。假如User 未被authenticated，则getAuthType 未回传null。

getRemoteUser方法，回传发出请求的User 的login name。

getUserPrincipal方法，回传一个包含认证过的User 的名字的java.security.Principal 物件。

sUserInRole方法，显示了是否一个认证过的User 是否拥有特定的role。

isSecure方法，则是检验一个request 是否通过安全的协定来传递(ex：HTTPS)。

Portlet developer可以写一个支持多重content type 的portlet。Portlet 可以利用request 物件的getResponseContentType 方法来取得container 所认为该output 所代表的的一个字符串模式的content type。在portlet 的output 上，若是container 有支持其他的content types，则必须利用request 物件的getResponseContentTypes 来得知。此方法回传一个包含所有container 所支持的content tpye 的Enumeration 物件。这里面的第一个content type 必须跟getResponseContentType 所回传的一样。

假如portlet 用万用字符'*' or ' / ' 来定义支持所有的content type，且container 支持全部的content type，则getResponseContentType 可以回传万用字符'*' or ' / *' 或是container 所prefer

getResponseContentTypes方法必须是回传该portlet mode 所支持的content types。

Portal/portlet-container决定要用什么locale 来产生response 给User。

Portal/portlet-container可以参考client 请求的信息。举例来说，HTTP/1.1 规格所定义的header 里面的Accept-Language。

PortletRequest的getLocale 方法，可以告知portal/portlet-container 所选择使用的locale。

PortletRequest接口提供的getPortletMode 可以让portlet 取得目前的的portlet mode。可以限制portlet 提供某种portal/portlet-container 所支持的portlet mode。

Portlet可以利用PortletRequest 接口提供的isPortletModeAllowed 来得知此portlet 是否可以使用某个portlet mode。

若portlet mode 并未被该portlet 所定义，或是portal 限制了该种portlet mode，则该portlet 就不能使用该portlet mode。

PortletRequest接口提供的getWindowState 让一个portlet 得知其目前的window state。

一个portlet 可以被限制只能使用某种portal/portlet-container 所支持的window state。

一个portlet 可以利用PortletRequest 接口提供的isWindowStateAllowed 方法来得知本身是否可

以使用该window state。

ActionRequest接口继承了PortletRequest 接口，且此接口使用在Portlet 接口里的processAction 里。除了PortletRequest 接口所提供的功能之外，ActionRequest 还提供可以取得request 的input stream 的方法。

当client request 包含了HTTP POST 资料为非"application/x-www-form-urlencoded" 的形态时，这个input stream 是非常有用的。比如，上传档案。就Portlet developer 的方便性来说，

ActionRequest

接口同时还提供getReader 方法来取得HTTP POST character 格式的资料。