WebSphere

 

Portal Express, Version 6.0
Operating systems: i5/OS, Linux, Windows

 

Deployment descriptors

Each portlet application requires two deployment descriptors:

The following topics describe the deployment descriptors of a portlet application:

 

Web application deployment descriptor

This section describes the required elements of the web.xml for IBM and standard portlets. For more information about the Web application deployment descriptor, see the Java Servlet Specification Version 2.3.

Web application descriptor for standard portlets

As described in the Java Portlet Specification, a portlet application is an extended web application and therefore has a servlet context. The portlet context leverages most of its functionality from the servlet context of the portlet application. Since the web.xml is a mandatory item in a J2EE web archive, you should make sure your portlet application includes a web.xml in its WAR file that conforms to Version 2.3 of the Java Servlet Specification. This ensures that the portlet application is compatible with other portal server implementations as well as WebSphere Portal Express. The 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. See the Java Servlet Specification Version 2.3 for more information about the structure of the Web application deployment descriptor. The <tag-lib/> must indicate the location of the standard portlet JSP tag library on the portal server, as follows: 

      <taglib>
        <taglib-uri>http://java.sun.com/portlet</taglib-uri>
        <taglib-location>/WEB-INF/tld/std-portlet.tld</taglib-location>
    </taglib>

If missing, the <taglib/> element is automatically inserted in the web.xml when a standard portlet application WAR file is deployed using portal administration or the XML configuration interface. However, the web.xml for standard portlet 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 deployment descriptor

This section describes the portlet.xml for standard and IBM portlets.

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.

Standard portlet deployment descriptor

In the Java Portlet Specification, the 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

This section describes parameters that can be set for portlets. There are two types of parameters:

Configuration parameters

These are parameters for a portlet that can be changed only by an administrator. They are defined in the file portlet.xml using either the <config-param/> elements (for IBM portlets) or the <preferences/> element marked as read-only (for standard portlets).

Initialization parameters

These parameters are set during deployment. For standard portlets, they are set by the <init-param/> element in the portlet.xml. For IBM portlets, they are set by the <init-param/> element in the web.xml.

The following parameters can be set as configuration parameters in IBM portlets or initialization parameters in standard portlets:

redirect.action.without.session = (false)

Set this parameter to true to enforce a redirect after an action on anonymous pages for this portlet.

wps.markup

This is an initialization parameter in standard portlets to define the supported markup types for the portlet. Use it to differentiate between markup types, such as HTML and cHTML, that use the same MIME type. Refer to Migrating from the IBM Portlet API for more information.

com.ibm.portal.automaximize

Set this parameter to true to automatically maximize the portlet when the user switches from view mode to any of the other supported modes. The default is false.

The following parameters can be set as configuration parameters in IBM portlets or read-only preferences in standard portlets:

parallel = (false)

When you set this parameter to true, you indicate that the portlet can be rendered in parallel with other portlets on the page. The default is false. For more information refer to Parallel portlet rendering.

com.ibm.portal.pagecontext.enable = (false)

When you set this parameter to true, you indicate that the portlet can retrieve task properties. This parameter is used by task processing portlets . The default is false.

 

Related information