2
RE Batch API Supporting Classes

This chapter describes the supporting classes for the REBatchProxy class. These classes are used to create instances of the objects used by the methods described in Chapter 3. You may be able to create one instance of many of these classes and use that one instance as an argument for several calls.

Note: Except for Location, these supporting classes are the same as the ones that are used by the OP real-time (REAPI) recommendations.

Before you issue any of the recommendation methods described in Chapter 3, you must generate appropriate FilteringSettings, TuningSettings, and Location instances.

All methods described in this chapter are public.

The supporting classes are divided into two categories:

• EnumType interfaces

• Other supporting classes

Ratings in OP

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.

Location of Classes

The following frequently used classes are in the oracle.dmt.re.base subdirectory:

• DataItem

• Enum

• FilteringSettings

• TuningSettings

For example, to use the Enum interfaces, you must include the following statement in your Java program:

import oracle.dmt.op.re.base.Enum;

EnumType Interfaces

Many of the RE Batch API methods reference attributes that can take on a finite number of values. The interface Enum is used to implement the base class for these "enumerations."

The Enum interface has a nested EnumType class with the following general methods:

int getId();

String toString();

String getName();

boolean isEqual(EnumType);

The following interfaces extend EnumType:

• CategoryMembership

• DataSource

• InterestDimension

• PersonalizationIndex

• ProfileDataBalance

• ProfileUsage

• Sorting

CategoryMembership Interface

CategoryMembershipType is implemented as:

• CategoryMembershipType (a class that extends EnumType)

• CategoryMembership (an interface)

The class CategoryMembership has the following methods:

CategoryMemberShipType getType(String name);

CategoryMemberShipType getType(int);

CategoryMembership specifies how categories in a list of categories should be applied for filtering. For example, Enum.CategoryMembership.EXCLUDE_ITEMS specifies that items from the category should be excluded from the category list. For details, see FilteringSettings later in this chapter.

CategoryMembership takes on the following values:

• Enum.CategoryMembership.EXCLUDE_ITEMS

• Enum.CategoryMembership.INCLUDE_ITEMS

• Enum.CategoryMembership.EXCLUDE_CATEGORIES

• Enum.CategoryMembership.INCLUDE_CATEGORIES

• Enum.CategoryMembership.LEVEL

• Enum.CategoryMembership.SUBTREE_ITEMS

• Enum.CategoryMembership.SUBTREE_CATEGORIES

• Enum.CategoryMembership.ALL_ITEMS

• Enum.CategoryMembership.ALL_CATEGORIES

The following statement assigns Enum.CategoryMembership.LEVEL to the variable myEnum:

CategoryMembershipType myEnum = Enum.CategoryMembership.LEVEL;

DataSource Interface

DataSource is implemented as:

• DataSourceType (a class that extends EnumType)

• DataSource (an interface)

The class DataSourceType has the following methods:

DataSourceType getType(String name);

DataSourceType getType(int);

DataSource specifies the type of data that is used when OP performs certain operations. For example, Enum.DataSource.DEMOGRAPHIC specifies that demographic data. The method DataItem, described later in this chapter, uses DataSource. Note that a given method may not support all values of DataSource. For details, see the description of the method in Chapter 3.

DataSource takes on the following values:

• Enum.DataSource.DEMOGRAPHIC

• Enum.DataSource.PURCHASING

• Enum.DataSource.RATING

• Enum.DataSource.NAVIGATION

• Enum.DataSource.ALL

The following statement assigns Enum.DataSource.ALL to the variable myEnum:

DataSourceType myEnum = Enum.DataSource.ALL;

InterestDimension Interface

InterestDimension is implemented as:

• InterestDimensionType (a class that extends EnumType)

• InterestDimension (an interface)

The class InterestDimensionType has the following methods:

InterestDimensionType getType(String name);

InterestDimensionType getType(int);

InterestDimension indicates the type of interest that the user of the web site has in a given item. NAVIGATION indicates that the user is interested in the items. PURCHASING indicates that the user would like to purchase the items. RATING indicates that the user likes the items. For more information, see the description of the TuningSettings method later in this chapter.

InterestDimension takes on the following values:

• Enum.InterestDimension.NAVIGATION

• Enum.InterestDimension.PURCHASING

• Enum.InterestDimension.RATING

The following statement assigns Enum.InterestDimension.PURCHASING to the variable myEnum:

InterestDimensionType myEnum = Enum.InterestDimension.PURCHASING;

PersonalizationIndex Interface

PersonalizationIndex is implemented as:

