A
REAPI Examples and Usage

This appendix provides examples of REAPI use. In some instances, we provide code snippets; in others, we describe an approach for performing certain kinds of tasks using OP.

REAPI Demo

OP includes REAPI Demo, a sample program that illustrates the use of many of the REAPI methods. This sample program can be used to learn about REAPI calls and can also 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 to install and run the demo, see Getting Started with Oracle9iAS Personalization.

REAPI Basic Usage

The REProxy methods described in Chapter 3 permit you to instrument your Web site. To use REAPI calls, you must perform the following steps:

1. Get an REProxy object.

2. Use the proxy instance as required in REAPI calls. The outline that your program should follow depends on whether your Web application is sessionful or sessionless.

3. Destroy the proxy instance when you are done with it. You may also want to destroy all proxy objects.

Create an REProxy Object

This section illustrates basic REProxy usage; for more information about REProxy and other ways to use it see, "REProxyManager Interaction with JVM" and "Using Multiple Instances of REProxy", later in this appendix.

The following code fragment creates an object name proxy: You use this object to perform REAPI calls. Note that you must specify the username and password for the RE schema.

    final String proxyName = "RE1";
    final String dbURL = "jdbc.oracle.thin:@DBServer.myshop.com:1521:DB1";
    final String user = "myself";
    final String passWd = "secret";
    final int cacheSize = 2048;        // 2 mbytes
    final int interval = 10000;    // 10 seconds
    REProxy proxy;
    ...

    try {
      proxy = REProxyManager.createProxy(proxyName,
                                         dbURL,
                                         user,
                                         passWd,
                                         cacheSixe,
                                         interval);
      ...
    } catch (Exception e) {
        // exception handling here 
    }

Use the Proxy

After you've created a REProxy object and gotten an instance of it, you use the proxy to specify REAPI calls, as, for example,

proxy.closeSession();

The sequence of calls depends on whether the application is sessionful or sessionless; see "Sessionful Web Application Outline" or "Sessionless Web Application Outline" later in this appendix for details.

Destroy the Proxy

When you are finished with the proxy instance, you should destroy it. Failure to destroy proxy instances can result in excess usage of system resources and even loss of data.

      // after it's all done
      REProxyManager.destroyProxy(proxyName);

Destroy All Proxy Objects

To destroy all proxy objects from the pool, use destroyAllProxies().

Sessionful Web Application Outline

The following outlines the required steps in the required order for a sessionful Web application (an application that starts a session for each customer).

1. Create an REProxy object as described in "Create an REProxy Object", earlier in this appendix. You need to know the user name and password for the RE schema.

2. Create a customer session or a visitor session

   proxy.createCustomerSession(userID, appSessionID); //customer session
   
   proxy.createVisitorSession(userID, appSessionID); //visitor session
   
   

3. Get identification data.

   idData = IdentificationData.createSessionful(appSessionID);
   
   

