Chapter 6. XML Descriptors
Prev |  | Next

## Chapter 6. XML Descriptors

### Roy Russo

`<roy@jboss.org>`

## 6.1. Portlet Descriptors

To define your portal objects (portals, pages, portlet instances, windows, and portlets), you will be using the descriptors found in this section. This section seeks to describe these descriptors. It is recommended you also look at Section 5.2, “Tutorials” and Section 6.3, “Descriptor Examples” for samples on how they are used within a portlet application.

### 6.1.1. *-object.xml

The *-object.xml file is used to define: portal instances, pages, windows, window layout. Additionally, you can also specify the themes and layouts used for specific portal instances, pages, and windows. The description below, only defines a portlet window being added to the default page in the default portal. For advanced functionality, using this descriptor, please read Section 6.3, “Descriptor Examples” .

    <?xml version="1.0" encoding="UTF-8"?>
    <deployments>
       <deployment>
          <if-exists>overwrite</if-exists>
          <parent-ref>default.default</parent-ref>
          <window>
             <window-name>HelloWorldJSPPortletWindow</window-name>
             <instance-ref>HelloWorldJSPPortletInstance</instance-ref>
             <region>center</region>
             <height>1</height>
          </window>
       </deployment>
    </deployments>

-     <deployments>...</deployments>

  The deployments tag, encapsulates the entire document. You may specify more than one deployment within this tag.

-     <deployment>...</deployment>

  The deployment tag is used to specify object deployments: portals, pages, windows, etc...

-     <if-exists>...</if-exists>

  Possible values are overwrite or keep . Overwrite will destroy the existing object in the database and create a new one, based on the content of the deployment. Keep will maintain the existing object deployment or create a new one if it does not yet exist.

-     <parent-ref>...</parent-ref>

  The parent-ref tag specifies where a particulare object will exist within the portal object tree. In our example, above, we are defining a window and assigning it to default.default , interpreted, this means the window will appear in the default portal and the default page within it.

-     <window>...</window>

  Used to define a portlet window. You will then need to assign to this window, a portlet instance and assign it to a layout region.

-     <window-name>...</window-name>

  A unique name given to this portlet window.

-     <instance-ref>...</instance-ref>

  The portlet instance that this window will represent. It must correspond to the value of instance-id , assigned in your portlet-instances.xml

-     <region>...</region><height>...</height>

  The values are used to specify where this window will appear within the page layout. Region often depends on regions defined in your layout. Height can be any number between 0-X.

The example *-object.xml, above, makes reference to items found in other descriptor files. To help with this topic, we have included a sample image that depicts the relationship:

### 6.1.2. portlet-instances.xml

This is a JBoss Portal specific descriptor that allows a developer to instantiate one-or-many instances of one-or-many portlets. The benefit of using this technique, is to allow one portlet to be instantiated several times with different preference parameters.

### Note

Is this descriptor mandatory? Technically, no, as you can deploy your portlet without this descriptor AND without the *-object.xml and then use the management portlet to create instances, assign the instances to windows, and then assign the windows to pages.

Our example, below, has us instantiating two separate instances of the NewsPortlet with different preference parameters, one instance will draw a feed for RedHat announcements and the other from McDonalds announcements.

    <?xml version="1.0" standalone="yes"?>
    <deployments>
       <deployment>
          <instance>
             <instance-id>NewsPortletInstance2</instance-id>
             <portlet-ref>NewsPortlet</portlet-ref>
             <preferences>
                <preference>
                   <name>expires</name>
                   <value>180</value>
                </preference>
                <preference>
                   <name>RssXml</name>
                   <value>http://finance.yahoo.com/rss/headline?s=rhat</value>
                </preference>
             </preferences>
             <security-constraint>
                <policy-permission>
                   <unchecked/>
                   <action-name>view</action-name>
                </policy-permission>
             </security-constraint>
          </instance>
       </deployment>
       <deployment>
          <instance>
             <instance-id>NewsPortletInstance2</instance-id>
             <portlet-ref>NewsPortlet</portlet-ref>
             <preferences>
                <preference>
                   <name>expires</name>
                   <value>180</value>
                </preference>
                <preference>
                   <name>RssXml</name>
                   <value>http://finance.yahoo.com/rss/headline?s=mcd</value>
                </preference>
             </preferences>
             <security-constraint>
                <policy-permission>
                   <unchecked/>
                   <action-name>view</action-name>
                </policy-permission>
             </security-constraint>
          </instance>
       </deployment>
    </deployments>

