摘要JSR168 PORLET标准手册汉化整理

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

 

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

 

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

 

第一、第二章节     台湾省   Jini   

第三章节           上海市   风之舞

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

JSR168 PORLET标准手册汉化整理

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

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

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

第一、第二章节     台湾省   Jini   
第三章节           上海市   风之舞
第四章~最后章节    台湾省   koji lin

PLT.1.1 序言                                                           参考 jini

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

如果你从来沒有用过 portal server 或是似懂非懂.. 大家可以连结到 MyNetscape 或 MyYahoo 去 注册一个帐号。因为 MyNetscape 的样式比较好看, 所以我接下来就以 MyNetscape 为介绍的范例。
 
如果你第一次接触到 portal，你会惊讶的发现... 哇.. 为何一个网站里面充满了这么多小窗口. 我们称这些小窗口叫做 "portlet"，而且每个小窗口都存在着独立的信息与内容，可以放到最大化，缩小，还原，关闭等等。当你登陆之后，可以选择及调整自己 portlet 的配置，也可以设置自己喜爱的风格与样式，更可以设置每个 portlet 的资料配置。

这种以客户为上帝的系统，就是我们将要介绍的 portal。
PLT.2.1 什么是Portal（门户）? 

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

1)Portal Server 的定义是

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

portlet container 是提供 portlets 执行的环境，包含了许多 portlets 并且管理他们的生命周期，他也会永远保存着 portlets 的喜好设置，一个 portlet container 接收到来自 portal 的请求后，接着将这个请求传递给存在 container 的 portlet 执行。portlet container 没有义务去组合 portlets 产生的信息內容，这个工作必须由 portal 来处理。portal 和 portlet container 可以放在一起视为同一个系统的组件，或者分开成为两个独立的组件。 
PLT.2.2 什么是 Portlet?

一个 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 的设置。

PLT.2.3 portlet 与 servlet 的关系?


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 有一些定义好的 request 处理，action request 以及 render request。
@ 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 请求

PLT.3.1 从 Portlets 到 Servlets/ JSPs 的关联

   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会话，反之亦然。
PLT.3.2   Servlet容器和Portlet容器的关系

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





PLT.4.1 Elements of a Portal Page （Portal页面的结构）

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



                                                                修饰和控件
标题                                                    portlet片段
                                                                               portlet窗口 
        <Portlet 内容>

                                                                                portal页面









PLT.4.2 Portal Page Creation	参考koji lin 

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
















PLT.4.3 Portal Page Request Sequence  

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



PLT.5 The Portlet Interface
   
Portlet interface 是 Portlet API 中主要的抽象接口，所有的 portlet 不是直接操作这个接口，就是继承了
这个接口类。

Portlet API包含 GenericPortlet 类，此类提供了一些预设的功能；开发人员应该继承、直接或间接地拓展
GenericPortlet类，以写出自己的 portlet。 
PLT.5.1 Number of Portlet Instances
   
    Portlet Container如何产生 portlet instances 是被布署描述(deployment descriptor)中 portlet 的
定义所控制的。在没有分布式的环境中（默认情况），portlet container 必须实例化一个并且只能使用一个 portlet 物件来对应一个 portlet 定义。

另一方面，在某种情况下，portlet在web.xml部署描述文件中被部署为分布式环境下的portlet应用程序的一部份。那么，在同一虚拟机（VM）中，同一部署描述文件内，同一portlet定义下，一个portlet容器只能实例该portlet一次。

PLT.5.2 Portlet Life Cycle 

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

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

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

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 章节。 
PLT.5.2.2.1 Error Conditions on Initialization

   在 portlet 初始化期间，portlet 物件可能会丟出 UnavailableException 或 PortletException 异常。此时，portlet container 不能把 portlet 物件置入已启动的服务，并且 portlet container 必需释放这个 
portlet 物件。 destory方法不能被呼叫，因为初始化被认为执行失败。
发生 failure 后，portlet container 会尝试着重新实例化及初始化 portlet。这个异常处理的规则是：由一个
UnavailableException 指定一个不能执行的最小时间，当此异常发生时，portlet container 必需等到指定时间过去
后才产生并且初始化一个新的 portlet 物件。

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

PLT.5.2.2.2 Tools Consideration    待续






































PLT.6 Portlet Config

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

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

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

<init-param> 
   <name>dummyName</name> 
   <value>dummyValue</value> 
</init-param>
PLT.6.2 Portlet Resource Bundle

在 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 信息的例子：

<portlet> 
    … 
    <portlet-info> 
        <title>Stock Quote Portlet</title> 
        <short-title>Stock</short-title> 
        <keywords>finance， stock market</keywords> 
    </portlet-info> 
    … 
</portlet>
   
  假如这些信息的定义是写在 resource bundle 中的话， 此时这个 portlet 必须提供一个 resource bundle
的名字。
示例如下：
<portlet> 
    … 
    <resource=bundle>com.foo.myApp.QuotePortlet</resource-bundle> 
    … 
</portlet>

    假如 portlet 定义提供了一个resource bundle 的话， portlet-container 则必须通过 ResourceBundle
来 look up 这些设定值。
假如 root resource bundle 没有设定这些信息， 且同时这些信息是写在<portlet-info>的话， 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部署描述文件中的资料而来。










PLT.7 Portlet URLs

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

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 加上一些参数的例子。 

http://localhost:7001/my.portal?_nfpb=true&_pageLabel=book_33

一个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 的例子: 
...
PortletURL url = response.createRenderURL();
url.setParameter(“customer”，”foo.com”);
url.setParameter(“show”，”summary”);
writer.print(“<A HREF=\””+url.toString()+”\”>Summary</A>”);
...

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

Portlet URL可以包含一个特定的 portlet mode (参考 PLT.8 Portlet Modes Chapter) 或 window state (参考 PLT.9 Window States Chapter). 这个 PortletURL 接口提供 setWindowState 和 setPortletMode 方法，在 URL 里加入一些参数来设定 portlet mode 和 window state。
例如： 
...
PortletURL url = response.createActionURL(); 25
url.setParameter(“paymentMethod”，”creditCardInProfile”);
url.setWindowState(WindowState.MAXIMIZED);
writer.print(“<FORM METHOD=\”POST\” ACTION=\””+ url.toString()+”\”>”);
...
     因为 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.。
PLT.7.1.2 Portlet URL securit

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


PLT.8 Portlet Modes

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 模式所提供的内容或动作。
PLT.8.1 VIEW Portlet Mode
    
    在 VIEW 这个 portlet 模式里，所被期望要提供的功能是产生 markup 语言来表现此时 portlet 的状态。 举例来说， portlet 的 VIEW 模式可以包含一个或多个画面让使用者可以浏览与互动， 或是一些不需要
与使用者互动的静态内容。 
Portlet开发者应该重写 doView 这个被定义在 GenericPortlet 类別里的方法，来执行 VIEW 模式的功能。所有的 Portlet 都必须支持 VIEW模式。
PLT.8.2 EDIT Portlet Mode

   在 EDIT 这个 portlet 模式里， protlet 需要提供内容和逻辑来让使用者定制 portlet 的行为。portlet 的
