JBoss Portal 2.6.4

To start JBoss EAP or JBoss AS and deploy JBoss Portal:

WARN  [JDBCExceptionReporter] SQL Error: -22, SQLState: S0002
ERROR [JDBCExceptionReporter] Table not found in statement ...
WARN  [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02
ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_repositoryentry' doesn't exist
WARN  [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02
ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_version_refs' doesn't exist

The JBoss Portal source files can be obtained from the JBoss Portal Downloads page. The source files download uses a JBoss Portal Source Code naming convention. As well, the sources can be obtained from SVN:

Several modules have been extracted from the JBoss Portal SVN repository. These modules have a different lifecycle and a different version scheme. The following is a list of modules used in JBoss Portal 2.6.4, and the locations of their source code:

After checking out the source from SVN, or after extracting the JBoss Portal Source Code zip file, a directory structure similar to the following will be created:

If the source files were obtained from SVN, change into the trunk/src/ directory to see the directories from the above image. As well, there will be an empty thirdparty directory. This directory will contain files after building the JBoss Portal source code (Section 2.3.3, “Building and Deploying from the Sources”). For more information about the JBoss Portal SVN repository, and accessing different versions of the JBoss Portal codebase, please visit the JBoss Portal SVN Repo page on the JBoss Wiki.

During the first build, third-party libraries will be obtained from an online repository, so you must be connected to the Internet, and if you are behind a proxy server, you need to define your proxy server address and proxy server port number. If you are running Linux, add the following line to the $JBOSS_HOME/bin/run.sh file:

JAVA_OPTS=-Dhttp.proxyHost=<proxy-hostname> -Dhttp.proxyPort=<proxy-port>

Replace proxy-hostname with the proxy server's hostname, and proxy-port with the correct proxy server port number. If you are running Microsoft Windows, add the following line to the $JBOSS_HOME/bin/run.bat file:

set JAVA_OPTS=-Dhttp.proxyHost=<proxy-hostname> -Dhttp.proxyPort=<proxy-port>

Replace proxy-hostname with the proxy server's hostname, and proxy-port with the correct proxy server port number.

To build and deploy JBoss Portal from the sources, change into the JBOSS_PORTAL_SOURCE_DIRECTORY/build/ directory, where JBOSS_PORTAL_SOURCE_DIRECTORY is the directory where the JBoss Portal source code was downloaded to. Then, Microsoft Windows users need to run the build.bat deploy command, and Linux users need to run the ./build.sh deploy command.

At the end of the build process, the jboss-portal.sar file is copied into the $JBOSS_HOME/server/default/deploy/ directory:

To build the clustered version on Linux Operating Systems:

To build the clustered version on Microsoft Windows, repeat the previous steps, replacing ./build.sh with build.bat.

A database is required for JBoss Portal to run. JBoss EAP and JBoss AS include an embedded Hypersonic SQL database that JBoss Portal can use; however, this is only recommended for developer use. The following databases are recommended for production use, and have had test suites run against them: MySQL 4, MySQL 5, Microsoft SQL Server, PostgreSQL 8, Oracle 9, and Oracle 10. JBoss Portal can use any database that is supported by Hibernate.

To configure a database to use with JBoss Portal:

The JBoss Portal binary download that was extracted in Section 2.2.1.1, “Getting the Binary”, contains pre-configured Datasource descriptors for the more popular databases. Datasource descriptors are provided for the MySQL 4, MySQL 5, PostgreSQL, Microsoft SQL Server, and Oracle databases, and can be found in the setup subdirectory where the JBoss Portal binary was extracted to:

Copy the Datasource descriptor that matches your database into the $JBOSS_HOME/server/configuration/deploy/ directory, where configuration is either all, default, minimal, or production. For example, if you are using the production configuration, copy the Datasource descriptor into the $JBOSS_HOME/server/production/deploy/ directory. The production configuration only exists on JBoss EAP installations, and not JBoss AS.

After the Datasource descriptor has been copied into the deploy directory, make sure the username, password, connection-url, and driver-class are correct for your chosen database. Datasource descriptor files can be deployed to test before being used in production. The following is an example Datasource descriptor for the 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>
					  

For further details about Datasource descriptors, please refer to the JBoss JDBC Datasource wiki page.

All hibernate.cfg.xml files in all JBoss Portal modules you intend to use need to be modified. The hibernate.cfg.xml files are found in the jboss-portal.sar/module/conf/hibernate/directory/ directory, where module is the module name, and directory is a directory that, depending on the module, may or may not exist.

To modify these files to force the DB dialect, un-comment the following line from each hibernate.cfg.xml file in each JBoss Portal module you intend to use, so that it looks like the following:

<!-- Force the dialect instead of using autodetection -->
<property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property>

Note: this example is for a PostgreSQL database. If you use another database, you will need to modify org.hibernate.dialect.PostgreSQLDialect to reflect the correct database. For a list of supported dialects, refer to the dialects list on the Hibernate website.

To modify the DB dialect setting for the JBoss Portal CMS component:

Note: this example is for a PostgreSQL database. If you use another database, you will need to modify org.hibernate.dialect.PostgreSQLDialect to reflect the correct database. For a list of supported dialects, refer to the dialects list on the Hibernate website.

Themes in JBoss Portal 2.6 have changed since the Portal pages now contain additional areas, such as the Login, Admin, and Dashboard links, on the top right-hand corner:

If you use a default theme that exists in JBoss Portal 2.6, such as renaissance, no configuration should be necessary. Using old themes from JBoss Portal 2.4 may make JBoss Portal 2.6 unusable, for example, not being able to log in. To update custom themes, please refer to those bundled with JBoss Portal as an example.

All procedures described in the following sections can performed using the AdminPortlet. Treat the directions as guidelines if you need to automate the migration of a large JBoss Portal deployment.

Database schema has not changed between the JBoss Portal 2.4 and 2.6 releases, but certain content that is kept in the databases has changed. Data can be updated manually by using the correct tools for your RDBMS. For example, if you are using a MySQL database, you can use the MySQL Query Browser.

The following instructions refer to a standard JBoss Portal 2.4 deployment. If you named core portlets, portlet instances, or portlet windows differently, you will need to make the appropriate modifications. The following is an example of using the MySQL Query Browser:

Names of certain core bundled portlets have changed. Destroy the following instances and use the AdminPortlet to recreate them, or, edit the JBP_INSTANCES table as follows:

The NavigationPortlet from JBoss Portal 2.4 has been removed, and its functionality is now replaced by PageCustomizerInterceptor. All references to the NavigationPortlet should be removed from all portal pages. Remove NavigationPortletInstance using the AdminPortlet, or edit the database as follows:

In JBoss Portal 2.6 versions, the way the CMS content is displayed changed significantly. For further information, please refer to Chapter 9, Content Integration and Chapter 21, CMS Portlet. Currently there is no need to have more than one instance of the CMSPortlet. The portlet window displays CMS content, not by referring to that portlet instance, but by having the proper content-type defined. The following configuration is in the jboss-portal.sar/conf/data/default-object.xml file:

<window>
   <window-name>CMSWindow</window-name>
   <content>
      <content-type>cms</content-type>
      <content-uri>/default/index.html</content-uri>
   </content>
   <region>center</region>
   <height>0</height>
</window>

The following example uses the MySQL Query Browser. Open the JBP_OBJECT_NODE table in your database schema. Look at the PATH column to identify any occurrences of CMS in your JBoss Portal deployment. Identify any row referring to CMSPortletWindow, and remember the number in PK column. The PK number is needed in the following steps:

Go to the JBP_WINDOW table and find a row with the same PK value from the JBP_OBJECT_NODE table. In such a row, replace CMSPortletInstance with a path to your CMS resource. For example, by default, JBoss Portal displays /default/index.html.

Go to the JBP_PORTAL_OBJECT_PROPS table and add a row containing:

A portal can be seen as pages with different areas, and inside areas, different windows, and each window having one portlet:

A portlet can have different view modes. Three modes are defined by the JSR-168 specification, but a portal can extend those modes. The three modes are:

Window states are an indicator of how much page real-estate a portlet should consume on any given page. The three states defined by the JSR-168 specification are:

This overview of the JSR-168 Portlet Specification is a work in progress. Check back for more in-depth analsis of the specification. The sections following here after contain real-world cases for how to leverage the specification.

The *-object.xml file is used to define: portal instances, pages, windows, window layout. Additionally, you can also specify the themes and layouts used for specific portal instances, pages, and windows. The description below, only defines a portlet window being added to the default page in the default portal. For advanced functionality, using this descriptor, please read Section 6.4, “Descriptor Examples”.

<?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 example *-object.xml, above, makes reference to items found in other descriptor files. To help with this topic, we have included a sample image that depicts the relationship:

This is a JBoss Portal specific descriptor that allows a developer to instantiate one-or-many instances of one-or-many portlets. The benefit of using this technique, is to allow one portlet to be instantiated several times with different preference parameters.

Our example, below, has us instantiating two separate instances of the NewsPortlet with different preference parameters, one instance will draw a feed for RedHat announcements and the other from McDonalds announcements.

<?xml version="1.0" standalone="yes"?>
<!DOCTYPE deployments PUBLIC
   "-//JBoss Portal//DTD Portlet Instances 2.6//EN"
   "http://www.jboss.org/portal/dtd/portlet-instances_2_6.dtd">
<deployments>
   <deployment>
      <instance>
         <instance-id>NewsPortletInstance2</instance-id>
         <portlet-ref>NewsPortlet</portlet-ref>
         <preferences>
            <preference>
               <name>expires</name>
               <value>180</value>
            </preference>
            <preference>
               <name>RssXml</name>
               <value>http://finance.yahoo.com/rss/headline?s=rhat</value>
            </preference>
         </preferences>
         <security-constraint>
            <policy-permission>
               <action-name>view</action-name>
               <unchecked/>
            </policy-permission>
         </security-constraint>
      </instance>
   </deployment>
   <deployment>
      <instance>
         <instance-id>NewsPortletInstance2</instance-id>
         <portlet-ref>NewsPortlet</portlet-ref>
         <preferences>
            <preference>
               <name>expires</name>
               <value>180</value>
            </preference>
            <preference>
               <name>RssXml</name>
               <value>http://finance.yahoo.com/rss/headline?s=mcd</value>
            </preference>
         </preferences>
         <security-constraint>
            <policy-permission>
               <action-name>view</action-name>
               <unchecked/>
            </policy-permission>
         </security-constraint>
      </instance>
   </deployment>
</deployments>

The example portlet-instances.xml, above, makes reference to items found in other descriptor files. To help with this topic, we have included a sample image that depicts the relationship:

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

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

See Section 13.5, “Portlet Session Replication”.

This is the standard portlet descriptor covered by the JSR-168 Specification. It is advisable that developers read the specification items covering proper use of this descriptor, as it is only covered here briefly. For example purposes, we use an edited version of our JBoss Portal UserPortlet definition. Normally, you would package this descriptor in your portlet WAR file.

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app
      xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd
                          http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
      version="1.0">
   <portlet>
      <description>Portlet providing user login/logout and profile management</description>
      <portlet-name>UserPortlet</portlet-name>
      <display-name>User Portlet</display-name>
      <portlet-class>org.jboss.portal.core.portlet.user.UserPortlet</portlet-class>
      <init-param>
         <description>Whether we should use ssl on login and throughout the Portal.
         1=yes;0=no</description>
         <name>useSSL</name>
         <value>0</value>
      </init-param>
      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>VIEW</portlet-mode>
      </supports>
      <supported-locale>en</supported-locale>
      <supported-locale>fr</supported-locale>
      <supported-locale>es</supported-locale>
      <resource-bundle>Resource</resource-bundle>
      <portlet-info>
         <title>User portlet</title>
      </portlet-info>
   </portlet>
</portlet-app>

JBoss Portal requires a Datasource descriptor to be deployed alongside the jboss-portal.sar for access to a database. This section does not explain what a Datasource Descriptor is, but does explain where to obtain some templates that you can configure for your own installation.

6.3.1.1. Obtaining Datasource Descriptors Binary releases

Several template datasource descriptors can be found in the binary and bundle distributions. They are commonly located under the setup directory:

The directory setup should contain the following files, that you can customize for your own Database/Connector:

6.3.1.2. Building Datasource Descriptors from Source

You will need a valid datasource descriptor, for JBoss Portal to communicate with your database. Having obtained the sources and having set your JBOSS_HOME environment variable ( Section 2.3.2.2, “Operating System Environment Settings” ), you can now have the JBoss Portal build system generate preconfigured datasources for you.

Navigate to JBOSS_PORTAL_HOME_DIRECTORY/core and type:

build datasource

Once complete, the datasource build should produce the following directory and file structure:

At this point, you should configure the one that suits you best with your Database and JDBC driver.

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
  <local-tx-datasource>
    <jndi-name>PortalDS</jndi-name>
    <connection-url>jdbc:postgresql:jbossportal</connection-url>
    <driver-class>org.postgresql.Driver</driver-class>
    <user-name>portal</user-name>
    <password>portalpassword</password>
  </local-tx-datasource>
</datasources>

Please verify that the username, password, url, and driver-class are correct for your flavor of DB.

By default, JBoss Portal ships with all errors set to display. You can fine-tune this behavior by modifying some properties in the file, jboss-portal.sar/conf/config.xml :

<!-- When a window has restrictedaccess : show or hide values are permitted -->
<entry key="core.render.window_access_denied">show</entry>
<!-- When a window is unavailable : show or hide values are permitted -->
<entry key="core.render.window_unavailable">show</entry>
<!-- When a window produces an error : show, hide or message_only values are permitted -->
<entry key="core.render.window_error">message_only</entry>
<!-- When a window produces an internal error : show, hide are permitted -->
<entry key="core.render.window_internal_error">show</entry>
<!-- When a window is not found : show or hide values are permitted -->
<entry key="core.render.window_not_found">show</entry>

Either show or hide are allowed as flags in these elements. Depending on the setting and actual error, either an error message is deployed or a full stack trace within the portlet window. Additionally, the core.render.window_error property supports the message_only value. This value will only display the error message whereas show will display the full stack trace if it is available.

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

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

This sample application and descriptor will create a new page, named MyPage in your portal. To illustrate our example, we have made available a portlet with a page descriptor that you can download here: HelloWorld Page .

Our sample includes a descriptor to define this new portal page, helloworld-object.xml , located under helloworldportalpage.war/WEB-INF/ , and it looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deployments PUBLIC
   "-//JBoss Portal//DTD Portal Object 2.6//EN"
   "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">
<deployments>
   <deployment>
      <parent-ref>default</parent-ref>
      <if-exists>overwrite</if-exists>
      <properties/>
      <page>
         <page-name>MyPage</page-name>
         <security-constraint>
            <policy-permission>
               <action-name>viewrecursive</action-name>
               <unchecked/>
            </policy-permission>
         </security-constraint>
         <window>
            <window-name>HelloWorldPortletPageWindow</window-name>
            <instance-ref>HelloWorldPortletPageInstance</instance-ref>
            <region>center</region>
            <height>0</height>
         </window>
      </page>
   </deployment>
</deployments>
            

A deployment file can be composed of a set of <deployments>. In our example file, above, we are defining a page, placing the portlet as a window on that page, and creating an instance of that portlet. You can then use the Management Portlet (bundled with JBoss Portal) to modify the instances of this portlet, reposition it, and so on...

To illustrate our example, we have made available a portlet that you can download here: HelloPortal .

For our example we make available helloworld-object.xml located under helloworldportal.war/WEB-INF/ , and it looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deployments PUBLIC
   "-//JBoss Portal//DTD Portal Object 2.6//EN"
   "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">
<deployments>
   <deployment>
      <parent-ref/>
      <if-exists>overwrite</if-exists>
      <portal>
         <portal-name>HelloPortal</portal-name>
         <supported-modes>
            <mode>view</mode>
            <mode>edit</mode>
            <mode>help</mode>
         </supported-modes>
         <supported-window-states>
            <window-state>normal</window-state>
            <window-state>minimized</window-state>
            <window-state>maximized</window-state>
         </supported-window-states>
         <properties>
            <!-- Set the layout for the default portal -->
            <!-- see also portal-layouts.xml -->
            <property>
               <name>layout.id</name>
               <value>generic</value>
            </property>
            <!-- Set the theme for the default portal -->
            <!-- see also portal-themes.xml -->
            <property>
               <name>theme.id</name>
               <value>renaissance</value>
            </property>
            <!-- set the default render set name (used by the render tag in layouts) -->
            <!-- see also portal-renderSet.xml -->
            <property>
               <name>theme.renderSetId</name>
               <value>divRenderer</value>
            </property>
         </properties>
         <security-constraint>
            <policy-permission>
               <action-name>personalizerecursive</action-name>
               <unchecked/>
            </policy-permission>
         </security-constraint>
         <page>
            <page-name>default</page-name>
            <security-constraint>
               <policy-permission>
                  <action-name>viewrecursive</action-name>
                  <unchecked/>
               </policy-permission>
            </security-constraint>
            <window>
               <window-name>MyPortletWindow</window-name>
               <instance-ref>MyPortletInstance</instance-ref>
               <region>center</region>
               <height>0</height>
            </window>
         </page>
      </portal>
   </deployment>
   <deployment>
      <parent-ref>HelloPortal</parent-ref>
      <if-exists>overwrite</if-exists>
      <page>
         <page-name>foobar</page-name>
         <security-constraint>
            <policy-permission>
               <action-name>viewrecursive</action-name>
               <unchecked/>
            </policy-permission>
         </security-constraint>
         <window>
            <window-name>MyPortletWindow</window-name>
            <instance-ref>MyPortletInstance</instance-ref>
            <region>center</region>
            <height>0</height>
         </window>
      </page>
   </deployment>
</deployments>
            

This example, when deployed, will register a new portal instance named HelloPortal with two pages in it. The portal instance can be accessed by navigating to: http://localhost:8080/portal/portal/HelloPortal for the default page, and http://localhost:8080/portal/portal/HelloPortal/foobar , for the second page created.

Whenever a control policy is invoked it is possible to change the response sent by the control flow. If the control policy ignores the error then the next policy will handle the error at this turn. However if the control policy decides to provide a new response then the next policy will not be invoked since the new response will not be of type error. For instance, if a portlet part of a page produces an exception, the following reactions are possible:

The default policy applies when errors are not handled at other level. By default errors are translated into the most appropriate HTTP response:

The portal error policy controls the response that will be sent to the browser when an error occurs. There is a default configuration and it is reconfigurable per portal. Whenever an error occurs, the policy can either handle a redirect to a JSP page or ignore the error. If the error is ignored it will be handled by the default policy, otherwise a JSP page will be invoked with appropriate request attributes to allow page customization.

The window error policy controls how the page reacts to aggregation errors. Indeed the page is most of the time an aggregation of several portlet windows and the action to take when an error occurs is different than the other policies. Whenever an error occurs, the policy can either handle it or ignore it. If the error is ignored then it will be treated by the portal policy. The different actions that are possible upon an error are:

A set of properties configure the the behavior of the portal policy. Those properties will only be taken in account for objects of type portal.

An example of portal configuration:

<portal>
   <portal-name>MyPortal</portal-name>
   ...
   <properties>
      <property>
         <name>control.portal.access_denied</name>
         <value>ignore</value>
      </property>
      <property>
         <name>control.portal.unavailable</name>
         <value>ignore</value>
      </property>
      <property>
         <name>control.portal.not_found</name>
         <value>ignore</value>
      </property>
      <property>
         <name>control.portal.internal_error</name>
         <value>jsp</value>
      </property>
      <property>
         <name>control.portal.error</name>
         <value>jsp</value>
      </property>
      <property>
         <name>control.portal.resource_uri</name>
         <value>/WEB-INF/jsp/error/portal.jsp</value>
      </property>
      ...
   </properties>
   ...
</portal>

A set of properties configure the the behavior of the page policy. Those properties will only be taken in account for objects of type portal and page.

An example of page configuration:

<page>
   <page-name>MyPortal</page-name>
   ...
   <properties>
      <property>
         <name>control.page.access_denied</name>
         <value>hide</value>
      </property>
      <property>
         <name>control.page.unavailable</name>
         <value>hide</value>
      </property>
      <property>
         <name>control.page.not_found</name>
         <value>hide</value>
      </property>
      <property>
         <name>control.page.internal_error</name>
         <value>jsp</value>
      </property>
      <property>
         <name>control.page.error</name>
         <value>jsp</value>
      </property>
      <property>
         <name>control.page.resource_uri</name>
         <value>/WEB-INF/jsp/error/page.jsp</value>
      </property>
      ...
   </properties>
   ...
</page>

At runtime the portal will call the portlet with the view mode when it displays content. It will send information about the content to display using the render parameters to the portlet. Therefore the portlet has just to read the render parameters and use them to properly display the content in the portlet. The render parameters values are the key/value pairs that form the content properties and the resource URI is available under the uri parameter name.

As explained before, the portal will call the portlet using the edit_content mode. In that mode the portlet and the portal will communicate using either action or render parameters. We have two use cases which are:

In order to be able to use the admin mode, the portlet must declare it in the portlet deployment descriptor.

<portlet-app>
   ...
   <portlet>
      ...
      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>admin</portlet-mode>
      </supports>
      ...
   </portlet>
   ...
   <custom-portlet-mode>
      <name>admin</name>
   </custom-portlet-mode>
   ...
</portlet-app>

The following example shows the configuration of a portlet instance that grants the admin action permission to the Admin security role. It also grants the view action permission to all users.

...
<instance>
   <instance-id>ModePortletInstance</instance-id>
   <portlet-ref>ModePortlet</portlet-ref>
   <security-constraint>
      <policy-permission>
         <action-name>admin</action-name>
         <role-name>Admin</role-name>
      </policy-permission>
      <policy-permission>
         <action-name>view</action-name>
         <unchecked/>
      </policy-permission>
   </security-constraint>
</instance>
...

At runtime the security configuration section of the administration portlet can be used to grant or revoke the admin access. It can be done by clicking the security action of the portlet instance and then use the security editor.

Edit the security instance configuration

Portal node events extend the abstract portal event framework in order to provide notifications about user interface events happening at runtime. For instance when the portal renders a page or a window, a corresponding event will be fired.

The portal node event class hierarchy

The org.jboss.portal.api.node.event.PortalNodeEvent class extends the org.jboss.portal.api.node.PortalEvent class and is the base class for all events of portal nodes. It defines a single method PortalNode getNode() which can be used to retrieve the node targetted by the event.

The org.jboss.portal.api.node.event.WindowEvent is an extension for portal nodes of type window. It provides access to the mode and window state of the window. It has 3 subclasses which represent different kind of event that can target windows.

The org.jboss.portal.api.node.event.WindowNavigationEvent is fired when the window navigational state changes. For a portlet it means that the window is targetted by an URL of type render.

The org.jboss.portal.api.node.event.WindowActionEvent is fired when the window is targetted by an action. For a portlet it means that the window is targetted by an URL of type action.

The org.jboss.portal.api.node.event.WindowRenderEvent is fired when the window is going to be rendered by the portal.

The org.jboss.portal.api.node.event.PageEvent is an extension for portal nodes of type page.

The org.jboss.portal.api.node.event.PageRenderEvent is fired when the page is going to be rendered by the portal.

12.7.1.1. Portal node event propagation model

A portal node event is fired when an event of interest happens to a portal node of the portal tree. The notification model is comparable to the bubbling propagation model defined by the DOM specification. When an event is fired, the event is propagated in the hierarchy from the most inner node where the event happens to the root node of the tree.

The portal node event propagation model

12.7.1.3. Portal node event context

The PortalNodeEventContext interface

The org.jboss.portal.api.node.event.PortalNodeEventContext interface extends the PortalEventContext interface and plays an important role in the event delivery model explained in the previous section. That interface gives full control over the delivery of the event to ascendant nodes in the hierarchy, even more it gives the possibility to replace the current event being delivered by a new event that will be transformed into the corresponding portal behavior. However there are no guarantees that the portal will turn the returned event into a portal behavior, here the portal provides a best effort policy, indeed sometime it is not possible to achieve the substitution of one event by another.

Here the simplest implementation of a listener that does nothing except than correctly passing the control to a parent event listener if there is one.

public PortalNodeEvent onEvent(PortalNodeEventContext context, PortalNodeEvent event)
{
   return context.dispatch();
}

The method PortalNode getNode() returns the current node being selected during the event bubbler dispatching mechanism.

The life cycle of the session of the portal associated with the user can also raise events. This kind of event is not bound to a portal node since it is triggered whenever a portal session is created or destroyed

The PortalSessionEvent class

There are two different types of events:

The life cycle of the portal user can also raise events such as its authentication. A subclass of the wider scope UserEvent class is provided and triggers events whenever a user signs in or out. The UserEvent object gives access to the user name of the logged-in user through the method String getId().

The UserEvent class and UserAuthenticationEvent sub-classes

The UserAuthenticationEvent triggers two events that can be catched:

Based on the UserEvent class other custom user related events could be added like one that would trigger when a new user is being registered

In this example, we will create a simple counter of the number of logged-in registered users. In order to do that we just need to keep track of Sign-in and Sign-out events.

First, let's write our listener. It just a class that will implement org.jboss.portal.api.event.PortalEventListener and its unique method void onEvent(PortalEventContext eventContext, PortalEvent event). Here is such an example:

package org.jboss.portal.core.portlet.test.event;

import[...]

public class UserCounterListener implements PortalEventListener
{
   
   /** Thread-safe long */
   private final SynchronizedLong counter = new SynchronizedLong(0);

   /** Thread-safe long */
   private final SynchronizedLong counterEver = new SynchronizedLong(0);
   
   public void onEvent(PortalEventContext eventContext, PortalEvent event)
   {
      if (event instanceof UserAuthenticationEvent)
      {
         UserAuthenticationEvent userEvent = (UserAuthenticationEvent)event;
         if (userEvent.getType() == UserAuthenticationEvent.SIGN_IN)
         {
            counter.increment();
            counterEver.increment();
         }
         else if (userEvent.getType() == UserAuthenticationEvent.SIGN_OUT)
         {
            counter.decrement();
         }
         System.out.println("Counter     : " + counter.get());
         System.out.println("Counter ever: " + counterEver.get());
      }
   }
}
            

On this method we simply filter down to UserAuthenticationEvent then depending on the type of authentication event we update the counters. counter keeps track of the registered and logged-in users, while counterEver only counts the number of times people logged-in the portal.

Now that the Java class has been written we need to register it so that it can be called when the events are triggered. To do so we need to register it as an MBean. It can be done by editing the sar descriptor file: YourService.sar/META-INF/jboss-service.xml so that it looks like the following:

<?xml version="1.0" encoding="UTF-8"?>
<server>            
   <mbean
      code="org.jboss.portal.core.event.PortalEventListenerServiceImpl"
      name="portal:service=ListenerService,type=counter_listener"
      xmbean-dd=""
      xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">
      <xmbean/>
      <depends
         optional-attribute-name="Registry"
         proxy-type="attribute">portal:service=ListenerRegistry</depends>
      <attribute name="RegistryId">counter_listener</attribute>
      <attribute name="ListenerClassName">
      	org.jboss.portal.core.portlet.test.event.UserCounterListener
      </attribute>
   </mbean>
</server>
            

This snippet can be kept as it is, providing you change the values:

That's it - we now have a user counter that will display it states each time a user logs-in our logs-out.

The first version of the Portlet Specification (JSR 168), regretfully, did not cover interaction between portlets. The side-effect of diverting the issue to the subsequent release of the specification, has forced portal vendors to each craft their own proprietary API to achieve inter portlet communication. Here we will see how we can use the event mechanism to pass parameters from one portlet to the other (and only to the other portlet).

The overall scenario will be that Portlet B will need to be updated based on some parameter set on Portlet A. To achieve that we will use a portal node event.

Portlet A is a simple Generic portlet that has a form that sends a color name:

            
public class PortletA extends GenericPortlet
{
   protected void doView(RenderRequest request, RenderResponse response)
      throws PortletException, PortletSecurityException, IOException
   {
      response.setContentType("text/html");
      PrintWriter writer = response.getWriter();
      writer.println("<form action=\"" + response.createActionURL() + "\" method=\"post\">");
      writer.println("<select name=\"color\">");
      writer.println("<option>blue</option>");
      writer.println("<option>red</option>");
      writer.println("<option>black</option>");
      writer.println("</select>");
      writer.println("<input type=\"submit\"/>");
      writer.println("</form>");
      writer.close();
   }
}
            

The other portlet (Portlet B) that will receive parameters from Portlet A is also a simple Generic portlet:

            
public class PortletB extends GenericPortlet
{

   public void processAction(ActionRequest request, ActionResponse response)
              throws PortletException, PortletSecurityException, IOException
   {
      String color = request.getParameter("color");
      if (color != null)
      {
         response.setRenderParameter("color", color);
      }
   }

   protected void doView(RenderRequest request, RenderResponse response)
          throws PortletException, PortletSecurityException, IOException
   {
      String color = request.getParameter("color");
      response.setContentType("text/html");
      PrintWriter writer = response.getWriter();
      writer.println("<div" +
         (color == null ? "" : " style=\"color:" + color + ";\"") +
         ">some text in color</div>");
      writer.close();
   }
   
   // Inner listener explained after
}
            

With those two portlets in hands, we just want to pass parameters from Portlet A to Portlet B (the color in as a request parameter in our case). In order to achieve this goal, we will write an inner Listener in Portlet B that will be triggered on any WindowActionEvent of Portlet A. This listener will create a new WindowActionEvent on the window of Portlet B.

public static class Listener implements PortalNodeEventListener
{
   public PortalNodeEvent onEvent(PortalNodeEventContext context, PortalNodeEvent event)
   {
      PortalNode node = event.getNode();
      // Get node name
      String nodeName = node.getName();
      // See if we need to create a new event or not
      WindowActionEvent newEvent = null;
      if (nodeName.equals("PortletAWindow") && event instanceof WindowActionEvent)
      {
         // Find window B
         WindowActionEvent wae = (WindowActionEvent)event;
         PortalNode windowB = node.resolve("../PortletBWindow");
         if (windowB != null)
         {
            // We can redirect
            newEvent = new WindowActionEvent(windowB);
            newEvent.setParameters(wae.getParameters());
            
            newEvent.setMode(wae.getMode());
            newEvent.setWindowState(WindowState.MAXIMIZED); 
            
            // Redirect to the new event
            return newEvent;
         }
      }
      // Otherwise bubble up
      return context.dispatch();
   }
}
            

It is important to note here some of the important items in this listener class. Logic used to determine if the requesting node was Portlet A.:

nodeName.equals("PortletAWindow")

Get the current window object so we can dispatch the event to it:

PortalNode windowB = node.resolve("../PortletBWindow");

Set the original parameter from Portlet A, so Portlet B can access them in its processAction():

newEvent.setParameters(wae.getParameters());

We still need to register our listener as an mbean:

<mbean
   code="org.jboss.portal.core.event.PortalEventListenerServiceImpl"
   name="portal:service=ListenerService,type=test_listener"
   xmbean-dd=""
   xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">
   <xmbean/>
   <depends
      optional-attribute-name="Registry"
      proxy-type="attribute">portal:service=ListenerRegistry</depends>
   <attribute name="RegistryId">test_listener</attribute>
   <attribute name="ListenerClassName">
      org.jboss.portal.core.samples.basic.event.PortletB$Listener
   </attribute>
</mbean>

For node events, we also need to declare on which node we want to listen, this is done by modifying the *-object.xml that defines your portal nodes. In this example we want to trigger the listener each time the window containing the portlet A is actioned. We can add the listener tag to specify that out listener with RegistryId=test_listener should be triggered on events on the embedding object.

...
   <window>
      <window-name>PortletAWindow</window-name>
      <instance-ref>PortletAInstance</instance-ref>
      <region>center</region>
      <height>0</height>
      <listener>test_listener</listener>
   </window>
...
            

Of course we could have added it at the page level instead of the window level. Note that a unique listener can be specified, the event mechanism is primarily done to let the developer change the navigation state of the portal, this example being a nice side-effect of this feature.

Linking to some other pages or portals is also out of the scope of the portlet specification. As seen previously JBoss Portal offers an API in order to create links to other portal nodes. The JBoss request gives access to the current window node from which we can navigate from.

// Get the ParentNode. Since we are inside a Window, the Parent is the Page
PortalNode thisNode = req.getPortalNode().getParent();

// Get the Node in the Portal hierarchy tree known as "../default"
PortalNode linkToNode = thisNode.resolve("../default");

// Create a RenderURL to the "../default" Page Node
PortalNodeURL pageURL = resp.createRenderURL(linkToNode);

// Output the Node's name and URL for users
html.append("Page: " + linkToNode.getName() + " -> ");
html.append("<a href=\"" + pageURL.toString() + "\">" + linkToNode.getName() + "</a>");
   

From this, it is easy to create a menu or sitemap, the List getChildren() method will return all the child nodes on which the user has the view right access.

The portal associates with each user a http session in order to keep specific objects such as:

Replicating the portal session ensures that this state will be kept in sync on the cluster, e.g The user will see exactly the same portlet window on every node of the cluster. The activation of the portal session replication is made through the configuration of the web application that is the main entry point of the portal. This setting is available in the file jboss-portal.sar/portal-server.war/WEB-INF/web.xml

<web-app>
   <description>JBoss Portal</description>
   <!-- Comment/Uncomment to enable portal session replication -->
   <distributable/>
   ...
</web-app>

JBoss Portal leverages hibernate for its database access. In order to improve performances it uses the caching features provided by hibernate. On a cluster the cache needs to be replicated in order to avoid state inconsistencies. Hibernate is configured with JBoss Cache which performs that synchronization transparently. Therefore the different hibernate services must be configured to use JBoss Cache. The following hibernate configurations needs to use a replicated JBoss Cache :

The cache configuration should look like :

<!--
   | Uncomment in clustered mode : use transactional replicated cache
   -->
   <property name="cache.provider_class">org.jboss.portal.core.hibernate.JMXTreeCacheProvider
   </property>
   <property name="cache.object_name">portal:service=TreeCacheProvider,type=hibernate
   </property>

<!--
   | Comment in clustered mode
   <property name="cache.provider_configuration_file_resource_path">
   conf/hibernate/instance/ehcache.xml</property>
   <property name="cache.provider_class">org.hibernate.cache.EhCacheProvider</property>
-->

Also we need to ensure that the cache is deployed by having in the file jboss-portal.sar/META-INF/jboss-service.xml the cache service uncommented :

<!--
   | Uncomment in clustered mode : replicated cache for hibernate
   -->
   <mbean
   code="org.jboss.cache.TreeCache"
   name="portal:service=TreeCache,type=hibernate">
   <depends>jboss:service=Naming</depends>
   <depends>jboss:service=TransactionManager</depends>
   <attribute name="TransactionManagerLookupClass">
   org.jboss.cache.JBossTransactionManagerLookup</attribute>
   <attribute name="IsolationLevel">REPEATABLE_READ</attribute>
   <attribute name="CacheMode">REPL_SYNC</attribute>
   <attribute name="ClusterName">portal.hibernate</attribute>
   </mbean>

   <mbean
   code="org.jboss.portal.core.hibernate.JBossTreeCacheProvider"
   name="portal:service=TreeCacheProvider,type=hibernate">
   <depends optional-attribute-name="CacheName">portal:service=TreeCache,type=hibernate
   </depends>
   </mbean>

More information can be found here.

JBoss Portal leverages the servlet container authentication for its own authentication mechanism. When the user is authenticated on one particular node he will have to reauthenticate again if a different node of the cluster (during a failover for instance) is used. This is valid only for the FORM based authentication which is the default form of authentication that JBoss Portal uses. Fortunately JBoss provides transparent reauthentication of the user called JBoss clustered SSO. Its configuration can be found in $JBOSS_HOME/server/all/deploy/jboss-web.deployer/server.xml and you will need to uncomment the following valve:

<Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" />

More information can be found here.

The CMS backend storage relies on the Apache Jackrabbit project. Jackrabbit does not support clustering out of the box. So the portal run the Jackrabbit servicey on one node of the cluster using the HA-Singleton technology. The file jboss-portal.sar/portal-cms.sar/META-INF/jboss-service.xml contains the configuration. We will not reproduce it in this documentation as the changes are quite complex and numerous. Access from all nodes of the cluster is provided by a proxy bound in HA-JNDI. In order to avoid any bottleneck JBoss Cache is leveraged to cache CMS content cluster wide.

The mandatory step to make JBoss Portal able to replicate portlet sessions is to configure the portal web application to be distributed as explained in Section 13.3.1, “Portal Session Replication”

In order to activate portlet session replication you need to:

<web-app>
   ...
   <listener>
      <listener-class> org.jboss.portal.portlet.session.SessionListener </listener-class>
   </listener>
   ...
</web-app>

<portlet-app>
   ...
   <portlet>
      <portlet-name>YourPortlet</portlet-name>
      ...
      <session-config>
         <distributed>true</distributed>
      </session-config>
      ...
   </portlet>
   ...
</portlet-app>

As we noted above there are advantages as well as limitations to the clustering configuration

public void processAction(ActionRequest req, ActionResponse resp)
               throws PortletException, IOException
{
   ...
   if ("addItem".equals(action))
   {
      PortletSession session = req.getPortletSession();
      ShoppingCart cart = (PortletSession)session.getAttribute("cart");
      cart.addItem(item);

      // Perform an explicit set in order to signal to the container that the object
      // state has changed
      session.setAttribute("cart", cart);
   }
   ...
}

If you have modified the port number on which Portal runs or bound your Application Server to a specific host name, you will also need update the port and/or hostname information for WSRP as found on JBoss Portal's wiki.

It is possible to use WSRP over SSL for secure exchange of data. Please refer to the instructions on how to do so from JBoss Portal's wiki.

To be able to consume WSRP portlets exposed by a remote producer, JBoss Portal's WSRP consumer needs to know how to access that remote producer. One can configure access to a remote producer using WSRP Producer descriptors. Alternatively, a portlet is provided to configure remote producers.

Once a remote producer has been configured, it can be made available in the list of portlet providers in the Management portlet on the Admin page of JBoss Portal. You can then examine the list of portlets that are exposed by this producer and configure the portlets just like you would for local portlets.

JBoss Portal's default configuration exposes some of the sample portlets for remote consumption. As a way to test the WSRP service, a default consumer has been configured to consume these portlets. To make sure that the service indeed works, check that there is a portlet provider with the self identifier in the portlet providers list in the Management portlet of the Admin page. All local portlets marked as remotable are exposed as remote portlets via the self portlet provider so that you can check that they work as expected with WSRP. The portal-wsrp.sar file contains a WSRP Producer descriptor (default-wsrp.xml) that configures this default producer. This file can be edited or removed if needed.

Let's work through the steps of defining access to a remote producer so that its portlets can be consumed within JBoss Portal. We will configure access to BEA's public WSRP producer. We will first examine how to do so using the configuration portlet. We will then show how the same result can be accomplish with a producer descriptor.

14.6.2.1. Using the configuration portlet

As of Portal 2.6, a configuration portlet is provided to configure access to remote WSRP Producers grahically. You can access it at http://{hostname}:{port}/portal/auth/portal/admin/WSRP or by logging in as a Portal administrator and clicking on the WSRP tab in the Admin portal. If all went well, you should see something similar to this:

This screen presents all the configured producers associated with their status and possible actions on them. A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. Deactivating it will remove it from the list of available portlet providers. Note also that a Consumer can be marked as requiring refresh meaning that the information held about it might not be up to date and refreshing it from the remote Producer might be a good idea. This can happen for several reasons: the service description for that remote Producer has not been fetched yet, the cached version has expired or modifications have been made to the configuration that could potentially invalidate it, thus requiring re-validation of the information.

Next, we create a new Consumer which we will callbea. Type "bea" in the "Create a consumer named:" field then click on "Create consumer":

You should now see a form allowing you to enter/modify the information about the Consumer. Set the cache expiration value to 300 seconds and enter the WSDL URL for the producer in the text field and press the "Refresh & Save" button:

This will retrieve the service description associated with the Producer which WSRP is described by the WSDL file found at the URL you just entered. In our case, querying the service description will allow us to learn that the Producer requires registration and that it expects a value for the registration property named registration/consumerRole:

Note

At this point, there is no automated way to learn about which possible values (if any) are expected by the remote Producer. In the case of BEA's public producer, the possible values are indicated in the registration property description. This is not always the case... Please refer to the specific Producer's documentation.

Enter "public" as the value for the registration property and press "Save & Refresh" once more. You should now see something similar to:

The Consumer for the bea Producer should now be available as a portlet provider and is ready to be used.

A producer is configured, by default, by retrieving the producer's information via a WSDL URL. There are rare cases, however, where URLs need to be provided for each of the producer's end points. You can do exactly that by unchecking the "Use WSDL?" checkbox, as is the case for the self producer:

<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN"
   "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd">
<deployments>
  <deployment>
    <wsrp-producer id="bea" expiration-cache="300">
      <endpoint-wsdl-url>http://wsrp.bea.com:7001/producer/producer?WSDL</endpoint-wsdl-url>
      <registration-data>
        <property>
          <name>registration/consumerRole</name>
          <lang>en</lang>
          <value>public</value>
        </property>
      </registration-data>
    </wsrp-producer>
  </deployment>
</deployments>

14.6.2.3. Configuring access to a remote portlet

Let's now look at the Admin page and the Management portlet. Click on the "Portlet definitions" tab at the top. Once this is done, look at the list of available portlet providers. If all went well, you should see something similar to this:

We have 3 available portlet providers: local, self andbea. The local portlet provider exposes all the portlets deployed in this particular instance of Portal. As explained above, the self provider refers to the default WSRP consumer bundled with Portal that consumes the portlets exposed by the default WSRP producer. The bea provider corresponds to BEA's public producer we just configured. Select it and click on "View portlets". You should now see something similar to:

From there on out, you should be able to configure WSRP portlets just as any other. In particular, you can create an instance of one of the remote portlets offered by BEA's public producer just like you would create an instance of a local portlet and then assign it to a window in a page. If you go to that page, you should see something similar to below for this portlet:

A WSRP Producer descriptor is an XML file which name ends in -wsrp.xml and which can be dropped in the deploy directory of the JBoss application server or nested in .sar files. It is possible to configure access to several different producers within a single descriptor or use one file per producer, depending on your needs. An XML Schema for the WSRP Producer descriptor format can be found at jboss-portal.sar/portal-wsrp.sar/xsd/jboss-wsrp-consumer_2_6.xsd, while a (legacy) DTD can be found at jboss-portal.sar/portal-wsrp.sar/dtd/jboss-wsrp-consumer_2_6.dtd.

Here is the configuration of the self producer as found in default-wsrp.xml with a cache expiring every five minutes:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN"
   "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd">

<deployments>
   <deployment>
      <wsrp-producer id="self" expiration-cache="300">
         <!--
         we need to use the individual endpoint configuration because the configuration via
         wsdl forces an immediate attempt to access the web service description which is not
         available yet at this point of deployment
         -->
         <endpoint-config>
            <service-description-url>
              http://localhost:8080/portal-wsrp/ServiceDescriptionService
            </service-description-url>
            <markup-url>http://localhost:8080/portal-wsrp/MarkupService</markup-url>
            <registration-url>
              http://localhost:8080/portal-wsrp/RegistrationService
            </registration-url>
            <portlet-management-url>
              http://localhost:8080/portal-wsrp/PortletManagementService
            </portlet-management-url>
         </endpoint-config>
         <registration-data/>
      </wsrp-producer>
   </deployment>
</deployments>
            

Here is an example of a WSRP descriptor with a 2 minute caching time and manual definition of the endpoint URLs:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN"
   "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd">

<deployments>
   <deployment>
      <wsrp-producer id="MyProducer" expiration-cache="120">
         <endpoint-config>
            <service-description-url>
             http://www.someproducer.com/portal-wsrp/ServiceDescriptionService
            </service-description-url>
            <markup-url>
             http://www.someproducer.com/portal-wsrp/MarkupService
            </markup-url>
            <registration-url>
             http://www.someproducer.com/portal-wsrp/RegistrationService
            </registration-url>
            <portlet-management-url>
             http://www.someproducer.com/portal-wsrp/PortletManagementService
            </portlet-management-url>
         </endpoint-config>
      </wsrp-producer>
   </deployment>
</deployments>

Here is an example of a WSRP descriptor with endpoint definition via remote WSDL file, registration data and cache expiring every minute:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN"
   "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd">

<deployments>
   <deployment>
      <wsrp-producer id="AnotherProducer" expiration-cache="60">
         <endpoint-wsdl-url>http://example.com/producer/producer?WSDL</endpoint-wsdl-url>
         <registration-data>
            <property>
               <name>property name</name>
               <lang>en</lang>
               <value>property value</value>
            </property>
         </registration-data>
      </wsrp-producer>
   </deployment>
</deployments>

Several operations are available from the consumer list view of the WSRP configuration portlet:

The available operations are:

There are rare cases where it might be required to erase the local information without being able to deregister first. This is the case when a consumer is registered with a producer that has been modified by its administrator to not require registration anymore. If that ever was to happen (most likely, it won't), you can erase the local registration information from the consumer so that it can resume interacting with the remote producer. To do so, click on "Erase local registration" button next to the registration context information on the consumer configuration screen:

Note

This operation is dangerous as it can result in inability to interact with the remote producer if invoked when not required. A warning screen will be displayed to give you a chance to change your mind!

You can configure the behavior of Portal's WSRP Producer by using the WSRP administration interface, which is the preferred way, or by editing the conf/config.xml file found in portal-wsrp.sar. Several aspects can be modified with respects to whether registration is required for consumers to access the Producer's services. An XML Schema for the configuration format is available at jboss-portal.sar/portal-wsrp.sar/xsd/jboss-wsrp-producer_2_6.xsd, while a (legacy) DTD is available at jboss-portal.sar/portal-wsrp.sar/dtd/jboss-wsrp-producer_2_6.dtd

The default producer configuration is to require that consumers register with it before providing access its services but does not require any specific registration properties (apart from what is mandated by the WSRP standard). It does, however, require consumers to be registered before sending them a full service description. This means that our WSRP producer will not provide the list of offered portlets and other capabilities to unregistered consumers. The producer also uses the default RegistrationPolicy paired with the default RegistrationPropertyValidator. We will look into property validators in greater detail later in Section 14.8.3, “Registration configuration”. Suffice to say for now that this allows users to customize how Portal's WSRP Producer decides whether a given registration property is valid or not.

JBoss Portal 2.6.3 introduces a web interface to configure the producer's behavior. You can access it by clicking on the "Producer Configuration" tab of the "WSRP" page of the "admin" portal. Here's what you should see with the default configuration:

As would be expected, you can specify whether or not the producer will send the full service description to unregistered consumers, and, if it requires registration, which RegistrationPolicy to use (and, if needed, which RegistrationPropertyValidator), along with required registration property description for which consumers must provide acceptable values to successfully register.

In order to require consumers to register with Portal's producer before interacting with it, you need to configure Portal's behavior with respect to registration. Registration is optional, as are registration properties. The producer can require registration without requiring consumers to pass any registration properties as is the case in the default configuration. Let's configure our producer starting with a blank state:

We will allow unregistered consumers to see the list of offered portlets so we leave the first checkbox ("Access to full service description requires consumers to be registered.") unchecked. We will, however, specify that consumers will need to be registered to be able to interact with our producer. Check the second checkbox ("Requires registration. Modifying this information will trigger invalidation of consumer registrations."). The screen should now refresh and display:

You can specify the fully-qualified name for your RegistrationPolicy and RegistrationPropertyValidator there. We will keep the default value. See Section 14.8.3.1, “Customization of Registration handling behavior” for more details. Let's add, however, a registration property called email. Click "Add property" and enter the appropriate information in the fields, providing a description for the registration property that can be used by consumers to figure out its purpose:

Press "Save" to record your modifications.

The configuration for the CMS Security service is specified in the jboss-portal.sar/portal-cms.sar/META-INF/jboss-service.xml file. The portion of the configuration relevant for securing the CMS service is listed as follows:

      	  	  
			   <!-- CMS Authorization Security Service -->
			   <mbean
			      code="org.jboss.portal.cms.security.AuthorizationManagerImpl"
			      name="portal:service=AuthorizationManager,type=cms"
			      xmbean-dd=""
			      xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">
			      <xmbean/>
			      <attribute name="JNDIName">java:portal/cms/AuthorizationManager</attribute>  
			      <depends optional-attribute-name="Provider" proxy-type="attribute">
			      	portal:service=AuthorizationProvider,type=cms
			      </depends>         
			   </mbean>   
			   <mbean
			      code="org.jboss.portal.cms.security.AuthorizationProviderImpl"
			      name="portal:service=AuthorizationProvider,type=cms"
			      xmbean-dd=""
			      xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">
			      <xmbean/> 
			      <!--
			      	NOTE: cmsRootUserName denotes a single Portal user that has access to everything in the CMS. Denote this user
			      	carefully and should be synonymous to the 'root' user in a Unix system. By default: this value is the built-in
			      	'admin' user account. This can be changed to any other user account registered in your Portal
			      -->
			      <attribute name="CmsRootUserName">admin</attribute>  
			      <depends optional-attribute-name="IdentityServiceController" proxy-type="attribute">portal:service=Module,type=IdentityServiceController</depends>     
			   </mbean>			
			   <!-- ACL Security Interceptor -->
			   <mbean
			      code="org.jboss.portal.cms.impl.interceptors.ACLInterceptor"
			      name="portal:service=Interceptor,type=Cms,name=ACL"
			      xmbean-dd=""
			      xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">
			      <xmbean/>
			      <attribute name="JNDIName">java:/portal/cms/ACLInterceptor</attribute>
			      <attribute name="CmsSessionFactory">java:/portal/cms/CMSSessionFactory</attribute>
			      <attribute name="IdentitySessionFactory">java:/portal/IdentitySessionFactory</attribute>
			      <attribute name="DefaultPolicy">
			      	<policy>
			      			<!-- permissions on the root cms node -->      			
			      			<criteria name="path" value="/">
			      				<permission name="cms" action="read">
			      					<role name="Anonymous"/>
			      				</permission>
			      				<permission name="cms" action="write">
			      					<role name="User"/>
			      				</permission>
			      				<permission name="cms" action="manage">
			      					<role name="Admin"/>
			      				</permission>
			      			</criteria>
			      			<!-- permissions on the default cms node -->      			
			      			<criteria name="path" value="/default">
			      				<permission name="cms" action="read">
			      					<role name="Anonymous"/>
			      				</permission>
			      				<permission name="cms" action="write">
			      					<role name="User"/>
			      				</permission>
			      				<permission name="cms" action="manage">
			      					<role name="Admin"/>
			      				</permission>
			      			</criteria>      			
			      			<!-- permissions on the private/protected node -->
			      			<criteria name="path" value="/default/private">
			      				<permission name="cms" action="manage">
			      					<role name="Admin"/>
			      				</permission>
			      			</criteria>
			      	</policy>
			      </attribute>
			      <depends optional-attribute-name="AuthorizationManager" proxy-type="attribute">
			      	portal:service=AuthorizationManager,type=cms
			      </depends>            
			      <depends>portal:service=Hibernate,type=CMS</depends>
			      <depends>portal:service=Module,type=IdentityServiceController</depends>      
			   </mbean>
      	  

      					      
			    <mbean
			      code="org.jboss.portal.cms.security.AuthorizationProviderImpl"
			      name="portal:service=AuthorizationProvider,type=cms"
			      xmbean-dd=""
			      xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">
			      <xmbean/> 
			      <!--
			      	NOTE: cmsRootUserName denotes a single Portal user that has access to everything in the CMS. Denote this user
			      	carefully and should be synonymous to the 'root' user in a Unix system. By default: this value is the built-in
			      	'admin' user account. This can be changed to any other user account registered in your Portal
			      -->
			      <attribute name="CmsRootUserName">admin</attribute>  
			      <depends optional-attribute-name="IdentityServiceController" proxy-type="attribute">portal:service=Module,type=IdentityServiceController</depends>     
			   </mbean>			
			   
      			

JBoss Portal can be seen before all as a web application and therefore inherits all the configuration mechanisms related to web applications. The main entry point of the whole portal is the jboss-portal.sar/portal-server.war deployment which is the web application that defines and maps the portal servlet. Here you can configure various things

The portal defines a single servlet to take care of all portal requests. The class name of that servlet is org.jboss.portal.server.servlet.PortalServlet. That servlet needs to be declared two times with different configurations otherwise the portal would not be able to know about some request details which are importants.

The portal servlet is mapped four times with different semantics, the differences between the semantics are related to the transport layer. Each one of those for mappings will have the same request meaning for the portal beside the transport aspect. By default those mappings are

Usually ones should not care much about those mappings as the portal will by itself switch to the most appropriate mapping.

The org.jboss.portal.security.PortalPermission object is used to describe a permission for the portal. It extends the java.security.Permission class and any permission checked in the portal should extend the PortalPermission as well. That permission adds two fields to the Permission class

The org.jboss.portal.security.spi.provider.AuthorizationDomain is an interface which provides access to several services.

public interface AuthorizationDomain
{
   String getType();
   DomainConfigurator getConfigurator();
   PermissionRepository getPermissionRepository();
   PermissionFactory getPermissionFactory();
}
            

Making a security check is an easy thing as it consists in creating a permission of the appropriate type and make a check against the org.jboss.portal.spi.auth.PortalAuthorizationManager service. That service is used by the portal to make security checks. It is connected to the different authorization providers in order to take decisions at runtime based on the type of the permission. Access to that service is done through the org.jboss.portal.spi.auth.PortalAuthorizationManagerFactory. The factory is a portal service which is usually injected in other services like that

<?xml version="1.0" encoding="UTF-8"?>
<server>
   ...
   <mbean
      code='MyService"
      name="portal:service=MyService">
	   <depends
         optional-attribute-name="PortalAuthorizationManagerFactory"
         proxy-type="attribute">portal:service=PortalAuthorizationManagerFactory</depends>
      ...
   </mbean>
   ...
</server>

It can be injected in the servlet context of a war file in the file WEB-INF/jboss-portlet.xml

<?xml version="1.0" encoding="UTF-8"?>
<!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>PortalAuthorizationManagerFactory</service-name>
      <service-class>
      org.jboss.portal.security.spi.auth.PortalAuthorizationManagerFactory
      </service-class>
      <service-ref>:service=PortalAuthorizationManagerFactory</service-ref>
   </service>
   ...
</portlet-app>

Here is an example of how a security check is made for a specific page

PortalAuthorizationManager pam = factory.getManager();
PortalObjectId id = page.getId();
PortalObjectPermission perm = new PortalObjectPermission(id, PortalObjectPermission.VIEW_MASK);
if (pam.checkPermission(perm) == false)
{
   System.out.println("Current user is not authorized to view page " + id);
}

Configuring a domain can be done through the DomainConfigurator interface

public interface DomainConfigurator
{
   Set getSecurityBindings(String uri);
   void setSecurityBindings(String uri, Set securityBindings)
           throws SecurityConfigurationException;
   void removeSecurityBindings(String uri) throws SecurityConfigurationException;
}

The various methods of that interface allows to configure security bindings for a given resource where a resource is naturally identified by an URI. The org.jboss.portal.security.RoleSecurityBinding object is an object which encapsulate a role name and a set of actions bound to this role.

RoleSecurityBinding binding1 = new RoleSecurityBinding(Collections.singleton("view"), "Admin");
RoleSecurityBinding binding2 = new RoleSecurityBinding(Collections.singleton("view"), "User");
Set bindings = new HashSet();
bindings.add(binding1);
bindings.add(binding2);
configurator.setSecurityBinding(pageURI, bindings);            

The advocated way to get a reference to the identity modules is by using JNDI:

import org.jboss.portal.identity.UserModule;
import org.jboss.portal.identity.RoleModule;
import org.jboss.portal.identity.MembershipModule;
import org.jboss.portal.identity.UserProfileModule;

[...]

(UserModule)new InitialContext().lookup("java:portal/UserModule");
(RoleModule)new InitialContext().lookup("java:portal/RoleModule");
(MembershipModule)new InitialContext().lookup("java:portal/MembershipModule");
(UserProfileModule)new InitialContext().lookup("java:portal/UserProfileModule");

Another way to do this is, if you are fimiliar with JBoss Microkernel architecture is to get the IdentityServiceController mbean. You may want to inject it into your services like this:

<depends optional-attribute-name="IdentityServiceController" proxy-type="attribute">
   portal:service=Module,type=IdentityServiceController
</depends>

or simply obtain in your code by doing a lookup using the portal:service=Module,type=IdentityServiceController name. Please refer to the JBoss Application Server documentation if you want to learn more about service MBeans. Once you obtained the object you can use it:

(UserModule)identityServiceController.getIdentityContext()
            .getObject(IdentityContext.TYPE_USER_MODULE);

(RoleModule)identityServiceController.getIdentityContext()
            .getObject(IdentityContext.TYPE_ROLE_MODULE);

(MembershipModule)identityServiceController.getIdentityContext()
            .getObject(IdentityContext.TYPE_MEMBERSHIP_MODULE);

(UserProfileModule)identityServiceController.getIdentityContext()
            .getObject(IdentityContext.TYPE_USER_PROFILE_MODULE);
         

Because in JBoss Portal 2.4 there were only UserModule , RoleModule , User and Role interfaces some API usages changed. Here are the most important changes you will need to aply to your code while migrating your aplication to 2.6:

The file describing portal identity services contains three sections:

<identity-configuration>
   <datasources>
      <!-- Datasources section -->
      <datasource> ... </datasource>
      <datasource> ... </datasource>
      ...
   </datasources>
   <modules>
      <!-- Modules section -->
      <module> ... </module>
      <module> ... </module>
      ...
   </modules>
   <options>
      <!-- Options section -->
      <option-group> ... </option-group>
      <option-group> ... </option-group>
      ...
   </options>
</identity-configuration>

By default you can find it in jboss-portal.sar/conf/identity/identity-config.xml

<datasource>
   <name>LDAP</name>
   <service-name>portal:service=Module,type=LDAPConnectionContext</service-name>
   <class>org.jboss.portal.identity.ldap.LDAPConnectionContext</class>
   <config>
      <option>
         <name>host</name>
         <value>jboss.com</value>
      </option>
      <option>
         <name>port</name>
         <value>10389</value>
      </option>
      <option>
         <name>adminDN</name>
         <value>cn=Directory Manager</value>
      </option>
      <option>
         <name>adminPassword</name>
         <value>xxxxx</value>
      </option>

      <!-- Other options here.... -->

   </config>
</datasource>

<module>
   <!--type used to correctly map in IdentityContext registry-->
   <type>User</type>
   <implementation>DB</implementation>

   <!--name of service and class for creating mbean-->
   <service-name>portal:service=Module,type=User</service-name>
   <class>org.jboss.portal.identity.db.HibernateUserModuleImpl</class>

   <!--set of options that are in the instantiated object-->
   <config>
      <option>
         <name>sessionFactoryJNDIName</name>
         <value>java:/portal/IdentitySessionFactory</value>
      </option>
      <option>
         <name>jNDIName</name>
         <value>java:/portal/UserModule</value>
      </option>
   </config>
</module>

<module>
   <!--type used to correctly map in IdentityContext registry-->
   <type>User</type>
   <implementation>DB</implementation>
   <config/>
</module>

<options>
<!--Common options section-->
<option-group>
   <group-name>common</group-name>
   <option>
      <name>userCtxDN</name>
      <value>ou=People,dc=example,dc=com</value>
   </option>
   <option>
      <name>uidAttributeID</name>
      <value>uid</value>
   </option>
   <option>
      <name>passwordAttributeID</name>
      <value>userPassword</value>
   </option>
   <option>
      <name>roleCtxDN</name>
      <value>ou=Roles,dc=example,dc=com</value>
   </option>
   <option>
      <name>ridAttributeId</name>
      <value>cn</value>
   </option>
   <option>
      <name>roleDisplayNameAttributeID</name>
      <value>cn</value>
   </option>
   <option>
      <name>membershipAttributeID</name>
      <value>member</value>
   </option>
   <option>
      <name>membershipAttributeIsDN</name>
      <value>true</value>
   </option>
</option-group>
<option-group>
   <group-name>userCreateAttibutes</group-name>
   <option>
      <name>objectClass</name>
      <value>top</value>
      <value>uidObject</value>
      <value>person</value>
      <value>inetUser</value>
   </option>
   <!--Schema requires those to have initial value-->
   <option>
      <name>cn</name>
      <value>none</value>
   </option>
   <option>
      <name>sn</name>
      <value>none</value>
   </option>
</option-group>

JBoss portal comes with a set of database related identity modules implementations done using Hibernate - those are configured by default. Those are not very configurable in identity-config.xml file. The reason is that to keep backwards compatibility of database schema with previous portal version, we reused most of hibernate implementation. If you want to tweak the hibernate mappings you should look into files in jboss-portal.sar/conf/hibernate. Also those modules rely on hibernate SessionFactory components that are created in SessionFactoryBinder mbeans defined in jboss-portal.sar/META-INF/jboss-service.xml

Classes implementing identity modules:

For each of those modules you can alter two config options:

Delegating UserProfileModule implementation has very specific role. When we use a storage mechanism like LDAP we may not be able to map all user properties into LDAP attributes because of schema limitations. To solve this problem we still can use the database to store user properties that do not exist in the LDAP schema. The Delegating user profile module will recognize if a property is mapped as ldap or database and delegate setProperty()/getProperty() method invocation to proper module implementation. This is implemented in org.jboss.portal.identity.DelegatingUserProfileModuleImpl. If property is mapped either as ldap and database the ldap mapping will have higher priority.

            
<module>
   <!--type used to correctly map in IdentityContext registry-->
   <type>UserProfile</type>
   <implementation>DELEGATING</implementation>

   <!--name of service and class for creating mbean-->
   <service-name>portal:service=Module,type=UserProfile</service-name>
   <class>org.jboss.portal.identity.DelegatingUserProfileModuleImpl</class>
   <!--set of options that are set in instantiated object-->
   <config>
      <option>
         <name>jNDIName</name>
         <value>java:/portal/UserProfileModule</value>
      </option>
      <option>
         <name>dbModuleJNDIName</name>
         <value>java:/portal/DBUserProfileModule</value>
      </option>
      <option>
         <name>profileConfigFile</name>
         <value>conf/identity/profile-config.xml</value>
      </option>
   </config>
</module>
         

Module options are:

Because of the behavior described in the previous section, database UserProfileModule requires some special features. If a user is present in LDAP server but a writable property isn't mapped as an LDAP attribute, such property requires to be stored in the database. In order to achieve such result the user need to be synchronized from LDAP into the database first.

Class org.jboss.portal.identity.db.HibernateUserProfileModuleImpl has additional synchronization features. Here are the options:

The identity portlets provide the following features:

CAPTCHA is an acronym for Completely Automated Public Turing test to tell Computers and Humans Apart. This is providing a mechanism to prevent automated programs from using different services. The User Portlet uses JCaptcha to provide a challenge-response.

-Djava.awt.headless=true

The registration page with captcha.

The captcha support can be enabled by changing the portlet preference 'captcha' to 'true'. If enabled, captcha will be used for the registration and lost password action.

...
<portlet>
...
	<display-name>User portlet</display-name>
...
	<portlet-preferences>
		<preference>
			<name>captcha</name>
			<value>true</value>
      	</preference>
	</portlet-preferences>
</portlet>
...

The lost password feature enables the end user to reset his password by entering his username.

The lost password page with captcha enabled.

The lost password feature can be enabled by changing the portlet preference 'lostPassword' to 'true'. If captcha is enabled it will be also used for verifying the lost password action.

...
<portlet>
...
	<display-name>User portlet</display-name>
...
	<portlet-preferences>
		<preference>
			<name>lostPassword</name>
			<value>true</value>
		</preference>
	</portlet-preferences>
</portlet>
...

The reset password feature is similar to the lost password feature, but it is used in the User Management Portlet to reset the password of a user. That means changing the password of a user is slightly simplified, because a random password will be generated and sent to the users e-mail address.

...
<portlet>
...
	<display-name>User management portlet</display-name>
...
	<portlet-preferences>
		<preference>
      		<name>resetPassword</name>
      		<value>true</value>
		</preference>
	</portlet-preferences>
</portlet>
...

JBoss Portal supports three different subscription modes by default:

Approve or reject pending registrations (jbp_identity_validation_approval_workflow).

The Identity Portlets use some metadata which can be easily changed in the main configuration file, which is located at jboss-portal.sar/portal-identity.sar/conf/identity-ui-configuration.xml as shown here:

<identity-ui-configuration>

	<subscription-mode>automatic</subscription-mode>
	<admin-subscription-mode>automatic</admin-subscription-mode>
	<overwrite-workflow>false</overwrite-workflow>
	<email-domain>jboss.org</email-domain>
	<email-from>no-reply@jboss.com</email-from>
	<password-generation-characters>a...Z</password-generation-characters>
	<default-roles>
		<role>User</role>
	</default-roles>

	<!-- user interface components -->
	<ui-components>
		<ui-component name="givenname">
			<property-ref>user.name.given</property-ref>
		</ui-component>
		<ui-component name="familyname">
			<property-ref>user.name.family</property-ref>
		</ui-component>
		...
</identity-ui-configuration>

Due to the differentiation between subscription-mode and admin-subscription-mode it is possible to require e-mail validation and approval for new registrations and e-mail validation only when a user is created in the user management portlet.

The email templates can be found in the folder: portal-identity.sar/conf/templates/
New languages can be added by creating a new file like: emailTemplate_fr.tpl

This example explains how to change optional properties to required properties, of course once this is done, we will also need to add the corresponding fields in the registration page.
Here are the modifications in portal-identity.sar/conf/identity-ui-configuration.xml, we simply changed the required element to true on our two fields corresponding to the given and family names.

<identity-ui-configuration>
...
	<!-- user interface components -->
		...
		<ui-component name="givenname">
			<property-ref>user.name.given</property-ref>
			<required>true</required>
		</ui-component>
		<ui-component name="familyname">
			<property-ref>user.name.family</property-ref>
			<required>true</required>
		</ui-component>
		...
</identity-ui-configuration>

Now that we changed those values to "required" we need to give a chance to the user to enter those values, here are the changes done in portal-identity.sar/portal-identity.war/WEB-INF/jsf/common/register.xhtml

...
	<h:outputText value="#{bundle.IDENTITY_GIVENNAME}"/>
  	<h:inputText id="givenname" value="#{manager.uiUser.attribute.givenname}"
  			required="#{metadataservice.givenname.required}"/>
  	<h:panelGroup />
  	<h:message for="givenname" />

  	<h:outputText value="#{bundle.IDENTITY_FAMILYNAME}"/>
  	<h:inputText id="lastname"  value="#{manager.uiUser.attribute.familyname}"
  			required="#{metadataservice.familyname.required}"/>
  	<h:panelGroup />
  	<h:message for="lastname"/>
...

That's it - from now on the given name and family name will be required on registration. We dynamically obtain the values from the descriptor. Now if i just wanted to make them back to optional, i would change the values only in the descriptor, letting the user enter or not those values.

If the data to enter is a choice instead of a free-text value, you can also define those in the descriptor like shown here:

<identity-ui-configuration>
...
	<!-- user interface components -->
		...
		<ui-component name="interests">
			<property-ref>portal.user.interests</property-ref>
			<values>
				<value key="board">snowboarding</value>
				<value key="ski">skiing</value>
				<value key="sledge">sledging</value>
			</values>
		</ui-component>
		...
</identity-ui-configuration>

In portal-identity.sar/portal-identity.war/WEB-INF/jsf/common/profile.xhtml - change inputText to a selectOneMenu:

	...
	<h:outputText value="#{bundle.IDENTITY_INTERESTS}"/>
	<h:selectOneMenu id="interests" value="#{manager.uiUser.attribute.interests}"
		required="#{metadataservice.interests.required}">
	<f:selectItems value="#{metadataservice.interests.values}" />
	</h.selectOneMenu>
  	<h:panelGroup />
	<h:message for="interests"/>
...

For localizing dynamic values it is also possible to use the resource bundle. This can be done by adding the key with a prefix (to i.e. Identity.properties) like in the following listing. The key will be stored in the users property and is used to identify the element. The value of the configuration file will only be used if no localization information is found.

...
IDENTITY_DYNAMIC_VALUE_BOARD=localized snowboarding
IDENTITY_DYNAMIC_VALUE_SKI=localized skiing
IDENTITY_DYNAMIC_VALUE_SLEDGE=localized sledging
...

step 1: add a new property to profile-config.xml e.g. a dynamic property called gender:

...
   <property>
      <name>user.gender</name>
      <type>java.lang.String</type>
      <access-mode>read-write</access-mode>
      <usage>optional</usage>
      <display-name xml:lang="en">Gender</display-name>
      <description xml:lang="en">The gender</description>
      <mapping>
         <database>
            <type>dynamic</type>
            <value>user.gender</value>
         </database>
      </mapping>
   </property>
...

step 2: add the property to the identity-ui-configuration: (portal-identity.sar/conf/identity-ui-configuration.xml)

...
	<ui-component name="gender">
		<property-ref>user.gender</property-ref>
		<required>true</required>
		<values>
			<value key="male">Male</value>
			<value key="female">Female</value>
		</values>
	</ui-component>
...

step 3: add your custom ui-component to the profile page: (portal-identity.sar/portal-identity.war/WEB-INF/jsf/profile.xhtml)

...
	<h:outputText value="#{bundle.IDENTITY_GENDER}"/>
	<h:selectOneMenu id="gender" value="#{manager.uiUser.attribute.gender}"
			required="#{metadataservice.gender.required}">
		<f:selectItems value="#{metadataservice.gender.values}" />
	</h.selectOneMenu>
  	<h:panelGroup />
	<h:message for="gender"/>
...

Illustration of the relationship between the configuration files.

The JSF-View in more detail:

By default not all values of the user profile will be displayed on the View profile page. For customization it is possible to add further properties to the page by editing the file: portal-identity.sar/portal-identity.war/WEB-INF/jsf/profile/viewProfile.xhtml

By default requests (e.g. e-mail validation and registrations) expire after some time in the validation state. Therefore it is not required to add additional maintenance mechanism to invalidate a request. The default expiration time is 2 days, but is quite easy to change the timing by editing the duedate attribute in the process definition. changes in: portal-identity.sar/conf/processes/*.xml

<process-definition>
...
  <state name="validate_email">
  	  <timer name="time_to_expire" duedate="2 days" transition="timedOut" />
  </state>
...
</process-definition>

When migrating from former versions of JBoss Portal the Identity User Portlets won't be displayed by default, but Windows can be created on basis of the existing Portlet Instances which are deployed by default. (The instances names being IdentityUserPortletInstance and IdentityAdminPortletInstance.)

You can configure the JAAS authentication stack in jboss-portal.sar/conf/login-config.xml. It is important to remember that authorization in portal starts at the JAAS level - configured LoginModules apply proper Principal objects representing the roles of authenticated user. As you can see in jboss-portal.sar/portal-server.war/WEB-INF/web.xml portal servlet is secured with specified role ("Authenticated"). In the default portal configuration this role is dynamically added by IdentityLoginModule. If you reconfigure the default JAAS authentication chain with other LoginModule implementations, you should remember that you must deal with that security constraints in order to be able to access portal. For example if you place only one LoginModule that will authenticate users against LDAP server you may consider adding all users in your LDAP tree to such role.