Exercise 1.4: Comparing deployment descriptor differences

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.

Tagging rules for portlet.xml

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.

IBM portlet API
<!DOCTYPE portlet-app-def PUBLIC "-//IBM//DTD Portlet Application 1.1//EN"
          "portlet_1.1.dtd ">
JSR 168 portlet API
<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 id attribute on the <portlet-app> element

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.

IBM portlet API
<portlet-app uid="com.ibm.etools.portal.portletexamples.bookmark.legacy"
JSR 168 portlet API
<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 href attribute on the <portlet> element

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.

IBM portlet API
portlet.xml: <portlet id="Bookmark" href="WEB-INF/web.xml#Servlet_1086938566718"
web.xml:     <servlet id="Servlet_1086938566718">
JSR 168 portlet API
<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">

Portlet versions

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.

IBM portlet API
<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">
JSR 168 portlet API
<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">

Supported markup types

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.

IBM portlet API
<supports>
   <markup name="html">
      <view />
      <edit />
   </markup>
   <markup name="chtml">
      <view />
   </markup>
</supports>
JSR 168 portlet API
<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

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.

IBM portlet API
<supports>
   <markup name="html">
      <view />
      <edit />
   </markup>
</supports>
JSR 168 portlet API
<supports>
   <portlet-mode>VIEW</portlet-mode>
   <portlet-mode>EDIT</portlet-mode>
</supports>

Allowable window states

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.

IBM portlet API
<allows>
   <maximized/>
   <minimized/>
</allows>
JSR 168 portlet API
no custom states are shown in the example, but the <custom-window-state> element would be used

Localization

Some localized strings that define a portlet are defined in the portlet deployment descriptor. The IBM portlet API's portlet.xml defines localized values for the title, short title, description and keywords. The IBM API also has a setting for the default locale. The JSR 168 portlet API defines localized values for the portlet description and display name in portlet.xml. Values for title, short title and keywords are located in a portlet resource bundle. As shown below, the portlet resource bundle, 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.
IBM portlet API
<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>
JSR 168 portlet API
<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

Cache expiration

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.

IBM portlet API
<cache>
   <expires>-1</expires>
   <shared>no</shared>
</cache>
JSR 168 portlet API
<expiration-cache>0</expiration-cache>

Now you are ready to begin Exercise 1.5: Comparing JSP file coding differences.

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.