-     <deployments>...</deployments>

  The deployments tag, encapsulates the entire document. You may specify more than one portlet instance deployment, within this tag.

-     <deployment><instance>...</instance></deployment>

  The deployment , and embedded instance tags are used to specify one portlet instance.

-     <instance-id>...</instance-id>

  A unique name given to this instance of the portlet. It must correspond to the value of instance-ref , assigned to the window in your *-object.xml .

-     <portlet-ref>...</portlet-ref>

  The portlet that this instance will represent. It must correspond to the value of portlet-name , assigned in your portlet.xml .

-                             <preferences><preference>...</preference></preferences>

  Preferences for this portlet instance are defined here, as type String, in a key-value pair style. It is also possible to specify preferences as type String[], as in:

      <preferences>
         <preference>
            <name>fruit</name>
            <value>apple</value>
            <value>orange</value>
            <value>kiwi</value>
         </preference>
      </preferences>

-     <security-constraint>
         <policy-permission>
            <unchecked/>
            <action-name>viewrecursive</action-name>
         </policy-permission>
      </security-constraint>

  The security contraint portion is worth taking a look at, in an isolated fashion. It allows you to secure a specific portlet instance based on a user's role.

  Role definition: You must define a role that this security constraint will apply to. Possible values are:

  - <unchecked/> Anyone can view this page.
  - <role-name>SOMEROLE</role-name> Access to this page is limited to the defined role.

  Access Rights: You must define the access rights given to the role defined. Possible values are:

  - view Users can view the page.
  - viewrecursive Users can view the page and child pages.
  - personalize Users are able to view AND personalize the page.
  - personalizerecursive Users are able to view AND personalize the page AND its child pages.

The example portlet-instances.xml, above, makes reference to items found in other descriptor files. To help with this topic, we have included a sample image that depicts the relationship:

### 6.1.3. jboss-portlet.xml

This descriptor is not mandatory, but is useful when having to add JBoss-Specific contexts to your portlet descriptor. It would normally be packaged inside your portlet war, alongside the other descriptors in this section.

#### 6.1.3.1. Injecting Header Content

    <portlet-app>
       <portlet>
          <portlet-name>ManagementPortlet</portlet-name>
          <header-content>
             <link rel="stylesheet" type="text/css" href="/images/management/management.css" title="" media="screen"/>
          </header-content>
       </portlet>
    </portlet-app>

The above example will inject a specific style sheet link in the top of the portal page, allowing this portlet to leverage its specific style selectors.

#### 6.1.3.2. Injecting Services in the portlet context

    <portlet-app>
       <service>
          <service-name>UserModule</service-name>
          <service-class>org.jboss.portal.identity.UserModule</service-class>
          <service-ref>:service=Module,type=User</service-ref>
       </service>
    </portlet-app>

Injects the UserModule service in to the portlet context, allowing a portlet to then leverage the service. For example:

    UserModule userModule = (UserModule) getPortletContext().getAttribute("UserModule");
    String userId = request.getParameters().getParameter("userid");
    User user = userModule.findUserById(userId);

#### 6.1.3.3. Portlet Session Replication in a Clustered Environment

See Section 8.5, “Portlet Session Replication”

### 6.1.4. portlet.xml