VIEW 模式可以包含一个或多个画面让使用者可以浏览并输入一些定制的资料。典型的说， EDIT 模式的 portlet 会设定或更新 portlet 的参数设定值。
参考 PLT.14 Portlet Preferences Chapter 可以得到更多有关 portlet 参数设定的信息。
Portlet开发者应该重写 doEdit 这个被定义在 GenericPortlet 类別里的方法，来执行 EDIT 模式的功能。所有的 portlet 并不需要都提供 EDIT 这个模式。
PLT.8.3 HELP Portlet Mode

在 HELP 这个模式里，portlet 应该提供有关这个 portlet 的 help 讯息。这个 help 讯息可以是有关这个 portlet 的简单且条理清楚的视窗说明或是详细的说明整个来龙去脉。 
Portlet开发者应该重写 doHelp 这个被定义在 GenericPortlet 类別里的方法，来执行 HELP 模式的功能。
所有的 portlet 并不需要都提供 HELP 这个模式. 
PLT.8.4 Custom Portlet Modes

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

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

举个例子， 一个支持 clipboard 和 config 这两个定制的 portlet 模式的 portlet， 必须在部署描述档里写下这些设定： 
<portlet-app>
...
    <custom-portlet-mode>
        <description>Creates content for Cut and Paste</description>
        <name>clipboard</name>
    </custom-portlet-mode>

    <custom-portlet-mode>
        <description>Provides administration functions</description>
        <name>config</name>
    </custom-portlet-mode>
...
</portlet-app>

     在附录 PLT.A Extended Portlet Modes 里定义了一连串的 portlet 模式的名称，和可以利用在哪些方
面的建议。 
在执行的时候， 若有在部署描述文件中定义到这几个预先定义的定制化的 portlet 模式的名字时
Portals 可以自动把这几个定义给 mapping 起来。
PLT.8.5 GenericPortlet Render Handling

GenericPortlet类別在执行 render 方法时， 会根据在 doDispatch 方法里所指定的 portlet 模式， 而把请求分配给 doView， doEdit，doHelp 这几个方法。
portlet 可以重载 GenericPortlet 的 doDispatch 这个方法来达到将请求分配给另外定制的 portlet 模式。 
PLT.8.6 Defining Portlet Modes Support

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

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



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

...
<supports>
    <mime-type>text/html</mime-type>
    <portlet-mode>edit</portlet-mode>
    <portlet-mode>help</portlet-mode>
    ...
</supports>
<supports>
    <mime-type>text/vnd.wap.wml</mime-type>
    <portlet-mode>help</portlet-mode>
    ...
</supports>
...

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


PLT.9 Window States

一个 portlet 可以根据视窗状态来决定在一个页面里该占多少大小。 当调用一个 portlet 时， portlet-container 需要告诉该 portlet 目前的视窗状态。 此时 portlet 可以根据视窗状态来决定它该对多少信息来作处理。 在处理请求的过程中， portlet 可以通过程序的方式来改变视窗状态。 
Portlet规格里定义了三个视窗状态： NORMAL， MAXMIZED， MINIMIZED。 WindowState 这个类定义了这三个状态的常量值。 
PLT.9.1 NORMAL Window State
NORMAL 表示：
portlet 可以与其他 portlet 一起共用一个页面。
读取的此页面的客户端设备(ex: PDA， 手机， etc.) 有受限的显示功能。 因此在这此视窗状态下，portlet 必须限制其本身画面可以显示的大小， 以符合读取设备的显示功能。
PLT.9.2 MAXIMIZED Window State
MAXIMIZED 表示：
portlet 可以把整个画面都占掉， 也就是说在整个 portal 页面里只有一个 portlet。
或是相对地来说，整个页面里就属这一个 portlet 占了最大的版面。
当然， 在此状态下，portlet 可以产生更丰富的资料。 
PLT.9.3 MINIMIZED Window State
MINIMIZED 表示：
在此状态下， portlet 必须处理产生最小化的资料， 亦或是都不输出任何内容。 
PLT.9.4 Custom Window States

Portal的提供者可以定义定制的视窗状态。
Portlets只能使用 portal 所定义的视窗状态。 也就是说 portlets 必须在其部署描述文件中定义其可以使用的视窗状态。 在部署的时候， 部署描述文件中所定义的定制化的视窗状态必须符合 portal 执行所支持的视窗状态。 否则， 在此状态下 portlet 是不会被调用的。
假设要做到 half_page 这个视窗状态时， 要如何定义，以下例子说明在部署描述文件中该如何定义所支持的视窗状态：

<portlet-app>
    ...
    <custom-window-state>
        <description>Occupies 50% of the portal page</description>
        <name>half_page</name>
    </custom-window-state>
    ...
</portlet-app>


PLT.10 Portlet Context

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

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

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

      一个 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 
PLT.11 Portlet Request

      Request 物件封装了所有有关 client 的请求， 参数， 请求内容，portlet mode， portlet state等
等的信息。
Portlet的 request 物件是交由 processAction 和 render method 来处理。 
PLT.11.1 PortletRequest Interface

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

    假若 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(java.lang.String name) 所用的 name， 则必须回传一个 size=1 的 String 阵列。 getParameterMap 方法必须回传一个不能被修改的 Map 物件。 假如 request 没有任何参数， 则 getParameterMap 必须回传一个空的 Map 物件(non null)。 
这 Map 物件里的 key 是 type String ， 而 value 是 String array(String[])。 
PLT.11.1.2 Extra Request Parameters

Portal/portlet-container执行时可能在 portlet URLs 里加一些额外的参数来做整体的 routing 和 处理 client requests。 Portal/portlet-container 所用的额外参数必须不被正在接收请求的portlet 所见。如果portal/portlet-container 用的参数的命名有可能与 portlet 所定义的参数冲突， 这些问题必须由 portal/
portlet-container 负责避免。
当然 Portlet Spec. 就有规定一些名字是保留字： “javax.portlet.”。
PLT.11.1.3 Request Attributes

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 的命名。 
PLT.11.1.4 Request Properties

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 仍可利用这些特定的方法来取的这些信息。
PLT.11.1.5 Request Context Path

在 request 物件里就可以看到 context path。Context path 是所部署的 portlet application 的前缀字。
假若 portlet application 在 web server URL namespace 里是 root 的话(也就是 "default" context)， 此时的 context path 必是一个空字串。 否则 context path 就是这个 portlet application 的 root 路径。 这个 path 必须是"/"开头，且结尾不能是"/"。
PLT.11.1.6 Security Attributes

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)。
PLT.11.1.7 Response Content Types

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 的 content type。 
getResponseContentTypes方法必须是回传该 portlet mode 所支持的 content types。
PLT.11.1.8 Internationalization

Portal/portlet-container决定要用什么 locale 来产生 response 给 User。
Portal/portlet-container可以参考 client 请求的信息。 举例来说， HTTP/1.1 规格所定义的 header 里面的 Accept-Language。
PortletRequest的 getLocale 方法， 可以告知 portal/portlet-container 所选择使用的 locale。
PLT.11.1.9 Portlet Mode

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。 
PLT.11.1.10 Window State

