4 Using REAPI

4.2.1.1 RE Data Collection

The REProxyRT class includes the DataCollection cache, which supports data collection in the RE. Every time you create an REProxyRT object, the cache is built as a subcomponent of the proxy object. When data is collected using the REAPI calls addItem() and addItems(), the data is stored in the cache (in the memory) and is periodically flushed to RE schema. This "batch save" improves RE performance. The cache is created when a new REProxyRT object is created. The refresh rate is defined by an input parameter to REProxyManager.createProxy().

Currently, only item and user ID data in the classes DataItem and IdentificationData are cached, and they are cached as current session data.

4.2.1.2 REProxyManager Class

REProxyManager is a singleton implementation, that is, only one instance of the REProxyManager class is created in a particular JVM instance, and the class is loaded automatically.

The REProxyManager class is used to create and manage the instances of REProxyRT. REProxyManager has only static public methods. REProxyManager does not have a public constructor and hence cannot be created by the user. REProxyManager maintains an REProxyRT pool and uses proxy names to reference individual REProxyRT objects.

The following methods manage REProxyRT objects:

• createProxy

• getProxy

• destroyAllProxies

• destroyProxy

For examples of how to use the proxy manager, see Chapter 5 and the complete example in Appendix A.

4.2.6.1 Ratings in OracleAS Personalization

Ratings in OracleAS Personalization 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. OracleAS Personalization algorithms use these assumptions, so it is important that ratings are in ascending order of goodness. Note that sorting in ascending or descending order is possible on recommendations containing ratings.

4.2.6.2 Meaning of Returned Value for Recommendations

The meaning of the value returned for recommendation instances where ItemDetailData.attribute is equal to Enum.RecommendationAttribute.PREDICTION depends on the value of interestDimension as follows:

• For InterestDimension.RATING, the expected rating for the item is returned.

• For InterestDimension.PURCHASING or InterestDimension.NAVIGATION, the ranking is returned. The most probable item is assigned a value of 1 and other items are assigned integer values representing their rank according to how probable the item is.

4.4.2.1 Add Items

For both addItem and addItems, items are cached locally first and synchronously written to the RE; the frequency of the writes is specified as a configuration parameter when OracleAS Personalization is installed. It is important that the data synchronization interval is frequent enough to support the Web applications' requirements. For more information about data synchronization, see the administrator's guide.

When an application needs to add several items at a time, it can either use several addItem calls or one addItems call. When using addItems, the application must maintain the details of the items to be added until the call is made; in other words, the application needs to keep the state. It may be simpler to issue several addItem calls.

addItem and addItems are asynchronous, so the calling application does not need to wait until either call saves the data to the RE database.

Data collected in the RE is automatically written to the MTR, if the RE is configured to do so.

4.4.2.2 Remove Items

removeitem and removeItems remove items that have not been written to the MTR (permanent storage). Once data is written to the MTR, you cannot use these methods to remove the data. In the applied scenario where a customer returns an item after purchasing it, this item will have to be removed from the MTR or source sales database. Similarly, if a customer abandons the purchase process before fully completing the process, the items selected for purchase will have to be removed from the MTR.

4.4.3.1 Cache Size

The cache size is the size of the cache used by the recommendation engine, in kilobytes.

There are several factors to consider when determining the cache size:

1. System resources: Since cache takes memory space, you must make sure that you have enough memory to do what you want.

2. Archive interval: The longer the interval, the larger the cache size.

3. Maximum VArray size: The PL/SQL procedure that performs the archive uses VArrays, and the maximum size is currently set at 5000. The archive can handle more than 5000 items, but performance increasingly worsens above that size. Therefore, it is not recommended to have the cache buffer larger than 5000. Each data item stored in the cache takes up about 340 bytes; so, the maximum VArray size translates to 3.4 MB (the actual cache buffer size is half of that since the cache has two buffers).

4. Data collection rate, the most important factor: If the data collection rate is no more than 100 items per second and the archive interval is 20 seconds, then a reasonable cache size is (assuming a safety factor of 1.5 to ensure that no data is dropped): 100 * 340 * 1.5 * 20, which is approximately 2 MB.

4.4.3.2 Interval

The interval determines how often the collected data is archived (flushed from memory to the RE schema). There are several factors to consider when determining this setting:

1. Data collection volume and speed: The more frequent the data collection and the larger the volume of data collected, the shorter the interval should be.

2. Cache size: The smaller the cache, the shorter the interval.

3. Use of current session data: If you want to use the current session data to improve the recommendation accuracy, the data should not be held in the cache for too long. If the volume and speed of the data collection is not a problem, an interval of 10-30 seconds may be fine.