4. Call REAPI methods: for example,

   /*Set input parameters.; see Chapter 2 for details. */
   int nRec=10;
   TuningSettings tune = new TuningSettings(Enum.DataSourec.NAVIGATION,
                          Enum.InterestDimension.NAVIGATION,
                          Enum.PersonalizationIndex.HIGH,
                          Enum.ProfileDataBalance.BALANCED,
                          Enum.ProfileUsage.EXCLUDE);
   long [] catList = {1, 2, 3, 4};
   FilteringSettings filters = new FilteringSettings();
   filters.setItemFiltering(1, catList);
   RecommendationContent rContent = new RecommendationContent (
                                        Enum.Sorting.ASCENDING);
   /*Get a recommendation. */
   try {
        RecommendationList rList = proxy.recommendTopItems(idData,
                                    nRec, tune, filters, rContent);
   /* Parse the results and pass recommendations to the user*/
   
   

5. Make other REAPI calls as required.

6. Close the session.

   proxy.closeSession();
   
   

7. Destroy the proxy.

   REProxyManager.destroyProxy(proxy); //destroy proxy when done
   

Sessionless Web Application Outline

The following outlines the required steps in the required order for a sessionless Web application (an application that does not start a session for each customer). Note that sessionless applications close when they time out.

1. Create an REProxy object as described in "Create an REProxy Object", earlier in this appendix. You need to know the user name and password for the RE schema.

2. Get identification data.

   idData = IdentificationData.createSessionless(customerID);
   
   

3. Call REAPI methods: for example,

   /*Set input parameters; see Chapter 2 for details.*/
   int nRec=10;
   TuningSettings tune = new TuningSettings(Enum.DataSourec.NAVIGATION,
                          Enum.InterestDimension.NAVIGATION,
                          Enum.PersonalizationIndex.HIGH,
                          Enum.ProfileDataBalance.BALANCED,
                          Enum.ProfileUsage.EXCLUDE);
   long [] catList = {1, 2, 3, 4};
   FilteringSettings filters = new FilteringSettings();
   filters.setItemFiltering(1, catList);
   RecommendationContent rContent = new RecommendationContent (
                                        Enum.Sortinh.ASCENDING);
   /*Get a recommendation. */
   try {
        RecommendationList rList = proxy.recommendTopItems(idData,
                                    nRec, tune, filters, rContent);
   /* Parse the results and pass recommendations to the user*/
   
   

4. Make other REAPI calls as required.

5. Destroy the proxy.

   REProxyManager.destroyProxy(proxy); //destroy proxy when done
   

REProxyManager Interaction with JVM

REProxyManager is a singleton implementation, that is, only one instance of the REProxyManager class is created in a give JVM instance and the class is automatically loaded in the JVM instance. This behavior has implications about how your program behaves. The behavior is different depending on whether your application is a standalone Java program or if it is a servelet.

Standalone Java Applications

Suppose that you create a standalone Java application using REAPI calls that you execute from the command line with a command such as

java myapplication.class

Such an application has the following characteristics:

• It runs in a separate JVM instance.

• The REProxyManager instance is automatically loaded into the JVM instance.

• After the application finishes executing, the JVM instance goes away.

If you do not destroy the proxy before the program exits, the REProxy objects remain in memory; they cannot be accessed because the JVM instance that created them no longer exists.

To avoid memory leaks, you must destroy the proxy before the program ends.

Servelets

If REAPI calls are used in a servelet, REProxyManager continues to exist as long as the JServ instance continues to exist; REProxy objects are not removed. To conserve resources, you should destroy proxy objects when you are done using them.

Using Multiple Instances of REProxy

REProxyManager manages a pool of one or more proxies. This section illustrates several ways to use multiple proxies:

• Initialization fail safe

• Ensuring that REAPI server is not interrupted

• Load balancing

Initialization Fail Safe

The following code fragment illustrates how you might use two RE to prevent utilization failure. This code assumes that the schema for normal recommendation service is named "RE"; if "RE" fails, you will use a backup RE schema, named "RE_BACKUP".

  REProxy initProxy(...)
  {
    REProxy proxy;

    // initialization
    try {
      if ((proxy = REProxyManager.getProxy("RE")) == null)
        proxy = REProxyManager.createProxy("RE",
                                           dbURL,
                                           username,
                                           passWd,
                                           cacheSize,
                                           interval);
    } catch (REProxyInitException rie) {
      proxy = REProxyManager.createProxy("RE_BACKUP",
                                           dbURL1,
                                           username1,
                                           passWd1,
                                           cacheSize,
                                           interval);
    }
    return proxy;
  }

Uninterrupted REAPI Service

The following code fragment illustrates how to guarantee that the recommendation service does not fail when the regular RE server fails. The code implements the class NeverFail for this purpose.

 class NeverFail() {
    REProxy re1;
    REProxy re2;

    void initProxies() {
      try {
        if ((re1 = REProxyManager.getProxy("RE1")) == null)
         String dbURL1="jdbc:oracle:thin:@db1.mycorp.com:1521:orc1";
         re1 = REProxyManager.createProxy("RE1",
                                           dbURL1,
                                          "user1",
                                          "pw1",
                                          2048,
                                          10000);
        if ((re2 = REProxyManager.getProxy("RE2")) == null)
          String dbURL2="jdbc:oracle:thin:@db2.mycorp.com:1521:orc2"; 
            re2 = REProxyManager.createProxy("RE2",
                                          dbURL2,
                                          "user2",
                                          "pw2",
                                          2048,
                                          10000);
      } catch (REProxyInitException rie) {
        // exception handling
      }
    }

    RecommendationList getRecommendation() {
      RecommendationList rList;

      // initialize input
      ....
      try {
        rList = re1.recommendTopItems(...);
      } catch (Exception e) {
        rList = re2.recommendTopItems(...);
        return rList;
      }
      return rList;
    }
  }

Load Balancing

The following code fragment illustrates a simple way to do load balancing so that not all customers are handled by the same RE. This example assumes that customers with odd IDs are processed using RE1 and those with even IDs are processed using RE2, a different RE. To accomplish this, first create two different proxies re1 and re2, and then code getRecommendation() as follows:

 RecommendationList getRecommendation() {
      RecommendationList rList;

      // initialize input
      ....
      try {
        if ((idData.getUserID() % 2) == 1)
          rList = re1.recommendTopItems(...);
        else
          rList = re2.recommendTopItems(...);
      } catch (Exception e) {
        // exception handling
        ......
      }
      return rList;
    }

Extracting Individual Recommendations

Use the getAttributes method of the "Recommendation" class rather than attempting to extract the individual recommendations from the array.

Handling Multiple Currencies

OP stores currency data in the demographic table (for example, someone's income) as numbers; that is, OP does not store any kind of label. Both ten dollars (US) and ten pounds sterling (UK) are stored as "10".

There are several ways to ensure that currency data is interpreted correctly; the solution that you pick for your application depends on how your application uses currency data.

• Include a country code in customer demographics.

  This solution allows the country to be taken into account, but it does not closely associate the value with the country.

• Convert all currencies to a common currency such as Euros or United States dollars.

  This solution permits you to compare individual currency values in a meaningful way (10 pounds sterling is more than $10 US) but does not permit you preserve the difference between data such as a salary of $30,000 US in the US, versus the same $30,000 US salary in Brazil. You need such information if, for example, you want to recommend items to highly remunerated individuals in both the US and Brazil; the salary in US dollars of highly remunerated individuals will vary considerably from country to country.

  This approach requires that you preprocess the data outside of OP before OP creates recommendations.

• Bin currency values according to the mean to get relative values that can be compared across countries.

  This solution would permit you, for example, to determine the highly remunerated individuals for a given country, but it requires that you determine and maintain the bin boundaries appropriately.

  This approach requires that you preprocess the data outside of OP before OP creates recommendations.

Recommendation Engine Usage

Oracle9iAS Personalization requires at least one recommendation engine (RE) in at least one recommendation engine farm. In general, you will want to use more than one RE to get satisfactory recommendation performance. Most applications will use multiple REs on different machines and subsequently different database instances. See "Load Balancing" earlier in this appendix for an example of how you might code one of these solutions.

Typically, for a given application, these REs will belong to the same RE farm. If a physical system has multiple processors, and the processors can be leveraged effectively by the database, the number of REs required for a given number of users can be reduced, perhaps even to one. See the administration guide for more information.

If your application has more than one RE available for use, it must determine which one to use. Here are three possible solutions:

1. A given user of the Web site (either a visitor or a customer) is always handled by the same JServ instance and that JServ instance is configured to use one RE at all times. The application must route users to "their" JServs and configure JServs to contact specific REs. The REProxy class takes configuration arguments to specify which RE to connect to. The application must determine how to get these configuration arguments, either from a jserv.properties file, or by being explicitly coded in the Web applications, or by some other means.

2. Allow any JServ to handle any customer. This requires that a customer be "hashed" to a specific RE. It is important that the same customer be routed to the same RE, at least within the session, since data is cached for the user's session in the RE.

3. Provide a fail-over mechanism in the application to allow a different RE to be contacted in the event the primary RE for a given customer cannot be contacted. This can be applied in addition to either solutions 1 or 2 above. In this case, the application specifies the primary RE and the backup RE (or the multiple backup REs) and controls the logic to switch between REs. The same user session may not always be routed to the same RE; however, the ability to get some kind of recommendation will be maintained. Note that it may not be necessary to implement such a solution, especially in a reasonably robust environment.

Using Demographic Data

The schema of the MTR_CUSTOMER table consists of 50 generic attributes that can be mapped to any column in the site database. In order to support all different data types, all attributes are of type VARCHAR. Therefore, the mapped columns should be converted to strings. In this release of OP, these mapped columns are treated as categorical or numeric only. If any of the mapped columns is a DATE attribute, it should be converted to a number using the TO_NUMBER function. The converted values can then be binned just like any other attribute by specifying the bin boundaries.

There is binning for demographic data. The attributes that are binned can be of type boolean. In OP, the bin numbers are represented internally as integers, but the actual values are passed back to the calling applications. That is, the Web application passes in the actual values and gets back actual values.

Handling Time-Based Items

For certain items, such as airline tickets, the price depends on when the item is purchased. For example, an airline ticket for a Boston to London flight has one price if it purchased 6 months before the date of the flight and a different price if it is purchased two days before the date of the flight.

If the Web application assigns the same item ID to all tickets for the same trip, regardless of when they are purchased, then the items should have different item types, such as "6-month advance", "2-day advance", etc. Alternatively, the application could define taxonomies on the items and get recommendations on the categories.

If the application assigns different item IDs to the same flight purchased at different times (so that a ticket purchased 6 months before the flight has a different ID from a ticket for the same flight purchased 2 days before the flight), all tickets can have the same item type. In this case recommending item IDs may not be appropriate; therefore, the application should define a taxonomy and request recommendations on the categories.