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.

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:

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

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:

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

<!ELEMENT property (name,value)>

A generic string property.

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

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

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.

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>

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:

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>

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:

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.

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

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

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

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

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

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>

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.

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.

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>

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:

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:

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:

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

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:

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.