• PersonalizationIndexType (a class that extends EnumType)

• PersonalizationIndex (an interface)

The class PersonalizationIndexType has the following methods:

PersonalizationIndexType getType(String name);

PersonalizationIndexType getType(int);

PersonalizationIndex specifies how "unusual" the recommendations returned will be. For example, LOW specifies not unusual. For more information, see the description of the TuningSettings method later in this chapter.

PersonalizationIndex takes on the following values:

• Enum.PersonalizationIndex.LOW

• Enum.PersonalizationIndex.MEDIUM

• Enum.PersonalizationIndex.HIGH

The following statement assigns Enum.PersonalizationIndex.LOW to the variable myEnum:

PersonalizationIndexType myEnum = Enum.PersonalizationIndex.LOW;

ProfileDataBalance Interface

ProfileDataBalance is implemented as:

• ProfileDataBalanceType (a class that extends EnumType)

• ProfileDataBalance (an interface)

The class ProfileDataBalanceType has the following methods:

ProfileDataBalanceType getType(String name);

ProfileDataBalanceType getType(int);

ProfileDataBalance specifies whether to take data from the current session or from history or to balance data between data from the current session and history when making recommendations. For more information, see the description of the TuningSettings method later in this chapter.

ProfileDataBalance takes on the following values:

• Enum.ProfileDataBalance.HISTORY

  Note: The only value of profile data balance that makes sense for bulk recommendations is Enum.ProfileDataBalance.HISTORY. You must specify this value. (There is no current session data available.)

The following statement assigns Enum.ProfileDataBalance.HISTORY to the variable myEnum:

ProfileDataBalanceType myEnum = Enum.ProfileDataBalance.HISTORY;

ProfileUsage Interface

ProfileUsage is implemented as:

• ProfileUsageType (a class that extends EnumType)

• ProfileUsage (an interface)

The class ProfileUsageType has the following methods:

ProfileUsageType getType(String name);

ProfileUsageType getType(int);

ProfileUsage specifies whether the recommendation list can include or exclude items in a customer's profile. For more information, see the description of TuningSettings later in this chapter.

ProfileUsage takes on the following values:

• Enum.ProfileUsage.INCLUDE

• Enum.ProfileUsage.EXCLUDE

The following statement assigns Enum.ProfileUsage.INCLUDE to the variable myEnum:

ProfileUsageType myEnum = Enum.ProfileUsage.INCLUDE;

Sorting Interface

Sorting is implemented as:

• SortingType (a class that extends EnumType)

• Sorting (an interface)

The class SortingType has the following methods:

SortingType getType(String name);

SortingType getType(int);

Sorting indicates whether sorting is done (none implies no sorting), and, if sorting is done, how it is done (ascending or descending). For more information, see the discussion of the DataItem class later in this chapter.

Sorting takes on the following values:

• Enum.Sorting.NONE

• Enum.Sorting.DESCENDING

• Enum.Sorting.ASCENDING

The following statement assigns Enum.Sorting.NONE to the variable myEnum:

SortingType myEnum = Enum.Sorting.NONE; 

Other Supporting Classes

The other supporting classes are

• DataItem

• FilteringSettings

• Location

• TuningSettings

---

DataItem

A subclass of class Item. This class encapsulates data about an item.

Attributes

No public attributes.

Methods

There are two kinds of methods provided with this class:

• A constructor that creates a DataItem instance

• Methods that return attribute values

The following constructor creates a data item. For a description of an attribute, see the description of the corresponding method that returns the attribute value.

//Constructor
DataItem(String type, long ID, DataSourceType dataSource, String value);

Create a DataItem instance for a given item. An item is uniquely identified by its type and ID. For a description of an attribute, see the description of the method that returns that attribute value.

The remaining methods return attribute values:

getDataSource();

Returns a value of type DataSourceType representing the type of data associated with the item; the values supported are

• Enum.DataSource.DEMOGRAPHIC

• Enum.DataSource.PURCHASING

• Enum.DataSource.RATING

• Enum.DataSource.NAVIGATION

getValue();

Returns an value of type String that represents the value associated with the item.

Usage Notes

dataSource cannot be Enum.DataSource.ALL.

---

FilteringSettings

Specifies the items to include or exclude when generating recommendations. Release 1 of OP supports category filtering only.

Attributes

No public attributes.

Methods

There are three kinds of methods provided with this class:

• A constructor for FilteringSettings

• Methods that set the attributes values

• Methods that return attribute values

//Constructor
FilteringSettings (int taxonomyID);