PortletRequest接口提供的 getWindowState 让一个 portlet 得知其目前的 window state。
一个 portlet 可以被限制只能使用某种 portal/portlet-container 所支持的 window state。
一个 portlet 可以利用 PortletRequest 接口提供的 isWindowStateAllowed 方法来得知本身是否可以使用该 window state。
PLT.11.2 ActionRequest Interface

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

     当 client request 包含了 HTTP POST 资料为非 "application/x-www-form-urlencoded" 的形态时， 这个 input stream 是非常有用的。 比如， 上传档案。就 Portlet developer 的方便性来说， ActionRequest 
接口同时还提供 getReader 方法来取得 HTTP POST character 格式的资料。

在一个 action request 里， 只有 getPortletInputStream 或 getReader 其中一个可以被使用。 假如已经呼叫 getPortletInputStream， 则又呼叫 getReader 时， 就必须丟出 IllegalStateException， 反之亦然。
为了帮助管理 input stream，ActionRequest 接口也提供下列方法：
getContentType 
getCharacterEncoding 
setCharacterEncoding 
getContentLength 
setCharacterEncoding 只有设定 character set 给 getReader 方法所回传的 Reader 用。
假如 user 请求的 HTTP POST data 是 application/x-www-form-urlencoded 的格式， 则这个资料必须
是已经被 portal/portlet-container 所处理过， 且可以在 request parameters 里被取得。 此时若呼叫 getPortletInputStream or getReader 方法时都必须丟出 IllegalStateException. 
PLT.11.3 RenderRequest Interface

继承自 PortletRequest 接口的 RenderRequest 接口是用在 Portlet 接口定义的 render method。且RenderRequest 接口并未定义其他方法。
PLT.11.4 Lifetime of the Request Objects

每一个 request 物件只有在一个特定的 processAction or render 方法里时是有用的。 Containers 通常会循环再利用 request 物件以避免在每次产生 request 物件时， 造成效能上的负担。 开发人员应该注意到若在 processAction 或 render 方法这两个 scope 之外来维护参照 request 物件时， 可能会造成 non-determisnistic 的反应。

PLT.12 Portlet Response

  Response 物件在 client 请求的过程中封装了所有从 portlet 回传给 portlet container 的信息，如 redirection， portlet mode，title 和内容等等。而portal/portlet container 利用这些信息产生 response 并回传给(通常为 portal page ) client端。 Portlet 的 response 物件是交由 processAction 和 render 
method 来处理。
PLT.12.1 PortletResponse Interface

PortletResponse接口定义了一些一般的功能， 并且由 ActionResponse 和 RenderResponse 两个接口来继承。
PLT.12.1.1 Response Properties

Portlets可以利用 Properties 将 portlet 制造厂商定义的信息传给portal/portlet-container。
portlet可以通过以下 PortletResponse 接口所提供的方法来设定 properties
setProperty 
addProperty 
    setProperty 方法分別传入参数 name 和 value 来设定 property 。而之前设定的 property 将会被新的 property 所取代。如果此 name 含有多个 property values，则同样所有 property values 将会被清空，而被新的 property value 所取代。 addProperty 则是新增一个 property value 到要求的 name 的集合中， 而不会清除掉之前已存在的property 。如果此 name 没有任何相关的 property values ，则新增一个
集合。 
PLT.12.1.2 Encoding of URLs

Portlet产生的内容 ，可能包含了指到 portal 内的其他资源的 URLs 。如 servlets， JSPs， images 和其他静态档案。某些 portal/portlet-container 执行可能会需要让此 URLs 把执行特有的资料 encode 在其中。因为这样， portlets 应该使用 encodeURL 方法去产生这些 URLs 。 encodeURL 可能得把 session ID 和 portal/portletcontainer 特有的信息包含到 URL 中。如果不需要 encoding ，则回传原本未被更动过的 URL 。 
PLT.12.2 ActionResponse Interface

ActionResponse接口继承自 PortalResponse 接口，且被使用在 Portlet 接口中的 processAction 方法中.此接口让 portlet 可以 redirect 使用者到其他 URL ， 设定 render parameters ， 改变 portlet 的 window state 和 portlet mode 。 
PLT.12.2.1 Redirections

sendRedirect方法命令 portal/portlet-container 设定适当的 header 跟 content body 让使用者导向到不同的URL 。必须指定 fully qualified full path URL 或者 full path URL 。如果给予的是 relative path URL ，那么将会丟出 IllegalArgumentException 。
如果 sendRedirect 被使用于 ActionResponse 接口中的 setPortletMode ， setWindowState ， setRenderParameter 或 setRenderParameters 之后，将会丟出IllegalStateException 且 sendRedirect 将不会产生任何作用。 
PLT.12.2.2 Portlet Modes and Window State Changes

SetPortlet方法让portlet可以去更改现存的 portlet mode 。新的 portlet mode 将会在之后的 render request 发生效果。如果 portlet 尝试将 portlet mode 改变成不允许的状态，将会丟出 PortletModeException。 

SetWindowState方法让 portlet 可以去更改现存的 window state 。新的 window state 将会在之后的 render request 发生效果。如果 portlet 尝试将 window state 改变成不允许的状态，将会丟出 WindowStateException 。 
   Portlets cannot assume that subsequent renders will be called in the set portlet mode or window state as the portal/portlet-container could override these changes。
如果 SetPortlet 和 SetWindowState 方法被呼叫在 sendRedirect 之后，将会丟出IllegalStateException ，如果 Exception 被 portlet 所 catch 住，那么 redirection 仍会发生作用。但是如果 excpetion 被传递回 portlet-container 中，则 redirection 不会发生任何作用。 
PLT.12.2.3 Render Parameters

在一个 action 的 request 中使用 ActionResponse 接口所定义的 setRenderParameter 和 setRenderParameters 方法能设定 render parameters 。呼叫 setRenderParameter 将会把之前所设定的同名的任何 parameter 取代掉。这些 parameters 将会被后来的 requests 使用直到新的 client request 锁定 portlet 。如果没有任何 render parameter 在 processAction唤起中被设定，则 render request 将不包含任何 request parameters 。 
Portlet developers不需要去“x-www-form-urlencoded” encode 被设在ActionResponse 中的 render parameters names 和 values 。
如果 setRenderParameter 和 setRenderParameters 方法在 sendRedirect 之后被呼叫，则必须丟出 IllegalStateException ，如果 Exception 被 portlet 所 catch 住，那么 redirection 仍会发生作用。但是如果 excpetion 被传递回 portlet-container 中，则 redirection 不会发生任何作用。 
PLT.12.3 RenderResponse Interface

继承自 PortletResponse 接口的 RenderResponse 接口是用在 Portlet 接口定义的 render method 。 且RenderResponse 接口让 portlet 可以设定 title 跟所产生的内容。 
PLT.12.3.1 Content Type

Portlet必须使用 RenderResponse 接口的 setContentType 方法设定 response 的 content type 
当 content type set 和从 PortletRequest 物件的getResponseContentType 回传的 content types 不相符，则 setContentType 会丟出IllegalArgumentException。 portlet container 应该忽略那些指定成部分 content type 的任意 character encoding 。
如果 getWriter 或 getPortletOutputStream 方法在 setContentType 之前被呼叫，则必须丟出 IllegalStateException。 
setContentType方法必须在 getWriter 或 getPortletOutputStream 方法前被呼叫。如果在之后被呼叫，则不发挥作用。
如果 portlet 已经设定好了 content type ，那么 getContentType 必须回传他。相反的如果没有设，则 getContentType 方法会回传 null 。 
PLT.12.3.2 Output Stream and Writer Objects

