Chapter 6. XML Descriptors

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/jboss-portlet.xml file, which uses the <portlet-name>, <remotable>, and <trans-attribute> elements:
<portlet>
   <portlet-name>MyPortlet</portlet-name>
   <remotable>true</remotable>
   <transaction>
     <trans-attribute>Required</transaction>
   <transaction>
</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 sub-pages 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.