This is the standard portlet descriptor covered by the JSR-168 Specification. It is advisable that developers read the specification items covering proper use of this descriptor, as it is only covered here briefly. For example purposes, we use an editted version of our JBoss Portal UserPortlet definition. Normally, you would package this descriptor in your portlet war.

    <?xml version="1.0" encoding="UTF-8"?>
    <portlet-app
          xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
          version="1.0">
       <portlet>
          <description>Portlet providing user login/logout and profile management</description>
          <portlet-name>UserPortlet</portlet-name>
          <display-name>User Portlet</display-name>
          <portlet-class>org.jboss.portal.core.portlet.user.UserPortlet</portlet-class>
          <init-param>
             <description>Whether we should use ssl on login and throughout the Portal. 1=yes;0=no</description>
             <name>useSSL</name>
             <value>0</value>
          </init-param>
          <supports>
             <mime-type>text/html</mime-type>
             <portlet-mode>VIEW</portlet-mode>
          </supports>
          <supported-locale>en</supported-locale>
          <supported-locale>fr</supported-locale>
          <supported-locale>es</supported-locale>
          <resource-bundle>Resource</resource-bundle>
          <portlet-info>
             <title>User portlet</title>
          </portlet-info>
       </portlet>
    </portlet-app>

-     <portlet-app>...</portlet-app>

  The portlet-app tag, encapsulates the entire document. You may specify more than one portlet, within this tag.

-     <portlet>...</portlet>

  The portlet tag is used to define one portlet that is deployed withing this archive.

-     <description>...</description>

  A verbal description of tis portlet's function.

-     <portlet-name>...</portlet-name>

  The name of this portlet, usually the class name

-     <portlet-class>...</portlet-class>

  The fully-qualified-name of this portlet class.

-                             <init-param><name>...</name><value>...</value></init-param>

  Using the init-param tag, you can specify initialization parameters to create initial state inside your portlet class. Normally, they would be used in the portlet's init() method. You can specify more than one init-param.

-     <supports>...</supports>

  Here, you would advertise the supported mime-type and supported portlet-modes for this portlet.

-     <supported-locale>...</supported-locale>

  Here, you would advertise the supported locales for this portlet. You can specify many.

-     <resource-bundle>...</resource-bundle>

  The resource bundle that will back the locales specified.

-     <portlet-info><title>...</title></portlet-info>

  The portlet title that will be displayed in the portlet window's title bar.

### Note

This is a simple portlet.xml primer, and is not meant as a replacement for what is covered in the actual Portlet specification.

## 6.2. JBoss Portal Descriptors

### 6.2.1. Datasource Descriptor (portal-*-ds.xml)

JBoss Portal requires a Datasource descriptor to be deployed alongside the jboss-portal.sar for access to a database. This section does not explain what a Datasource Descriptor is, but does explain where to obtain some templates that you can configure for your own installation.

### Note

For an in-depth introduction to datasources, you can view the JBoss AS documentation online here .

#### 6.2.1.1. Obtaining Datasource Descriptors Binary releases

Several template datasource descriptors can be found in the binary and bundle distributions. They are commonly located under the setup directory:

The directory setup should contain the following files, that you can customize for your own Database/Connector:

#### 6.2.1.2. Building Datasource Descriptors from Source

You will need a valid datasource descriptor, for JBoss Portal to communicate with your database. Having obtained the sources and having set your JBOSS_HOME environment variable ( Section 2.3.2.2, “Operating System Environment Setting” ), you can now have the JBoss Portal build system generate preconfigured datasources for you.

Navigate to JBOSS_PORTAL_HOME_DIRECTORY/core and type:

    build datasource

Once complete, the datasource build should produce the following directory and file structure:

At this point, you should configure the one that suits you best with your Database and JDBC driver.

    <?xml version="1.0" encoding="UTF-8"?>
    <datasources>
      <local-tx-datasource>
        <jndi-name>PortalDS</jndi-name>
        <connection-url>jdbc:postgresql:jbossportal</connection-url>
        <driver-class>org.postgresql.Driver</driver-class>
        <user-name>portal</user-name>
        <password>portalpassword</password>
      </local-tx-datasource>
    </datasources>

