Red Hat JBoss Portal 6.0

Migration Guide

For use with Red Hat JBoss Portal 6.0.

Red Hat Documentation Group

Legal Notice

This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Abstract

Read this guide to learn the areas that require attention when migrating your portal platform from JBoss Enterprise Portal Platform 5 to Red Hat JBoss Portal 6.0.

1. Before Starting

1.1. Get Assistance Before Migrating

These notes are specific to migrating from JBoss Enterprise Portal Platform 5 to JBoss Portal Platform 6, and are by no means exhaustive. It is not possible to predict all configuration scenarios used by customers in production environments, due to the highly customizable nature of the platform.

Bearing this in mind, it is strongly recommended that you seek further assistance and guidance with migrating your production environment by contacting your Red Hat support representative. Do so by opening a support case at https://access.redhat.com/support/ .

It is also strongly recommended that you read the JBoss Enterprise Application Platform 6 Migration Guide, for information on general Middleware application server migration steps not specifically related to JBoss Portal Platform 6. This guide, along with all Enterprise Middleware documentation is available on https://access.redhat.com/knowledge/docs/

1.2. Back-up Databases

The first step in migrating to JBoss Portal Platform is to back-up all databases used in the previous platform.

Consult the user documentation for your production database, and follow the back-up instructions.

When restoring data from the back-ups, it is strongly recommended to rebuild the indexes according to the methods specific in your production database user documentation. Before doing so, ensure you retain a copy of the indexes.

Note

Depending on the size of the database, re-indexing may take a significant amount of time.

2. JNDI Pattern Changes

In JBoss Enterprise Portal Platform 5, the JNDI pattern for datasource names were included the portal name as a suffix when there were two or more portal containers. Adding a second portal container was over-complicated, because the portal container suffix needed to be added to the existing (default) portal container.

In JBoss Portal Platform 6, the portal container name of the default portal is always suffixed to the JNDI name of the datasource. This allows new portal containers and datasources to be provisioned without the constraints of the previous requirements.

The JNDI patterns for the default datasources in JBoss Portal Platform 6 are:

java:/jdbcidm_portal for the user storage.
java:/jdbcjcr_portal for the JCR storage.

Ensure the patterns are used when defining datasources in the JBOSS_HOME/standalone/configuration/standalone.xml file.

3. Data Migration

Full data migration is not required for existing portlet data.

A selection of default options need to be altered to allow legacy portlet data to be accessed and operate correctly in the new environment.

3.1. Value Storage

In JBoss Enterprise Portal Platform 5, binary files and large text files were stored in the file system. In most common scenarios, only gadget images would be stored in this manner and in most cases a better default configuration was to store everything in database since it reduced shared file system overhead and backups.

In JBoss Portal Platform 6, all the Java Content Repository (JCR) data is stored in the database by default. Therefore, existing implementations that have binaries stored in the file-system, and metadata in databases need to specify the correct location to load the metadata from.

Important

Failure to change the location of the value storage will result in runtime errors similar to:

Caused by: org.exoplatform.services.jcr.impl.storage.value.ValueStorageNotFoundException: No value storage found with id portal-system

To revert the behavior to the previous portal platform behavior, add the following configuration to JBOSS_HOME/standalone/configuration/gatein/configuration.properties. Ensure there are no conflicting definitions already specified for the values.

gatein.jcr.storage.enabled=true
gatein.jcr.storage.data.dir=<<use your former value, pointing to the shared 'values' directory>>

Because of the JNDI pattern changes described in Section 2, “JNDI Pattern Changes”, the directories containing the data must also be renamed, as shown in the example directory names in Table 1, “Value Storage Directory Name Change”. When implementing the changes, replace portal with the name of the portal in your production instance.

Table 1. Value Storage Directory Name Change

Legacy Directory Name	New Directory Name
values/pc	values/pc_`portal`
values/system	values/system_`portal`
values/wsrp	values/wsrp_`portal`
values/portal-system	values/portal-system_`portal`
values/portal-work	values/portal-work_`portal`

3.2. Isolated Mode

JBoss Portal Platform 6 allows data to be stored for each JCR workspace in unique tables, which greatly simplifies database provisioning for new installations.

It is not possible to split current platform data into individual tables for compatibility with previous versions, therefore the portal needs to be configured back to the former default to operate correctly with legacy data.

Edit JBOSS_HOME/standalone/configuration/gatein/configuration.properties and add change gatein.jcr.db-structure-type=isolated to gatein.jcr.db-structure-type=single.

3.3. Index Storage

In clustered environments, previous versions of the portal required a shared file system to host the JCR indexes across all nodes of a cluster. In JBoss Enterprise Portal Platform 5.2, a method for each node to keep a local index copy was introduced.

In JBoss Portal Platform 6, the local index method is now standard configuration.

To revert to the shared file system method, the following uncommented lines must be uncommented in the JBOSS_HOME/standalone/configuration/gatein/configuration.properties file for all nodes:

# JCR
# All gatein nodes have to point to the same shared filesystem directory
gatein.clustered.data.dir=<<use your former value, pointing to the shared 'lucene' directory>>
gatein.jcr.index.changefilterclass=org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter

