Migrating WebLogic Personalization Server to Version 3.1

 

This document describes the changes between WebLogic Personalization Server (WLPS) 2.0.1 and WebLogic Personalization Server 3.1. It includes specific information for migrating existing code to WebLogic Personalization Server 3.1.

Note: Both the Commerce Server and Personalization Server functionality now reside in a unified Java package hierarchy located at com.beasys.commerce.

This section includes the following topics:

• Navigating with Flow Manager

• Changes to the Personalization Advisor

• Changes to the Rules Editor

• Changes to Content Management

• Schema Tables

  Note: Changes to the JSP Tag Library in Version 3.1 are covered in the next chapter.

 

---

Navigating with Flow Manager

The Flow Manager is a servlet implementation that allows the hot-deployment of applications within the WebLogic Application Server. Flow Manager also adds flexibility to navigation through the system-it moves navigation information off the JSP page and into a single point of control. Using a destination determiner and a destination handler, the Flow Manager dynamically determines a destination for a given page request and dynamically handles it.

This topic includes the following sections:

• Deprecated Service Managers

• Hot Deployment

• Dynamic Flow Determination and Handling

• Property Set Usage

• Go with the Flow: Migrating to the Flow Manager

• Accessing Your Application via the Flow Managers

For more information, see "Flow Manager" in the Foundation chapter in the WebLogic Personalization Server Developer's Guide.

Deprecated Service Managers

In WebLogic Personalization Server 3.1, all of the functionality of the JSP Service Manager and the Portal Service Manager has been ported to the new Flow Manager. The JSP Service Manager and the Portal Service Manager have been deprecated.

Hot Deployment

The Flow Manager is a servlet implementation that allows the hot-deployment of applications within the WebLogic Application Server.

Registering a new portal or a new application no longer requires restarting the server, as it did in WebLogic Personalization Server 2.0.1. Instead of registering servlets in the weblogic.properties file, the Flow Manager relies on a property set to obtain information about a specific application or portal. You simply create a new instance of a property set to hold the equivalent parameters that were in the properties file. Default values are supplied during property set creation. Any changes become visible according to a configurable refresh setting in the property set.

Dynamic Flow Determination and Handling

Flow Manager also provides the basic infrastructure to support the new Webflow functionality. Webflow dynamically determines a destination for a given page request and dynamically handles it. Using a destination determiner and a destination handler, the Flow Manager moves navigation information off the JSP page and into a single point of control.

The old service managers relied on a hidden form field in the current page to determine where an HTTP request should be routed:

<input type="hidden" name="<%=DESTINATION_TAG%>"

value="<%=PortalJspBase.getRequestURI(request)%>">

This scheme required destination (or routing) information to be distributed across the JSP/HTML pages. While this works fine, it can be cumbersome to modify if destination values needs to change.

The Flow Manager, on the other hand, allows the determination of page routing to be centralized on the server based on an application's needs.

Backward Compatibility

For backward compatibility, default implementations of the destination determiner and the destination handler are provided which support destination information being passed via the DESTINATION_TAG mentioned above. These implementations are:

com.beasys.commerce.portal.flow.PortalDestinationDeterminer
and 
com.beasys.commerce.foundation.flow.ServletDestinationHandler

Also, for non-portal based personalized applications, the following default implementations may be used:

com.beasys.commerce.foundation.flow.jsp.DefaultDestinationDeterminer
and
com.beasys.commerce.foundation.flow.ServletDestinationHandler

Property Set Usage

A new class of property sets, "Application Initialization Property Sets" has been added to the Property Set Management admin tools. These are the property sets used by the Flow Manager in support of portal (_DEFAULT_PORTAL_INIT) and non-portal (_DEFAULT_APP_INIT) based personalized applications.

Three new properties have been added to support the Flow Manager:

• destinationdeterminer Property

  The destination determiner is responsible for evaluating an HTTP request and determining which servlet to route it to.

  The value provided for this property should be the name of a class that implements the com.beasys.commerce.foundation.flow.DestinationDeterminer interface. If appropriate, use a default implementation provided by WebLogic Personalization Server or WebLogic Commerce Server. Otherwise, develop your own implementation according to the needs of your application.

• destinatationhandler Property

  Given a destination route, the destination handler is responsible for envoking the requested processing.

  The value provided for this property should be the name of a class that implements the com.beasys.commerce.foundation.flow.DestinationHandler interface. If appropriate, use a default implementation provided by WebLogic Personalization Server or WebLogic Commerce Server. Otherwise, develop your own implementation according to the needs of your application.

