Oracle9iAS Personalization Recommendation Engine API Programmer's Guide Release 9.0.1 Part Number A87536-01 |
|
This chapter describes the supporting classes for the REProxy 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.
All methods described in this chapter are public.
The supporting classes are divided into two categories:
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.
The following classes are in the oracle.dmt.op.re.base package:
For example, to use the Enum interfaces, you must include the following statement in your Java program:
import oracle.dmt.op.re.base.Enum;
Many of the REAPI methods reference attributes that can take on a finite number of values. The interface Enum is used to implement the base class for these enumerated constants.
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:
CategoryMembershipType is implemented as:
The class CategoryMembership has the following methods:
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 categories in the category list should be excluded from the recommendations list. For details, see FilteringSettings later in this chapter.
CategoryMembership takes on the following values:
The following statement assigns Enum.CategoryMembership.LEVEL to the variable myEnum:
CategoryMembershipType myEnum = Enum.CategoryMembership.LEVEL;
DataSource is implemented as:
The class DataSourceType has the following methods:
DataSource specifies the type of data that is used when OP performs certain operations. For example, Enum.DataSource.DEMOGRAPHIC specifies that demographic data should be used. The class 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 methods in Chapter 3.
DataSource takes on the following values:
The following statement assigns Enum.DataSource.ALL to the variable myEnum:
DataSourceType myEnum = Enum.DataSource.ALL;
Filtering is implemented as:
The class FilteringType has the following methods:
Filtering is used to turn filtering on or off. See the description of the FilteringSettings class, later in this chapter for more information.
Filtering takes on the following values:
The following statement assigns Enum.Filtering.OFF to the variable myEnum:
FilteringType myEnum = Enum.Filtering.OFF;
InterestDimension is implemented as:
The class InterestDimensionType has the following methods:
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 purchased an item. RATING indicates that the user likes the items. For more information, see the description of the RecommendationList and TuningSettings classes later in this chapter.
InterestDimension takes on the following values:
The following statement assigns Enum.InterestDimension.PURCHASING to the variable myEnum:
InterestDimension myEnum = Enum.InterestDimension.PURCHASING;
PersonalizationIndex is implemented as:
The class PersonalizationIndexType has the following methods:
PersonalizationIndex specifies how "unusual" the recommendations returned will be. For example, LOW specifies not unusual. For more information, see the description of the TuningSettings class later in this chapter.
PersonalizationIndex takes on the following values:
The following statement assigns Enum.PersonalizationIndex.LOW to the variable myEnum:
PersonalizationIndexType myEnum = Enum.PersonalizationIndex.LOW;
ProfileDataBalance is implemented as:
The class ProfileDataBalanceType has the following methods:
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 class later in this chapter.
ProfileDataBalance takes on the following values:
The following statement assigns Enum.ProfileDataBalance.BALANCED to the variable myEnum:
ProfileDataBalanceType myEnum = Enum.ProfileDataBalance.BALANCED;
ProfileUsage is implemented as:
The class ProfileUsageType has the following methods:
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:
The following statement assigns Enum.ProfileUsage.INCLUDE to the variable myEnum:
ProfileUsageType myEnum = Enum.ProfileUsage.INCLUDE;
RecommendationAttribute is implemented as:
The class RecommendationAttributeType has the following methods:
RecommendationAttribute indicates the attribute to be included in the returned content; possible choices are type, ID, and prediction. For more information, see the descriptions of the ContentItem and RecommendationContent classes later in this chapter.
RecommendationAttribute takes on the following values:
The following statement assigns Enum.RecommendationAttribute.URL to the variable myEnum:
RecommendationAttributeType myEnum = Enum.RecommendationAttribute.TYPE;
Sorting is implemented as:
The class SortingType has the following methods:
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 discussions of the ContentItem and RecommendationContent classes later in this chapter.
Sorting takes on the following values:
The following statement assigns Enum.Sorting.NONE to the variable myEnum:
SortingType myEnum = Enum.Sorting.NONE;
User is implemented as:
The class UserType has the following methods:
UserType is either customer, a registered user of the calling Web site, or visitor, an unregistered user. For more information see the description of the IdentificationData class later in this chapter.
UserType takes on the following values:
The following statement assigns Enum.User.CUSTOMER to the variable myEnum:
UserTypeType myEnum = Enum.User.CUSTOMER;
The other supporting classes are
Encapsulates the information that should be included in the object returned by a recommendation request. It describes the attributes to be included in the recommendation list returned by a call as well as specifying whether the list should be sorted according to one of the attributes. RecommendationContent, described later in this chapter, is any array of items of type ContentItem; the description of RecommendationContent explains how sorting order works when multiple orders are specified.
No public attributes.
getContentAttribute();
Returns the attribute to be included in the returned content. Attributes can be any of the following:
getSorting()
Returns the sorting option for the content item.The following sorting options are supported:
A subclass of class Item. This class encapsulates data about an item. This object is used as an argument in the data collection methods addItem() and addItems().
No public attributes.
There are two kinds of methods provided with this class:
//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.
getDataSource():
Returns the value of type DataSourceType indicating the kind of data associated with the item; the values supported are
getValue()
Returns the value of type String associated with the item.
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.
dataSource cannot be Enum.DataSource.ALL.
Specifies the items to include or exclude when generating recommendations.
Release 1 of OP supports category filtering only.
No public attributes.
There are three kinds of methods provided with this class:
//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 : int
Returns the integer that identifies the taxonomy to which the categories belong.
getCategoryFiltering : FilteringType
Returns the value of Category Filtering. The options are
getCategoryList : long[]
Returns the array of 64-bit integers that indicates the list of categories to be used as a filter for recommending categories or items.
getCategoryMembership : CategoryMembershipType
Returns a value that specifies how the categories in the category list should be applied for filtering. Options are
Not all filtering settings can be used will all methods. In particular, the following filtering setting cannot be used with the cross-sell methods (recommendCrossSellForItem, recommendCrossSellForItems, crossSellForItemFromHotPicks, and crossSellForItemsFromHotPicks):
Identifies the user and/or the session.
No public attributes.
There are two kinds of methods provided with this class:
The following methods create IdentificationData instances. For a description of an attribute, see the description of the method that returns that attribute value.
createSessionful(String appSessionID, UserType userType)
Create an IdentificationData instance for use in REAPI calls from a sessionful Web application.
createSessionless(String appSessionID, UserType userType)
Create an IdentificationData instance for use in REAPI calls from a sessionless application.
The following methods get attributes:
getUserID()
Returns the identifier of type String that the calling Web application assigns to the user
getAppSessionID() :
Returns the identifier of type String that the calling Web application assigns to the session
getUserType()
Returns a value of type UserType, either Enum.UserType.CUSTOMER or Enum.UserType.VISITOR. This attribute is used to identify the user as a customer (registered user) or as a visitor (unregistered user)
The calling Web application should assign a userID to all users, both customers (registered users) and visitors. IDs for customers must be unique. If IDs for visitors are not unique, OP will not be able to make recommendations that are specific to a given visitor; instead the same recommendations would be made for all visitors who had the given ID.
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.
No public attributes.
There are three kinds of methods provided with this class:
//Constructor
Item(String type, long ID);
Creates an item 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 representing 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 (): long
Returns the unique identifier (type long) for an item within a given type.
Different items in a given type must have different IDs.
This class is created internally by OP as part of the result of recommendation request. The calling Web application will have to examine the attributes to determine what attributes and values they contain. See the description of Recommendation later in this chapter for more details.
No public attributes.
getAttribute() : RecommendationAttributeType
Returns the recommendation attribute. Attributes can be any of the following:
getValue()
Returns the value (type String) of the item attribute.
toString()
Converts to String, so that it can be printed.
This class encapsulates information about a single recommended item. The information about the item is stored in the attributes array.
No public attributes.
getAttributes()
Returns an array of type ItemDetailData[] for the recommendation. Each instance stores information about a different item attribute. Item attributes are itemID, item type, and prediction value. For release 1.0 of OP, the set of item attributes is fixed and is precisely the set of attributes listed.
toString()
Converts to String, so that it can be printed.
You should use this method to access information about recommended items and not try to access the array element directly.
Specifies the type of information that a recommendation request should return.
No public attributes.
There are two kinds of methods provided with this class:
The following constructors create recommendation content instances depending on how sorting is to be done:
//Constructor - default sorting
RecommendationContent(SortingType sorting);
This constructor creates a default RecommendationContent instance with default sorting. The default instance has the following three entries:
//Constructor - specified sorting
RecommendationContent(SortingType sortingForType, SortingType sortingForID, SortingType sortingforPrediction);
This constructor creates a default RecommendationContent instance with sorting as specified in the parameters. The default instance has the following three entries:
The following method returns the content items
getContentItems : ContentItem[]
Returns the array of type ContentItem[]. Each entry specifies the type of information to be included in the result object of a recommendation request call. The information includes the attribute name and how or if it should be sorted. See "Usage Notes" (below) for information about sorting multiple array instances.
If multiple instances of the array are to be sorted, the sorting order follows the array index order. That is, the result is sorted according to the attribute in the first array entry marked to be sorted, followed by the attribute in the second entry marked to be sorted, etc.
A collection of recommendations for a specific InterestDimension. RecommendationList is the class returned by all REAPI methods that return recommendations.
No public attributes.
The methods described below permit the calling Web application to determine the interest dimension type, to determine the actual number of recommendations returned, and to get the individual recommendations. See the description of the Recommendation class for more information.
getInterestDimension()
Returns the interest dimension of type InterestDimension, which specifies the interest dimension that the items were ranked against. Possible values are
getNumberOfRecommendations()
The actual number (type int) of recommendations returned.
getRecommendation(int index)
Returns the recommendation instance (type Recommendation) at position index in the Recommendation array. If index is out of range, the method returns an exception.
toString()
Converts to String, so that it can be printed.
Specifies settings to be applied when computing a recommendation. An instance of this class is passed to all recommendation requests.
No public attributes.
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
setInterestDimension();
Sets the interest dimension that items should be ranked against. The options are
setPersonalizationIndex();
Sets the attribute that specifies how "unusual" the recommendations returned will be. The options are
setProfileDataBalance();
Sets the attribute that indicates whether to take data from current session or from history when making recommendations. The options are
setProfileUsage();
Sets the attribute that specifies if the recommendation list can include items in a customer's profile. Options are
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
getInterestDimension();
Returns the interest dimension that items should be ranked against. The options are
getPersonalizationIndex();
Returns the attribute that specifies how "unusual" the recommendations returned will be. The options are
getProfileDataBalance();
Returns the attribute that indicates whether to take data from current session or from history when making recommendations. The options are
getProfileUsage();
Returns the attribute that specifies if the recommendation list can include items in a customer's profile. Options are
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.
|
Copyright © 2001 Oracle Corporation. All Rights Reserved. |
|