Creates an instance with CategoryFiltering set to Enum.Filtering.OFF, CategoryMembership set to Enum.CategoryMembership.ALL_ITEMS, and taxonomyID set to the provided integer.

The following methods set the attributes of a FilteringSettings instance. First you must use the default constructor to create an instance. For a description of an attribute, see the description of the method that returns that attribute value.

setItemFiltering(int taxonomyID);

Creates an instance with CategoryFiltering set to Enum.Filtering.ON, CategoryMembership set to Enum.CategoryMembership.ALL_ITEMS, categoryList set to null, and taxonomyID set to the provided integer. Use this method to recommend items from all leaves in the taxonomy with the specified ID.

setItemFiltering(int taxonomyID, long[] categoryList);

Creates an instance with CategoryFiltering set to Enum.Filtering.ON, CategoryMembership set to Enum.CategoryMembership.INCLUDE_ITEMS, taxonomyID set to the provided integer, and categoryList set to the provided array. Use this method to recommend items that belong to the categories in the categoryList argument and the taxonomy with the specified ID.

setItemExclusion(int taxonomyID, long[] categoryList);

Creates an instance with CategoryFiltering set to Enum.Filtering.ON, CategoryMembership set to Enum.CategoryMembership.EXCLUDE_ITEMS, taxonomyID set to the provided integer, and categoryList set to the provided array. Use this method to recommend those items in the taxonomy with the specified ID that do not belong to the categories in the categoryList argument.

setItemSubTreeFiltering(int taxonomyID, long[] categoryList);

Creates an instance with CategoryFiltering set to Enum.Filtering.ON, CategoryMembership set to Enum.CategoryMembership.SUBTREE_ITEMS, taxonomyID set to the provided integer, and categoryList set to the provided array. Use this method to recommend those items in the taxonomy with the specified ID that belong to the subtrees of the categories in the categoryList argument.

setCategoryExclusion(int taxonomyID, long[] categoryList);

Creates an instance with CategoryFiltering set to Enum.Filtering.ON, CategoryMembership set to Enum.CategoryMembership.EXCLUDE_CATEGORIES, categoryList set to the provided array, and taxonomyID set to the provided integer. Use this method to recommend those categories in the taxonomy with the specified ID that are not in the category list.

setCategorySubTreeFiltering(int taxonomyID, long[] categoryList);

Creates an instance with CategoryFiltering set to Enum.Filtering.ON, CategoryMembership set to Enum.CategoryMembership.SUBTREE_CATEGORIES, taxonomyID set to the provided integer, and categoryList set to the provided array. Use this method to recommend categories in the taxonomy with the specified ID that belong to the subtrees of the categories in the categoryList argument.

setCategoryLevelFiltering(int taxonomyID, long[] categoryList);

Creates an instance with CategoryFiltering set to Enum.Filtering.ON, CategoryMembership set to Enum.CategoryMembership.LEVEL, taxonomyID set to the provided integer, and categoryList set to the provided array. Use this method to recommend categories in the taxonomy with the specified ID that belong to the same levels as the categories in the categoryList argument.

setCategoryFiltering(int taxonomyID);

Creates an instance with CategoryFiltering set to Enum.Filtering.ON, CategoryMembership set to Enum.CategoryMembership.ALL_CATEGORIES, and taxonomyID set to the provided integer. Use this method to recommend categories from all categories in the taxonomy with the specified ID.

setCategoryFiltering(int taxonomyID, long[] categoryList);

Creates an instance with CategoryFiltering set to Enum.Filtering.ON, CategoryMembership set to INCLUDE _CATEGORIES, taxonomyID set to the provided integer, and categoryList set to the argument provided. Use this method to recommend categories in the taxonomy with the specified ID that belong to the subtrees of the categories in the categoryList argument.

The following methods return the FilteringSettings attributes:

getTaxonomyID();

Returns the integer (type int) that identifies the taxonomy to which the categories belong.

getCategoryFiltering();

Returns the value of Category Filtering (type FilteringType). The options are

• Enum.Filtering.ON -- perform category filtering

• Enum.Filtering.OFF-- do not perform category filtering

getCategoryList();

Returns the array of 64-bit integers (type long[]) that indicates the list of categories to be used as a filter for recommending categories or items.

getCategoryMembership();

Returns a value of type CategoryMembershipType that specifies how the categories in the category list should be applied for filtering. Options are

• Enum.CategoryMembership.EXCLUDE_ITEMS -- exclude items that belong to categories in the category list

• Enum.CategoryMembership.EXCLUDE_CATEGORIES -- exclude categories in the category list