• ttl (time to live) Property

  ttl, which stands for time to live, represents how often (in milliseconds) the Flow Manager reloads the _APPLICATION_INIT property set from the database. This allows changes that you make to the _APPLICATION_INIT property set to be visible while the application or portal is running.

  Note: To force immediate reloading of the property set, append the "flowReset" argument to your URL, like this: http://localhost:7001/application/exampleportal?flowReset=true

Go with the Flow: Migrating to the Flow Manager

To migrate your portal or non-portal application to use the Flow Manager, do the following:

To create a new property set:

1. Open the Administration Tools Home page. Click the Property Set Management icon to open the Property Set Management screen.

2. From the main Property Set Management screen, click Create.

3. Name the new property set you are creating (100 character maximum). The name of the property set should be the same as the name you used to create the portal, or the name you will use to access the application.

4. Enter a description of the property set (255 character maximum).

5. From the Copy Properties From drop-down list, select APPLICATION_INIT._DEFAULT_PORTAL_INIT (for a portal)
   or
   APPLICATION_INIT._DEFAULT_APP_INIT (for a non-portal application).

6. From the Property Set Type drop-down list, select Application Init.

7. Click the Create button.

8. At the top of the page, in red, you will see the message "Property Set creation was successful." (Or, you will see an error message indicating why the property set was not created.)

9. Click Back to return to the main Property Set Management screen.

To set parameters for your portal or application:

1. From the Property Set Management Home page, under the Application Initialization Property Sets heading, click the name of the property set you just created.

2. A Property Set page comes up, allowing you to set parameters.

3. Note: For non-portal applications, skip this step.
   To edit the portal name, click the Edit button to the right of the "portal name" property. Change the default value from UNKNOWN to the name of your portal, as you created it in Portal Management.

4. Edit the destinationdeterminer property. Either accept the default, or edit to provide your own implementation of these classes.

5. Edit the destinationhandler property. Either accept the default, or edit to provide your own implementation of these classes.

6. Customize any other properties you choose. For information about customizing properties in portals, see Creating and Managing Portals in the WebLogic Personalization Server User's Guide and Creating Custom Portals in the WebLogic Personalization Server Developer's Guide.

7. When you have finished setting properties, click the Finished button at the bottom of the page.

   Note: In WebLogic Personalization Server 2.0.1, you registered servlets in the weblogic.properties file. This is not required for WebLogic Personalization Server 3.1. You have the option to remove them, but it is not required. The WebLogic Personalization Server will ignore them.

Accessing Your Application via the Flow Manager

The exact URL you use depends upon whether or not you have deployed your application as a web application. WebLogic Personalization Server 3.1 includes sample configurations for both a web application/web archive deployment and a non-web application configuration. For more information, see the chapter Using the Catalog Application in a Portal in the WebLogic Personalization Server Developer's Guide.

 

---

Changes to the Personalization Advisor

For WebLogic Personalization Server 3.1, the Personalization Advisor has been renamed to Advisor and has undergone some API changes. However, its functionality remains the same. The Advisor has been improved to provide better error reporting and to make use of the unified logging facility provided by the WLCS/PS 3.1.

This topic includes the following sections:

• JSP Tags Ported to Use the New Advisor

• Deprecated Personalization Advisor Classes

• Changes in Advisor APIs

• Terminology Change: Agents Changed to Advislets

JSP Tags Ported to Use the New Advisor

The three pz library tags (pz:div, pz:contentQuery, and pz:contentSelector) have been changed to use the new Advisor Session Bean. However, the tag usage remains the same. For more information, see the JSP Tag Library Reference in the WebLogic Personalization Server Developer's Guide.

To use the <pz:div> and <pz:contentSelector> tags, you are no longer require to insert the following JSP directive into your JSP code:
<%@ page extends="com.beasys.commerce.axiom.p13n.jsp.P13NJspBase" %>
However if it is already in your code, you do not need to remove it.

Deprecated Personalization Advisor Classes

All of the Java classes for the Personalization Advisor released in WebLogic Personalization Server 2.0.1 have been deprecated. This includes all of the Java classes in the following Java packages:
com.beasys.commerce.axiom.p13n.advisor
com.beasys.commerce.axiom.p13n.agents

In WebLogic Personalization Server 3.1, these deprecated classes are replaced by new Advisor Java packages. They include:
com.beasys.commerce.axiom.advisor
com.beasys.commerce.axiom.advislets

