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

  • Dynamic Flow Determination and Handling

  • Property Set Usage

  • Webflow

  • Accessing Your Application via the Flow Manager

• Repository

• HTTP Handling

• Personalization Request Object

  • Default Request Property Set

• Personalization Session Object

  • Default Session Property Set

• Utilities

  • JspHelper

  • JspBase

  • P13NJspBase

  • ContentHelper

  • CommercePropertiesHelper

• Utilities in commerce.util Package

  • ExpressionHelper

  • TypesHelper

 

---

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 destinationdeterminer and a destinationhandler, 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.

Dynamic Flow Determination and Handling

The Flow Manager allows the determination of page routing to be centralized on the server based on an application's needs. To define properties of your unique application, you will create a property set of type APPLICATION_INIT. (See Property Set Usage.) There are three required values:

• destinationdeterminer - an implementation of the com.beasys.commerce.foundation.flow.DestinationDeterminer interface.

• destinationhandler - an implementation of the com.beasys.commerce.foundation.flow.DestinationHandler interface.

• ttl - how long (in milliseconds) before reloading the application init property set.

How the FlowManager Works

When WebLogic Personalization Server is installed, the Flow Manager servlet is registered with the WebLogic server in the web.xml file:
<servlet>

<servlet-name>application</servlet-name>

<servlet-class>com.beasys.commerce.foundation.flow.
FlowManager</servlet-class>

</servlet>

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.

 

Let's look at the diagram one step at a time, using our example.

1. A client browser makes an HTTP request via a form submission, hyperlink, etc.

   In this example, the request is for the exampleportal at http://localhost:7501/application/exampleportal.

   WebLogic Server (WLS) routes the request to the servlet registered in web.xml with the name "application," which is the Flow Manager.

2. The request is analyzed within the servlet, and the path-info is pulled out. The path-info is the name of the property set to retrieve.

   In our example, the Flow Manager extracts the string "exampleportal" from the URL.

   The property set is retrieved from the database (or the cache).

   Using the SchemaManager, the Flow Manager reads the Application Init property set of that name from the database. The Flow Manager reads the properties named "destinationdeterminer" and "destinationhandler" from the property set and instantiates each class.

   Note: Implementations of these classes are to be provided by the application developer, as needed.

3. The Flow Manager then calls the destinationdeterminer defined in the property set, using the DestinationDeterminer.determineDestination method.

   In this example, the PortalDestinationDeterminer class does not find a DESTINATION_URI in the request and the user is not logged in, so it retrieves the "defaultdest" property and returns the destination string "/portals/example/portal.jsp" to the Flow Manager.

4. The Flow Manager then calls the DestinationHandler.handleDestination method. The destination returned from the previous call is passed on to the destinationhandler defined in the property set.

5. In this example, the portal uses the ServletDestinationHandler which calls the requestDispatcher.forward method, passing execution control to the portal.jsp servlet.

6. Finally, application processing proceeds in the servlet which uses the response object to return data to the client browser.

Property Set Usage

The Property Set Management Administration Tools include a class of property sets called Application Initialization Property Sets. To support non-portal based personalized applications, the Flow Manager uses _DEFAULT_APP_INIT. For portals, the Flow Manager uses the_DEFAULT_PORTAL_INIT property set. For more information, see the topic "_DEFAULT_PORTAL_INIT Property Set" in the chapter "Creating and Managing Portals" in the Guide to Creating Portals and Portlets.

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.

 

destinationdeterminer Property

The destinationdeterminer 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 invoking 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

Time-to-live (ttl) 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

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.

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 Guide to Creating Portals and Portlets.

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

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 WebLogic 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.

The Webflow scheme provides a good example of centralized routing information. It provides an implementation of the destinationdeterminer which uses a properties file resource as a state table to determine the routing destination. For more information about the Webflow implementation in the WebLogic Commerce Server, see the guide Guide to Managing Presentation and Business Logic: Using Webflow and Pipeline.

Accessing Your Application via the Flow Manager

The URL for Acme Demo Portal accessed as a Web application is:
http://localhost:7501/exampleportal

The exampleportal portion of the URL is the context name for the Web application, as defined through the WebLogic console in the config.xml file.

<WebAppComponent Name="exampleportal" Targets="wlcsServer" URI="exampleportal" ServletReloadCheckSecs="300" />

Within the Web application, 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.

In the above URL example, the HTTP request defaults to index.jsp, as defined in the <welcome-file-list> element in the Web application's 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.

 

---

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 property set (for the admin Web application) 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.

 

---

HTTP Handling

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

The tags utilize 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

In order to use HttpRequest parameters in requests to the rules service, they must be wrapped in a Personalization Request object (com.beasys.commerce.axiom.p13n.http.Request) before they can be set on the appropriate AdviceRequest (see the Javadoc API documentation). While the HttpRequest object can be wrapped by directly calling the Personalization Request constructor, it is recommend that developers use the createP13NRequest helper method on P13NJspBase (com.beasys.commerce.axiom.p13n.jsp.P13NJspBase) for this purpose. See the Javadoc API documentation for more information.

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 Advisor 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:

1. The getProperty method first looks in the HttpRequest's attributes for the property.

2. If not found, getProperty looks for the property in the HttpRequest parameters.

3. If not found, getProperty looks in the HTTP headers.

4. If not found, getProperty looks in the Request methods (getContentType, getLocale, etc.).

5. If not found, getProperty uses the scopeName parameter to find a schema entity for a Request schema group name and, if the schema is found, uses the default value in the schema.

6. If not found, getProperty uses the default value passed into the method call.

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 E-Business Control Center and the Rules Manager.

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()
Authorization Scheme	request.getScheme()
Context Path	request.getContextPath()
Character Encoding	request.getCharacterEncoding()

 

---

Personalization Session Object

In order to use HTTP Session parameters in requests to the rules service, they must be wrapped in a Personalization Session object (com.beasys.commerce.axiom.p13n.http.Session) before they can be set on the appropriate AdviceRequest (see the Javadoc API documentation). While the HttpSession object can be wrapped by directly calling the Personalization Session constructor, using the createP13NSession helper method on P13NJspBase (com.beasys.commerce.axiom.p13n.jsp.P13NJspBase)is recommended. See the Javadoc API documentation for more information.

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 E-Business Control Center and the Rules Manager.

The Personalization Session object retrieves the session values from the Service Manager (see "Repository" on page 3-11) for the current thread and clones them so they can be used on a remote machine.

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

1. It first looks in its own cloned HTTP Session properties.

2. If it does not find the property, it locates the schema for the Personalization Session for the scopeName method parameter.

3. If it still does not find the property, it uses the scopeName parameter to find a schema entity for the Session schema group name and, if the schema is found, uses the default value in the schema.

4. If it still does not find the property, it uses the default value passed into the getProperty method call.

 

---

Utilities

You can view more detailed documentation for the utilities listed here in the Javadoc API documentation.

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 Flow Manager. A wide variety of important methods are provided:

• Get methods for the TrafficURI, working directory, repository directory, default destination, RequestURI, default successor, home page, and current page.

• Methods to create URLs, and fixup (fully qualified) URLs.

• Methods to override the destination tag.

• Methods to set and get logged-in status.

• Methods to get, set, and remove session values.

• A method to convert HTML special characters to HTML entities.

• Methods to set the user and successor.

P13NJSPHelper

P13NJspHelper 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.