部署描述符
portlet 应用程序的 WAR 文件必须包含两个描述符文档:Web 应用程序部署描述符和 portlet 部署描述符。Web 应用程序部署描述符中的 servlet 定义必须与 portlet 部署描述符中的 portlet 定义有相同的次序。
Web 应用程序部署描述符
和其它 servlet 一样跟随着 J2EE 型号,portlet 和 Web 应用程序部署描述符(web.xml )一起被封装为 WAR 或 EAR 文件。该描述符在 Web 应用程序中定义每个 portlet 成为 servlet,包含每个 portlet 唯一的标识、portlet 类,以及初始化参数。
要获取更多关于 Web 应用程序部署描述符的信息,请参阅 Java Servlet 规范版本 2.3 。
portlet 部署描述符
portlet 部署描述符的 DTD 位于 wp_root /app/web/dtd/portlet_1.1.dtd。
单个 PAR 文件的描述符保存为文件 portlet.xml
,并且必须以下列 XML 和 DOCTYPE 声明开头:
<?xml version="1.0"?> <!DOCTYPE portlet-app PUBLIC "-//IBM//DTD Portlet Application 1.0//EN" "portlet.dtd">
下面显示 portlet 部署描述符(portlet.xml)的结构。单击任意标记获取关于其使用的更多信息。
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE portlet-app-def PUBLIC "-//IBM//DTD Portlet Application 1.1//EN" "portlet_1.1.dtd"> <portlet-app-def > <portlet-app uid="uid "> <portlet-app-name >portlet_application_name </portlet-app-name> <portlet id="portlet_id " href="WEB-INF/web.xml#servlet_id "> <portlet-name >portlet_name </portlet-name> <cache > <expires >number </expires> <shared >yes|no </shared> </cache> <allows > <maximized /> <minimized /> </allows> <supports > <markup name="html|wml|chtml "> <view output="fragment"/> <edit output="fragment"/> <help output="fragment"/> <configure output="fragment"/> </markup> </supports> </portlet> </portlet-app> <concrete-portlet-app uid="uid "> <portlet-app-name >portlet_application_name </portlet-app-name> <context-param > <param-name>name</param-name> <param-value>value</param-value> </concrete-param> <concrete-portlet href="#portlet_id "> <portlet-name >portlet_name </portlet-name> <default-locale >locale</default-locale> <language locale="locale "> <title >title </title> <title-short >short title </title-short> <description >description </description> <keywords >keyword1 , keyword2 </keywords> </language> <config-param > <param-name>name</param-name> <param-value>value</param-value> </config-param> </concrete-portlet> </concrete-portlet-app> </portlet-app-def>
<portlet-app-def>
必需。包含关于 portlet 应用程序的信息的顶级元素。该元素精确地包含一个 <portlet-app> 元素和一个或多个 <concrete-portlet-app> 元素。
-
<portlet-app uid="uid ">
-
必需。包含关于 portlet 应用程序的信息。每个 portlet 的 uid 在 portlet 应用程序中必须是唯一的。请参阅
portlet UID 准则 。以下是 <portlet-app> 的子元素。
-
<portlet-app-name>
- 需要且只需要一个。表明 portlet 应用程序的名称。 <portlet id="id " href="href " major-version="version " minor-version="version ">
-
至少需要一个。包含描述属于此 portlet 应用程序的 portlet 的元素。
id 和
href 是必需的。在 portlet 应用程序中,id 必须是唯一的。href 属性指向 servlet 的标识,如
WEB-INF/web.xml#servlet_id 中所示。下面是 <portlet> 的子元素:
-
<portlet-name>
- 必需。Portlet 的名称。此名称不出现在门户网站页面上。 <cache>
-
可选。描述门户网站如何处理高速缓存该 portlet 输出。下面是 <cache> 的子元素:
-
<expires>
-
如果指定了 <cache>,则为必需。表明刷新 portlet 输出所需的秒数。
- 0 表明 portlet 输出总是到期。每个请求导致 portlet 刷新其输出。 如果未显示 <cache>,则这就是缺省设置。
- 任何大于 0 的数表明高速缓存 portlet 输出所需的秒数。 在高速缓存时间到期后,后继请求导致 portlet 刷新其输出。
- -1 表明 portlet 输出从不到期。在 portlet 初始化后,不再刷新其内容。
<shared>
- 如果指定了 <cache>,则为必需。表明如果高速缓存 portlet 输出并与所有用户或每个个人用户共享 portlet 输出。指定“yes”或“no”。
<allows>
-
如果指定了 <cache>,则为必需。表明刷新 portlet 输出所需的秒数。
-
可选。表明 portlet 支持的状态。在一个 portlet 上可指定的 <allows> 元素不得超过一个。这些设置仅影响 HTML 中的 portlet 输出。下面是 <allows> 的子元素:
-
<maximized/>
- 可选。表明 portlet 是否可最大化。最大化时,该 portlet 替换门户网站页面上的所有其它 portlet。如果此元素存在,则在该 portlet 的标题栏上输出最大化按钮。 <minimized/>
- 可选。表明 portlet 是否可最小化。最小化时,该 portlet 仅被输出成一个标题栏。如果此元素存在,则在该 portlet 的标题栏上输出最小化按钮。
<supports>
-
必需。表明 portlet 支持的方式和标记类型。所有 portlet 都必须支持视图方式。仅当该 portlet 支持它们时,才必须提供其它方式。下面是 <supports> 的子元素:
-
<markup name="name ">
-
至少需要一个。表明此 portlet 支持的标记类型。
name 是下列值之一:
- html
- wml
- chtml
<markup name="html"> ... </markup> <markup name="wml"> ... </markup>
下面是 <markup> 的子元素:-
<view/>
- 必需。表明此 portlet 支持视图方式。 <edit/>
- 可选。表明此 portlet 支持编辑方式。此元素是可选的。如果支持编辑方式,该 portlet 必须提供方法,供用户调用来定制 portlet 给他们自己使用。 <help/>
- 可选。表明此 portlet 支持帮助方式。此元素是可选的。如果支持帮助方式,该 portlet 必须提供帮助输出,它将在用户单击帮助图标时替换 portlet 显示出来。 <configure/>
- 可选。表明此 portlet 支持的配置方式。此元素是可选的。
-
至少需要一个。表明此 portlet 支持的标记类型。
name 是下列值之一:
<concrete-portlet-app uid="uid ">
-
至少需要一个。包含有关具体 portlet 应用程序的信息。以下是 <concrete-portlet-app> 的子元素。
-
<portlet-app-name>
- 需要且只需要一个。表明 portlet 应用程序的名称。 <context-param>
- 可 选。包含此具体的 portlet 应用程序可接受作为输入参数的一对 <param-name> 和 <param-value> 元素。一个具体的 portlet 应用程序可接受任何数量的上下文参数。管理员在配置具体的 portlet 应用程序时,可以更改上下文参数。使用 XML 注释提供帮助信息,说明 portlet 应用程序可以接受哪些值。具体 portlet 应用程序的唯一配置设置组成了其 PortletApplicationSettings 。 <concrete-portlet id="id " href="href " >
-
至少需要一个。包含描述属于具体 portlet 应用程序的具体 portlet 的元素。
id 和
href 是必需的。在 portlet 应用程序中,id 必须是唯一的。 href 属性指向 portlet 的标识,如
#portlet_id 中所示。下面是 <concrete-portlet> 的子元素:
-
<portlet-name>
- 必需。Portlet 的名称。此名称不出现在门户网站页面上。 <default-locale>
- 必需。表明如果无法确定客户机语言环境时将要使用的语言环境。 <language locale="locale ">
-
至少需要一个。为 portlet 所支持的每个
语言环境 提供一个 <language> 元素。
语言环境 可以是下列值之一:
- en 英语
- de 德语
- fr 法语
- es 西班牙语
- ja 日语
- ko 韩国语
- zh 简体中文
- zh_TW 繁体中文
- pt_BR 巴西葡萄牙语
- it 意大利语
- he 希伯来语
- cs 捷克斯洛伐克语
- tr 土耳其语
- pl 波兰语
下面是 <language> 的子元素:
-
<title>
- 每个 <language> 正好只必需一个 <title>。请指定一个为给定的 locale 翻译的 portlet 标题。 <title-short>
- 可选。表明翻译的简短标题。 <description>
- 可选。为 portlet 提供一个翻译的描述。 <keywords>
- 可选。提供与 portlet 相关的任何翻译的关键字。
<config-param>
- 包含此 portlet 可接受为输入参数的一对 <param-name> 和 <param-value> 元素。Portlet 可接受任何数量的配置参数。管理员在配置具体的 portlet 时,可以更改配置参数。使用 XML 注释提供帮助信息,说明 portlet 应用程序可以接受哪些值。具体 portlet 的唯一配置设置组成了其 PortletSettings
链接 servlet、portlet 和具体 portlet
web.xml 中 servlet 的定义必须与 portlet.xml 中 portlet 的定义有相同的次序。servlet 标识必须由 portlet 部署描述符使用 <portlet> 标记的 href 属性来引用。如下表所示,href 属性表明 由 servlet 标识附加作为锚的 WAR 文件中 Web 应用程序描述符的路径。
portlet.xml | web.xml |
---|---|
<portlet id="Portlet_1"
href="WEB-INF/web.xml#Servlet_1
">
<portlet-name>Mail</portlet-name>
...
</portlet>
| <servlet
id="Servlet_1
">
<servlet-name>MailPortlet</servlet-name>
...
</servlet>
|
<portlet id="Portlet_2"
href="WEB-INF/web.xml#Servlet_2
">
<portlet-name>Calendar</portlet-name>
...
</portlet>
| <servlet
id="Servlet_2
">
<servlet-name>CalendarPortlet</servlet-name>
...
</servlet>
|
每个具体 portlet 定义使用 <concrete-portlet> 标记的 href 属性表明其父 portlet。如下表所示,href 属性表明 portlet 标识为锚。
Portlet 标记 | 具体 portlet 标记 |
---|---|
<portlet id="Portlet_1
"
href="WEB-INF/web.xml#Servlet_1">
<portlet-name>Mail</portlet-name>
...
</portlet>
| <concrete-portlet href="#Portlet_1
">
<portlet-name>Mail Box</portlet-name>
...
</concrete-portlet>
|
<portlet id="Portlet_2
"
href="WEB-INF/web.xml#Servlet_2">
<portlet-name>Calendar</portlet-name>
...
</portlet>
| <concrete-portlet href="#Portlet_2
">
<portlet-name>Group calendar</portlet-name>
...
</concrete-portlet>
|
portlet 应用程序 UID 的准则
portlet 应用程序和具体 portlet 应用程序的 UID 必须能在它们的使用区域(可能是世界范围)中清楚地标识它们。为了使之可能,强烈建议遵循以下这些准则。
- 使用与用于 Java 软件包相同的格式把 portlet 的名称空间包含在 UID 中
- 添加一些 portlet 应用程序特定的描述
- 添加一些随机的字符以确保名称空间中的唯一性,例如:
com.ibm.wps.samplet.mail.4969
- 为对应的具体 portlet 应用程序添加后缀,例如:
com.ibm.wps.samplet.mail.4969.1
在应用程序中,Portlet 标识必须是唯一的。
源文件地址:http://ssconnect.sscoop.com/wps/doc/zh/InfoCenter/wps/wpspapi.html