Portlet可以通过写到 RenderResponse 物件的 OutputStream 或者是 Writer 来产生内容。 portlet 只可以用其中一种 object 。如果 portlet 尝试使用两者，则 portlet container必须丟出 IllegalStateException。 
PLT.12.3.3 Buffering

Portlet container允许(但不是必须)为了效率问题，将输出到 client 的 output buffer 起来。一般来说 servers 会将 buffering 设为 default ，但是允许 portlets 去指定buffering parameters。 
RenderResponse接口提供的以下方法，允许 portlet 去操作和设定 buffering 信息。
getBufferSize 
setBufferSize 
isCommitted 
reset 
resetBuffer 
flushBuffer 
    以上方法都由 RenderResponse 接口所提供，允许当 portlet 在使用 OutputStream 或 Writer 时运
行 buffering operations。 
getBufferSize方法回传底层已经使用的 buffer 大小。如果没有任何 buffering 被使用，则回传int 0。 
Portlet可以使用 setBufferSize 方法来要求选择的 buffer 大小。 assigned 的 buffer 大小并不一定得和 portlet 要求的大小相同，但是至少必须等于所要求的大小。这可以使container 重复使用固定大小的 buffers ，提供大于要求的合适大小。此方法必须在任何内容使用 OutputStream 或 Writer 写出之前呼叫。如果已经有内容被写出，则此方法会丟出 IllegalStateException 。 
isCommitted方法回传boolean 值，表示所有回传资料是否已回传到 client 端。 flushBuffer 方法则是将所有在 buffer 内的内容传到 client 端。 
Reset方法是当 response 并未 commit 时清空 buffer 内的资料，且在呼叫 reset 方法之前portlet 设定的 Properties set 必须被清除。 resetBuffer 是当 response 并未 commit 时清除buffer 内的资料。但是并不清除 properties 。
如果 response 被 commit 之后呼叫了 reset 或是 resetBuffer 方法，则必须丟出 IllegalStateException ，而 response 跟其相关的 buffer 不能被更动。。
当使用 buffer 时， container 必须将塞满 buffer 的内容 flush 到 client 。如果这是第一次将资料送到 client ，则 response 必须被视为已经 commit 了。 
PLT.12.3.4 Namespace encoding
在 content 中， portlet 包含的 elements 必须在整个 portal page 中是唯一的值， JavaScript function 和变量就是其中一种例子。 
getNamespace必须提供 portlet 一个方法，以确保回传的字串在整个 portal page 中是唯一的。例如使用 getNamespace 可以取得一个特殊字串，可以用来 prefix 在 portlet 产生的 content 中的 Javascript 变量名称的前面，以确保它在整个 portal page 中是独一无二的。 
getNamespace必须回传由 Java Language Specification Second Edition中3。8 Identifier Section 所定义的合适的 Identifier。 
PLT.12.3.5 Portlet Title

Portlet可以向 portal/portlet-container 提出所 preferred 的 title。是否使用 portlet 所设定 的preferred title ，则是 portal/portlet-container 的责任。 
SetTitle必须在 portlet 写出到 output 之前呼叫， 如果在之后呼叫，则 setTitle 将不会产生任何作用。 
PLT.12.4 Lifetime of Response Objects

一个 response 物件只有在一个特定的 processAction or render 方法里时是有用的。 Containers 通常会循环再利用 response 物件以避免在每次产生 response 物件时， 造成效能上的负担。 开发人员应该注意到若在 processAction or render 方法这两个 scope 之外来维护参照 response 物件时， 可能会造成 non-determisnistic 的反应。

PLT.13 Portal Context

PortalContext 是一个 interface 让 portlet 可以去取得来自 portal 的一些讯息
而 portlet 只能读取 portal 的信息， 不能去修改他
目前提供了以下几个 method。
getPortalInfo()
o 回传一些 Portal 的信息， 例如 Portal 的制造厂商及版本， 如果是我们就要回传 jCharon 1。0 
getProperty(java。lang。String name)
o 依照给的属性名称回传 Portal 的 Properties 设定值， 如果没有该属性则回传 null。 
getPropertyNames()
o 回传 Portal 所有的 Properties 设定值， 传回物件是 Enumeration 
getSupportedPortletModes()
o 回传 Portal 支持哪些 portlet mode， 传回物件是 Enumeration . 
getSupportedWindowStates()
o 回传 Portal 支持哪些 window state， 传回物件是 Enumeration . 
一个 portlet 包含一个 PortalContext 的物件
使用 portlet request 物件的 getPortalContext() 取得该物件

PLT.15 Sessions

在建制一个 portlet application 当中， 要把一个 request 跟某个 client 做关联是很重要的。 有很多的方法来达到 session tracking 的目的， 这包括 HTTP Cookie， SSL Sessions 或是 URL rewriting。 为了能够让程序设计者无须直接应付 session tracking， 在 portlet 中提供了 PortletSession 此 interface 来允许 portlet 或是 portlet container 通过任何方法来追踪使用者 session 而无需开发者去干涉到底层执行的细节。
PLT.15.1 产生 Session

当一个 session 只是能被预期的而非已经建立者， 我们称此 session 为 'new'。 因为 portlet 是被设计来处理 request-response 为基础的协定( HTTP 就是此种类型的典范)在使用者 'join' 一个session之前， 我们都视此 session 为 'new'。 而当使用者通过回传 session tracking 的资料来加入此 session 之后， 此 session 才是真的建立起来。 在 client 加入一个 session 之前， 我们都不能视下一个从此 client 传过来的 request 当作此 session 的一部分。
在下列其中一个成立之下， 我们视此 session 为 'new'
当 client 还不知道此 session 的存在之前 
当 client 选择不要加入此 session 
这些情况定义了 portlet container 不会用任何的机制来关联一个 request 到前一个 request 的情况。 portlet 开发者必须要处理使用者还未， 不可， 或不想加入一个session的情况。
对同一个 portlet application 的所有 portlets 来说， portlet container必须要保证对所有由同一个使用者所发出的 reqeust 要接收或取得同一个 session。 除此之外， 如果在这些 request 之中有不只一个 portlet 产生 session， 这些 session object 必须对所有的 portlet 要是相同的。 
PLT.15.2 Session Scope

Portlet Session必须要是Porlet应用程序环境的层级。
每个 portlet 应用程序的每个使用者都拥有属于自己不同的 PortletSession 物件。 Portlet Container不允许共享不同的 portlet application 或不同的 client 之间的 PortletSession 物件以及存放在其中的属性。 
PLT.15.3 系结属性到 Session