• Enum.CategoryMembership.INCLUDE_ITEMS -- include items that belong to categories in the category list

• Enum.CategoryMembership.INCLUDE_CATEGORIES -- include categories in the category list

• Enum.CategoryMembership.LEVEL -- recommend categories from the same level as the category in the list

• Enum.CategoryMembership.SUBTREE_ITEMS -- recommend items that belong to levels in the category list below those of the categories in the category list

• Enum.CategoryMembership.SUBTREE_CATEGORIES -- recommend categories that belong to the subtrees in the category list below the categories in the category list.

• Enum.CategoryMembership.ALL_ITEMS -- include all items in the specified taxonomy

• Enum.CategoryMembership.ALL_CATEGORIES -- include all categories in the specified taxonomy

Usage Notes

Not all filtering settings can be used will all methods. In particular, the following filtering setting cannot be used with the cross-sell methods (crossSellForItems):

• setCategoryLevelFiltering

• setCategorySubtreeFiltering

• setCategoryExclusion

• setCategoryFiltering(int)

• setCategoryFiltering(int, long[])

---

Item

This class is used to represent items that can be recommended and for which data can be collected. An item is uniquely represented by the combination of type and ID. Item IDs must be unique within a given type, but different types can have the same IDs.

Attributes

No public attributes.

Methods

There are two kinds of methods provided with this class:

• A constructor that creates an Item instance

• Methods that return attribute values

The following method creates an Item instance:

//Constructor
Item(String type, long ID);

Creates an instance with the specified type and ID. For descriptions of type and ID, see the descriptions of the methods that return them.

The following methods return attributes:

getType();

Returns a value of type String that identifies the group to which an item belongs. For example, a web site might have two types of items: products and banner ads. Individual products will have unique IDs, as will individual banner ads.

getID();

Returns an number of type long that is the unique identifier for an item within a given type.

Usage Note

Different items in a given type must have different IDs.

---

Location

Specifies the location of the input table or the table containing the results of an REBatchProxy method are stored. The schema for the table depends on the call made. See the descriptions of the individual methods in Chapter 3 for details.

Attributes

No public attributes.

Methods

There are three kinds of methods provided with this class:

• A constructor that creates a Location instance

• Methods that return attribute values

• Methods that set attribute values

//constructor
Location(String DatabaseURL, String DatabaseAlias, String SchemaName, String TableName, String UserName, String Password);

Creates an instance of the Location object with default attributes. Use the "set" methods described below to set the attributes. The meaning of each attribute is described in the corresponding "set" method.

get DatabaseURL();

Returns the string containing the database URL.

getDatabaseAlias();

Returns a string of type String that is the database alias for a location object.

getSchemaName();

Returns a string of type String that is the schema name for a location object.

getTableName();

Returns a string of type String that is the table name for a location object.

getUserName();

Returns a string of type String that is the user name for a location object.

getPassword();

Returns a string of type String that is the password for a location object.

setDatabaseURL(String URL);

Sets the Database URL in a Location object. The URL is used to create a JDBC connection to the database in which the table of interest resides or should be created.

setDatabaseAlias(String Alias);

Sets the Database Alias in a Location object. The alias identifies the database in which the table of interest resides or should be created.

setSchemaName(String SchemeName);

Sets the Schema Name in a Location object. The schema name identifies the schema for the data that is to be read or written.

setTableName(String TableName);

Sets the Table Name in a Location object. The table name identifies the input or output table used by a method.

setUserName(String UserName);

Sets the User Name in a Location object. The user name is the name to be used when connecting to the specified database.

setPassword(String Password);

Sets the password in a location object. The password is used in conjunction with the use name to connect to the database.

---

TuningSettings

Specifies settings to be applied when computing a recommendation. An instance of this class is passed to all recommendation requests.

Attributes

No public attributes.

Methods

There are two kinds of methods provided with this class:

A constructor that creates an TuningSettings instance

Methods that set attribute values

Methods that return attribute values

The following constructor creates a TuningSettings instance:

//Constructor
TuningSettings(DataSourceType dataSource
InterestDimensionType interestDimension,
PersonalizationIndexType personalizationIndex ,
ProfileDataBalanceType profileDataBalance,
ProfileUsageType profileUsage);

Create a tuning settings instance for use in recommendation requests. For descriptions of the attributes, see the descriptions of the methods that set attribute values.

The following methods set attribute values:

setDataSourceType();

Sets the type of data to consider when computing recommendations. The options are

