JBoss.org Community Documentation

- Prev
- Next

## Chapter 6. XML Descriptors

### Thomas Heute

### Roy Russo

## 6.1. DTDs

To use a DTD, add the following declaration to the start of the desired descriptors:

    <?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 use the DTD declaration, the previous mechanism for XML validation is used. The DTD is more strict, specifically with the order of XML elements. The following is an example from a `*-object.xml` descriptor, which is valid if you are not using the DTD, but is rejected if you are:

    <if-exists>overwrite</if-exists>

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

The correct element order, and one which is valid against the DTD, is as follows:

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

    <if-exists>overwrite</if-exists>

The following DTDs are available:

- 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"`

The DTDs are located in the `$JBOSS_HOME/server/`configuration`/deploy/jboss-portal.sar/dtd/` directory.

### 6.1.1. The JBoss Portlet DTD

The following items refer to elements found in the JBoss Portlet DTD, `$JBOSS_HOME/server/`configuration`/deploy/jboss-portal.sar/dtd/jboss-portlet_`version_number`.dtd`:

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

Use the `<remotable>` element to configure the default behavior of portlets with respect to WSRP exposure: if no value is given, the value is either the value globally defined at the portlet application level, or `false`. Accepted values are `true` and `false`.

You can configure specific settings of the portlet container for each portlet defined in the `WEB-INF/portlet.xml` file. Use the `<service>` element to inject services into the portlet context of applications.

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

Additional configuration of the portlet. The `<portlet-name>` element defines the portlet name. It must match a portlet defined in the `WEB-INF/portlet.xml` file for that application.

Use the `<remotable>` element to configure the default behavior of portlets with respect to WSRP exposure: if no value is given, the value is either the value globally defined at the portlet application level, or `false`.

The `<trans-attribute>` element specifies the behavior of the portlet when it is invoked at runtime with respect to the transactional context. Depending on how the portlet is invoked, a transaction may or may not exist before the portlet is invoked. The portal transaction is usually present in the local context. The default value is `NotSupported`, which means that the portal transaction is suspended for the duration of the portlet's invocation. Accepted values are `Required`, `Mandatory`, `Never`, `Supports`, `NotSupported`, and `RequiresNew`.