在 Portlet 中我们可以通过 name 来系结一个属性到 session 之上。 在 Portlet 中， PortletSession 定义了 APPLICATION_SCOPE 及 PORTLET_SCOPE 两种scope来存放物件。
若物件存放在 APPLICAITON_SCOPE 的 session， 则此 object 可以被其他在同 portlet application 的 portlet 所存取。
若物件存放在 PORTLET_SCOPE， 则此 object 可被当初存放此物件的 portlet 所存取。 但此物件还是会放在 APPLICATION_SCOPE 的 session 中， 并且以‘javax。portlet。p。<ID>?<ATTRIBUTE_NAME>’。 <ID>的name来做为识別。 而 <ID> 为 portlet windows 的识別， <ATTRIBUTE_NAME> 为此 attribute 的 name。 
Attribute放在 PORTLET_SCOPE 并不是用来保护不被其他 web component 存取， 而仅是为了提共一个方便的 namespace 来使用。 
PortletSession的 setAttribute 此 method 是用来系结一个 object 到一个指定 scope 的 session。 
PortletSession session = request.getSession(true);
URL url = new URL("http://www.foo.com"); 25
session.setAttribute("home.url"，url，PortletSession.APPLICATION_SCOPE);
session.setAttribute("bkg.color"，"RED"，PortletSession.PORTLET_SCOPE);

PortletSession 的 getAttribute 此 method 是用来取得存放在一个 session 中的某个 attribute。 
PortletSession的 removeAttribute 此 method 是用来移除存放在一个 session 中的某个 attribute。
而若要知道物件什么时候从 session 中放入或移除，可以通过执行 HttpSessionBindingListener 来达到目的， 相关内容在 Servlet Specification 有详述。
另外 PortletSessionUtil 提供一些 method 来分辨 object 是存放在哪一个 scope 中的。 
PLT.15.4 跟Web Application HttpSession之间的关系

Portlet Applciation本身也是一个 Web Application. 所以 Portlet Application 中也有可能会有 Servlet 或是 jsp。 Porltet， servlet， jsp可以通过session来分享信息。 
PortletSession存放的资料必须可以通过 HttpSession 取得， 反之亦然。 而当某个 HttpSession 被注销掉 (invalidated)， 对应的 PortletSession 也会被注销掉， 反之亦然。 
PLT.15.4.1 和HttpSession Method的对应

以下几个 PortletSession 的 method 必须以 HttpSession 同名的 method 为基础: getCreationTime， getId， getLastAccessedTime， getMaxInactiveInterval， invalidate， isNew， setMaxInactiveInterval。
   其中getAttribute， setAttribute， removeAttribute， getAttributeNames 必须遵守以下一些原则 :
如果使用 APPLICAITON_SCOPE， 则 attribute names 必须相同。 
如果使用 PORTLET_SCOPE， 则必须遵守特殊的 prefix。 
若使用没有指定 scope， 则等同于使用 PORTLET_SCOPE 
PLT.15.5 保留的HttpSession Attribute Names

以 "javax.portlet。" 开头的 session attribute names 是保留给 Portlet Specification 以及执行 portlet container 厂商所使用的。 Portlet container的厂商可以使用此namespace来来存放执行特有的元件， 因此application developer不可使用用此namespace当做attribute name的开头。 
PLT.15.6 Session Timeout

跟 Servlet Specification 2.3， SRV.7.5 Section 相同。 
PLT.15.7 Last Accessed Times

跟 Servlet Specification 2.3， SRV.7.6 Section 相同. 
PLT.15.8 Important Session Semantics

跟 Servlet Specification 2.3， SRV.7.7.3 Section 相同.

PLT.16 






























PLT.17 User Information

通常来说， portlets 提供个人化的网页设定给予使用者建立一些 reuqest. 为了达到这个功效，他们必须取得使用者的一些属性例如使用者的姓名， email， 电话及地址。 Portlet container　提供一个机制去陈列出使用者的属性给予 portlets　使用。 
PLT.17.1 Defining User Attributes

portlet application中的　deployment descriptor　必须定义 portlets　会使用到的 user　属性，　
下面是一个定义的范例： 
<portlet-app>
…
<user-attribute>
<description>User Given Name</description>
<name>user.name.given</name>
</user-attribute>
<user-attribute>
<description>User Last Name</description>
<name>user.name.family</name>
</user-attribute>
<user-attribute>
<description>User eMail</description>
<name>user.home-info.online.email</name>
</user-attribute>
<user-attribute>
<description>Company Organization</description>
<name>user.business-info.postal.organization</name>
</user-attribute>
…
<portlet-app>
deployer　必须对应到 portlet application　的使用者属性，　去符合 runtime　环境的使用者属性。 在 runtime　环境中， portlet container　使用这对应表去陈列使用者属性给予 portlet application　中的　portlets. runtime　环境中的使用者属性如果无法对应到 deploytment 中就不允许给予 portlet　取得。
可以参考附录中的 PLT.D User Information Attribute Names 里面有属性列表。 
PLT.17.2 Accessing User Attributes

Portlets可以包含一个不可修改的使用者属性 Map Object， 目前这个 request　和使用者相关的一些属性。 这个 Map Object 可以通过 USER_INFO 解析定义在 PortletRequest　interface　之中。　假如在 context 被没有认证(un-authenticated)过的使用者执行 request ，　呼叫 USER_INFO 常量的　getAttribute method　将会回传 NULL。　假如这个使用者被认证过 ( authenticated ) 且没有可获得的任何使用者属性， Map 则是一个空(empty)的 Map。 Map Object 中的 user attribute 必须包含一个 String 名称-数值 (name-value) pair。 Map object 应该只有包含使用者属性对应到 deployment 。
简单的 portlet　解析使用者属性的程序应该如下： 
...

Map userInfo = (Map) request.getAttribute(PortletRequest.USER_INFO);

String givenName = (userInfo!=null) ? (String) userInfo.get(“user.name.given”) : “”; 15

String lastName = (userInfo!=null)? (String) userInfo.get(“user.name.family”) : “”;

...

PLT.17.3 Important Note on User Information

Portlet规格制作群担心使用者资料制定超过了这份规格书的范围。 目前没有标准的 Java 标准去存取使用者资料，　也没有相关的 Java 标准正在定义，　所以 Portlet　规格书将提供这个机制， 也让 Portlet API　不要被认为是太多管闲事。 未来只要有相关的 Java 使用者信息的标准被制定，　现在这个机制将会失效 ( deprecated )。


PLT.18 Caching

Caching content 将减少 Portal 回应给使用者的时间。 他也减低了 server 的负载量。 Portlet 规格书定义了基于 caching 机制的一个过期( expiration ) 的时间值。 Caching 机制是属于每个使用者每个 portlet。 Cached content 不允许分享相同 portlet 显示给予不同的使用者。 Portlet container 不需要去执行 expiration caching。 Portlet containers 执行这 caching 机制可能去取消他， 为了内存资源在任何时间可以作部分取消或全部取消。 

PLT.18.1 Expiration Cache

Portlets希望他们的内容可以被 cached 使用 expirtation cache 必须定义 expiration cache 的期间(秒) 在 deployment descriptor。
以下是一个定义 5 分钟(300秒)的范例 ：
...
<portlet>
...

<expiration-cache>300</expiration-cache>

… 
</portlet>
...

在 portlet 定义的 expiration cache 可以通过程序化地修改 expiration 时间， 只要使用在 PortletResponse 接口中 RenderResponse ， 调整 EXPIRATION_CACHE 这个参数。如果 expiration 属性值设为 0， 这个 portlet 的 caching 将被取消。 而 expiration 的属性值设为 -1， 则这个 cache 将永远存在。 假如一个 render 的呼叫 expiration cache 属性却没有设定， 那么 expiration 的时间将会根据 deployment descriptor 中的定义。 为了没有在 deployment descriptor 定义 expiration cache 参数的 portlet， 假如又去设定他的 expiration cache， portlet container 必须去忽视他。

