Chapter 6. XML Descriptors
Prev |  | Next

## Chapter 6. XML Descriptors

### Roy Russo

`<roy@jboss.org>`

## 6.1. Changes since previous releases

The previous releases of JBoss Portal did not have an external schema to validate the various XML descriptors although it was internally validated by the portal. Since 2.6 we have worked on providing Document Type Definition (DTD) for the various descriptors. The DTD validation will be only effective if you XML descriptors declares it like that:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE deployments PUBLIC
    "-//JBoss Portal//DTD Portal Object 2.6//EN"
    "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">
    ...

If you do not perform the declaration then the previous mechanism will be used. The main difference between using the DTD and not is that the additional DTD validation is more strict specifically on the order of the XML elements. The following example will be accepted without the DTD declaration and will not with the DTD declaration:

    <?xml version="1.0" encoding="UTF-8"?>
    <deployment>
       <if-exists>overwrite</if-exists>
       <parent-ref>default.default</parent-ref>
       ...
    </deployment>

The correct descriptor is rather:

    <?xml version="1.0" encoding="UTF-8"?>
    <deployment>
       <parent-ref>default.default</parent-ref>
       <if-exists>overwrite</if-exists>
       ...
    </deployment>

The various DTD available are:

- For -object.xml descriptors: "-//JBoss Portal//DTD Portal Object 2.6//EN"
- For jboss-app.xml descriptors: "-//JBoss Portal//DTD JBoss Web Application 2.6//EN"
- For jboss-portlet.xml descriptors: "-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
- For portlet-instances.xml descriptors: "-//JBoss Portal//DTD Portlet Instances 2.6//EN"

Those files are available in the jboss-portal.sar/dtd/ folder

### 6.1.1. JBoss Portlet DTD

- Element <!ELEMENT portlet-app (remotable?,portlet*,service*)>

      The remotable element is used to configure the default behavior of the portlets with
      respect to WSRP exposure.

      For each portlet defined in portlet.xml, it is possible to configure specific
      settings of the portlet container.

      It is also possible to inject services in the portlet context of the application
      using the service elements.

- Element <!ELEMENT portlet (portlet-name,remotable?,ajax?,session-config?,transaction?,header-content?)>

      Additional configuration for a portlet.

      The portlet-name defines the name of the portlet. It must match a portlet defined already
      in portlet.xml of the same web application.

      The remotable element configures the portlet exposure to WSRP. If no value is present
      then the value considered is either the value defined globally at the portlet
      application level or false.

      The trans-attribute value specifies the behavior of the portlet when it is invoked at
      runtime with respect to the transactionnal context. According to how the portlet is
      invoked a transaction may exist or not before the portlet is invoked. Usually in the
      local context the portal transaction could be present. By default the value considered is
       NotSupported which means that the portal transaction will be suspended for the duration
       of the portlet invocation.

      Example:

      <portlet>
         <portlet-name>MyPortlet</portlet-name>
         <remotable>true</remotable>
         <trans-attribute>Required</trans-attribute>
      </portlet>