The following is an example section from a `WEB-INF/portlet.xml` file, which uses the `<portlet-name>`, `<remotable>`, and `<trans-attribute>` elements:

    <portlet>

       <portlet-name>MyPortlet</portlet-name>

       <remotable>true</remotable>

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

    </portlet>

    <!ELEMENT portlet-name (#PCDATA)>

The portlet name.

    <!ELEMENT remotable (#PCDATA)>

Accepted values are `true` and `false`.

    <!ELEMENT ajax (partial-refresh)>

Use the `ajax` element to configure the Asynchronous JavaScript and XML (AJAX) capabilities of the portlet.

    <!ELEMENT partial-refresh (#PCDATA)>

If a portlet uses the `true` value for the `<partial-refresh>` element, the portal uses partial-page refreshing and only renders that portlet. If the `<partial-refresh>` element uses a `false` value, the portal uses a full-page refresh when the portlet is refreshed.

    <!ELEMENT session-config (distributed)>

The `<session-config>` element configures the portlet session for the portlet. The `<distributed>` element instructs the container to distribute the session attributes using portal session replication. This only applies to local portlets, not remote portlets.

The following is an example of the `<session-config>` and `<distributed>` elements:

    <session-config>

       <distributed>true</distributed>

    </session-config>

    <!ELEMENT distributed (#PCDATA)>

Accepted values are `true` and `false`. The default value is `false`.

    <!ELEMENT transaction (trans-attribute)>

The `<transaction>` element defines how the portlet behaves with regards to the transactional context. The `<trans-attribute>` element specifies the behavior of the portlet when it is invoked at runtime, with respect to the transactional context. Depending on how the portlet is invoked, a transaction may or may not exist before the portlet is invoked. The portal transaction is usually present in the local context.

The following is an example of the `<transaction>` and `<trans-attribute>` elements:

    <transaction>

       <trans-attribute>Required</transaction>

    <transaction>

    <!ELEMENT trans-attribute (#PCDATA)>

The default value is `NotSupported`, which means that the portal transaction is suspended for the duration of the portlet's invocation. Accepted values are `Required`, `Mandatory`, `Never`, `Supports`, `NotSupported`, and `RequiresNew`.

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

Specify the content to 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 link EMPTY>

No content is allowed inside a link element.

    <!ELEMENT script (#PCDATA)>

Use the `<script>` element for inline script definitions.

    <!ELEMENT meta EMPTY>

No content is allowed for the `<meta>` 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.

The following is an example of the `<service>` element:

    <service>

       <service-name>UserModule</service-name>

       <service-class>org.jboss.portal.identity.UserModule</service-class>

       <service-ref>:service=Module,type=User</service-ref>

    </service>

To use an injected service in a portlet, perform a lookup of the `<service-name>`, for example, using the `init()` lifecycle method:

    public void init()

    {

       UserModule userModule = (UserModule)getPortletContext().getAttribute("UserModule");

    }

    <!ELEMENT service-name (#PCDATA)>

The `<service-name>` element defines the name that binds the service as a portlet context attribute.

    <!ELEMENT service-class (#PCDATA)>

The `<service-class>` element defines the fully qualified name of the interface that the service implements.

    <!ELEMENT service-ref (#PCDATA)>

The `<service-ref>` element defines the reference to the service. In the JMX Microkernel environment, this consist of the JMX name of the service MBean. For an MBean reference, if the domain is left out, the current domain of the portal is used.

### 6.1.2. The JBoss Portlet Instance DTD

The following items refer to elements found in the JBoss Portlet Instance DTD, `$JBOSS_HOME/server/`configuration`/deploy/jboss-portal.sar/dtd/portlet-instances_`version_number`.dtd`:

    <!ELEMENT deployments (deployment*)>

The `<deployments>` element is a container for `<deployment>` elements.

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

The `<deployment>` element is a container for the `<instance>` element.

    <!ELEMENT if-exists (#PCDATA)>

The `<if-exists>` element defines the action to take if an instance with the same name already exists. Accepted values are `overwrite` and `keep`. The `overwrite` option destroys the existing object, and creates a new one based on the content of the deployment. The `keep` option maintains the existing object deployment, or creates a new one if it does not exist.

    <!ELEMENT instance (instance-id,portlet-ref,display-name*,preferences?,
    security-constraint?, (display-name* | (resource-bundle, supported-locale+)))>

The `<instance>` element is used in the `WEB-INF/portlet-instances.xml` file, which 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.

The following is an example of the `<instance>` element, which also contains the `<security-constraint>` element. Descriptions of each element follow afterwards:

    <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 instance-id (#PCDATA)>

The instance identifier. The `<instance-id>` value can be named anything, but it must match the `<instance-ref>`value given in the `*-object.xml` file.

    <!ELEMENT portlet-ref (#PCDATA)>

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.

    <!ELEMENT preferences (preference+)>

The `<preferences>` element configures an instance with a set of preferences.

    <!ELEMENT preference (name,value)>

The `<preference>` element configures one preference, which is part of a set of preferences. Use the `<preferences>` element to define a set of preferences.

    <!ELEMENT name (#PCDATA)>

A name.

    <!ELEMENT value (#PCDATA)>

A string value.

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

The `<security-constraint>` element is a container for `<policy-permission>` elements. The following is an example of the `<security-constraint>` and `<policy-permission>` elements:

    <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 policy-permission (action-name*,unchecked?,role-name*)>

The `<policy-permission>` element secures a specific portlet instance based on a user's role.

    <!ELEMENT action-name (#PCDATA)>

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.

    <!ELEMENT unchecked EMPTY>

If present, the `<unchecked>` element defines anyone can view the instance.

    <!ELEMENT role-name (#PCDATA)>

The `<role-name>` element defines a role that the security constraint will apply to. The following example only allows users that are part of the `EXAMPLEROLE` role to access the instance:

    <role-name>EXAMPLEROLE</role-name>

### 6.1.3. The JBoss Portal Object DTD

The following items refer to elements found in the JBoss Portal Object DTD, `$JBOSS_HOME/server/`configuration`/deploy/jboss-portal.sar/dtd/portal-object_`version_number`.dtd`:

    <!ELEMENT deployments (deployment*)>

The `<deployments>` element is a container for `<deployment>` elements.

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

The `<deployment>` element is a generic container for portal object elements. The `<parent-ref>` child element gives the name of the parent object that the current object will use as parent. The optional `<if-exists>` element defines the action to take if an instance with the same name already exists. The default behavior of the `<if-exists>` element is to keep the existing object, and not to create a new object.

The following is an example of the `<deployment>` and `<parent-ref>` elements:

    <deployment>

       <parent-ref>default</parent-ref>

       <page>

          ...

       </page>

    </deployment>

All portal objects have a common configuration which can include:

- a listener: specifies the ID of a listener in the listener registry. A listener object is able to listen to portal events, which apply to the portal node hierarchy.

- properties: a set of generic properties owned by the portal object. Certain properties drive the behavior of the portal object.

- security-constraint: defines the security configuration for the portal object.

    <!ELEMENT parent-ref (#PCDATA)>

The `<parent-ref>` element contains a reference to the parent object. The naming convention for naming objects is to concatenate the names of the path to the object, and separate the names using a period. If the path is empty, the empty string must be used. The `<parent-ref>` element tells the portal where the portlet appears. The syntax for the `<parent-ref>` element is ``portal-instance`.`portal-page``.

The following is an example of the root having an empty path:

    <parent-ref />

The following specifies that the portlet appears in the portal instance named `default`:

    <parent-ref>default</parent-ref>

The following specifies that the portlet appear in the portal instance named `default`, and on the page named `default`:

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

    <!ELEMENT if-exists (#PCDATA)>

The `<if-exists>` element defines the action to take if an instance with the same name already exists. Accepted values are `overwrite` and `keep`. The `overwrite` option destroys the existing object, and creates a new one based on the content of the deployment. The `keep` option matains the existing object deployment, or creates a new one if it does not exist.

    <!ELEMENT context (context-name,properties?,listener?,security-constraint?,portal*,
    (display-name* | (resource-bundle, supported-locale+)))>

The context type of the portal object. A context type represent a node in a tree, which does not have a visual representation, and only exists under the root. A context can only have children that use the portal type.

    <!ELEMENT context-name (#PCDATA)>

The context name.

    <!ELEMENT portal (portal-name,supported-modes,supported-window-states?,properties?,listener?,
    security-constraint?,page*, (display-name* | (resource-bundle, supported-locale+)))>

A portal object that uses the portal type. A portal type represents a virtual portal, and can only have children that use the page type. In addition to the common portal object elements, it also allows you to declare modes and window states that are supported.

    <!ELEMENT portal-name (#PCDATA)>

The portal name.

    <!ELEMENT supported-modes (mode*)>

The `<supported-modes>` elements defines the supported modes of the portal. Accepted values are `view`, `edit`, and `help`.

The following is an example of the `<supported-mode>` and `<mode>` elements:

    <supported-mode>

       <mode>view</mode>

       <mode>edit</mode>

       <mode>help</mode>

    </supported-mode>

    <!ELEMENT mode (#PCDATA)>

The portlet mode value. If there are no declarations of modes or window states, the default values are `view`, `edit`, `help`, and `normal`, `minimized`, `maximized`, respectively.

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

Use the `<supported-window-states>` element to define the supported window states of the portal. The following is an example of the `<supported-window-states>` and `<window-state>` elements:

    <supported-window-states>

       <window-state>normal</window-state>

       <window-state>minimized</window-state>

       <window-state>maximized</window-state>

    </supported-window-states>

    <!ELEMENT window-state (#PCDATA)>

Use the `<window-state>` element to define a window states. Accepted values are `normal`, `minimized`, and `maximized`.

    <!ELEMENT page (page-name,properties?,listener?,security-constraint?,(page | window)*,
    (display-name* | (resource-bundle, supported-locale+)))>

A portal object that uses the page type. A page type represents a page, and can only have children that use the page and window types. The children windows are the windows of the page, and the children pages are the subpages of the page.

    <!ELEMENT page-name (#PCDATA)>

The page name.

    <!ELEMENT window (window-name,(instance-ref|content),region,height,initial-window-state?,
    initial-mode?,properties?,listener?, (display-name* | (resource-bundle, supported-locale+)))>

A portal object that uses the window type. A window type represents a window. Besides the common properties, a window has content, and belongs to a region on the page.

The `<instance-ref>` and `<content>` elements, configured in the `WEB-INF/*-object.xml` files, define the content of a window. The `<content>` element is generic, and describes any kind of content. The `<instance-ref>` element is a shortcut to define the content-type of the portlet, which points to a portlet instance. The value of `<instance-ref>` must match the value of one of the `<instance-id>` elements in the `WEB-INF/portlet-instances.xml` file.

    <!ELEMENT window-name (#PCDATA)>

The window name value.

    <!ELEMENT instance-ref (#PCDATA)>

Define the content of the window as a reference to a portlet instance. This value is the ID of a portlet instance, and must much the value of one of the `<instance-id>` elements in the `WEB-INF/portlet-instances.xml` file. The following is an example of the `<instance-ref>` element:

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

    <!ELEMENT region (#PCDATA)>

The region the window belongs to. The `<region>` element specifies where the window appears on the page.

    <!ELEMENT height (#PCDATA)>

The height of the window in a particular region.

    <!ELEMENT listener (#PCDATA)>

Define a listener for a portal object. This value is the ID of the listener.

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

Define the content of a window in a generic manner. The content is defined by the type of content, and a URI, which acts as an identifier for the content. The following is an example of the `<content>` element, which is configured in the `WEB-INF/*-object.xml` files:

    <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 content-type (#PCDATA)>

The content type of the window. The `<content-type>` element specifies the content to display, for example, a `portlet`.

    <!ELEMENT content-uri (#PCDATA)>

The content URI of the window. The `<content-uri>` element specifies which content to display, for example, a portlet instance. To display a file from the CMS, use the `<content-uri>` element to define the full path to that file in the CMS.

    <!ELEMENT properties (property*)>

A set of generic properties for the portal object. The `<properties>` elements contain definitions specific to a portal object.

    <!ELEMENT property (name,value)>

A generic string property. The following table lists accepted values. This table is not exhaustive:

Table 6.1. Properties

Name | Description
--- | ---
`layout.id` | Defines the layout to use for the portal object and sub-objects if they do not override the value.
`theme.id` | Defines the theme used for the portal object and sub-objects if they do not override the value.
`portal.defaultObjectName` | Defines the default child object. If applied to a `context`, it defines the default portal. If applied to a `portal`, it defines the default portal page.

    <!ELEMENT name (#PCDATA)>

A name value.

    <!ELEMENT value (#PCDATA)>

A value.

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

The `<security-constraint>` element is a container for `<policy-permission>` elements. The following is an example of the `<security-constraint>` and `<policy-permission>` elements:

    <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 policy-permission (action-name*,unchecked?,role-name*)>

The `<policy-permission>` element is secures a specific portlet instance based on a user's role.

    <!ELEMENT action-name (#PCDATA)>

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.

    <!ELEMENT unchecked EMPTY>

If present, the `<unchecked>` element defines that anyone can view the instance.

    <!ELEMENT role-name (#PCDATA)>

The `<role-name>` element defines a role that the security constraint applies to. The following example only allows users that are part of the `EXAMPLEROLE` role to access the instance:

    <role-name>EXAMPLEROLE</role-name>

### 6.1.4. The JBoss Portal App DTD

The following items refer to elements found in the JBoss Portal App DTD, `$JBOSS_HOME/server/`configuration`/jboss-portal.sar/dtd/jboss-app_`version_number`.dtd`:

    <Element <![CDATA[<!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 app-name (#PCDATA)>

When a web application is deployed, the context path under which it is deployed is taken as the application name. The application name value in the `<app-name>` element overrides it. When a component references a portlet, it needs to reference the application too, and if the portlet application WAR file is renamed, the reference is no longer valid; therefore, the `<app-name>` element 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

The following sections describe the descriptors that define portal objects, such as portals, pages, portlet instances, windows, and portlets. Refer to Section 5.2, “Tutorials” and Section 6.4, “Descriptor Examples” for examples on using these descriptors within a portlet application.

### 6.2.1. `*-object.xml` Descriptors

The `*-object.xml` descriptors define portal instances, pages, windows, and the window layout. As well, themes and layouts for specific portal instances, pages, and windows, can be defined. The following example defines a portlet window being added to the `default` page, in the `default` portal. For advanced functionality using these descriptors, refer to Section 6.4, “Descriptor Examples”:

    <?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>` element encapsulates the entire document, and is a container for `<deployment>` elements. Multiple deployments can be specified within the `<deployments>` element.

-     <deployment>...</deployment>

  The `<deployment>` element specifies object deployments, such as portals, pages, windows, and so on.

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

  The `<if-exists>` element defines the action to take if an instance with the same name already exists. Accepted values are `overwrite` and `keep`. The `overwrite` option destroys the existing object, and creates a new one based on the content of the deployment. The `keep` option maintains the existing object deployment, or creates a new one if it does not exist.

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

  The `<parent-ref>` element contains a reference to the parent object. The naming convention for naming objects is to concatenate the names of the path to the object, and separate the names using a period. If the path is empty, the empty string must be used. The `<parent-ref>` element tells the portal where the portlet appears. The syntax for the `<parent-ref>` element is ``portal-instance`.`portal-page``.

  In the example above, a window is defined, and assigned to `default.default`. This means the window appears on the `default` page, in the `default` portal.

-     <window>...</window>

  The `<window>` element defines a portlet window. The `<window>` element requires an `<instance-ref>` element, which assigns a portal instance to a window.

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

  The `<window-name>` element defines the unique name given to a portlet window. This can be named anything.

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

  The `<instance-ref>` elements define the portlet instances that windows represent. This value is the ID of a portlet instance, and must match the value of one of the `<instance-id>` elements in the `WEB-INF/portlet-instances.xml` file.

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

  The `<region>` and `<height>` elements define where the window appears within the page layout. The `<region>` element specifies where the window appears on the page. The `<region>` element often depends on other regions defined in the portal layout. The `<height>` element can be assigned a value between one and `X`.

The previous `*-object.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:

## Are `*-object.xml` descriptors required?

Technically, they are 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.

### 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.

### 6.2.3. The `jboss-portlet.xml` Descriptor

The `jboss-portlet.xml` descriptor allows you to use JBoss-specific functionality within your portlet application. This descriptor is covered by the JSR-168 Portlet Specification, and is normally packaged inside your portlet WAR file, alongside the other descriptors in these sections.

#### 6.2.3.1. Injecting Header Content

The following example injects a specific style sheet, `/images/management/management.css`, allowing the portlet to leverage a specific style:

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

Use the `<header-content>` and `<link>` elements to specify a style sheet.

#### 6.2.3.2. Injecting Services in the portlet Context

The following example injects the `UserModule` service as an attribute to 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>

This allows the portlet to 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

As of JBoss Portal 2.6.3, icons can be defined for a portlet by using the `<icon>`, `<small-icon>`, and `<large-icon>` elements:

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

References to icons can be absolute, for example, http://www.example.com/images/smallIcon.png, or relative to the web application context, for example, `/images/smallIcon.png`. Icons can be used by different parts of the portlet user interface.

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

For information about portlet session replication in clustered environments, refer to Section 14.5, “Portlet Session Replication”.

## Is the `jboss-portlet.xml` descriptor required?

Technically, it is not; however, it may be required to access JBoss-specific functionality that is not covered by the Portlet specification.

### 6.2.4. The `portlet.xml` Descriptor

The `portlet.xml` descriptor is the standard portlet descriptor covered by the JSR-168 Portlet Specification. Developers are strongly encouraged to read the JSR-168 Portlet Specification items covering the correct use of this descriptor, as it is only covered briefly in these sections. Normally the `portlet.xml` descriptor is packaged inside your portlet WAR file, alongside the other descriptors in these sections. The following example is a modified version of the JBoss Portal UserPortlet definition:

    <?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>Initialize the portlet with a default page to render</description>
    	 <name>>default-view</name>
    	 <value>/WEB-INF/jsf/objects.xhtml</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>` element encapsulates the entire document. Multiple portlets can be specified using the `<portlet-app>` element.

-     <portlet>...</portlet>

  The `<portlet>` element defines one portlet that is deployed within this archive.

-     <description>...</description>

  The `<description>` element is a verbal description of the portlet's function.

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

  The `<portlet-name>` element defines the portlet name. It does not have to be the class name.

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

  The `<portlet-class>` element defines the Fully Qualified Name (FQN) of the portlet class.

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

  The `<init-param>` element specifies initialization parameters to create an initial state inside your portlet class. This is usually used in the portlet's init() method, but not necessarily. Unlike a preference, an init-parameter is data that does not change at runtime and does not go into a database. If the value is changed in the descriptor, the change takes immediate effect after re-deploying the portlet. Multiple `<init-param>` elements can be used.

-     <supports>...</supports>

  The `<supports>` element declares all of the markup types that a portlet supports. Use the `<mime-type>` element to declare supported capabilities, for example, if the only outputs are text and HTML, use `<mime-type>text/html</mime-type>`. Use the `<portlet-mode>` element to define the supported portlet modes for the portlet. For example, all portlets must support the `view` portlet mode, which is defined using `<portlet-mode>view</portlet-mode>`.

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

  The `<supported-locale>` elements advertise the supported locales for the portlet. Use multiple `<supported-locale>` elements to specify multiple locales.

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

  The `<resource-bundle>` element specifies the resource bundle that contains the localized information for the specified locales.

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

  The `<title>` element defines the portlet's title, which is displayed in the portlet window's title bar.

## The `portlet.xml` Example

This `portlet.xml` example is not a replacement for what is covered in the JSR-168 Portlet Specification.

## 6.3. JBoss Portal Descriptors

This section describes Datasource descriptors, which are required for JBoss Portal to communicate with a database, and briefly covers the `jboss-portal.sar/conf/config.xml` descriptor, which can be used for configuring logging, and configuring which page a user goes to when they log in.

### 6.3.1. Datasource Descriptors (`portal-*-ds.xml`)

JBoss Portal requires a Datasource descriptor to be deployed alongside the `jboss-portal.sar`, in order to communicate with a database. This section explains where to obtain template Datasource descriptors, how to compile them from source, and how to configure them for your installation. For an in-depth introduction to datasources, refer to the JBoss AS documentation online on the JBoss Datasource Wiki page.

#### 6.3.1.1. Datasource Descriptors included in Binary releases

Several template Datasource descriptors are included in the binary and bundled distributions of JBoss Portal. They are commonly located in the `jboss-portal-`version`/setup/` directory:

The `jboss-portal-`version`/setup/` directory contains sample Datasource descriptors for the MySQL, Microsoft SQL Server, PostgreSQL, and Oracle databases, which can be customized for your own database:

#### 6.3.1.2. Building Datasource Descriptors from Source

To build the Datasource descriptors from source:

1. Obtain the JBoss Portal source code: Section 2.3, “Installing from the Sources”.

2. Configure the `JBOSS_HOME` environment variable: Section 2.3.2.2, “Operating System Environment Settings”.

3. Change into the `JBOSS_PORTAL_SOURCE_DIRECTORY/build/` directory. To build the JBoss Portal source code on Linux, run the `sh build.sh deploy` command, or, if you are running Windows, run the `build.bat deploy` command. If this is the first build, third-party libraries are obtained from an online repository, so you must be connected to the Internet. After building, if the `JBOSS_PORTAL_SOURCE_DIRECTORY/thirdparty/` directory does not exist, it is created, and populated with the files required for later steps. For further details, refer to Section 2.3.3, “Building and Deploying from the Sources”.

4. Change into the `JBOSS_PORTAL_SOURCE_DIRECTORY/core/` directory, and run the `sh build.sh datasource` command, or, if you are running Windows, run the `build.bat datasource` command:

Note: if the JBoss Portal source was not built as per step 3, the `sh build.sh datasource` and `build.bat datasource` commands fail with an error, such as the following:

    BUILD FAILED
    java.io.FileNotFoundException: /jboss-portal-2.6.3.GA-src/core/../thirdparty/libraries.ent
    (No such file or directory)

The datasource build process produces the following directory and file structure, with the Datasource descriptors in the `JBOSS_PORTAL_SOURCE_DIRECTORY/core/output/resources/setup` directory:

The following is an example Datasource descriptor for a PostgreSQL database:

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

Make sure the `user-name`, `password`, `connection-url`, and `driver-class`, are correct for your chosen database.

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

By default, JBoss Portal is configured to display all errors. This behavior can be configured by modifying the `jboss-portal.sar/conf/config.xml` file:

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

For these parameters, accepted values are `show` and `hide`. Depending on the setting, and the actual error, either an error message is displayed, or a full stack trace within the portlet window occurs. Additionally, the `core.render.window_error` property supports the `message_only` value. The `message_only` value will only display an error message, whereas the `show` value will, if available, display the full stack trace.

### 6.3.3. Log in to Dashboard

By default, when a user logs in they are forwarded to the default page of the default portal. In order to forward a user to their Dashboard, set the `core.login.namespace` value to `dashboard` in the `jboss-portal.sar/conf/config.xml` file:

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

The sample application descriptor in this section creates a new page, `MyPage`, in a portal. To illustrate this example, download the HelloWorldPortalPage portlet. To use the HelloWorldPortalPage portlet:

1. Download the HelloWorldPortalPage portlet.

2. Unzip the `HelloWorldPortalPage` ZIP file.

3. To expand the WAR file, which gives you access to the XML descriptors, change into the `HelloWorldPortalPage/` directory, and run the `ant explode` command.

4. If you did not expand the `helloworldportalpage.war` file, copy the `helloworldportalpage.war` file into the correct JBoss AS or JBoss EAP `deploy/` directory. If you expanded the `helloworldportalpage.war` file, copy the `HelloWorldPortalPage/output/lib/exploded/helloworldportalpage.war/` directory into the correct JBoss AS or JBoss EAP `deploy/` directory. For example, if you are using the `default` JBoss AS profile, copy the WAR file or the expanded directory into the `$JBOSS_HOME/server/default/deploy/` directory.

The HelloWorldPortalPage portlet is hot-deployable, so the JBoss EAP or JBoss AS server does not have to be restarted after deploying the HelloWorldPortalPage portlet. The following is an example of the `HelloWorldPortalPage/WEB-INF/helloworld-object.xml` descriptor:

    <?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>
          <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 depoloyment is composed of a `<deployments>` element, which is a container for `<deployment>` elements. In the previous example, a page is defined, the portlet is placed as a window on a page, and an instance of the portlet is created. The Mangement portlet (bundled with JBoss Portal) can modify portal instances, page position, and so on.

The following list describes elements in a `*-object.xml` file:

-     <if-exists>

  The `<if-exists>` element defines the action to take if an instance with the same name already exists. Accepted values are `overwrite` and `keep`. The `overwrite` option destroys the existing object, and creates a new one based on the content of the deployment. The `keep` option matains the existing object deployment, or creates a new one if it does not exist.

-     <parent-ref>

  The `<parent-ref>` element contains a reference to the parent object. The naming convention for naming objects is to concatenate the names of the path to the object, and separate the names using a period. If the path is empty, the empty string must be used. The `<parent-ref>` element tells the portal where the portlet appears. The syntax for the `<parent-ref>` element is ``portal-instance`.`portal-page``.

-     <properties>

  A set of generic properties for the portal object. The `<properties>` elements contains definitions specific to a page. This is commonly used to define the specific theme and layout to use. If not defined, the default portal theme and layout are used.

-     <page>

  The start of a page definition. Among others, the `<page>` element is a container for the `<page-name>`, `<window>`, and `<security-constraint>` elements.

-     <page-name>

  The page name.

-     <window>

  The `<window>` element defines a portlet window. The `<window>` element requires an `<instance-ref>` element, which assigns a portal instance to a window.

-     <window-name>

  The `<window-name>` element defines the unique name given to a portlet window. This can be named anything.

-     <instance-ref>

  The `<instance-ref>` elements define the portlet instances that windows represent. This value is the ID of a portlet instance, and must match the value of one of the `<instance-id>` elements in the `WEB-INF/portlet-instances.xml` file.

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

  The `<region>` and `<height>` elements define where the window appears within the page layout. The `<region>` element specifies where the window appears on the page. The `<region>` element often depends on other regions defined in the portal layout. The `<height>` element can be assigned a value between one and `X`.

-     <instance>

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

  The `<instance-name>` element maps to the `<instance-ref>` element.

-     <component-ref>

  The `<component-ref>` element takes the name of the application, followed by the name of the portlet, as defined in the `WEB-INF/portlet.xml` file.

The `<security-constraint>` element is a container for `<policy-permission>` elements. The following is an example of the `<security-constraint>` and `<policy-permission>` elements:

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

    <action-name>

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.

    <unchecked/>

If present, the `<unchecked>` element defines that anyone can view the instance.

    <role-name>

The `<role-name>` element defines a role that the security constraint will apply to. The following example only allows users that are part of the `EXAMPLEROLE` role to access the instance:

    <role-name>EXAMPLEROLE</role-name>

### 6.4.2. Defining a new Portal Instance

The sample application descriptor in this section creates a new portal instance, `HelloPortal`, that contains two pages. To illustrate this example, download the HelloWorldPortal portlet. To use the HelloWorldPortal portlet:

1. Download the HelloWorldPortal portlet.

2. Unzip the `HelloWorldPortal` ZIP file.

3. To expand the WAR file, which gives you access to the XML descriptors, change into the `HelloWorldPortal/` directory, and run the `ant explode` command.

4. If you did not expand the `helloworldportal.war` file, copy the `helloworldportal.war` file into the correct JBoss AS or JBoss EAP `deploy/` directory. If you expanded the `helloworldportal.war` file, copy the `HelloWorldPortal/output/lib/exploded/helloworldportal.war/` directory into the correct JBoss AS or JBoss EAP `deploy/` directory. For example, if you are using the `default` JBoss AS profile, copy the WAR file or the expanded directory into the `$JBOSS_HOME/server/default/deploy/` directory.

The HelloWorldPortal portlet is hot-deployable, so the JBoss EAP or JBoss AS server does not have to be restarted after deploying the HelloWorldPortal portlet. The following is an example of the `HelloWorldPortal/WEB-INF/helloworld-object.xml` descriptor:

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

When deployed, this example registers a new portal instance, `HelloPortal`, that contains two pages. To view the default page in the `HelloPortal` instance, navigate to http://localhost:8080/portal/portal/HelloPortal, and for the second page, http://localhost:8080/portal/portal/HelloPortal/foobar.

## Portal Instance `default` Page

For a portal instance to be accessible via a Web browser, you must define a default page.

- PrevChapter 5. Portlet Primer
- Top of page
- Front page
- NextChapter 7. Portal URLs