|
Oracle® Application Server Personalization Programmer's Guide
10g Release 2 (10.1.2) B14051-01 |
|
 Previous |
 Next |
|
Oracle® Application Server Personalization Programmer's Guide
10g Release 2 (10.1.2) B14051-01 |
|
|
Previous |
Next |
This chapter 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 OracleAS Personalization.
OracleAS Personalization 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 OracleAS Personalization is correctly installed.
After you have installed OracleAS Personalization, 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 Oracle Application Server is installed. The REAPI test site is displayed.
To view the source code for the OracleAS Personalization REAPI Demo, click "View Source Code."
For information about how to install and run the demo, see the Oracle Application Server Personalization User's Guide.
The REProxy methods described in Chapter 4 permit you to instrument your Web site. To use REAPI calls, you must perform the following steps:
Get an REProxy object.
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.
This section illustrates basic REProxy usage; for more information about REProxy and other ways to use it, see Section 5.5, "REProxyManager Interaction with JVM" and Section 5.6, "Using Multiple Instances of REProxy" later in this chapter.
The following code fragment creates an object named 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
}
After you've created an 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 Section 5.3, "Sessionful Web Application Outline" or Section 5.4, "Sessionless Web Application Outline" later in this chapter for details.
The following outlines the required steps in the required order for a sessionful Web application (an application that starts a session for each customer).
Create an REProxy object as described in Section 5.2.1, "Create an REProxy Object" earlier in this chapter. You need to know the user name and password for the RE schema. If the proxy already exists, call getProxy.
Create a customer session or a visitor session.
proxy.createCustomerSession(userID, appSessionID); //customer session
proxy.createVisitorSession(userID, appSessionID); //visitor session
Get identification data.
idData = IdentificationData.createSessionful(appSessionID);
Call REAPI methods: for example:
/*Set input parameters */
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*/
Make other REAPI calls as required.
Close the session.
proxy.closeSession();
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.
Create an REProxy object as described in Section 5.2.1, "Create an REProxy Object" earlier in this chapter. You need to know the user name and password for the RE schema. If the proxy already exists, call getProxy.
Get identification data.
idData = IdentificationData.createSessionless(customerID);
Call REAPI methods. See the example in the similar step in the previous section (Section 5.3, "Sessionful Web Application Outline").
Make other REAPI calls as required.
REProxyManager is a singleton implementation, that is, only one instance of the REProxyManager class is created in a given JVM instance and the class is automatically loaded in the JVM instance. This behavior has implications about the way your program behaves. The behavior is different depending on whether your application is a standalone Java program or a Java server-side module. The same principle may apply but different usage models for proxy management should be considered
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.
If REAPI is called from Java server-side modules, such as servlets or Java Server Pages (JSPs), the REProxyManager class is loaded on the Oracle Application Server where the modules reside.
The Web application that owns and uses the Java modules often starts when the server boots up, and does not close until the server shuts down. In this circumstance, you may create the proxies during the initiation of the Web application or as soon as the first RE request is being processed, but never have to worry about destroying the proxy. As long as the Web application is up and running, the proxy will be used to serve ongoing recommendation requests.
Creation of a proxy is time consuming (a few hundred milliseconds on a Sun E450 server). It is therefore more efficient to never destroy a proxy until the server shuts down, for example, when the system administrator needs to bring the Web application down for maintenance purposes.
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
The following code fragment illustrates the way you might use two REs 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;
}
The following code fragment illustrates the way 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;
}
}
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 a different RE, RE2. To accomplish this, first create two different proxies, RE1 and RE2, and then call 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;
}
To extract individual recommendations, use the getAttributes method of the Recommendation class rather than attempt to extract the individual recommendations from the array. The following code shows this usage:
protected void printRecList(RecommendationList recList, String ID)
{
if (recList.getNumberOfRecommendations() <= 0 )
{
System.out.println("No Recommendation Returned");
}
else {
System.out.println("The Following " + recList.getNumberOfRecommendations() +
" Recommendations were returned for user " + ID);
System.out.println("ItemID\t\tItemType\t\tPrediction");
StringBuffer id = new StringBuffer(30);
StringBuffer predctn = new StringBuffer(30);
StringBuffer typ = new StringBuffer(30);
for ( int i = 0; i < recList.getNumberOfRecommendations(); i++ )
{
Recommendation reck = recList.getRecommendation(i);
ItemDetailData[] idd = reck.getAttributes();
for (int j = 0; j < idd.length; j++)
{
if (idd[j].getAtribute() == Enum.RecommendationAttribute.ID){
id.replace(0,idd[j].getValue().length(),idd[j].getValue());}
if (idd[j].getAtribute() == Enum.RecommendationAttribute.PREDICTION){
predctn.replace(0,idd[j].getValue().length(),idd[j].getValue());}
if (idd[j].getAtribute() == Enum.RecommendationAttribute.TYPE){
typ.replace(0,idd[j].getValue().length(),idd[j].getValue());}
}
System.out.println(id + "\t\t" + typ + "\t\t" + predctn);
}
}
}
OracleAS Personalization stores currency data in the demographic table (for example, someone's income) as numbers; that is, OracleAS Personalization 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 OracleAS Personalization before OracleAS Personalization 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 OracleAS Personalization before OracleAS Personalization creates recommendations.
OracleAS 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 Section 5.6.3, "Load Balancing", earlier in this chapter 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 administrator's 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:
A given user of the Web site (either a visitor or a customer) is always handled by the same Oracle Application Server Containers for J2EE (OC4J) instance and that OC4J instance is configured to use one RE at all times. The application must route users to "their" OC4J instance and configure OC4J instances 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 an OC4J.properties file, or by being explicitly coded in the Web applications, or by some other means.
Allow any OC4J instance 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.
Provide a failover 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 solution 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.
Demographic data that is used to produce recommendations is populated into the MTR_CUSTOMER table. This table includes several predefined fields and 50 fields for generic attributes. The first 25 of these attributes are of type VARCHAR, and the second 25 attributes are of type NUMBER. These generic attributes can be populated or mapped to any table column. The generic attributes are treated as categorical or numerical data only. If a mapped column is a DATE type, it should be converted to a NUMBER type using the TO_NUMBER function.
To improve model performance, OracleAS Personalization MTR data should be binned to reduce attribute cardinality, that is, the number of distinct values in a column. This is particularly necessary for numeric columns where there can be many values along a continuous range. The binning parameters are specified in the MTR_BIN_BOUNDARY table.
As a categorical binning example, consider the case where the two-letter United States state abbreviation is added as one of the generic attributes. The entire United States can be divided into four main regions: western states, mid-western states, southern states, and eastern states. These regions can correspond to bin numbers of 1, 2, 3, and 4, respectively. Hence, bin 1 contains CA, OR, WA, AZ, and other western states. Bin 3 contains TX, MS, LA, and the other southern states. Bin 2 contains the mid-western states, and bin 4 contains the eastern states.
As a numerical binning example, consider the attribute "age" where the values may range from 1 to 100. We may define bin 1 as ages 1 through 25, bin 2 as ages 26 through 50, and bin 3 as ages 51 through 100.
|
See Also: The OracleAS Personalization schemas chapter in the Oracle Application Server Personalization Administrator's Guide for MTR_BIN_BOUNDARY details. |
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", for example. 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 an ID different 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.
