6.2.2. The portlet-instances.xml Descriptor

The portlet-instances.xml descriptor is JBoss Portal specific, and allows developers to instantiate one-or-many instances of one-or-many portlets. The benefit of this allows one portlet to be instantiated several times, with different preference parameters. The following example instantiates two separate instances of the NewsPortlet, both using different parameters. One instance draws feeds from Red Hat announcements, and the other from McDonalds announcements:
<?xml version="1.0" standalone="yes"?>
<!DOCTYPE deployments PUBLIC
   "-//JBoss Portal//DTD Portlet Instances 2.6//EN"
   "http://www.jboss.org/portal/dtd/portlet-instances_2_6.dtd">
<deployments>
   <deployment>
      <instance>
         <instance-id>NewsPortletInstance1</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>
               <action-name>view</action-name>
               <unchecked/>
            </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>
               <action-name>view</action-name>
               <unchecked/>
            </policy-permission>
         </security-constraint>
      </instance>
   </deployment>
</deployments>
  • <deployments>...</deployments>
    The <deployments> element encapsulates the entire document, and is a container for <deployment> elements. Multiple deployments can be specified within the <deployments> element.
  • <deployment>
       <instance>...</instance>
    </deployment>
    The <deployment> element, and the embedded <instance> element, specify a portlet instance. The <deployment> element specifies object deployments, such as portals, pages, windows, and so on. The <instance> element creates instances of portlets. The portlet will only be created and configured if the portlet is present, and if an instance with the same name does not already exist.
  • <instance-id>...</instance-id>
    The <instance-id> elements defines a unique name given to an instance of a portlet. The <instance-id> value can be named anything, but it must match the value of one of the <instance-ref> elements in the WEB-INF/*-object.xml file.
  • <portlet-ref>...</portlet-ref>
    The <portlet-ref> element defines the portlet that an instance represents. The <portlet-ref> value must match the <portlet-name> given in the WEB-INF/portlet.xml file.
  • <preferences>
       <preference>...</preference>
    </preferences>
    The <preference> element configures a preference as a key-value pair. This value can be composed of a single string value, for example, the preference fruit can have the apple value. As well, this value can be composed of multiple strings, for example, the preference fruits can have values of apple, orange, and kiwi:
    <preferences>
       <preference>
          <name>fruits</name>
          <value>apple</value>
          <value>orange</value>
          <value>kiwi</value>
       </preference>
    </preferences>
    
    The <preference> element configures one preference, which is part of a set of preferences. Use the <preferences> element to define a set of preferences.
  • <security-constraint>
       <policy-permission>
          <action-name>viewrecursive</action-name>
          <unchecked/>
       </policy-permission>
    </security-constraint>
    The <security-constraint> element is a container for <policy-permission> elements. This example demonstrates the <security-constraint> and <policy-permission> elements.
    The <action-name> element defines the access rights given to the role defined. Accepted values are:
    • view: users can view the page.
    • viewrecursive: users can view the page and child pages.
    • personalize: users are able personalize the page's theme.
    • personalizerecursive: users are able personalize the page and child pages themes.
    You must define a role that the security constraint will apply to:
    • unchecked: anyone can view the page.
    • <role-name>EXAMPLEROLE</role-name>: only allow users that are part of the EXAMPLEROLE role to access the instance.
The previous portlet-instances.xml example makes reference to items found in other descriptor files. The following diagram illustrates the relationship between the portlet.xml, portlet-instances.xml, and *-object.xml descriptors:

Is the portlet-instances.xml descriptor required?

Technically, it is not. The portal object hierarchy, such as creating portals, pages, instances, and organizing them on the page, can be defined using the management portlet, which is accessible to JBoss Portal administrators.