Before you begin, you should complete Exercise 1.3: Comparing Java class differences.
In this exercise, you will learn differences between the deployment descriptors for the two portlet APIs. Examine the two versions of the portlet deployment descriptor (portlet.xml). The basic differences illustrated in the samples are shown below. To edit the portlet deployment descriptor, use the portlet deployment descriptor editor.
The tagging rules for the IBM portlet API are defined by a DTD; the JSR 168 portlet API is defined by an XML schema. This requires different XML definition statements at the top of the portlet deployment descriptor.
<!DOCTYPE portlet-app-def PUBLIC "-//IBM//DTD Portlet Application 1.1//EN"
"portlet_1.1.dtd ">
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
id="bookmark_03_jsr.1">
The two APIs use different names for the id attribute on the <portlet-app> element. The IBM portlet API uses uid, while the JSR 168 portlet API uses id.
<portlet-app uid="com.ibm.etools.portal.portletexamples.bookmark.legacy"
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance "
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd "
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
id="bookmark_03_jsr.1">
Using the IBM portlet API, the href attribute of the <portlet> element must point to the corresponding id of the <servlet> element in the Web deployment descriptor (web.xml); using the JSR 168 portlet API, the id attribute on the <portlet-app> element uniquely identifies the portlet to the server. JSR 168 portlets are not servlets, and do not need the reference to web.xml.
portlet.xml: <portlet id="Bookmark" href="WEB-INF/web.xml#Servlet_1086938566718"
web.xml: <servlet id="Servlet_1086938566718">
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance "
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd "
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
id="bookmark_03_jsr.1">
For the IBM portlet API, use the major-version and minor-version attributes of the <portlet-app> and <portlet> elements; for the JSR 168 portlet API, use the version attribute of the <portlet-app> element.
<portlet-app uid="com.ibm.etools.portal.portletexamples.bookmark.legacy"
major-version="1" minor-version="0">
<portlet id="Bookmark" href="WEB-INF/web.xml#Servlet_1086938566718"
major-version="1" minor-version="0">
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance "
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd "
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
id="bookmark_03_jsr.1">
In the portlet deployment descriptor, the IBM portlet API declares supported markup types, while the
JSR 168 portlet API declares supported MIME types.
IBM provides an extension, the wps.markup
initialization parameter, that lets you define the
supported markup types for JSR 168 portlets. This is used to differentiate between markup types,
like HTML and cHTML, that use the same MIME type.
<supports>
<markup name="html">
<view />
<edit />
</markup>
<markup name="chtml">
<view />
</markup>
</supports>
<init-param>
<name>wps.markup</name>
<value>html,chtml</value>
</init-param>
<supports>
<mime-type>text/html</mime-type>
<portlet-mode>VIEW</portlet-mode>
<portlet-mode>EDIT</portlet-mode>
</supports>
Supported modes must be defined in the portlet deployment descriptor for both APIs, although the syntax is slightly different. Both APIs support edit, view and help modes. The IBM portlet API also supports a config mode. The JSR 168 portlet API supports custom modes such as about, preview, print, edit defaults, and config. For both APIs, the view mode is required; all other modes are optional.
<supports>
<markup name="html">
<view />
<edit />
</markup>
</supports>
<supports>
<portlet-mode>VIEW</portlet-mode>
<portlet-mode>EDIT</portlet-mode>
</supports>
The normal state is automatically provided for both APIs. With the IBM portlet API, other states, such as solo, must be explicitly declared. With the JSR 168 portlet API, maximized and minimized states are also automatically provided; custom states must be explicitly declared.
<allows>
<maximized/>
<minimized/>
</allows>
Portlet.properties
, is located in the nls
directory
of the sample.
The JSR 168 API has settings to define the resource bundle and supported locales.
<default-locale>en</default-locale>
<language locale="en">
<title>Bookmark portlet (IBM)</title>
<title-short>Bookmark</title-short>
<keywords>Bookmark</keywords>
</language>
<language locale="de">
<title>Lesezeichen Portlet (IBM)</title>
<title-short>Lesezeichen</title-short>
<keywords>Lesezeichen, Bookmark</keywords>
</language>
<resource-bundle>nls.Portlet</resource-bundle>
<supported-locale>en</supported-locale>
<supported-locale>de</supported-locale>
<description xml:lang="EN">English description</description>
<display-name xml:lang="EN">English display name</display>-name>
<description xml:lang="DE">German description</description>
<display-name xml:lang="DE">German display name</display>-name>
Sample portlet resource bundle, Portlet.properties:
javax.portlet.title = Bookmark Portlet
javax.portlet.short-title = Bookmark
javax.portlet.keywords = Bookmark
In the IBM portlet API, portlets can explicitly invalidate the cache (invalidation-based caching)
using the invalidateCache() method of the PortletRequest object. The
default cache expiration and scope are set in the portlet deployment descriptor.
The value of the <expires> element can be 0 (always expires), -1 (never expires), or the number
of seconds before expiration. The <shared> element value of no
means that the cache
is not shared between portlet instances.
The JSR portlet API uses expiration-based caching, where the cache expiration time is defined in the deployment descriptor, but portlets can reset the value using the EXPIRATION_CACHE value with the setAttribute() method of the RenderResponse object. The <expiration-cache> element uses the same values as the IBM portlet API uses for the <expires> element.
<cache>
<expires>-1</expires>
<shared>no</shared>
</cache>
<expiration-cache>0</expiration-cache>
Now you are ready to begin Exercise 1.5: Comparing JSP file coding differences.