假如 portlet content 被 cahced， 那么 cache 将不会 expired 而且那 portlet 不是使用者 request 的目标， 所以 portlet 的 request 处理方式不应该呼叫成为 client request 的一部份。 换句话说， portlet container 就应该要由 cache 取出资料。 假使 portlet content 是被 cached， 但是 client request 的目标是相同的 portlet， 则 portlet-container 应该不要理会 cache 的值， 必须重新呼叫 request 要求执行 portlet 中的method。

PLT.19 Portlet Applications

一个 portlet application 就是一个 web application， 就如同定义在 Servlet Specification 2.3， SRV.9 章节， 包含了 portlets 及一个 portlet deploytment descriptor ( portlet.xml ) 附加一些 servlets， JSPs， HTML pages， classes 及other resources 都会在一般的 web application 看到相似的东西。 一个包装好的 portlet application 可以在执行多任务的 portlet containers 中执行。 
PLT.19.1 Relationship with Web Applications

所有的 portlet application　元件和资源文件( resources )　除了 portlets，　是被 servlet container 所管理， portlet container　也是建置在 servlet container　之上。 
PLT.19.2 Relationship to PortletContext

portlet container必须强制　portlet application　和 PortletContext　是一对一的对应关系。　假如这个 application　是分布式的 application， portlet container 必须对每个 VM 建立一个 instance。 PortletContext object 将提供给 portlet application 一个具有 view 端呈现的 portlet。 
PLT.19.3 Elements of a Portlet Application

Portlet application可能包含了一些 portlets 加上其他可以放在 web application 的元素， 例如 servlet， JSP pages， classes， 静态的文件。　除了 web application 规定的 meta 信息， portlet application　必须包含一个 descriptive meta information 去描述 portlet 所包含的东西。 
PLT.19.4 Directory Structure

Portlet application允许和 web application 具有相同的目录结构。　除此之外，　他必须包含 /WEB-INF/portlet。xml　这个 deployment descriptor 档案。　Portlet classes， utility classes 及其他 resources accessed 通过 portlet application classloader必须摆放在 /WEB-INF/classes 目录或包装在　/WEB-INF/lib/　目录下的 JAR 档案。 
PLT.19.5 Portlet Application Classloader

Portlet container必须和 servlet container 给 web application 使用的相同的 classloader 去载入 portlets 及 portlet application 相关的资源 ( resources )， portlet container 必须确认定义在 Servlet Specification 2.3 SRV.9.7.1 and SRV.9.7.2 章节中的需求。 
PLT.19.6 Portlet Application Archive File

Portlet applications是被包装成 Web Application Archives (WAR)， 可以查看 Servlet Specification 2.3 SRV.9.6 章节。 
PLT.19.7 Portlet Application Deployment Descriptor

除了 web application 有个 deployment descriptor ( web.xml ) ，Portlet application也有一个 portlet application deployment descriptor (portlet.xml)。 portlet deployment descriptor 包含了一些 portlets 的设定信息。 

可以参考PLT.21 Packaging and Deployment Descriptor 这个章节会有详细的说明。 
PLT.19.8 Replacing a Portlet Application

Portlet container应该能够置换新版本的 portlet application ， 而不用重新启动 container。 此外， 在置换 porlet application 的同时， portlet container 应该提供一个穩定安全的方法去存放在 portlet application 之中的 session data 。 
PLT.19.9 Error Handling

这是留给执行 portal/portlet-container 如何作出当 portlet 接到一个 request 后丟出一个exception。 例如 portal/portlet-container 可以产生一个错误页面去代替原本的 portal 页面， 或是产生一个错误讯息在 portlet window， 甚至可以从 portal 页面中移除该 portlet 只要记录 log 讯息提供给 administrator 查询。 
PLT.19.10 Portlet Application Environment

Portlet Specification利用了许多Servlet Specification 2.3 SRV.9.11 制定好的规格。


PLT.20 Security

不同的 developer 做出不同的 Portlet applications， 但是可能都是由同一个 deployer 来作部署的动作， 因此 developer 需要告诉 deployer 该如何设定相关的 security。
   
PLT.20.1 Introduction

一个 portlet application 包含了许多可以被存取的资源， 但是在公开的环境中， security 的需求就相对重要。 portlet container 将通过 user 的 role 来决定是否给予 user 存取该 portlet。 portlet container 不需要处理 user 的 authetication ( 就是不需要检查登录检查机制 )， 而 authetication 应该是在 servlet container 所处理的， 定义在 Servlet Spec 2.3 ， SRV.12.1 Security。

附注： Servlet Specification 2.3 Security 的特性。
Authentication(身份验证): 提供身份的验证。 
Access control for resources(资源的控制权): 资源仅仅提供给予特定的族群使用。 
Data Integrity (资料的完整): 保证传送中的资料不会被修改。 
Confidentiality or Data Privacy(机密或资料隐私): 只有具权限的使用者使用该资料。 
在 Servlet security 的机制中， 提供了 3 个 method 来验证身份及权限
getRemoteUser : 得到form 传来的 j_username ， 如果没有通过 authetication， 则回传 null 。 
isUserInRole : 

http://jakarta.apache.org/tomcat/tomcat-4.1-doc/realm-howto.html 
http://jakarta.apache.org/tomcat/tomcat-4.1-doc/security-manager-howto.html
http://java.sun.com/webservices/docs/1.3/tutorial/doc/Security.html
getUserPrinciple : 
回传user java.security.Principle资料， 如果没有通过 authetication， 回传 null。 
http://java.sun.com/j2se/1.4.2/docs/api/java/security/Principal.html
http://java.sun.com/j2se/1.4.2/docs/guide/security/index.html 
PLT.20.2 Roles

和 Servlet 2.3 SVR12.4 定义的是一样的 
PLT.20.3 Programmatic Security

其运行时和 Servlet 一样也是提供相同的 methods 
getRemoteUser， isUserInRole， getUserPrinciple

而且也可以在 portlet 的 element 中增加 security-role-ref 
<portlet-app>
...
<portlet>
...
<security-role-ref>
<role-name>FOO</role-name>
<role-link>manager</role-link>
</security-role-ref>
</portlet>
...
...
</portlet-app>

PLT.20.4 Specifying Security Constraints

Portlet也有一些特殊的 elements 可以设定 。portlet collection可以设定哪些 portlets 是被保护的， 这些 portlets 给予哪些群组才可以使用。 

user data constaint可以设定例如 SSL 来保证资料的完整性。 
<portlet-app>
...
<portlet>
<portlet-name>accountSummary</portlet-name>
...
</portlet>
...
<security-constraint>
<display-name>Secure Portlets</display-name>
<portlet-collection>
<portlet-name>accountSummary</portlet-name>
</portlet-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
...
</portlet-app>
PLT.20.5 Propagation of Security

因为 Portlet 属于 J2EE 的其中一个部分， 当 portlet application 呼叫 EJB 的时候 ， user的 security 身份应该由 portlet container 传递到 EJB container。 

所以需要在 web.xml 设定相关的 security 机制， 才能让 EJB container 认得这份 security identity。 

另外可能的方法就是让 portlet application单独登录 EJB 来作程序开发。


