IBM portlet API.docx
《IBM portlet API.docx》由会员分享，可在线阅读，更多相关《IBM portlet API.docx（41页珍藏版）》请在冰豆网上搜索。
IBMportletAPI
IBMportletAPI
概述
本主题简单概述了IBMportletAPI。
不推荐使用该API，并且本主题仅为尚未迁移到标准portletAPI的portlet提供支持内容。
抽象Portlet类是IBMportletAPI的核心抽象。
Portlet类扩展ServletAPI的HTTPServlet。
所有portlet间接地扩展此抽象类，且从HttpServlet继承，如下所示：
...+--javax.servlet.http.HttpServlet
|
+--org.apache.jetspeed.portlet.Portlet
|
+--org.apache.jetspeed.portlet.PortletAdapter
|
+--com.myCompany.myApplication.myPortlet
因此，portlet是特殊类型的servlet。
这种类型的servlet的属性使它们能容易地插入并在门户网站服务器中运行。
与servlet不同，portlet不能直接发送重定向或错误到浏览器，转发请求，或者写任意的标记到输出流。
portlet容器依赖于WebSphereApplicationServer实现的J2EE体系结构。
结果是，portlet按类似于J2EEWeb应用程序的方式封装，并按类似于servlet的方式部署。
总之，与servlet相比，可更加动态地管理portlet。
可在不启动和重新启动门户网站服务器的情况下，应用以下更新：
∙可使用门户网站管理用户界面安装和除去由几个portlet组成的portlet应用程序。
∙portlet的设置可由有适当访问权的管理员更改
∙可使用管理portlet动态创建和删除portlet。
例如，一旦管理员创建新的剪切，剪切portlet就可用于创建新的portlet实例。
portlet容器依赖于WebSphereApplicationServer实现的J2EE体系结构。
结果是，portlet按类似于J2EEWeb应用程序的方式封装在WAR文件中，并按类似于servlet的方式部署。
与其他servlet相似，要使用servlet部署描述符（web.xml）把portlet定义到应用程序服务器。
这个文件定义portlet的类文件和只读初始化参数。
下图显示部署了其WAR文件之后的portlet。
对于门户网站服务器上部署的每个portlet，它在应用程序服务器上创建一个servlet或者portlet类实例。
初始化参数是由portlet开发者设置的，并可由portlet使用PortletConfig对象读取。
servlet部署描述符可以包含多个Web应用程序，每个Web应用程序由元素定义。
此外，每个servlet定义可以指向同一portlet类文件，这样可为每个portlet类实例使用不同的初始化参数，创建不同的PortletConfig对象。
有关更多信息，请参阅Web应用程序部署描述符。
portletAPI概念
下图显示创建portlet，在页面上放置portlet和用户访问portlet时portlet的不同变化。
注意，前两个步骤涉及使用持续数据，但对于第三个步骤，数据只在会话持续时间内可用。
门户网站管理员使用管理界面来部署新的portlet应用程序WAR文件或安装portlet的副本。
这两个操作都创建一个具体portlet，这是由单个PortletSettings对象参数化的portlet。
每个portlet可能具有许多具体portlet。
PortletSettings是具有读/写访问权，并是持久的。
PortletSettings包含最初在portlet部署描述符中定义的配置参数。
使用具体portlet能在不创建另外的portlet类实例的情况下，运行许多portlet不同配置的实例。
在单个portlet的生命周期期间，可创建和销毁许多具体portlet。
无明确代表具体portlet的对象。
可在许多用户之间共享同一个具体portlet。
用户或管理员把portlet放到页面上。
这创建一个具体portlet实例，这是由单个PortletData对象参数化的具体portlet。
每个具体portlet可能具有许多具体portlet实例。
PortletData存储已添加到页面的portlet的持久信息。
例如，用户可以编辑股票报价portlet，并可保存股票符号的列表以供公司跟踪。
PortletData的作用域取决于具体portlet所在的页面的作用域。
1.如果管理员把具体portlet放到组页面，那么PortletData对象包含为用户的组存储的数据。
这将为对页面具有查看访问权的用户组保留为真。
然而，如果用户对组页面上的portlet具有编辑访问权，那么为编辑portlet的每个用户创建新的具体portlet实例。
在这种情况下，PortletData包含编辑portlet的每个用户的数据。
2.如果具体portlet放在用户的页面上，那么PortletData包含那个用户的数据。
当用户访问包含portlet的页面时，会创建一个用户portlet实例。
当用户登录门户网站时，门户网站服务器会为每个用户的portlet创建核心对象。
PortletSession参数化的具体portlet实例称为用户portlet实例。
每个具体portlet实例可能具有许多用户portlet实例。
用户portlet实例是由单个PortletSession参数化的具体portlet实例。
每个具体portlet实例可能具有许多用户portlet实例。
PortletSession存储与单次使用portlet相关的瞬时信息。
portlet应用程序
portlet应用程序提供了封装一组共享相同上下文的相关portlet的方法。
上下文包含所有资源，例如，图像、属性文件和类。
所有portlet必须封装为portlet应用程序的一部分。
Concreteportlet应用程序
具体portlet应用程序是由单个PortletApplicationSettings对象参数化的portlet应用程序。
每个portlet应用程序可能具有许多具体portlet应用程序。
PortletApplicationSettings是具有读/写访问权，并是持久的。
无明确代表具体portlet应用程序的对象。
具体portlet应用程序至少包含一个来自portlet应用程序的具体portlet，但是无需全部包含它们。
portlet应用程序自己不提供代码，但是形成portlet的逻辑组。
除了这更多的逻辑收益之外，同一portlet应用程序的portlet也可交换消息。
portlet方式
portlet方式允许portlet显示不同的用户界面，这取决于portlet所需的任务。
portlet有四种显示方式，这是在portlet部署描述符中定义的。
portlet容器在Portlet.Mode对象中维护portlet方式。
以下方式由IBMportletAPI标记库提供：
查看
当最初为用户在门户网站页面上构造portlet时，它以其查看方式显示。
这是portlet操作的正常方式。
帮助
如果portlet支持该方式，那么portlet提供帮助页面以便用户能获取更多有关portlet的信息。
编辑
如果由portlet支持该方式，那么portlet对用户提供页面以便按其本身的需要定制portlet。
例如，portlet能为用户提供页面来指定其位置以获取当地的天气和事件信息。
用户必须登录到门户网站来访问编辑方式。
配置
如果portlet支持此方式，那么portlet会向门户网站管理员提供一个页面以供其为此portlet的所有用户配置该portlet。
portlet在portlet部署描述符中声明支持这些方式。
所有portlet都必须支持查看方式。
IBMportletAPI为portlet提供了PortletReuest.getMode（）andPortletRequest.getPreviousMode（）方法，以确定当前或先前的方式。
portlet外表可提供链接，允许用户在portlet方式间进行切换。
单击其中某个链接可以更改portlet的方式或状态。
这些链接可以在上下文菜单中实现，或者可以呈现在标题栏中。
portlet状态
portlet状态允许用户更改在门户网站中怎样显示portlet窗口。
portlet状态用布尔值在PortletWindow.State对象中维护。
portletAPI提供PortletWindow.getWindowState（）方法来确定portlet的当前状态。
可以使用标题栏中的图标调用以下状态，调用方式与操纵Windows应用程序的方式一样。
∙最大化：
当最大化portlet时，它会在整个门户网站主体中显示，并替换其他portlet的视图。
∙最小化：
当最小化portlet时，仅会在门户网站页面上显示portlet标题栏。
∙正常：
当最初在门户网站页面上构建portlet时，它会以正常状态显示－与其他portlet一起排列在页面上。
在将portlet最大化或最小化后，可以使用复原图标将portlet回复到正常状态。
portlet在portlet部署描述符中声明支持这些状态。
单独状态
portlet还能以单独状态显示，在此状态下将隐藏门户网站主题元素，如条幅、页面导航或工具栏。
但不能使用标题栏上的图标来调用单独状态。
另外，单独状态不同于其他状态，它不是在portlet部署描述符中声明的。
portlet会在以下情况进入单独状态：
∙从portlet外部使用URLGenerationportletWindowState=solo"/>标记进入。
∙从portlet内部使用createURIstate="Solo"/>标记或createURI（PortletWindow.StateSOLO）方法进入。
门户网站主题开发者使用ifportletSolo=""/>标记确定在单独状态下隐藏的元素。
如果用户尚未登录，portlet就无法进入单独状态。
处于单独状态时，最小化图标和最大化图标不能改变portlet的状态。
portlet只能使用createReturnURI（）方法退出单独状态。
虽然这不是必须的，但建议所有portlet都使用此方法以确保用户能从单独方式退出并返回正常门户网站界面。
portletAPI的元素
本部分描述portletAPI的基本接口、类和方法。
下图显示portletAPI中许多公共对象的图。
∙Portlet
由
PortletAdapter扩展
oservice（）1
PortletResponse
▪createURI（）
PortletURI
oservice（）1
PortletRequest
▪getPortletSettings（）
PortletSettings
▪getPortletApplicationSettings
PortletApplicationSettings
▪getMode（）
Portlet.Mode
▪getClient（）
Client
▪getData（）
PortletData
▪getWindow（）
PortletWindow
▪getWindowState（）
PortletWindow.State
▪getPortletSession（）
PortletSession
▪getUser（）
User
∙getPortletConfig（）
PortletConfig
ogetContext（）
PortletContext
▪getLog（）
PortletLog
▪getService（）
PortletService
1PortletRequest和PortletResponse由PortletAdapter的helper方法（如doView（））传递。
portlet类
抽象Portlet类是portletAPI的核心抽象。
所有portlet通过扩展该抽象类的子类之一（例如，PortletAdapter）来扩展该抽象类，这提供有助于开发者的方法。
portlet生命周期
portlet容器在portlet的生命周期期间调用抽象portlet的以下方法2：
init（）
门户网站初始化之后，即构造出portlet并随后使用init（）方法初始化。
门户网站总是仅实例化portlet的单个实例，而且此实例在所有用户之间共享，与servlet在应用程序服务器的所有用户之间共享的方式完全相同。
initConcrete（）
构造portlet之后，在第一次访问该portlet之前，具体portlet由PortletSettings实例化。
service（）
要求portlet呈现它的内容时，门户网站调用service（）方法。
在portlet的生命周期期间，通常会多次调用service（）方法。
对于页面上的每个portlet，不是按保证的顺序调用service（）方法，甚至可能对于每个请求以不同的顺序调用service（）方法。
destroyConcrete（）
使用destroyConcrete（）方法除去具体portlet服务。
当管理员在门户网站服务器上的运行时期间删除具体portlet时，可能发生这种情况。
destroy（）
门户网站即将终止时，取消portlet服务，然后使用destroy（）方法销毁portlet。
最后，portlet会作为无用信息被收集和终结。
2这代表所有portlet上调用的方法。
为实现侦听器的portlet调用其他方法。
有关更多信息，请参阅侦听器生命周期。
getLastModified（）
除了在portlet生命周期期间调用的方法外，portlet容器为每个portlet请求调用getLastModified（）方法。
该方法返回portlet内容上次更改的时间（以毫秒为单位），该时间在当前时间和1970年1月1日午夜之间UTC（java.lang.System.currentTimeMillis（））或为负值（如果时间未知）。
要获取更多有关何时使用getLastModified（）的信息，请参阅刷新portlet高速缓存。
Helper类
portlet不直接扩展抽象Portlet类，而是扩展PortletAdapter或任何其他helper类依次扩展Portlet。
扩展这些类之一，有助于保护portlet不被抽象Portlet类更改。
此外，它保存必须实现所有Portlet接口的方法，即使portlet不需要全部使用它们。
使用PortletAdapter类，只需覆盖真正需要的方法。
在它的service（）方法中，PortletAdapter类调用对应于portlet方式的方法。
扩展该类的portlet能覆盖doView（）、doEdit（）和doHelp（）方法，而不必测试该方法或编写特定的service（）方法。
此外，PortletAdapter使portlet能在具体portlet中存储变量。
具体portlet变量与Java实例变量是不同的，因为它们绑定到portlet类或非具体portlet。
PortletAdapter提供了setVariable（）、getVariable（）和removeVariable（）方法以处理具体portlet变量。
核心对象
以下对象是portlet最常用的：
∙PortletRequest
∙PortletResponse
∙PortletSession
这些对象的每一个是它在ServletAPI中的对应对象的扩展。
PortletRequest
PortletRequest对象通过login（）、beginPage（）、endPage（）和service（）方法传递给portlet，为portlet提供请求特定的数据并使其能进一步访问以下所列的重要信息。
属性
属性是与请求相关的名称/值对。
属性仅能用于请求的作用域。
此portlet能在一个请求期间获取、设置和除去属性。
参数
参数是名称/值对，由客户机在URI查询字符串中作为请求的一部分发送。
通常参数从表单公布。
参数用于特定请求的作用域。
portlet能从请求获取却不能设置参数。
Client
Client对象封装与请求相关的指定请求的用户代理信息。
来自Client的信息包含用户代理的制造商或客户机支持的标记类型。
使用getClient（）方法从PortletRequest解压缩Client。
能从Client获取以下信息：
用户代理
portlet能获取由用户代理发送以向门户网站标识其自身的字符串。
标记名称
portlet可以获取表明客户机支持的标记语言的字符串，例如“wml”。
MIME类型
portlet能获取表明由客户机支持的MIME类型的字符串（如text/vnd.wap.wml）。
如果portlet支持多个设备类型，它将获取标记名称而非MIME类型。
下表显示MIME类型和它们相应的标记类型。
检索MIME类型不区别HTML和cHTML标记。
MIME类型
标记类型
Text/html
html
Text/vnd.wap.wml
wml
Text/html
chtml
功能
与标记类型相比，Capability对象包含更为详细的有关客户机支持信息，如支持的HTML的级别、JavaScript的级别或WML表的级别。
用户数据
PortletData对象代表保存到持久存储的具体portlet实例的数据。
例如，用户能设置portlet电子邮件应用程序为了每隔30分钟检查新邮件。
在PortletData对象中为实例存储该首选项。
会话
PortletSession代表多个请求的特定用户的瞬时数据。
与请求对比，请求在请求完全处理后不保留数据，而会话属性可为不止一个请求记录/保存。
portlet设置
PortletSettings对象代表保存到持久存储的具体portlet的配置。
例如，管理员可以设置Stockportlet应该连接到哪个主机和端口以获取实时数据。
在PortletSettings对象中为具体portlet存储该首选项。
方式
Portlet.Mode提供当前或前一个portlet的方式。
PortletWindow
PortletWindow对象代表当前portlet窗口的状态。
portlet能访问该对象来确定当前的portlet是要以最大化、最小化还是其正常视图呈现。
ModeModifier
在呈现portlet前，可在portlet操作中使用该对象把portlet方式设置为它的当前、前一个或请求的方式。
例如，处于编辑方式的portlet可以处理用户操作，并可在返回查看方式之前先使portlet返回编辑方式以获取更多的输入。
PortletResponse
响应对象封装从服务器返回到客户机的信息。
PortletResponse通过beginPage（）、endPage（）和service（）方法传递，并可由portlet通过使用JavaPrintWriter用于返回portlet输出。
响应还包含创建PortletURI对象的方法或使用portlet的名称空间限制portlet标记。
使用以下方法之一来创建PortletURI：
createURI（）
创建指向具有当前方式的调用portlet的PortletURI对象
createURI（PortletWindow.Statestate）
创建指向具有当前方式和给定portlet窗口状态的调用portlet的PortletURI对象。
portlet可以使用此方法进入单独状态。
createReturnURI（）
创建portletURI，指向portlet的调用者。
例如，createReturnURI（）可用于在编辑方式中创建后退按钮。
portlet必须使用此方法退出单独状态。
每个portlet在其本身的唯一名称空间中运行。
portlet使用encodeNamespace（）方法把属性带至portlet输出以避免名称与其他portlet冲突。
属性可以包含参数名、全局变量或JavaScript函数名。
PortletURI
PortletURI对象包含指向portlet实例的URI，并能通过添加portlet特定的参数或通过附加操作进一步扩展。
操作是portlet特定的活动，但在调用portletservice（）方法之前，它需要以入站请求的结果来执行。
例如，当用户在portlet编辑方式中输入数据并单击保存按钮时，在下一个标记生成前，portlet需要处理已公布的数据。
这能通过将保存操作添加到代表保存按钮的URI来实现。
完整的URI可转换为可嵌入到标记中的字符串。
PortletSession
PortletSession保存portlet的具体portlet实例的特定用户数据，创建portlet用户实例。
具体portlet实例之间的不同仅在于存储在它们的PortletData中的数据。
portlet用户实例之间的不同仅在于存储在它们的PortletSession中的瞬时数据。
任何持续数据必须使用PortletData存储。
存储在portlet的实例变量中的信息通过读和写访问在所有具体portlet实例（甚至所有具体portlet）之间共享。
确保未对
升级会员 