2
REAPI Overview

The OP (Oracle9iAS Personalization) REAPI (Recommendation Engine Application Programming Interface) enables a Web application written in Java to collect and preprocess data used to build OP models and to request recommendations. The recommendations are returned in real time.

OP also includes the Recommendation Engine Batch API, which returns bulk recommendations.

REAPI was designed to be extensible, to minimize the number of API functions, to be uniform, and to keep the number of arguments to a minimum.

Appendix A contains a complete example of REAPI use.

OP includes a demo program that helps you learn how the API methods work.

REAPI classes and methods are described in detail in the Javadoc in the OP section of the Oracle9i Application Server Documentation Library.

REAPI Prerequisites

Before you can use REAPI methods, OP must be installed and the appropriate tables must be created and populated. If you plan to use existing data, the data must be converted to use the appropriate schema. If you plan to use Hot Picks, you must specify Hot Pick groups, as well as Hot Picks. If you are using one or more taxonomies, they must be properly specified.

If you plan to request recommendations, you must build and deploy an OP package before you request any recommendations. Use the OP Administrative UI to do this.

For detailed information about how to install OP, see the Oracle9i Application Server Installation Guide and the Oracle9iAS Personalization Administrator's Guide. For information about how to create and deploy packages, see Oracle9iAS Personalization User's Guide and the online help for the OP administrative UI.

REAPI Definitions and Concepts

This section describes the collections of methods that make up the REAPI and concepts and terms used in the description of the API.

REAPI End Users (Customers and Visitors)

End users (users of a Web site that uses OP for personalization services) are divided into two groups: customers and visitors. A customer is a registered user, who can be identified by a unique customer ID assigned by the Web application. A visitor is an unregistered user; a visitor is usually assigned a visitor ID by the Web application. A visitor can become a customer by completing registration. End users are specified using the IdentificationData class.

Web Applications and Sessions

Some Web applications are stateful, that is, they maintains the state of the client activities during a certain time period; other Web applications are stateless. Most Web applications that support eCommerce are stateful or sessionful. A client session often starts with a login and ends with either an explicit logout or when the session times out. Oracle Personalization maintains its own session for data mining purpose regardless of whether the application is stateful or stateless. If the application is stateful, the session that OP maintains can be perfectly mapped as the application's session. (For an eCommerce application, the recommendation made to the user is based on the user activities.) If the application does not maintain user session, OP then tracks the user session on itself. In this case, the OP session starts when a particular user ID appears in any REAPI method call the first time, and the session ends when the session times out, that is, when the user ID remains inactive for a preset time period.

In summary, the Web application that calls REAPI can be either of the following:

• sessionful (stateful), that is, it creates a session for each user visit to the Web site

• sessionless (stateless), that is, it does not create such a session

OP is always sessionful; it creates a session even if the Web application does not.

During the OP session, the Web application can collect data and/or request recommendations.

REAPI Sessionful Web Applications

If the Web application is sessionful, OP will map its session to the application session. To create a sessionful application, use one of the following methods:

• createCustomerSession to create a session for a customer (registered user)