The Personalization Advisor Bean has been replaced by the new Advisor Bean.

This change only affects the case when the Advisor API is used directly and is transparent to JSP tag users.

Changes in Advisor APIs

The changes made while porting the WebLogic Personalization Server 2.0.1 Personalization Advisor interface to the new Advisor interface are as follows:

• The Personalization Advisor pzTechnique parameter is not supported in the new Advisor implementation.

• The createRequestTemplate method parameters have been simplified to use a single string lookup name for the advice request, instead of a fully qualified class name. The three advice request lookup names supported for WebLogic Personalization Server 3.1 are ClassificationAdviceRequest, ContentSelectorAdviceRequest, and ContentQueryAdviceRequest.

The following example shows the difference in the createRequestTemplate method between the Personalization Advisor and the Advisor.

Personalization Advisor Interface

public AdviceRequest createRequestTemplate(
String adviceRequestClassName,
String pzTechnique)
throws IllegalArgumentException,
PersonalizationAdvisorException,
RemoteException;

Advisor Interface

public AdviceRequest createRequestTemplate(
String theKindOfRequest)
throws IllegalArgumentException,
AdvisorException,
RemoteException;

Terminology Change: Agents Changed to Advislets

The three WebLogic Personalization Server 2.0.1 Personalization Agents have been renamed and repackaged to advislets. The following table defines the mapping between the WebLogic Personalization Server 2.0.1 Agent Java classes to the WebLogic Personalization Server 3.0 advislet Java classes.

2.0 Agent class	com.beasys.commerce.axiom.p13n.agents.ClassificationAgentImpl
3.1 Advislet class	com.beasys.commerce.axiom.advisor.advislets.ClassificationAdvisletImpl
2.0 Agent class	com.beasys.commerce.axiom.p13n.agents. ContentSelectorAgentImpl
3.1 Advislet class	com.beasys.commerce.axiom.advisor.advislets.ContentSelectorAdvisletImpl
2.0 Agent class	com.beasys.commerce.axiom.p13n.agents. ContentQueryAgentImpl
3.1 Advislet class	com.beasys.commerce.axiom.advisor.advislets.ContentQueryAdvisletImpl

 

---

Changes to the Rules Editor

The WebLogic Personalization Server provides rule sets that include a set of classifier and content selector rules. These rule sets act as containers for rules that match personalized content with users.

This topic includes the following sections:

• Relationship Between Rules and Property Sets

• The Use of And or Or to Connect Expressions

• Change the Word Rule Sheet to Rule Set

For more information, see Creating and Managing Rules in the WebLogic Personalization Server User's Guide.

Relationship Between Rules and Property Sets

In previous releases, the rule sets (also called rule sheets) were associated with property sets that defined the attributes available for user and group profiles. Once defined, this relationship between rules and property sets could not be undone.

In the current WebLogic Personalization Server 3.1 release, there is no longer an association between a rule set and a property set. Rules within a rule set may refer to any properties.

The Use of And or Or to Connect Expressions

The Rules Editor now allows the use of "and" or "or" to connect expressions that contain comparators.

Change the Word Rule Sheet to Rule Set

For consistency, an effort has been made to change the word "rule sheet" to "rule set" or ruleSet in all cases. However, the following legacy code continues to use Rulesheet:
jdbc://com.beasys.commerce.axiom.reasoning.rules.RulesheetDefinitionHome

 

---

Changes to Content Management

This topic includes the following sections:

• New features in <cm:select> and <cm:selectById> tags

• Changes to EJB Deployment Descriptors

• Changes to Object Interfaces

• Changes to the BulkLoader

New features in <cm:select> and <cm:selectById> tags

To retrieve Content or Documents, use a ContentManager or DocumentManager with <cm:select> or <cm:selectById>. The default DocumentManager is deployed at com.beasys.commerce.axiom.document.DocumentManager. For more information, see "Configuring WebLogic Commerce Properties" in the chapter Creating and Managing Content in the WebLogic Personalization Server User's Guide.

The <cm:select> and <cm:selectById> tags now support a session-based, per-user Content cache for content searches. For more information, see "Content Cache" in the chapter Creating and Managing Content in the WebLogic Personalization Server User's Guide.

The Content Manager now supports non-EJB context objects. The <cm:select> and <cm:selectById> tags support an optional readOnly parameter. For more information, see "readOnly Content Tag" in the chapter Creating and Managing Content in the WebLogic Personalization Server User's Guide.

Changes to EJB Deployment Descriptors