Please verify that the username, password, url, and driver-class are correct for your flavor of DB.

### 6.2.2. Portlet Debugging (jboss-portal.sar/conf/config.xml)

By default, JBoss Portal ships with all errors set to display. You can fine-tune this behaviour by modifying the file, jboss-portal.sar/conf/config.xml :

    <properties>
       <!-- When a window has restrictedaccess : show or hide values are permitted -->
       <entry key="core.render.window_access_denied">show</entry>
       <!-- When a window is unavailable : show or hide values are permitted -->
       <entry key="core.render.window_unavailable">show</entry>
       <!-- When a window produces an error : show, hide or message_only values are permitted -->
       <entry key="core.render.window_error">message_only</entry>
       <!-- When a window produces an internal error : show, hide are permitted -->
       <entry key="core.render.window_internal_error">show</entry>
       <!-- When a window is not found : show or hide values are permitted -->
       <entry key="core.render.window_not_found">show</entry>
    </properties>

Either show or hide are allowed as flags in these elements. Depending on the setting and actual error, either an error message is deployed or a full stack trace within the portlet window. Additionally, the core.render.window_error property supports the message_only value. This value will only display the error message whereas show will display the full stack trace if it is available.

## 6.3. Descriptor Examples

### 6.3.1. Defining a new portal page

This sample application and descriptor will create a new page, named MyPage in your portal. To illustrate our example, we have made available a portlet with a page descriptor that you can download here: HelloWorld Page .

### Note

To use this example, simply extract the zip, and deploy the helloworldportalpage.war where your portal is running (hot-deployment supported).

Our sample includes a descriptor to define this new portal page, helloworld-object.xml , located under helloworldportalpage.war/WEB-INF/ , and it looks like this:

    <?xml version="1.0" encoding="UTF-8"?>
    <deployments>
       <deployment>
          <if-exists>overwrite</if-exists>
          <parent-ref>default</parent-ref>
          <properties/>
          <page>
             <page-name>MyPage</page-name>
             <window>
                <window-name>HelloWorldPortletPageWindow</window-name>
                <instance-ref>HelloWorldPortletPageInstance</instance-ref>
                <region>center</region>
                <height>0</height>
             </window>
             <security-constraint>
                <policy-permission>
                   <unchecked/>
                   <action-name>viewrecursive</action-name>
                </policy-permission>
             </security-constraint>
          </page>
       </deployment>
    </deployments>

A deployment file can be composed of a set of <deployments>. In our example file, above, we are defining a page, placing the portlet as a window on that page, and creating an instance of that portlet. You can then use the Management Portlet (bundled with JBoss Portal) to modify the instances of this portlet, reposition it, and so on...

- <if-exists> Possible values are overwrite or keep . Overwrite will destroy the existing object and create a new one based on the content of the deployment. Keep will maintain the existing objct deployment or create a new one if it does not yet exist.
- <parent-ref> Indicates whether the object should be hooked in to the portal tree.
- <properties> Properties definition specific to this page, commonly used to define the specific theme and layout to use. If not defined, the default portal layouts/theme combination will be used.
- <page> The start of a page definition.
- <page-name> The name of the page.
- <window> The start of a window definition.
- <window-name> The name of the window.
- <instance-ref> The instance reference used by this window. Should correspond with the <instance-name> variable.
- <height> The vertical position of this window within the region defined in the layout.
- <instance> The start of an instance definition. page.
- <instance-name> Maps to the above <instance-ref> variable.
- <component-ref> Takes the name of the application followed by the name of the portlet, as defined in the portlet.xml