• createVisitorSession to create a session for a visitors (a user who isn't registered)

The Web application then uses the createSessionful() method of the class IdentificationData to create identification data used during the session.

REAPI Sessionless Web Applications

If the Web application is sessionless, the recommendation engine (RE) will maintain OP sessions by itself. An OP session will be created when the first REAPI method (either data collection or recommendation request) issued for a given customerId. The RE will track user activity until the session is timed out, that is, until the given customerId is inactive for a specified period.

The Web application uses the createSessionless() method of the class IdentificationData to create user identification for the session.

REAPI Data Collection

OP supports collecting several kinds of data: demographic data, purchasing, rating, and navigation data. The Web application decides what kind of data to collect.

Note: Ratings in OP are in "ascending order of goodness", that is, the higher the rating, the more the user prefers the item. Low rated items are items that the user does not prefer. OP algorithms use these assumptions, so it is important that ratings are in ascending order of goodness.

Data for both visitors and customers can be either persisted (stored in the database) or not. Data is collected in an RE and is persisted in the mining table repository (MTR) database. A configuration parameter specifies whether or not to persist data. For more information about what data is persisted and when, see the discussion of data synchronization in the Oracle9iAS Personalization Administrator's Guide.

Data collection makes it possible to generate recommendations based on user activity during the current session as well as historical data.

REAPI Recommendations

For both visitors and customers, recommendations are based on two kinds of data:

• Historical data, which is stored in the database and retrieved at the beginning of the current session

• Data collected during the current session

REAPI Hot Picks

On some e-commerce sites, vendors promote certain products called "hot picks"; the hot picks might, for example, be this week's specials. The hot pick items are grouped into Hot Pick Groups. The hot pick items and groups are specified by the OP administrator in the Mining Table Repository (MTR); each hot picks group is identified by a (long) integer.

Before Using REAPI

Before you can use REAPI, the following must be true:

• A recommendation engine farm containing at least one recommendation engine must exist.

• A package must have been successfully deployed in the recommendation engine farm.

Oracle9iAS Personalization User's Guide and the online help for the OP Administrative UI explain how to perform these steps.

Some REAPI methods collect data in the recommendation engine (RE), which resides in Oracle9i database; others retrieve recommendations.

You can then either collect data or get recommendations. You cannot get recommendations until there is an existing deployed package, which is created using the OP Administrative UI. You cannot create a package until there is some data available; this data can either be collected using the REAPI or converted from existing data collected by your Web application and stored in an Oracle database.

When you design an OP application, you must decide if there should be more than one RE and, if there are several REs, how to use them. For a discussion of the design considerations, see "Recommendation Engine Usage" in Chapter 5.

Recommendations may want to take income level (salary) into consideration; for example, you may want to recommend items that the user can afford to buy. If the users of the Web site live in several countries (for example, the Web site sells items in Japan and India), see "Handling Multiple Currencies" in Chapter 5.

REAPI Demo Program

OP includes REAPI Demo that illustrates the use of many of the REAPI methods. This sample program can be used to learn about REAPI calls and can also be used to verify that OP is correctly installed.

After you have installed OP, start REAPI Demo by opening the following URL in Netscape or Internet Explorer:

   http://server/redemo/

where server is the name of the system where Oracle9iAS is installed. The REAPI test site is displayed.

To view the source code for the OP REAPI Demo, click "View Source Code."

For information about how run the demo, see the Oracle9iAS Personalization User's Guide. There are also some examples of how to perform typical tasks using REAPI in Chapter 5 of this manual and a complete example using all REAPI functionality in Appendix A.

Creating REProxyRT Objects

Before any recommendation or data collection requests can be processed using REAPI methods, at least one REProxyRT object that connects to designated RE must be created.

In a Web application environment, it is better to create all required proxies during the initialization stage. This is a safe approach, because the application does not have to process any recommendation requests after the application is initialized successfully.

If it is not possible to create all required proxies during initialization, the proxies may be created when the very first recommendation request is being processed. In this case, the application code must handle race conditions properly when numerous requests come up simultaneously. If numerous recommendation requests came up before the proxy exists, only one of the requests will create the proxy object because creating a proxy is a synchronous process. Since it may take a few hundred milliseconds to create a proxy object, many requests may be held up during the time. Thus, a racing situation may occur. Although REAPI is multi-thread safe, such a racing situation will not cause any problem for REProxyRT. However, it may cause exceptions for the application.

See Chapter 5 for more information about proxies.

Starting an REAPI Session

If the Web application is sessionful, it must start a session. The Web application must take care to specify a unique session ID for each application session. For an example of how to do this, see Chapter 5.

If the Web application is sessionless, it does not have to start a session. (In this case OP will start an internal session for a given user when the Web application makes the first REAPI call.)

OP starts a session for each user, as defined by the user ID provided by the Web application. If two people are using a site at the same time and they both use the same user ID (and the application does not distinguish between different sessions), then OP assigns the same session ID to both users. OP treats them as a single user. After the OP session times out, OP assigns a new session ID when the user logs in again.

Sessionful and sessionless applications get recommendations on behalf of a user. User IDs must be unique.

Creating Instances of REAPI Supporting Classes

To use the REAPI, you must create instances of the objects used by the API method signatures. Use the REAPI supporting classes, described in Chapter 3, to create these instances. It is always necessary, for example, to create an IdentificationData object. The following classes are frequently used in REAPI signatures:

• IdentificationData

• FilteringSettings

• TuningSettings

• Item

• DataItem

• Recommendation

• Recommendation Content

For examples, see Chapter 5 and the complete example in Appendix A.

Collecting Data for REAPI Recommendations

OP generates recommendations based on data describing past and/or current user behavior.

If the Web application has user data stored in an Oracle table, the data must be transformed and stored in the Mining Table Repository (MTR) before it can be used to generate recommendations.

A Web application can also collect data during the current session. This data can be used to make recommendations during the current session and it can be stored to make recommendations in future sessions.

Use the following methods to collect and manage data during the current session:

   addItem();

   addItems();

   removeItem();

   removeItems();

These methods add information to or remove information from the OP Recommendation Engine (RE) and its cache for a specified OP internal session ID. The session ID is stored in the IdentificationData passed in the REAPI method.

OP Data Caching

When one of the OP data collection methods (addItem() or addItems()) is called, the user profile data is first saved in a buffer (the Data Collection Cache) on the Application Server. The data collection cache is created as part of the initialization of an REProxy object. The size of the data buffer is custom-configurable and is specified by the input parameter cacheSize of the method REProxyManager.createProxy(). The data saved in the buffer is periodically saved (archived) in the database. The interval of archive is set by another the input parameter interval of the same method. The data collection cache consists of two identical buffers; when one buffer is being archived, the other is used for saving the incoming data. Thus the data collection operation runs without interruption.

Getting REAPI Recommendations

To get a recommendation, the Web application calls one of the following recommendation methods:

• crossSellForItemFromHotPicks()

• crossSellForItemsFromHotPicks()

• rateItem()

• rateItems()

• recommendBottomItems()

• recommendCrossSellForItem()

• recommendCrossSellForItems()

• recommendFromHotPicks()

• recommendTopItems()

• selectFromHotPicks()

These methods are used to get recommendations for either visitors or customers.

How REAPI Creates Recommendations

OP uses rule tables stored in the RE cache to calculate the recommendations requested by the methods listed above. The specific rule table used depends upon the REAPI method made. In general, the antecedents of the rules are matched against the data in cache (both historical and current session data) and the probabilities of the various consequents are computed. These items are then ordered by probability, and numberOfItems (an API argument) items are returned.

If there is enough memory in the RE database, the RE caches all rules associated with a particular package deployed from the MTR to the RE, not just the most recently used rules.

Scoring for Visitors:

For visitors, only current session data is used. Usually only navigational data (click stream) is persisted for visitors, but if the Web application persists other kinds of data for visitors, that data will also be used for model building. (OP builds a model when it creates a package.) The scoring of these different methods uses only the data stored in the RE cache by addItem() methods.

Scoring for Customers:

For customers, the scoring is the same as for visitors. For customers, historical data can also be used for scoring.

The OP Mining Table Repository (MTR) contains historical rating, transactional data, and navigational data stored in both detailed and aggregated formats. The MTR also contains demographic data. When scoring for customers, the RE retrieves the demographic data and the aggregated version of the other data source types.

Making REAPI Recommendations

REAPI methods that make recommendations return the recommendations to the Web application. The Web application then decides which recommendations to pass to the user.

Closing an REAPI Session

A sessionful Web application should use closeSession() to close the OP session. If there is no explicit closeSession() method, OP automatically closes the session when it times out.

In a sessionless Web application, the OP session closes when it times out.

For either sessionless or sessionful Web applications, the time-out period is specified as a configuration parameter.

See the Oracle9iAS Personalization Administrator's Guide for information about configuration parameters.

Removing REProxyRT Objects

If you wish to destroy proxies programmatically you can use one of the following methods:

• destroyProxy(), which destroys one name proxy

• destroyAllProxies(), which destroys all existing proxies.

Both methods forcefully remove proxies regardless of their active status. See detailed discussion in Chapter 5 for different usage models.