Deployment descriptors handle the configuration for the Content Manager. This section describes the changes to the deployment descriptors:

• Document Schema EJB Deployment Descriptor

• DocumentManager EJB Deployment Descriptor

• Document EJB Deployment Descriptor (Deprecated)

Document Schema EJB Deployment Descriptor

Two EJB variables have been removed:
SmartConnectionPoolClass
SmartBMP_URL

Five EJB variables have been added:
UseDataSource
DocPoolURL
DocPoolDriver
jdbc/docPool
jdbc/commercePool

One EJB variable remain the same:
SmartBMPUpdate

For more information, see "Configuring the Document Schema EJB Deployment Descriptor" in the chapter Creating and Managing Content in the WebLogic Personalization Server User's Guide.

DocumentManager EJB Deployment Descriptor

All the EJB variables have been removed:
UseDefaultHomeNames
ContentHome
SchemaHome

Six EJB variables have been added:
PropertyCase
jdbc/docPool
ejb/ContentHome
ejb/SchemaHome
UseDataSource
DocPoolURL
DocPoolDriver

For more information, see "Configuring the DocumentManager EJB Deployment Descriptor" in the chapter Creating and Managing Content in the WebLogic Personalization Server User's Guide.

Document EJB Deployment Descriptor (Deprecated)

Note: The Document EJB has been deprecated and should not be used. Use the DocumentManager EJB instead.

To support legacy code, the Document EJB has been udgraded as follows:

Two EJB variables have been removed:
SmartConnectionPoolClass
SmartBMP_URL

Four EJB variables have been added:
UseDataSource
DocPoolURL
DocPoolDriver
jdbc/docPool

Two EJB variables remain the same:
SmartBMPUpdate
Propertycase

• SmartBMPUpdate: Set to false.

• UseDataSource: Controls whether jdbc/docPool (true) or DocPoolURL (false) is used to get connections. Defaults to true.

• DocPoolURL: Specifies the JDBC URL to the document JDBC connection to use (if UseDataSource is false.) Should point to a connection pool.
  For example: jdbc:weblogic:pool:docPool

• DocPoolDriver: Specifies the JDBC driver class to use to connect to the DocPoolURL. This is optional. If not specified, the EJB will try to determine the appropriate JDBC driver class from the DocPoolURL.

• jdbc/docPool: A Data Source reference to the document JDBC connection Pool. This should correspond to the Data Source attached to the WebLogic connection pool that uses the document reference implementation JDBC driver.

• PropertyCase: This sets how the DocumentImpl modifies incoming property names. If this is lower, all property names are converted to lower case. If this is upper, all property names are converted to upper case. If this is anything else or not specified, property names are not modified. Use lower or upper if the SmartBMP class expects everything in a certain case (for example, the Documentum SmartBMP expects everything in lower case). For the document reference implementation, do not specify the PropertyCase.

Other SmartBMP classes for other document management systems will possibly require more and/or different EJB environment variables.

Changes to Object Interfaces

The ConfigurableEntity, Content, Document, User and Group interfaces no longer extend EJBObject. Instead, those interfaces are code-identical to the original 2.0.1 versions (same method signatures).

The interfaces ConfigurableEntityRemote, ContentRemote, DocumentRemote, UserRemote and GroupRemote extend both EJBObject and their respective non-EJBObject interfaces.

For more information, see "Object Interfaces" in the chapter Creating and Managing Content in the WebLogic Personalization Server User's Guide

Changes to the BulkLoader

The BulkLoader now accepts a -encoding <enc> and -schemaName option. For more information, see "Command Line Usage" in the chapter Creating and Managing Content in the WebLogic Personalization Server User's Guide.

 

---

Schema Tables

The WebLogic Personalization Server Schema is now documented in the WebLogic Personalization Server Developer's Guide.

Updated User Management Schema Table

A new column called PROFILE_TYPE was added to the WLCS_USER table since release 2.0.1. It can be added to existing WLCS_USER tables with the following statement:

ALTER TABLE WLCS_USER ADD PROFILE_TYPE VARCHAR2(100);

This column holds the name of the Unified Profile Type that the User is an instance of.

For User objects that are of the standard type com.beasys.commerce.axiom.contact.User, this should be left as null. If the User is an extended User type, such as the 'Unified Profile Example', the column should be set to that type name. The example user for the Unified Profile Example should be updated with the following statement:

UPDATE WLCS_USER SET PROFILE_TYPE = 'Unified Profile Example' WHERE IDENTIFIER = 'unifieduser_bob';