Foundation Classes and Utilities

The Foundation is a set of miscellaneous utilities to aid JSP and Java developers in the development of personalized applications using the WebLogic Personalization Server. Its utilities include JSP files and Java classes that JSP developers can use to gain access to functions provided by the server, and helpers for gaining access to the Advisor services.

This topic includes the following sections:

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 by allowing navigation information to move 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.

Note: The Flow Manager replaces the functionality previously supplied by the Portal Service Manager and JSP Service Manager. All the functionality of the service managers now reside within the Flow Manager. The JSP Service Manager and the Portal Service Manager have been deprecated.

Hot Deployment

Hot deployment allows you to register a portal or non-portal application without restarting the server. To add a new portal with the Flow Manager, you simply create a new instance of a property set. The changes become visible according to a configurable refresh setting (ttl).

Dynamic Flow Determination and Handling

How the FlowManager Works

When WebLogic Personalization Server is installed, the Flow Manager servlet is registered with the WebLogic Server in the weblogic.properties file:
weblogic.httpd.register.application=com.beasys.commerce.foundation.flow.FlowManager

To access the servlet, a client browser makes an HTTP request. For example:
http://localhost:7501/application/exampleportal

In this example, "application" is the registered servlet (the Flow Manager), and "exampleportal" is the APPLICATION_INIT property set that you defined.

The following diagram illustrates how the Flow Manager handles the request.

Property Set Usage

The following three properties support the Flow Manager:

Property Name	Required	Description
destinationdeterminer	Yes	Used by Flow Manager to determine JSP page navigation.
destinationhandler	Yes	Used by Flow Manager to execute JSP page navigation.
ttl	Yes	Time to live determines (in milliseconds) how often the Flow Manager reloads the application init property set from the database.

The destination determiner evaluates an HTTP request and determines 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 DestinationHandler 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 you to make property set changes visible while the 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

Creating a New Property Set

Set Parameters for Your Portal or Application

Webflow

Webflow is a mechanism that controls the flow of a user session by determining which pages are displayed in a browser. The Flow Manager provides the basic infrastructure to support the Webflow functionality. On the WebLogic Personalization Server, Webflow does a simple dispatch to a target destination. When a request comes in from the browser, a destinationdeterminer looks for a dest parameter on the URL and grabs what dest asks for.

The WebLogic Commerce Server extends the Flow Manager with the addition of a Webflow properties file. By setting parameters, you can determine how Webflow reacts to events and which pieces of business logic to execute. When a request comes into the Commerce Server from a browser, Webflow looks for the origin and event parameters in the webflow.properties file and grabs what the properties file asks for.

Accessing Your Application via the Flow Manager

Using Flow Manager with a Web Application

The "portal" portion of the URL is the context name for the Web application as defined in the weblogic properties file:

weblogic.httpd.webApp.portal=C:/WebLogicCommerceServer3.1/server/
webapps/examples/portal/portal.war

Within the portal.war, the web-inf/web.xml file includes <servlet> and <servlet-mapping> entries for the Flow Manager, associating all URL accesses starting with "application/*" with the Flow Manager's class.

Note: To use hot-deployment here, the additional portal code deployments must live in the Web-application directory, so the same context name ("portal") can be used to access them.

In the above URL example, the HTTP request defaults to index.jsp, as defined in the <welcome-file-list> element in the Webapp web.xml file. When the HTTP request is routed to the Flow Manager, it extracts the path information "exampleportal" from the URL and retrieves the property set of the same name from the server (or cache). The "destinationdeterminer" and "destinationhandler" properties are used to instantiate the supporting implementations, and processing proceeds as described above.

Using Flow Manager with a non-Web Application

The URL for Acme Demo Portal accessed as a non-Web application is:

The Flow Manager accesses a non-Web application in almost the same way it accesses a Webapp. There are two primary differences:

Repository

The repository feature allows you to specify a single directory to contain files that otherwise would have to be replicated several times.

The administration pages for components take advantage of the repository feature to store images shared between components. Each HTML reference to an image is wrapped by the ToolsJspBase.fixupRelativeURL method. This method first looks in the path-relative directory for the image specified in the argument. If not found there, the repositorydir specified in the weblogic.properties file (for the wlpsadmin servlet) is searched for the image.

For portals, the default portal (Acme) implementation has its files contained in a folder named repository and specifies a repositorydir=/portal/repository. In an extreme example, a second portal which only differed from Acme in one file, say portal.jsp, would be created by creating a new directory named extremeExample and by adding one file (portal.jsp) to it. All files supporting the extremeExample portal which were not found in its workingdir will be fetched from the repository directory.