If the default platform behavior is desired in the future, ensure the gatein.clustered.data.dir does not point to a shared directory. By default, the value for this parameter is JBOSS_HOME/standalone/data/gatein/jcr/lucene for each node.

When the platform is restarted, the index is rebuilt to current portal platform defaults, and the index is shared on all nodes.

4. WS-Security

The Web Services stack used in the version of JBoss Enterprise Application Platform included in previous portal versions has been redesigned and now uses Apache CXF.

Follow the configuration specified in the Securing WSRP section of the JBoss Portal Platform 6 Reference Guide.

5. Portlet Bridge (JSF2)

5.1. Migration Complexity Level

The challenge to migrate Java Server Faces (JSF) 1.2 applications depends on the view technology used, and what type of view technology the applications will be upgraded to.

Migrating from JSP 2.x to JSP 2.x: Minimal anticipated effort.
Migrating from Facelets 1.x to Facelets 2.x: Minor anticipated effort.
Migrating from JSP 2.x to Facelets 2.x: Significant effort, particularly if the applications have custom components.

5.2. Basic Changes

The following basic changes need to be performed to applications using JSF 1.2, before they can be used in a JSF 2.x environment:

Remove JSF 1.2 JARs from /WEB-INF/lib, if the JARs are present in the application.

Declare the correct schema in the faces-config.xml file.

<faces-config
  xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd"
  version="2.0">

Declare a minimum servlet schema of version 2.5 in the WEB-INF/web.xml file.

<web-app 
  xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
  id="[YourWebappID]"
  version="2.5">

5.3. Facelets 1.x to Facelets 2.0

Follow this procedure when migrating applications from Facelets 1.x to Facelets 2.0 view technology.

Remove the Facelets 1.x JAR from /WEB-INF/lib.
Remove the Facelets 1.x FaceletViewHandler from faces-config.xml
Update customized FaceletViewHandler implementations to extend ViewHandlerWrapper instead.
Refer to the Oracle JavaEE 6 documentation for more information.

Update the root declaration of existing Facelet taglib XML directives with the new schema.

<facelet-taglib 
  xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facelettaglibrary_2_0.xsd"
  version="2.0">

Optional: Remove Facelets 1.x directives that are now default in Facelets 2.0
To maintain the application code, consider removing any Facelets 1.x <context-param> directives from the WEB-INF/web.xml file that have been incorporated by default into Facelets 2.0.

5.4. JSP 2.x to Facelets 2.x

Moving from JSP 2.x to Facelets 2.x requires significant rework. Switching between technologies changes the underlying view technology, and changes must be made before a site can move to production.

5.5. Master Page Changes

When creating a JSF Facelet view document, it was common practice to wrap the content using a <!DOCTYPE html> declaration. Because a single portlet often reflects a small portion of the HTML mark-up for a page, a JSF portlet returning <!DOCTYPE html> can be distracting, and can cause issues with page rendering.

All <!DOCTYPE html> declarations must be changed to <f:view> declarations to ensure that only the relevant content of the portlet is returned to the page.

Note

While not strictly relevant to a portlet, it is important to include <h:head> and <h:body> elements to allow JSF to process the Facelet correctly.

Example 1. Master page declaration changes

<!DOCTYPE html> declaration method.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" ">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"
    xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:a4j="http://richfaces.org/a4j">
...
</html>

<f:view> declaration method.

<f:view xmlns="http://www.w3.org/1999/xhtml" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core"
    xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:a4j="http://richfaces.org/a4j">
...
</f:view>

5.6. Include Page Changes

Follow the procedure to correctly implement JSP include across all affected resources. This procedure does not cover JSP pages that include scriptlet code.

Change all <jsp:include> directives to <ui:include> directives.
Example 2. <jsp:exclude> update example
Old directive:
```
<jsp:include page="include.jsp" />
```
New directive:
```
<ui:include page="include.xhtml" />
```

Change all JSP include page templates from <f:subview> directives to <ui:composition> directives

Example 3. <jsp:exclude> update example

Old directive:

<%@page contentType="text/html" pageEncoding="UTF-8"%>
<%@taglib prefix="f" uri="http://java.sun.com/jsf/core"%>
<%@taglib prefix="h" uri="http://java.sun.com/jsf/html"%>
<f:subview id="include">
  <h:outputText value="JSF components here." />
</f:subview>

New directive:

<ui:composition
  xmlns="http://www.w3.org/1999/xhtml"
  xmlns:f="http://java.sun.com/jsf/core"
  xmlns:h="http://java.sun.com/jsf/html"
  xmlns:ui="http://java.sun.com/jsf/facelets">
  <h:outputText value="JSF components here." />
</ui:composition>

5.7. Removing complexity in faces-config.xml

Annotations are widely supported in JSF 2.x, and remove the need to specify directives in faces-config.xml. During migration, consider removing faces-config.xml directives, and implement annotations directly in the application code.

