portlet规范笔记

Portlet规范笔记

一、Portlet什么周期
    1、Loading and instantiation
Portlet container负责装载和实例化portlet，装载和实例化过程发生在portlet容器启动portlet application时，或者延迟到容器决定portlet需要处理一个请求时。
Porlet 容器必须使用同一个calssloader来装载portletclass，之后容器初始化portlet
    2、初始化
实例化portlet对象后，容器在调用potlet处理请求之前必须初始化portlet。Portlet容器调用portlet对象的init方法来初始化，一般是初始化一些代价高的资源和执行一些一次性的操作。
初始化中出现异常，抛出unavailableException 或者portletException的话，portlet容器不会发布这个portlet，destory方法也不会调用。容器可能会在错误发生后在制定的任何时候重新实例化和初始化porlte，初始化中抛出的runtimeexception必须作为portletexception来处理。
    3、portal window
The portlet definition 可能包含一些默认值的参数属性。他们被用来创建perferences objects。
at runtime，当处理一个请求时，a portlet object和一个prefenrences object，一般一个portlet是在关联的参数对象的属性的基础上自定义它的行为和内容的。
默认一个参数对象使用在部署描述符里定义的初始参数值来构建。
    4、请求处理
Porlet接口提供了两个方法来处理request，processAction和render方法。
调用ProcessAction的请求称为action request，调用render的请求成为render quest。
一般,客户端请求是通过portles创建的url来触发的，portlet url分为action url和render url两种。
当客户端发起一个action url是，容器先调用portlet的processaction，处理完成之后再调用portal页面里所有的除了被缓存里的portlet的render方法。当客户端发起一个render url时，只调用render方法，不包括已经缓存的portlet
Action request
Processaction方法有actionrequest和actionreponse两个参数
ActionRequest提供一些actionrequest 的parameters、window state、portlet mode，portal context、portlet session、portlet preferences的信息。
ActionResponse可能用来修改portlet mode和portlet window state
在processaction里修改的状态和权限必须在后续的render请求里生效。
Render request
两个参数RenderRequest，RenderResponse
RenderRequest的功能类似ActionRequest，RenderRequest使用writer或者代理给jsp或servlet来产生portlet 的content。
GenericPortlet类提供了一些处理render request的默认功能和便利的方法。它的render方法根据portlet配置文件指定的portlet title然后调用doDispatch方法。doDispatch方法根据portlet mode调用相应的方法（doView，doEdit，doHelp）；如果window state是minimized（最小化）时，这个render方法就不调用任何方法。
对线程处理requset
Portlet容器通过在不同的线程上的并发运行来处理同一个portlet的多个并发请求。
处理请求时的exception
A portlet可能会在处理请求时抛出PortletException、PortletSecurityException或者UnavailableException
Portletexception发生时，容器应该clean up request，如果在processaction中抛出此异常，actionresponse的所有操作都必须忽略，并且不调用render方法，但是容器应该继续处理portal page其他的portlets。
UnavailableException指portlet临时或永久不能处理reqeust，如果是永久的话，portlet容器必须立即删除从服务里删除portlet，调用destroy方法然后释放porlet对象。当临时抛出此异常时，容器在临时异常期间可能不会将请求路由到portlet。Portlet可能不会区分这两种unavailableexception，可能都会将其看待为永久性的unavailableexception。
  A RuntimeException must be handled as a PortletException.
当一个portlet抛出异常时，容器可能会在portal page里包含一个恰当的错误消息
线程安全
。。。
End of service
当portlet容器决定要把一个portlet从服务里删除时，容器会调用portlet的destroy方法，释放一些资源，保存一些持久性状态。在调用destroy方法之前，应该等待正在处理portlet请求的其他线程处理完毕，可以预定义等待的时间。
一旦destroy方法调用后，容器就不处理所有被删除的portlet的请求。如果在destroy里抛出任何的runtimeException，应该视为destroy成功。

二、portlet config

<portlet>
<portlet-info>
<title>Stock Quote Portlet</title>
<short-title>Stock</short-title>
<keywords>finance,stock market</keywords>
</portlet-info>
<resource-bundle>com.foo.myApp.QuotePortlet</resource-bundle>
</portlet>

三、portlet url
PortletURL通过调用RenderResponse的createActionURL和createRenderURL来创建。

PortletURL url = response.createRenderURL();
url.setParameter(“customer”,”foo.com”);
url.setParameter(“show”,”summary”);
url.setWindowState(WindowState.MAXIMIZED);//设置window state
writer.print(“<A HREF=\””+url.toString()+”\”>Summary</A>”);