For Webapps, the repository directory must reside inside the Webapp context.

HTTP Handling

Both the <pz:div> and <pz:contentselector> tag implementations send HttpRequest and Session information to the Advisor.

The Advisor includes helper classes that transform an HttpRequest and Session into Serializable personalization surrogates for their HTTP counterparts. These surrogates are compatible with the Personalization Rules Service which uses these objects to execute classifier and content selector rules.

Personalization Request Object

Caution: The tag implementations for the <pz:div> and <pz:contentSelector> tags create the Personalization Request surrogate for the HttpRequest before calling the Advisor bean, so JSP developers need not worry about the details of the Request object. Only developers accessing the PersonalizationAdvisor bean directly need to wrap the HttpRequest object explicitly.

In order to avoid confusing results on getProperty method calls, developers need to know the algorithm used in the getProperty method implementation for determining the value of the property requested . When the Request's getProperty method is called (for example, by a rules engine), the system uses the following algorithm to find the property:

Default Request Property Set

For Rules developers to write rules for classifier rules that contain conditions based on an HttpRequest, there must be a property set defined for the HttpRequest. By default, WebLogic Personalization Server ships with a default request property set for the standard HttpRequest properties. Developers adding properties to the request programatically will need to add those properties to the default property set in order for them to be available to the rules editor and service.

The default Request properties include the following

Request Property Name	Associated Request Method
Request Method	request.getMethod()
Request URI	request.getRequestURI()
Request Protocol	request.getProtocol()
Servlet Path	request.getServletPath()
Path Info	request.getPathInfo()
Path Translated	request.getPathTranslated()
Locale	request.getLocale()
Query String	request.getQueryString()
Content Length	request.getContentLength()
Content Type	request.getContentType()
Server Name	request.getServerName()
Server Port	request.getServerPort()
Remote User	request.getRemoteUser()
Remote Address	request.getRemoteAddr()
Remote Host	request.getRemoteHost()
Scheme	request.getAuthType()
Request Property Name	Associated Request Method
Authorization Scheme	request.getScheme()
Context Path	request.getContextPath()
Character Encoding	request.getCharacterEncoding()

Personalization Session Object

The tag implementations for the <pz:div> and <pz:contentselector> tags create the Personalization Session surrogate for the HTTP Session before calling the Advisor bean, so JSP developers need not worry about the details of the HttpSession object. Only developers accessing the PersonalizationAdvisor bean directly need to wrap the HttpSession object explicitly.

Default Session Property Set

For Rules developers to write rules that contain conditions based on an HTTP session, there must be a property set defined for the HTTP session. WebLogic Personalization Server ships with a default session property that contains no values set as a placeholder. There are no default Session property set values. Developers adding properties to the session programatically will need to add those properties to the default property set in order for them to be available to the rules editor and service.

The Personalization Session uses the following algorithm to find a property:

Utilities

JspHelper

JspHelper provides get methods to the JspServiceManager URI, the working directory, the home page, and the current page. It also provides set and get methods for session values and JSP destinations.

Note: Some of these methods assume that the JspServiceManager model is being used.

JspBase

JspBase acts as a base class for all JSP pages that use a JspServiceManager. A wide variety of important methods are provided:

P13NJSPHelper

P13NJspBase provides convenience methods to developers writing JSP pages (including but not limited to portals and portlets) that include personalized content. It provides methods for wrapping HTTP Request and Session objects into their personalization surrogates, and a method for retrieving the current Profile (User, Group, and so on) for an application.

P13NJspBase

P13NJspBase acts as a base class for all personalized JSP pages. This class extends JspBase.

ContentHelper

ContentHelper simplifies the life of the developer using the Content Management component. Methods are provided to get an array of content given a search object, to get the length of a piece of content. Constants for the default Content and Document homes are also provided.

CommercePropertiesHelper

CommercePropertiesHelper allows easy access to the commerce.properties file's properties. Methods are provided to return the values of a given keys as various data types. Also provided is a method to return all keys that start with a given string as a string array. For example, use the method to find all of the keys that start with personalization.portal.

Utilities in commerce.util Package

ExpressionHelper

ExpressionHelper handles dealing with Expression, Criteria, and Logical objects. It contains methods for parsing query strings into Expressions, joining Expressions into Logicals, normalizing Expressions, changing Expressions, Logicals, and Criteria into Strings, and turning Expressions into String trees for debugging purposes.

TypesHelper

TypesHelper provides a set of constants corresponding to the types and operators used in the configurable entity properties. Methods are provided to get string representations of the type names, to determine a type from a java.sql.Type, and to get the list of comparison operators for a certain type.