A basic list of annotations is provided in Table 2, “JSF Annotations”. The table links the annotation name directly to the Oracle JavaEE documentation. For more general information about the available faces annotations, refer to http://docs.oracle.com/javaee/6/api/javax/faces/bean/package-summary.html.

Any <navigation-case> which uses the XHTML filename for <from-outcome> and <to-view-id> can be removed. The navigation behavior resulting from this configuration is done automatically in JSF 2.x using a feature called Implicit Navigation.

If no matching navigation case is found after checking all available rules, the navigation handler checks whether the action outcome corresponds to a view ID. If a view matching the action outcome is found, an implicit navigation to the matching view occurs.

Table 2. JSF Annotations

Annotation	Description
@ManagedBean	Replaces <managed-bean>
@RequestScoped	Replaces <managed-bean-scope>. Must be declared as part of @ManagedBean.
@ViewScoped	Replaces <managed-bean-scope>. Must be declared as part of @ManagedBean.
@SessionScoped	Replaces <managed-bean-scope>. Must be declared as part of @ManagedBean.
@ApplicationScoped	Replaces <managed-bean-scope>. Must be declared as part of @ManagedBean.
@ManagedProperty	Replaces <managed-property>.
@FacesValidator	Replaces <validator>. Must be declared as part of @ManagedBean
@FacesConverter	Replaces <converter>
@FacesRenderer	Replaces <renderer>.

6. Portal Containers and Extensions

JavaEE 6 imposes stricter packaging requirements for EAR packaging.

Previous examples of portal containers and portal extensions listed utility JARs in META-INF/application.xml. These JARs will not be available without setting up the other module's dependent classpath.

To make portal containers and extensions work, utility JARs should be moved to a 'lib' directory, or any other packaging that respects Java EE 6 classloading expectations.

Example 4. JavaEE 6 Utility Package Structure

|-- my-company-extension.ear
|   |-- my.company.extension.war
|   |-- lib
|   |   |-- my.company.extension.config.jar
|   |   `-- my.company.extension.lib.jar
|   `-- META-INF
|       |-- application.xml
|       |-- MANIFEST.MF

7. URL Redirect

URL handling was improved in JBoss Enterprise Portal Platform 5, and the public and private qualifiers in the URL were no longer specified in the authenticated or unauthenticated section of the portal.

In order to provide backwards compatibility with URLs used in JBoss Enterprise Portal Platform 4, accessing a URL such as /portal/public/classic would redirect the user to /portal/classic. If the user was unauthenticated, accessing a URL such as /portal/private/classic would redirect the user to /portal/classic and optionally redirect first to the login page.

In JBoss Portal Platform 6, the user will only be redirected to the login page if the redirect is to a page which requires authentication. This means that accessing /portal/private/classic will redirect the user to /portal/classic without first redirecting to the login page (because /portal/classic does not require authentication by default).

Note

It is possible to add the old behavior back into the platform, however this behavior will be deprecated permanently in future JBoss Portal Platform 6 releases.

Modify the portal's web.xml file to include portal/private/* as a url-pattern in the <security-constraint> section.

8. Picketlink IDM

There are two new options applicable to the Picketlink IDM configuration file located at JPP_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/idm-configuration.xml. These options affect customers with LDAP configured as the default store.

ignoreMappedMembershipTypeGroupList

Contains a list of roles, which are mapped to Picketlink IDM as simple relationships. For implementations using LDAP as the Default store this option is important because the configuration generally must mention all groups mapped to LDAP.

Example 5.

If an implementation specified groups /platform/* and /organization/* mapped to LDAP groups, the content of the option should look similar to

<field name="ignoreMappedMembershipTypeGroupList">
  <collection type="java.util.ArrayList" item-type="java.lang.String">
    <value>
      <string>/platform/*</string>
    </value>
    <value>
      <string>/organization/*</string>
    </value>
  </collection>
</field>

For implementations that use LDAP as a read-only store, or that do not use LDAP (database-only setup), the list should be empty (the default setting).

<field name="ignoreMappedMembershipTypeGroupList">
  <collection type="java.util.ArrayList" item-type="java.lang.String">
  </collection>
</field>

skipPaginationInMembershipQuery

Boolean option, which specifies how membership pagination in the JBoss Portal Platform GUI should be handled.

When set to true, membership pagination in the portal GUI is skipped (disabled).

When set to false, membership pagination is enabled, which will lead to a performance improvement.

Important

Do not enable membership pagination if the implementation uses DB+LDAP. Pagination will not work correctly for a DB+LDAP setup.

It is acceptable to enable membership pagination for database-only implementations.

A. Revision History

Revision History

Revision 6.0.0-3.400

2013-10-31

Rüdiger Landmann

Rebuild with publican 4.0.0

Revision 6.0.0-3

Fri Aug 9 2013

Jared Morgan

Updated the Product Name to reflect the new name grouping for the product. No update was made to details in the guide.

Revision 6.0.0-2

Tue Mar 05 2013

Jared Morgan

Prepared for JBoss Portal Platform 6.0 GA.

Revision 6.0.0-1

Wed Jan 16 2013

Jared Morgan

Prepared for JBoss Portal Platform 6.0 Beta.