setSecure方法将url指示是否是安全的url（https or http），如果未设，就和当前请求的安全级别一样。

四、portlet modes

<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>

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

六、portlet context
初始化参数的访问和servletContex具有同样的效果。和ServletContext功能类似，portletcontext的属性在servletcontext里可见

七、portlet request
    7.1Request parameters
1、容器实现参数必须经过encode
2、容器must not 在action request中将参数传播到后续的render request中，如果需要，使用processAction中actionResponse对象的setRenderParameter or setRenderParameters方法
3、如果一个portlte接受一个客户端请求到portal page的另一个portlet的结果的render request的时，参数和之前的render request的一样。
如果是从一个render request到一个action request时，render request的参数必须设置在action request的render parameters，确保参数在多个render request 里传播。
4、Commonly, portals provide controls to change the portlet mode and the window state of portlets. The URLs these controls use are generated by the portal. Client requests triggered by those URLs must be treated as render URLs and the existing render parameters must be preserved.
    7.2extra request parameters
容器的实现可能会在portlet url中增加一些extra parameters，用来帮助容器来路由和处理客户端请求。Extra parameters必须对接受请求的portlet不可见。容器应适当的对extra parameters编码来避免名字冲突。
    7.3 request attributes
Request Attributes能够在通过portletrequestdispatcher添加的jsp和servlet中共享使用。
    7.4request properties
The header of http client request through the following methods of methods of the portletrequest interface。
    7.5request context path
If the portlet application is rooted at the base of the web server URL namespace (also known as "default" context), this path must be an empty string.lviii Otherwise, it must be the path the portlet application is rooted to, the path must start with a '/' and it must not end with a '/' character.
    7.6 security attributes
getAuthType
getRemoteUser
getUserPrincipal
isUserInRole
isSecure
    7.7Response Content Types
getResponseContentTypes容器支持的文本类型
    7.8 internationalization
getLocale
    7.9portlet mode
getPortletMode
    7.10window state
getWindowState
ActionRequest Interface
Extends PortletRequest,增加了对request input stream 的访问
获取uploaded data，getPorletInputStream,getReader
RenderReqeust interface
Extends PortletRequest interface,为定义任何额外的方法。
Request object 的lifetime
每个reqest object在processAction或者render方法调用是有效。

八、Portlet Reponse
PorletResponse接口定义了ActionResponse和RenderResponse的通用功能。ActionResponse接口继承portletresponse接口，此接口可以redirect another url，set render parameters,change the window state of the portlet and change the protlet mode of portlet。
setPortletMode, setWindowState, setRenderParameter or setRenderParameters必须在sendRedirect方法之前设置，否则抛出IllegalStateException，setContentType在getWriter之前设置，否则也会抛出同样的异常。同样setBufferSize应在写入out流之前调用。
Life time同样也只在processAction和render方法调用时存在。
九、portal context
The PortalContext interface provides information about the portal that is invoking the portlet.
十、portlet preferences
。。。
十一、Session
Each portlet application has its own distinct PortletSession object per user session.The portlet container must not share the PortletSession object or the attributes stored in it among different portlet applications or among different user sessions
APPLICATION_SCOPE同一application内的portlet共享，PORTLET_SCOPE单个portlet的session，PortletSession必须存储portlet application所有httpsession里的attributes，portlet application范围的portletsession存储的data在httpsession里是可以访问的。如果httpsession对象被废弃，那么portletsession对象必须也被容器废弃；如果portletsession对象被一个portlet废弃，那么portlet容器必须废弃相关的httpsession对象。

十二、Dispatching Requests to Servlets and JSPs
PortletContext调用getRequestDispatcher或getNamedDispatcher来获得portletRequestDispatcher对象，
十三、User infomation
Portlet application部署描述符必须定义portlet使用的user attribute名字，获得用户信息代码示例如下：

<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>

Map userInfo = (Map) request.getAttribute(PortletRequest.USER_INFO);
String givenName = (userInfo!=null)
(String) userInfo.get(“user.name.given”) : “”;

十四、Caching
caching机制是一个用户客户端一个portlet，缓存的内容不能跨不同的显示相同portlet的用户客户端共享。
十五、Portlet application
构建portlet容器之上的servlet容器管理portlet application components and resources而不是portlets；每个portlets application和porletcontext是一对一的关系，如果是分布式的application，portlet容器必须在每个jvm中创建一个实例；目录结构遵循web application的目录架构，但是多一个portlet.xml文件；portlet容器必须使用servlet容器使用的web application resources的同一个classloader来装载portlets和相关的资源；portlet application也打包成war文件；portlet容器应该可以在无需重启的情况下来更新portlet application；
十六、安全