-     <security-constraint>
         <policy-permission>
            <unchecked/>
            <action-name>viewrecursive</action-name>
         </policy-permission>
      </security-constraint>

  The security contraint portion is worth taking a look at, in an isolated fashion. It allows you to secure a specific page/portal based on a user's role.

  Role definition: You must define a role that this security constraint will apply to. Possible values are:

  - <unchecked/> Anyone can view this page.
  - <role-name>SOMEROLE</role-name> Access to this page is limited to the defined role.

  Access Rights: You must define the access rights given to the role defined. Possible values are:

  - view Users can view the page.
  - viewrecursive Users can view the page and child pages.
  - personalize Users are able to view AND personalize the page.
  - personalizerecursive Users are able to view AND personalize the page AND its child pages.

### 6.3.2. Defining a new portal instance

To illustrate our example, we have made available a portlet that you can download here: HelloPortal .

For our example we make available helloworld-object.xml located under helloworldportal.war/WEB-INF/ , and it looks like this:

    <?xml version="1.0" encoding="UTF-8"?>
    <deployments>
       <deployment>
          <parent-ref/>
          <if-exists>overwrite</if-exists>
          <portal>
             <portal-name>HelloPortal</portal-name>
             <properties>
                <!-- Set the layout for the default portal -->
                <!-- see also portal-layouts.xml -->
                <property>
                   <name>layout.id</name>
                   <value>generic</value>
                </property>
                <!-- Set the theme for the default portal -->
                <!-- see also portal-themes.xml -->
                <property>
                   <name>theme.id</name>
                   <value>Nphalanx</value>
                </property>
                <!-- set the default render set name (used by the render tag in layouts) -->
                <!-- see also portal-renderSet.xml -->
                <property>
                   <name>theme.renderSetId</name>
                   <value>divRenderer</value>
                </property>
                <!-- set the default strategy name (used by the strategy interceptor) -->
                <!-- see also portal-strategies.xml -->
                <property>
                   <name>layout.strategyId</name>
                   <value>maximizedRegion</value>
                </property>
             </properties>
             <supported-modes>
                <mode>view</mode>
                <mode>edit</mode>
                <mode>help</mode>
             </supported-modes>
             <supported-window-states>
                <window-state>normal</window-state>
                <window-state>minimized</window-state>
                <window-state>maximized</window-state>
             </supported-window-states>
             <page>
                <page-name>default</page-name>
                <properties/>
                <window>
                   <window-name>MyPortletWindow</window-name>
                   <instance-ref>MyPortletInstance</instance-ref>
                   <region>center</region>
                   <height>0</height>
                </window>
                <security-constraint>
                   <policy-permission>
                      <unchecked/>
                      <action-name>viewrecursive</action-name>
                   </policy-permission>
                </security-constraint>
             </page>
             <security-constraint>
                <policy-permission>
                   <unchecked/>
                   <action-name>personalizerecursive</action-name>
                </policy-permission>
             </security-constraint>
          </portal>
       </deployment>
       <deployment>
          <if-exists>overwrite</if-exists>
          <parent-ref>HelloPortal</parent-ref>
          <page>
             <page-name>foobar</page-name>
             <window>
                <window-name>MyPortletWindow</window-name>
                <instance-ref>MyPortletInstance</instance-ref>
                <region>center</region>
                <height>0</height>
             </window>
             <security-constraint>
                <policy-permission>
                   <unchecked/>
                   <action-name>viewrecursive</action-name>
                </policy-permission>
             </security-constraint>
          </page>
       </deployment>
    </deployments>

This example, when deployed, will register a new portal instance named `HelloPortal` with two pages in it. The portal instance can be accessed by navigating to: http://localhost:8080/portal/portal/HelloPortal for the default page, and http://localhost:8080/portal/portal/HelloPortal/foobar , for the second page created.

### Note

You must define a page named `default` for any new portal instance to be accessible via a web browser.

Prev | Up | Next
Chapter 5. Portlet Primer | Home | Chapter 7. Portal urls