• Enum.DataSource.NAVIGATIONAL -- use navigational (click stream) data only.

• Enum.DataSource.PURCHASING -- use purchasing data only.

• Enum.DataSource.RATING -- use rating data only.

• Enum.DataSource.DEMOGRAPHIC -- use demographic data only.

• Enum.DataSource.ALL -- use all data (navigational, purchasing, rating, and demographics).

setInterestDimension();

Sets the interest dimension that items should be ranked against. The options are

• Enum.InterestDimension.RATING -- rank items according to the expected rating that the customer would assign to them. This interest dimension is useful in applications that collect rating data on items (that is, explicit preference or interest).

• Enum.InterestDimension.PURCHASING -- rank items according to the likelihood that the customer will buy them. This interest dimension is useful in situations where selling items is the main goal.

• Enum.InterestDimension.NAVIGATION -- rank items according to the likelihood that the customer would be interested in the items. This interest dimension is useful in situations where the intent is measured indirectly using navigational data (implicit preferences or interest). For example, how interested a customer would be in an article about a given subject.

setPersonalizationIndex();

Sets the attribute that specifies how "unusual" the recommendations returned will be. The options are

• Enum.PersonalizationIndex.LOW -- recommend obvious items for a given customer profile; "Best Sellers" will appear more frequently among the recommendations in this case

• Enum.PersonalizationIndex.MEDIUM -- recommend a balanced mixture of obvious and less obvious items for a given customer profile

• Enum.PersonalizationIndex.HIGH -- recommend less obvious items for a given customer profile

setProfileDataBalance();

Sets the attribute that indicates whether to take data from current session or from history when making recommendations. The only valid option for bulk recommendations is:

• Enum.ProfileDataBalance.HISTORY -- use historical data only for creating recommendation

setProfileUsage();

Sets the attribute that specifies if the recommendation list can include items in a customer's profile. Options are

• Enum.ProfileUsage.INCLUDE -- include items in the profile

• Enum.ProfileUsage.EXCLUDE -- do not include items in the profile

There are times when it is appropriate to exclude items in the profile; for example, you might not want to recommend that a customer buy books that he has already purchased.

The following methods return attribute values:

getDataSourceType();

Returns the type of data to consider when computing recommendations. The options are

• Enum.DataSource.NAVIGATIONAL -- use navigational (click stream) data only.

• Enum.DataSource.PURCHASING -- use purchasing data only.

• Enum.DataSource.RATING -- use rating data only.

• Enum.DataSource.DEMOGRAPHIC -- use demographic data only.

• Enum.DataSource.ALL -- use all data (navigational, purchasing, rating, and demographics).

getInterestDimension();

Returns the interest dimension that items should be ranked against. The options are

• Enum.InterestDimension.RATING -- rank items according to the expected rating that the customer would assign to them. This interest dimension is useful in applications that collect rating data on items (that is, explicit preference or interest).

• Enum.InterestDimension.PURCHASING -- rank items according to the likelihood that the customer will buy them. This interest dimension is useful in situations where selling items is the main goal.

• Enum.InterestDimension.NAVIGATION -- rank items according to the likelihood that the customer would be interested in the items. This interest dimension is useful in situations where the intent is measured indirectly using navigational data (implicit preferences or interest). For example, how interested a customer would be in an article about a given subject.

getPersonalizationIndex();

Returns the attribute that specifies how "unusual" the recommendations returned will be. The options are

• Enum.PersonalizationIndex.LOW -- recommend obvious items for a given customer profile; "Best Sellers" will appear more frequently among the recommendations in this case

• Enum.PersonalizationIndex.MEDIUM -- recommend a balanced mixture of obvious and less obvious items for a given customer profile

• Enum.PersonalizationIndex.HIGH -- recommend less obvious items for a given customer profile

getProfileDataBalance();

Returns the attribute that indicates whether to take data from current session or from history when making recommendations. The options are

• Enum.ProfileDataBalance.HISTORY -- use historical data only for creating recommendation

• Enum.ProfileDataBalance.BALANCED -- use a balanced mixture of historical data and current session data for creating recommendations

• Enum.ProfileDataBalance.CURRENT -- use current session data only for creating recommendation

getProfileUsage();

Returns the attribute that specifies if the recommendation list can include items in a customer's profile. Options are

• Enum.ProfileUsage.INCLUDE -- include items in the profile

• Enum.ProfileUsage.EXCLUDE -- do not include items in the profile

There are times when it is appropriate to exclude items in the profile; for example, you might not want to recommend that a customer buy books that he has already purchased.