PLT.22 Portlet Tag Library

portlet tag library 可以放在 JSPs 的档案之中去直接存取 portlet 特殊的元素，
例如 RenderRequest 及 RenderResponse。
他也提供了 JSPs 去存取 portlet 的一些功能如 portlet 的 URLs。 
Portlet container必须提供 portlet tag library 的执行。 Portlet 的开发人员可以使用定义在 JSP Specification 1.2 中 JSP.7.3.9 Well-Know URIs 的机制来执行。

而 JSP 该如何使用 tab library 呢 ? 如同下面的程序码 

<%@ taglib uri=”http://java.sun.com/portlet” prefix=”portlet” %>
PLT.22.1 defineObjects Tag

defineObjects tag必须定义以下的变量让 JSPs 可以使用
RenderRequest renderRequest 
RenderResponse renderResponse 
PortletConfig portletConfig 
这些变量必须参照 Portlet API 的物件并且放在 request scope 的物件中 ( 定义在 PLT.16.3.1 Included Request Attributes 章节 )

一个 JSP 程序中可以通过 scriptlet 利用到 defineObjects tag 在所有的地方。
defineObjects tag不可以定义任何属性， 也不可以包含任何 body content。

简单的 JSP 范例如下 

<portlet:defineObjects/>
<%=renderResponse.setTitle("my portlet title")%>

这就是通过 defineObjects tag， JSP 可以呼叫 renderResponse 的 setTitle() 去设定 portlet 的标题。 
PLT.22.2 actionURL Tag

portlet中 actionURL 是为了建立一个 URL 可以链结到目前的 portlet 并且可以通过带有参数的 request 动作去驱动。
而 URL 的传递参数必须使用 param tag 放在 actionURL 的起始以及结束的 tag 之间。
windowState ( 形态： String， 非必要的) 
当这个 link 被执行的时候， 这个 portlet windowState 应该要执行的动作。 预先设定的 windowState 有 minimized， normal， 以及 maximized 。 假如这些标准的视窗状态在这个 request 是非法的， 应该就要丟出 JspException。 非法的理由有可能是 portal 不支持这些状态， portlet 无法宣告他们在 Deployment Descriptor 之中让 portal 支持这些状态， 或是现在这个使用者不被允许使用到这些状态。 假如视窗状态不能让 URL 设定， portlet 将待在和现在这个 request 相同的状态。 WindowState 的属性应该是不分大小写的。
portletMode (形态: String， 非必要的) 
假如当这个 link 被执行的时候没有错误发生， 这个 portlet 应该要具备的 mode。 预先设定的 portlet mode 有 edit， help， 以及 view 。 假如这些标准的 portlet mode 在这个 request 是非法的， 应该就要丟出 JspException。 非法的理由有可能是 portal 不支持这些 mode， portlet 无法宣告他们在 Deployment Descriptor 之中让 portal 支持这些 mode， 或是现在这个使用者不被允许切换到这些 mode 。 假如 portlet mode 不能让 URL 设定， portlet 将待在和现在这个 request 相同的 mode 。 PortletMode 的属性应该是不分大小写的。
var (形态: String， 非必要的) 
为了 action URL 输出到某个 scope 变量的名称。 这输出到 scope 的变量名称应该是 String。 预设 URL 执行是把结果写到现在这个 JspWriter。 假如结果输出成为 JSP 的 scope 变量， 通过 var 的属性定义， 将不会有任何东西写到现在这个 JspWriter。
注意: 在 URL 被建立之后， 将不可能利用变量和 String 串联去 extend 那 URL 或增加任何更多的参数值。 假如被给定的参数名称已经存在在这个 page 的 scope 或他已经被使用在一个重复的迴圈中， 新的属性值将覆盖旧有的。
secure (形态: String， 非必要的) 
假如结果的 URL 必须是 secure 的链结 ( secure="true" ) 或一个 insecure one ( secure="false")。 假如 run-time 环境不支持标准的安全性设定， 将会丟出 JspException。 假如这 URL 没有设定任何 security， 他必须待在和现在 request 相同的 security 设定。
 
JspException具有 PortletException 将产生一些错误视为 root 产生会丟出以下的状况。
If an illegal window state is specified in the windowState attribute。 
If an illegal portlet mode is specified in the portletMode attribute。 
If an illegal security setting is specified in the secure attribute。 
以下是一个使用 actionURL tag 的例子 
<portlet:actionURL windowState=”maximized” portletMode=”edit”>
<portlet:param name=”action” value=”editStocks”/>
</portlet:actionURL>
这个范例是建立一个 URL 将让 portlet 进入 EDIT 的状态并且 window state 最大化 ( MAXIMIZED )的去编辑股票报价列表。 
PLT.22.3 renderURL Tag

portlet中 renderURL 是为了建立一个 URL 可以链结到目前的 portlet 并且可以通过带有参数的 request 动作去驱动。

而 URL 的传递参数必须使用 param tag 放在 renderURL 的起始以及结束的 tag 之间。
windowState ( 形态: String， 非必要的) 
当这个 link 被执行的时候， 这个 portlet windowState 应该要执行的动作。 预先设定的 windowState 有 minimized， normal， 以及 maximized 。 假如这些标准的视窗状态在这个 request 是非法的， 应该就要丟出 JspException。 非法的理由有可能是 portal 不支持这些状态， portlet 无法宣告他们在 Deployment Descriptor 之中让 portal 支持这些状态， 或是现在这个使用者不被允许使用到这些状态。 假如视窗状态不能让 URL 设定， portlet 将待在和现在这个 request 相同的状态。 WindowState 的属性应该是不分大小写的。
portletMode (形态: String， 非必要的) 
假如当这个 link 被执行的时候没有错误发生， 这个 portlet 应该要具备的 mode。 预先设定的 portlet mode 有 edit， help， 以及 view 。 假如这些标准的 portlet mode 在这个 request 是非法的， 应该就要丟出 JspException。 非法的理由有可能是 portal 不支持这些 mode， portlet 无法宣告他们在 Deployment Descriptor 之中让 portal 支持这些 mode， 或是现在这个使用者不被允许切换到这些 mode 。 假如 portlet mode 不能让 URL 设定， portlet 将待在和现在这个 request 相同的 mode 。 PortletMode 的属性应该是不分大小写的。
var (形态: String， 非必要的) 
为了 render URL 输出到某个 scope 变量的名称。 这输出到 scope 的变量名称应该是 String。 预设 URL 执行是把结果写到现在这个 JspWriter。 假如结果输出成为 JSP 的 scope 变量， 通过 var 的属性定义， 将不会有任何东西写到现在这个 JspWriter。
注意: 在 URL 被建立之后， 将不可能利用变量和 String 串联去 extend 那 URL 或增加任何更多的参数值。 假如被给定的参数名称已经存在在这个 page 的 scope 或他已经被使用在一个重复的迴圈中， 新的属性值将覆盖旧有的。
secure (形态: String， 非必要的) 
假如结果的 URL 必须是 secure 的链结 ( secure="true" ) 或一个 insecure one ( secure="false")。 假如 run-time 环境不支持标准的安全性设定， 将会丟出 JspException。 假如这 URL 没有设定任何 security， 他必须待在和现在 request 相同的 security 设定。 
JspException
具有 PortletException 将产生一些错误视为 root 产生会丟出以下的状况。
If an illegal window state is specified in the windowState attribute。 
If an illegal portlet mode is specified in the portletMode attribute。 
If an illegal security setting is specified in the secure attribute。 
以下是一个使用 renderURL tag 的例子
 