- Element <!ELEMENT portlet-name (#PCDATA)>

      The portlet name.

- Element <!ELEMENT remotable (#PCDATA)>

      The remotable value is used for WSRP exposure. The accepted values are the
      litterals true of false.

- Element <!ELEMENT ajax (partial-refresh)>

      The ajax tag allows to configure the ajax capabilities of the portlet. If
      the portlet is tagged as partial-refresh then the portal may use partial page
      refreshing and render only that portlet. If the portlet partial-refresh value
      is false, then the portal will perform a full page refresh when the portlet is refreshed.

- Element <!ELEMENT partial-refresh (#PCDATA)>

      The authorized values for the partial-refresh element are true or false.

- Element <!ELEMENT session-config (distributed)>

      This element configure the portlet session of the portlet.

      The distributed element instructs the container to distribute the session attributes
      using the portal session replication. It applies only to local portlets are not to
      remote portlets. The default value is false.

      Example:

      <session-config>
         <distributed>true</distributed>
      </session-config>

- Element <!ELEMENT distributed (#PCDATA)>

      The authorized values for the distributed element are true or false.

- Element <!ELEMENT transaction (trans-attribute)>

      Defines how the portlet behaves with the transactionnal context. The default value
      is Never.

      Example:

      <transaction>
         <trans-attribute>Required</transaction>
      <transaction>

- Element <!ELEMENT trans-attribute (#PCDATA)>

      The trans-attribute value defines the transactionnal behavior. The accepted values
      are Required, Mandatory, Never, Supports, NotSupported and RequiresNew.

- Element <!ELEMENT header-content (link | script | meta)*>

      Specify content which should be included in the portal aggregated page when the portlet
      is present on that page. This setting only applies when the portlet is used in the local mode.

- Element <!ELEMENT link EMPTY>

      No content is allowed inside an link element.

- Element <!ELEMENT script (#PCDATA)>

      The script header element can contain inline script definitions.

- Element <!ELEMENT meta EMPTY>

      No content is allowed for meta element.

- Element <!ELEMENT service (service-name,service-class,service-ref)>

      Declare a service that will be injected by the portlet container as an
      attribute of the portlet context.

      Example:

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

      In the portlet it is then possible to use it by doing a lookup on the service
      name, for example in the init() lifecycle method :

      public void init()
      {
         UserModule userModule = (UserModule)getPortletContext().getAttribute("UserModule");
      }

- Element <!ELEMENT service-name (#PCDATA)>

      The service name that will be used to bind the service as a portlet context attribute.

- Element <!ELEMENT service-class (#PCDATA)>

      The full qualified name of the interface that the service implements.

- Element <!ELEMENT service-ref (#PCDATA)>

      The reference to the service. In the JMX Microkernel environment it consist of the JMX
      name of the service MBean. For an MBean reference if the domain is left out, then the
      current domain of the portal will be used.

### 6.1.2. Portlet Instance DTD

- Element <!ELEMENT deployments (deployment*)>

      The deployements element is a container for deployment elements.

- Element <!ELEMENT deployment (if-exists?,instance)>

      The deployment is a container for an instance element.

- Element <!ELEMENT if-exists (#PCDATA)>

      The if-exists element is used to define action to take if instance with such name is
      already present. 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.

- Element <!ELEMENT instance (instance-id,portlet-ref,preferences?,security-constraint?)>

      The instance element is used to create an instance of a portlet from the portlet
      application of the same war file containing the portlet-instances.xml file. The portlet
      will be created and configured only if the portlet is present and an instance with
      such a name does not already exist.

      Example :

      <instance>
         <instance-id>MyPortletInstance</instance-id>
         <portlet-ref>MyPortlet</portlet-ref>
         <preferences>
            <preference>
               <name>abc</name>
               <value>def</value>
            </preference>
         </preferences>
         <security-constraint>
            <policy-permission>
               <role-name>User</role-name>
               <action-name>view</action-name>
            </policy-permission>
         </security-constraint>
      </instance>

- Element <!ELEMENT instance-id (#PCDATA)>

      The identifier of the instance.

- Element <!ELEMENT portlet-ref (#PCDATA)>

      The reference to the portlet which is its portlet name.

- Element <!ELEMENT preferences (preference)>

      The preferences element configures the instance with a specific set of preferences.

- Element <!ELEMENT preference (name,value)>

      The preference configure one preference of a set of preferences.

- Element <!ELEMENT name (#PCDATA)>

      A name.

- Element <!ELEMENT value (#PCDATA)>

      A string value.

- Element <!ELEMENT security-constraint (policy-permission*)>

      The security-constraint element is a container for policy-permission elements

      Examples:

      <security-constraint>
          <policy-permission>
             <role-name>User</role-name>
             <action-name>view</action-name>
          </policy-permission>
      </security-constraint>

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

- Element <!ELEMENT policy-permission (action-name*,unchecked?,role-name*)>

      The policy-permission element is used to secure a specific portlet instance based on a user's role.

- Element <!ELEMENT action-name (#PCDATA)>

      The action-name element is used to 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 personalize the page's theme.
          * personalizerecursive - Users are able personalize the page AND its children's themes.
            pages.

- Element <!ELEMENT unchecked EMPTY>

      The unchecked element is used to define (if present) that anyone can view this instance

- Element <!ELEMENT role-name (#PCDATA)>

      The role-name element is used to define a role that this security constraint will apply to

          * <role-name>SOMEROLE</role-name> Access to this instance is limited to the defined role.

### 6.1.3. Portal Object DTD

- Element <!ELEMENT deployments (deployment*)>

      The deployements element is a generic container for deployment elements.

- Element <!ELEMENT deployment (parent-ref,if-exists?,(context | portal | page | window))>

      The deployment is a generic container for portal object elements. The parent-ref
      child gives the name of the parent object that the current object will use as parent.
      The optional if-exists element define the behavior when a portal object which
      an identical name is already child of the parent element. The default behavior of
      the if-exist tag is to keep the existing object and not create a new object. The
      last element is the portal object itself.

      Example:

      <deployment>
         <parent-ref>default</parent-ref>
         <page>
            ...
         </page>
      </deployment>

      All portal objects have a common configuration which can be :

      1/ a listener : specifies the id of a listener is the listener registry. A listener
      object is able to listen portal events which apply to the portal node hierarchy.

      2/ properties : a set of generic properties owned by the portal object. Some
      properties can drive the behavior of the object.

      3/ security-constraint : defines security configuration of the portal object.

- Element <!ELEMENT parent-ref (#PCDATA)>

      Contains a reference to the parent object. The naming convention for naming object
      is to concatenate the names of the path to the object and separate the names by a dot.
      If the path is empty then the empty string must be used.

      Example:

      <parent-ref/> the root having an empty path

      <parent-ref>default</parent-ref> the object with the name default under the root
      having the path (default)

      <parent-ref>default.default</parent-ref> the object with the path (default,default)

- Element <!ELEMENT if-exists (#PCDATA)>

      The authorized values are overwrite and keep. Overwrite means that the existing
      object will be destroyed and the current declaration will be used. Keep means that
      the existing object will not be destroyed and no creation hence will be done.

- Element <!ELEMENT context (context-name,properties?,listener?,security-constraint?,portal*)>

      A portal object of type context. A context type represent a node in the tree which
      does not have a visual representation. It can exist only under the root. A context can
      only have children with the portal type.

- Element <!ELEMENT context-name (#PCDATA)>

      The context name value.

- Element <!ELEMENT portal (portal-name,supported-modes,supported-window-states?,properties?,listener?,security-constraint?,page*)>

      A portal object of type portal. A portal type represents a virtual portal and can
      have children of type page. In addition of the common portal object elements it support
      also the declaration of the modes and the window states it supports. If no declaration
      of modes or window states is done then the default value will be respectively
      (view,edit,help) and (normal,minimized,maximized).

- Element <!ELEMENT portal-name (#PCDATA)>

      The portal name value.

- Element <!ELEMENT supported-modes (mode*)>

      The supported modes of a portal.

      Example:

      <supported-mode>
         <mode>view</mode>
         <mode>edit</mode>
         <mode>help</mode>
      </supported-mode>

- Element <!ELEMENT mode (#PCDATA)>

      A portlet mode value.

- Element <!ELEMENT supported-window-states (window-state*)>

      The supported window states of a portal.

      Example:

      <supported-window-states>
         <window-state>normal</window-state>
         <window-state>minimized</window-state>
         <window-state>maximized</window-state>
      </supported-window-states>

- Element <!ELEMENT window-state (#PCDATA)>

      A window state value.

- Element <!ELEMENT page (page-name,properties?,listener?,security-constraint?,(page | window)*)>

      A portal object of type page. A page type represents a page which can have children of
      type page and window. The children windows are the windows of the page and the children
      pages are the subpages of this page.

- Element <!ELEMENT page-name (#PCDATA)>

      The page name value.

- Element <!ELEMENT window (window-name,(instance-ref | content),region,height,properties?,listener?)>

      A portal object of type window. A window type represents a window. Beside the common
      properties a window has a content and belong to a region on the page.

      The instance-ref or content tags are used to define the content of the window. The
      usage of the content tag is generic and can be used to describe any kind of content.
      The instance-ref is a shortcut to define a content type of portlet which points to a
      portlet instance.

      The region and height defines how the window is placed in the page.

- Element <!ELEMENT window-name (#PCDATA)>

      The window name value.

- Element <!ELEMENT instance-ref (#PCDATA)>

      Define the content of the window as a reference to a portlet instance. The value
      is the id of the instance.

      Example:

      <instance-ref>MyPortletInstance</instance-ref>

- Element <!ELEMENT content (content-type,content-uri)>

      Define the content of the window in a generic manner. The content is define by
      the type of the content and an URI which acts as an identificator for the content.

      Example:

      <content>
         <content-type>portlet</content-type>
         <content-uri>MyPortletInstance</content-uri>
      </content>

      <content>
         <content-type>cms</content-type>
         <content-uri>/default/index.html</content-uri>
      </content>

- Element <!ELEMENT content-type (#PCDATA)>

      The content type of the window.

- Element <!ELEMENT content-uri (#PCDATA)>

      The content URI of the window.

- Element <!ELEMENT region (#PCDATA)>

      The region the window belongs to.

- Element <!ELEMENT height (#PCDATA)>

      The height of the window in the particular region.

- Element <!ELEMENT listener (#PCDATA)>

      Define a listener for a portal object. The value is the id of the listener.

- Element <!ELEMENT properties (property*)>

      A set of generic properties for the portal object.

- Element <!ELEMENT property (name,value)>

      A generic string property.

- Element <!ELEMENT name (#PCDATA)>

      A name value.

- Element <!ELEMENT value (#PCDATA)>

      A value.

- Element <!ELEMENT security-constraint (policy-permission*)>

      The security-constraint element is a container for policy-permission elements

      Examples:

      <security-constraint>
          <policy-permission>
             <role-name>User</role-name>
             <action-name>view</action-name>
          </policy-permission>
      </security-constraint>

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

- Element <!ELEMENT policy-permission (action-name*,unchecked?,role-name*)>

      The policy-permission element is used to secure a specific portal page based on a user's role.

- Element <!ELEMENT action-name (#PCDATA)>

      The role-name element is used to define a role that this security constraint will apply to

          * <role-name>SOMEROLE</role-name> Access to this portal page is limited to the defined role.

- Element <!ELEMENT unchecked EMPTY>

      The unchecked element is used to define (if present) that anyone can view this portal page

- Element <!ELEMENT role-name (#PCDATA)>

      The action-name element is used to define the access rights given to the role defined.
      Possible values are:

          * view - Users can view the page.

### 6.1.4. JBoss App DTD

- Element <!ELEMENT jboss-app (app-name?)>

      <!DOCTYPE jboss-app PUBLIC
         "-//JBoss Portal//DTD JBoss Web Application 2.6//EN"
         "http://www.jboss.org/portal/dtd/jboss-app_2_6.dtd">

- Element <!ELEMENT app-name (#PCDATA)>

      When a web application is deployed, the context path under wich it is deployed
      is taken as application name. The application name value in this descriptor is
      used to override it. When a component references a references a portlet, it needs to
      reference the application too and if the portlet application war file is renammed
      the reference is not valid anymore. Therefore this tag is used to have an application
      name that does not depend upon the context path under which the application is deployed.

## 6.2. 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.4, “Descriptor Examples” for samples on how they are used within a portlet application.

### 6.2.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.4, “Descriptor Examples”.

### Note

Is this descriptor mandatory? Technically, no, as you can define your portal object hierarchy (create portals, pages, instances and organize them as you see fit) from the management portlet accessible to Portal administrators.

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE deployments PUBLIC
       "-//JBoss Portal//DTD Portal Object 2.6//EN"
       "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">
    <deployments>
       <deployment>
          <parent-ref>default.default</parent-ref>
          <if-exists>overwrite</if-exists>
          <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.2.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 define your portal object hierarchy (create portals, pages, instances and organize them as you see fit) from the management portlet accessible to Portal administrators.

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"?>
    <!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>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>
                   <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 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>
            <action-name>viewrecursive</action-name>
            <unchecked/>
         </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 personalize the page's theme.
  - personalizerecursive Users are able to personalize the page AND its children's themes.

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.2.3. jboss-portlet.xml

### Note

Is this descriptor mandatory? Technically, no, but might be required to access JBoss-specific functionality that is not covered by the Portlet specification.

This descriptor is useful when you need to access JBoss-specific functionality within your portlet application. It would normally be packaged inside your portlet war, alongside the other descriptors in this section.

#### 6.2.3.1. Injecting Header Content

    <?xml version="1.0" standalone="yes"?>
    <!DOCTYPE portlet-app PUBLIC
       "-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
       "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd">
    <portlet-app>
       <portlet>
          <portlet-name>ManagementPortlet</portlet-name>
          <header-content>
             <link rel="stylesheet" type="text/css" href="/images/management/management.css"
                   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.2.3.2. Injecting Services in the portlet context

    <?xml version="1.0" standalone="yes"?>
    <!DOCTYPE portlet-app PUBLIC
       "-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
       "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd">
    <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 as an attribute 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.2.3.3. Defining extra portlet information

Since JBoss Portal 2.6.3, icons can be defined for a portlet.

    <?xml version="1.0" standalone="yes"?>
    <!DOCTYPE portlet-app PUBLIC
       "-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
       "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd">
    <portlet-app>
       <portlet>
          <portlet-name>ManagementPortlet</portlet-name>
          <portlet-info>
             <icon>
                <small-icon>/images/smallIcon.png</small-icon>
                <large-icon>/images/largeIcon.png</small-icon>
             </icon>
          </portlet-info>
       </portlet>
    </portlet-app>

The reference can be absolute (http://www.example.com/images/smallIcon.png) or relative to the webapp context if starting with a '/'. Those icons can be used by different parts of the portal User Interface.

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

See Section 13.5, “Portlet Session Replication”.

### 6.2.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 edited version of our JBoss Portal UserPortlet definition. Normally, you would package this descriptor in your portlet WAR file.

    <?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 within this archive.

-     <description>...</description>

  A verbal description of this portlet's function.

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

  The name of this portlet, usually the class name, though it doesn't have to be.

-     <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. Several locales can be specified.

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

  The resource bundle that will containing the localized information for the specified locales.

-     <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.3. JBoss Portal Descriptors

### 6.3.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.3.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.3.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.3.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 behavior by modifying some properties in the file, jboss-portal.sar/conf/config.xml :

    <!-- 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>

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.3. Login to dashboard

By default, when a user logs in, she is forwarded to the default page of the default portal. In order to forward her to her dashboard, it is possible to set in the file jboss-portal.sar/conf/config.xml:

    <!-- Namespace to use when logging-in, use "dashboard" to directly
         log-in the dashboard otherwise use "default" -->
    <entry key="core.login.namespace">dashboard</entry>

## 6.4. Descriptor Examples

### 6.4.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"?>
    <!DOCTYPE deployments PUBLIC
       "-//JBoss Portal//DTD Portal Object 2.6//EN"
       "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">
    <deployments>
       <deployment>
          <parent-ref>default</parent-ref>
          <if-exists>overwrite</if-exists>
          <properties/>
          <page>
             <page-name>MyPage</page-name>
             <security-constraint>
                <policy-permission>
                   <action-name>viewrecursive</action-name>
                   <unchecked/>
                </policy-permission>
             </security-constraint>
             <window>
                <window-name>HelloWorldPortletPageWindow</window-name>
                <instance-ref>HelloWorldPortletPageInstance</instance-ref>
                <region>center</region>
                <height>0</height>
             </window>
          </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>
            <action-name>viewrecursive</action-name>
            <unchecked/>
         </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 personalize the page's theme.
  - personalizerecursive Users are able to personalize the page AND its children's themes.

### 6.4.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"?>
    <!DOCTYPE deployments PUBLIC
       "-//JBoss Portal//DTD Portal Object 2.6//EN"
       "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">
    <deployments>
       <deployment>
          <parent-ref/>
          <if-exists>overwrite</if-exists>
          <portal>
             <portal-name>HelloPortal</portal-name>
             <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>
             <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>renaissance</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>
             </properties>
             <security-constraint>
                <policy-permission>
                   <action-name>personalizerecursive</action-name>
                   <unchecked/>
                </policy-permission>
             </security-constraint>
             <page>
                <page-name>default</page-name>
                <security-constraint>
                   <policy-permission>
                      <action-name>viewrecursive</action-name>
                      <unchecked/>
                   </policy-permission>
                </security-constraint>
                <window>
                   <window-name>MyPortletWindow</window-name>
                   <instance-ref>MyPortletInstance</instance-ref>
                   <region>center</region>
                   <height>0</height>
                </window>
             </page>
          </portal>
       </deployment>
       <deployment>
          <parent-ref>HelloPortal</parent-ref>
          <if-exists>overwrite</if-exists>
          <page>
             <page-name>foobar</page-name>
             <security-constraint>
                <policy-permission>
                   <action-name>viewrecursive</action-name>
                   <unchecked/>
                </policy-permission>
             </security-constraint>
             <window>
                <window-name>MyPortletWindow</window-name>
                <instance-ref>MyPortletInstance</instance-ref>
                <region>center</region>
                <height>0</height>
             </window>
          </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