Upgrade Guide

Functional Changes for SP4

This appendix describes functional changes in WebLogic Portal Version 8.1 SP4 that affect your upgraded environment and might require that you perform manual tasks.

For additional information on new features in SP4, see the WebLogic Platform Release Notes at:

http://download.oracle.com/docs/cd/E13196_01/platform/docs81/relnotes/relnotes.html.

Aggressive Control Tree Persistence

SP4 contains Portal Framework changes that significantly improve performance. Most of these changes have no effect on how you implement WebLogic Portal; however, because of the new aggressive control tree state management improvements, you must be particularly careful not to duplicate session IDs within your portal/desktop. If you use duplicate IDs, unknown effects might occur and the resulting problems would be difficult to diagnose.

Content Management Portlet

The Content Management portlet now uses wlp-admin.jar rather than cms_tools.jar. If you added the Content Management portlet to your project in a previous Service Pack, you must delete cms_tools.jar and add the SP4 version of wlp-admin.jar to the following directory:

<portal_application>\<project>\WEB-INF\lib\

You can find the SP4 version of the wlp-admin.jar in the following directory:

WL_HOME\samples\portal\portalApp\sampleportal\WEB-INF\lib

For more information on setting up a Content Management portlet, see the WebLogic Workshop online help.

URL Template File Updates

The WEB-INF\url-template-config.xml file is automatically created in a portal Web project. The url-template-config.xml file contains multiple URL "templates," each with a unique name. Those template URLs contain variables such as url:domain and url:port that are read in from the active server.

If you are upgrading a web application from a previous service pack, review the following sections to determine if you need to edit the url-template-config.xml file.

Creating New Portals Using Administration Portal

When you create new portals with the Administration Portal, the generated url-template-config.xml file does not contain the {url:currentPage} variable. Add this variable to the file to allow the tree optimization feature to work, and to ensure full function of the Back button.

URL Template File Update for WSRP

The url-template-config.xml file contains URL templates and variables for remote portlets in a WSRP portal Web project. You must make the following two changes in this file for each WSRP URL template, so that the BEA-provided consumer will be able to handle mode changes and state changes from non-BEA producers:

Replace _mode with wsrp-mode
Replace _state with wsrp-windowState

Updates for Java Portlets

If you are using or you plan to use Java portlets (JSR 168 portlets), edit the url-template-config.xml file to match the new content in the SP4 version of this file; add/update the content as the following example shows:

<url-template name="portlet-secure-default"> https://{url:domain}:{url:securePort}/{url:path}?{url:queryString}{url:currentPage} </url-template>  <java-portlet-url-templates> <url-template-ref type="action" name="portlet-action"/> <url-template-ref type="secure-action" name="portlet-secure-action"/> <url-template-ref type="resource" name="portlet-resource"/> <url-template-ref type="secure-resource" name="portlet-secure-resource"/> <url-template-ref type="render" name="portlet-default"/> <url-template-ref type="secure-render" name="portlet-secure-default"/> </java-portlet-url-templates>

Portlet Preferences Behavior on Server Restart

Prior to Service Pack 4, when the server was bounced or redeployed, the preferences in the .portlet file always overrode the preferences in the database, so administrator additions and changes to any portlet preferences were lost on a server restart.

A new option allows you to control the way in which portlet preferences are reloaded on server restart. You implement this control using the "master" attribute on the "propagate-preferences-on-deploy" element in the WEB-INF/netuix-config.xml file.

Possible values for the master attribute are:

file

Provides the same behavior as in previous versions. The preferences in the file system always take precedence. To preserve existing behavior, select this value.

database

In the case of a restart, the values in the database always takes precedence. In the case of a first time startup, the database is seeded from the .portlet files.

both

The default behavior if the attribute is missing. The .portlet preferences are merged with the database preferences, with the database values taking precedence over the .portlet file's values.

The following example shows the element with an attribute value of both:

<customization>

<enable>true</enable>

<propagate-preferences-on-deploy propagate-to-instances="true" master="both"/> <reload-database-on-redeploy reload="false"/> </customization>

Entitlements Data Source

The policy reference RDBMS persistence feature is a performance enhancement in SP4. If you are upgrading from a previous service pack and upgrading a pre-SP4 domain, you must add a new JNDI name, which is used to look up the p13nDataSource.

To perform this task using the WebLogic Server console:

In the Services Configurations section, select JDBC Data Sources.

In the Name column, select p13nDataSource.

Append ;p13n.entitlementsDataSource to the JNDI Name: field and click Apply.

Restart the server.

Storage of Policy Reference Data in RDBMS

Starting with WebLogic Portal 8.1 SP4, new database tables store entitlement data and Delegated Administration security policy reference data. Policy storage remains within LDAP, but policy reference data is stored in the RDBMS. When you access the Administration Portal for the first time in an upgraded domain, the system performs an automatic migration of this policy reference data.

If you want to prevent the migration of data to the new database tables, set the following Java environment parameter in the startWebLogic.cmd/.sh file:

-Dp13n.policyRef.LdapPersistence=Y

For details on the new database tables, see the Data Dictionary in the Portal Database Administration Guide:

http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/db/4Schemas.html

Using Role Caching with Entitlements

Starting with WebLogic Portal 8.1 SP4, role values are cached automatically. Normally you do not need to change this setting. However, if you decide to define roles with expressions whose evaluation changes within the course of processing a request, you may need to disable this setting.

To disable role caching, edit the web.xml file for the respective application. For instructions on this task, see the WebLogic Portal Performance Tuning Guide at http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/perftune/4PortalApplication.html#1074386.

Setting up JDBC Connection Polling

In Service Pack 4, JDBC connection polling was added to the RDBMS authentication provider to keep JDBC connections active during long periods of inactivity. This was done to prevent firewalls or databases from timing out JDBC connections held by the internal pooling mechanism in the RDBMS authentication provider.

When configuring your RDBMS authentication provider you must enable connection polling. The WebLogic Server console includes the following two new attributes that you can set when you create/configure your provider:

TestConnections - A checkbox used to enable/disable JDBC connection polling (disabled by default).
TestInterval - The number of seconds between polling tests.

Creating Complex Content Queries

In Service Pack 4, the SQL generator which serves as the engine for content queries was updated for performance, to allow for more efficient use of the NOT (!) operator, and handle multi-valued properties more efficiently.

Performance

In SP4, the generator generates conjoined queries instead of co-related sub-selects. This results in higher performance. In addition, complex queries OR (||) queries have been improved for performance.

Using the NOT (!) Operator

When using the NOT operator for single-valued properties, the operator now returns only those values that meet the queries requirements. Previously, the NOT operator would return content that did not have an associated ObjectClass (content type).

Complex queries such as !(!(city != 'boulder' && sex!='male')) are now better supported.

Querying Multi-Valued Properties

Using the NOT operator has changed within multi-valued properties. If you need to use the NOT operator to query multi-valued properties, it is recommended that you use the CONTAINSALL clause. The NOT operator is not supported for other clauses when querying multi-valued properties.