<portlet:renderURL portletMode=”view” windowState=”normal”>
<portlet:param name=”showQuote” value=”myCompany”/>
<portlet:param name=”showQuote” value=”someOtherCompany”/>
</portlet:renderURL>

这个范例将产生一个 URL 去提供一个 link 可以去显示公司其他公司的股票报价及改变 portlet mode 成为 VIEW 并且将 window state 改成 NORMAL。 
PLT.22.4 namespace Tag
这个 tag 产生一个目前 portlet 中唯一的数值。
这个 tag 应该被 named elements 使用在 portlet 的输出， 例如 javascript 的功能或变量。 而 namespacing 就是确认给定的名称是这个 portlet 唯一的值， 是避免名称重复影响了其他 portal 的 element 以及这一页的其他 portlets。 
namespace tag
不允许任何 Body Content。
以下是一个使用 namespace tag 的例子 
<A HREF=”javascript:<portlet:namespace/>doFoo()”>Foo</A>
这个范例预先设定 javascript function 加上 namescape + 'doFoo'， 以确认这个功能在portal page 中是唯一的。 
PTL.22.5 param Tag
这个 tag 是定义一个参数值， 可能是放在 actionURL 或 renderURL 之中。 param Tag 不准包含任何 Body Content。
下面是 param Tag 一些必要的属性
name (形态: String， 必要的) 
增加在 URL 之中参数的属性名称。 假如 name 是空值 (NULL) 或 空白字串 ( empty )， 将不会执行任何动作。
value (形态: String， 必要的) 
增加在 URL 之中参数的属性值。 假如 value 是空值 (NULL) 他将视同空白字串 (empty) 处理。
以下是一个使用 param tag 的例子 

<portlet:param name=”myParam” value=”someValue”/>


PLT.B Markup Fragments

portlets 产生的 markup 片段将被结合在一份 portal page 里，因此 portlets 生成这些内容时必须遵守一些规则和限制。

以下所列不允许的 tags，是会影响到其他 portlet 产生的片段，甚至破坏整个 portal page 结构的 tags。markup 片段里含有这些 tag 将使整个片段无效。

若 portlets 产生的是 HTML 片段，不可使用以下 tags: base、body、iframe、frame、frameset、head、head、html、title。

若产生的是 XHTML 和 XHTML-Basic 片段，不可使用以下 tags: base、body、iframe、head、html、title。 

HTML、 XHTML 和 XHTML-Basic 的标准不允许某些元素用在 head 之外的地方，但有些浏览器允许这些元素用在其他地方。例如目前版本的 Internet Explorer 和 Netscape Navigator 都支持 style 用在文件的任何地方。portlet 开发者必须对使用以下符合本段描述的元素作谨慎的决定：link、meta、style。


PLT.C CSS Style Definitions

CSS 与 icon 的设计对于一个 Portal 来说就是更换 skin 的方式 jCharon会设计一个 Web Application， 暂时命名为 jCharonDesigner 

jCharonDesigner的目标就是让 Designer 可以快速地编写合适的 css 及 icon将他做成 zip 档案， 让工程师放到 skin 之中使用

不过， 该如何设计 CSS Style ?!

我们就需要先了解 JSR 168 做了哪些规范 
PLT.C.1 Links (Anchor) 链结文字

Spec并没有对 <a> tag 做特殊的 class 定义。 
PLT.C.2 Fonts 一般文字
Style	解释
portlet-font	一般最常使用的文字
portlet-font-dim	比正常文字更淺色一點的文字

如果开发人员需要放大縮小该文字

则是自行使用 

<div class="portlet-font" style="font-size:larger" > Important Information </div>
或 

<div class="portlet-font-dim" style="font-size:80%"> Small and Dim </div>
PLT.C.3 Messages 讯息文字

讯息文字通常会放在 paragraph (段落) 之中

往往是执行某个事件后产生的讯息文字

常常设定的 css 参数有 alignment (靠齐)， borders(宽度)， 及 background color(背景顏色) 等等属性 


Style	解释
portlet-msg-status	目前状态的讯息， 例如 "80%"
portlet-msg-info	辅助的信息讯息， 一般附加讯息， 例如 "关于xxx 请查阅 aaaa"
portlet-msg-error	错误讯息， 例如 "系统发生 404 错误"
portlet-msg-alert	警告讯息， 例如 "目前系统忙碌中， 请稍后链结"
portlet-msg-success	成功讯息， 例如 "你已经轉帳成功"
	
PLT.C.4 Sections 区块

section (区块)可能是由 table 或 div 所组成的
常常设定的 css 参数有 alignment (靠齐)， borders(宽度)， 及 background color(背景顏色) 等等属性 

Style	解释
portlet-section-header	section 表头文字
portlet-section-body	section 内文文字
portlet-section-alternate	section 交换文字， 通常用在奇数偶数列互换时候
portlet-section-selected	section 被选择到的文字， 通常用在 OnMouseOver 或要特別标示某一列时候
portlet-section-subheader	section 次表头文字， 有时候会有两个表头， 例如上方或左方都是表头的时候
portlet-section-footer	section 表尾文字， 表单结束通常会有一些附加文字
portlet-section-text	说明这个 section 到底在干麻的文字， 可能在这个 table 的上方或右下角等等
PLT.C.5 Forms
Style	解释
portlet-form-label	form 所有元素(elements)预设的标签文字
portlet-form-input-field	使用者输入的内容文字
portlet-form-button	按钮上的文字
portlet-icon-label	圖示旁邊的标签文字
portlet-dlg-icon-label	标准圖示 ( 例如"确定"， "取消") 旁邊的标签文字
portlet-form-field-label	如 checkbox， radio 等等的标签文字
portlet-form-field	和 portlet-form-input-field 不同， 不是输入内容 (input field)， 而是如 checkbox 前面的那些 □ 或 ○
PLT.C.6 Menus

选单， 大陆称为 "菜单"

可能会是左方的控制选单或 PopupMenu (浮动选单) 甚至是 TreeMenu (树状选单)， TabMenu (标签选单) 等等的样式

各种 Menu 可以参考 Java Opensource Newspaper 第 33 期-Struts 系列 I - StrutsMenu

或是直接链结 Struts-Menu 有更新的版本介绍 


Style	解释
portlet-menu	一般的选单， 定义他的背景顏色， 间距等等
portlet-menu-item	一般没有被选择到的选单元件
portlet-menu-item-selected	被选择到的选单元件
portlet-menu-item-hover	一般不是被选择到的选单元件， 当鼠标移到上面的时候呈现样式
portlet-menu-item-hover-selected	被选择到的选单元件， 当鼠标移到上面的时候呈现样式
portlet-menu-cascade-item	一般不是被选择到的选单元件， 但是具有次选单的样式
portlet-menu-cascade-item-selected	被选择到的选单元件， 但是具有次选单的样式
portlet-menu-description	选单的说明， 可能是在下方对这选单做一些解释
portlet-menu-caption	选单的标题， 可能在上方对于这选单做标题说明