Deployment descriptors

The WAR file for a portlet application must contain two descriptor documents: the Web application deployment descriptor and portlet.xml. The definition of the servlets in the Web application deployment descriptor must be in the same order as the definition of portlets in portlet.xml. The following topics describe the structure of these files and their relationship with each other.

 

Web application deployment descriptor

As with other servlets following the J2EE model, 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.

For more information about the Web application deployment descriptor, see the Java Servlet Specification Version 2.3.

 

Portlet deployment descriptor

The DTD for portlet.xml is located at wp_root/app/web/dtd/portlet_1.1.dtd. The descriptor for a single WAR file is saved as the file portlet.xml and must begin 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 portlet.xml (portlet.xml). 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 servlet, portlet, and concrete portlet

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

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>

 

Guidelines for portlet application UIDs

The UIDs of portlet applications and concrete portlet applications must identify them unambiguously in the area of their usage, which could be worldwide. To make this possible, it is strongly recommended that you follow these guidelines.

Portlet IDs must be unique within the application.

See also