Deployment descriptors

 

Each portlet application requires two deployment descriptors:

  1. web.xml

    Describes Web resources in the application. The format of this file is described in the Deployment Descriptor chapter of the Servlet Specification 2.3.

  2. portlet.xml

    Describes portlet resources in the application, including configuration, support characteristics, and localized titles. The portal server uses this information to provide services for the portlet. For example, if a portlet registers its support for help and edit mode in the portlet deployment descriptor, the portal server renders icons to allow the user to invoke the portlet's help and edit pages.

 

Directory Structure

 

web.xml

Include a web.xml deployment descriptor in each portal application WAR file.

web.xml should contain, at a minimum, the <web-app/>, <display-name/>, and <tag-lib/> elements. You can also include context-wide parameters using the <init-param> element.

The <tag-lib/> must indicate the location of the JSR 168 JSP tag library on the portal server, as follows: 

      <taglib id="PortletTLD">
         <taglib-uri>http://java.sun.com/portlet</taglib-uri>
         <taglib-location>tld/std-portlet.tld</taglib-location>
      </taglib>

If missing, the <taglib/> element is automatically inserted in the web.xml when a JSR 168 portlet application WAR file is deployed using portal administration or the XML configuration interface. However, the web.xml for JSR 168 EAR files that are installed using predeployment mode are not updated, so including the <taglib/> element is required.

 

IBM Web application descriptor

As with other servlets following the J2EE model, IBM portlets are packaged as WAR or EAR files with a Web application deployment descriptor (web.xml). This descriptor defines each portlet as a servlet within the Web application, including unique identifiers for each portlet, the portlet class, and initialization parameters.

The definition of the servlets in the web.xml must be in the same order as the definition of portlets in the portlet.xml . The servlet identifier must be referenced by the portlet deployment descriptor, using the href attribute of the <portlet> tag. As shown in the following table, the href attribute indicates the path of the Web application descriptor in the WAR file appended by the servlet ID as the anchor.

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

This section describes the portlet.xml for IBM and JSR 168 compliant portlets. The elements and structure of the IBM portlet.xml is provided in this topic. For information about the portlet deployment descriptor for JSR 168, see the JSR 168 Portlet Specification.

 

Guidelines for portlet application identifiers

The identifiers of portlet applications must identify them unambiguously in the area of their usage, which could be worldwide. The same is true for concrete portlet applications for IBM portlets. To make this possible, follow these guidelines.

  • Include the portlet's namespace in the identifier, using the same format that is used for the Java packages

  • Add some portlet application specific description

  • Add some arbitrary characters to guarantee uniqueness within the namespace, for example: 
      com.ibm.wps.samplet.mail.4969

  • For IBM portlets, add suffixes for the corresponding concrete portlet applications, for example: 
      com.ibm.wps.samplet.mail.4969.1

Portlet identifiers must be unique within the application.

 

JSR 168 portlet deployment descriptor

In JSR 168, portlet descriptor is in the format of an XML Schema. Since the portlet is not a servlet, the portlet descriptor does not reference a corresponding servlet ID in the web.xml. The top level element is the <portlet-app> which contains one or more <portlet> definitions. Portlet-specific initialization parameters are stored in the portlet.xml using the <init-param> element and are obtained from the PortletConfig object provided during initialization.

 

IBM portlet deployment descriptor

The structure of the IBM portlet deployment descriptor is defined by a DTD, which is located at wps.war/dtd/portlet_1.1.dtd. The descriptor for a single portlet application begins with the following XML and DOCTYPE declarations: 


  <?xml version="1.0"?>
  <!DOCTYPE portlet-app-def PUBLIC "-//IBM//DTD Portlet Application 1.1//EN" "portlet_1.1.dtd">

The following shows the structure of the deployment descriptor (portlet.xml) for IBM portlets. Click any tag to get more information about it's use. 

<?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"
       major-version="version" minor-version="version">
      <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>
    </context-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>

 

Linking the portlet and concrete portlet

For IBM portlets, each concrete portlet definition indicates its parent portlet using the href attribute of the <concrete-portlet> tag. As shown in the following table, the href attribute indicates the portlet ID as an anchor.

Portlet tag Concrete portlet tag 
<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>

 

Reserved parameter names

Configuration parameters are parameters for a portlet that can be changed only by an administrator. They are defined in the portlet.xml using either the <config-param/> elements (IBM) or the <preferences/> element marked as read-only (JSR 168). Initialization parameters are set in the web.xml. The following parameters are reserved for special use in WebSphere Portal.

com.ibm.wps.portlet.action.redirect

When true, prevents the portlet's actions from being executed every time a user refreshes or navigates to the page using the back button. The default is false. This can be set either as an initialization parameter or as a configuration parameter.

com.ibm.portal.pagecontext.enable

When true, indicates that the portlet can retrieve task properties. This parameter is used by task processing portlets The default is false. This is set as a configuration parameter.

parallel

When true, this parameter indicates that the portlet can be rendered in parallel with other portlets on the page. The default is false. This is set as a configuration parameter. See Parallel portlet rendering for more information.

wps.markup

Used as an initialization parameter in JSR 168 compliant portlets to 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. See Migrating from the IBM Portlet API for more information.

 

See also

Home |

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.