|
OracleAS Personalization Java API Reference 10g Release 2 (10.1.2) B14053-01 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object
oracle.dmt.op.re.reapi.rt.REProxyRT
This class provides real-time recommendation functions. An instance of REProxyRT
, a.k.a proxy, must be created or obtained before any REAPI method can be called in a client application. Although a public constructor is provided for creating proxies directly, it is strongly recommended that you create proxies through class REProxyManager
. Class REProxy
encapsulates a JDBC connection pool and a data collection cache; both are created during proxy initialization. The former is used to maintain a pooling mechanism for JDBC connections that are used by almost every REAPI method. This guarantees the best use of the resources. The latter provides the most efficient way to collect user profile data that is essential for building and improving data mining models, which is the core of the real-time recommendation engine.
It is expensive to create a new instance of REProxyRT
, both time-wise and resource-wise. For web applications, it is better to create the needed proxies during the application initiation stage. The REProxyRT
objects need NOT be destroyed until the application (not necessarily for every program module, such as servlets or JSPs) closes or when the server, namely OracleAS, shuts down.
The majority of the public methods provided in this class can be divided into two categories: recommendation and data collection. Every recommendation method requires a JDBC connection to the designated RE schema where the model and the profile data are stored. Recommendation results are made in real time based on the model and the profile. The data collection methods, such as addItem
, do not require individual JDBC connections. The profile data collected is first stored temporarily in the data collection cache. The data is then periodically archived, in batch, in the RE schema via a dedicated JDBC connection. Eventually, the data is saved (synchronised) in the MTR, either at the end of a synch interval or when the session closes or times out.
Although RE always maintains its own session internally, all methods in this class support both sessionful and sessionless applications. If the host application is sessionful, the RE session can be mapped to the host app session. This is done by calling create session methods. There are two such methods, one for customers, namely registered users; the other for visitors, those who never registered, hence there is no or little profle data about them. If the application is sessionless, all REProxyRT
methods can be called without creating a session first.
REProxyManager
Method Summary | |
void |
addItem(IdentificationData idData, DataItem item) Adds an item to the data collection cache. |
void |
addItems(IdentificationData idData, DataItem[] items) Adds multiple items to the data collection cache. |
void |
closeSession(IdentificationData idData) Closes an RE session and marks the session as closed. |
void |
createCustomerSession(java.lang.String customerID, java.lang.String appSessionID) Creates a new customer session, i.e., a new session for the specified customer (registered user). |
void |
createVisitorSession(java.lang.String visitorID, java.lang.String appSessionID) Creates a new visitor session, i.e., a new session for a visitor. |
RecommendationList |
crossSellForItemFromHotPicks(IdentificationData idData, Item item, int numOfItems, long[] hotPickGroups, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) Recommends a list of cross-sell items from Hotpicks related to the specified item. |
RecommendationList |
crossSellForItemsFromHotPicks(IdentificationData idData, Item[] items, int numOfItems, long[] hotPickGroups, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) Recommends a list of cross-sell items from Hotpicks related to the specified items. |
void |
freePooledConnection(java.sql.Connection conn) |
java.lang.String |
getName() Gets the name of this proxy. |
java.sql.Connection |
getPooledConnection() |
REProxyRT |
getProxy() Deprecated. use REProxyManager.getProxy instead. |
int |
getQueryTimeout() Returns the number of seconds the JDBC driver will wait for the underlying SQL query to execute. |
float |
rateItem(IdentificationData idData, Item item, int taxonomyId, TuningSettings tunings, RecommendationContent recContent) Gives the rating of an item. |
RecommendationList |
rateItems(IdentificationData idData, Item[] items, int taxonomyId, TuningSettings tunings, RecommendationContent recContent) Gives the rating of the specified items. |
RecommendationList |
recommendBottomItems(IdentificationData idData, int numOfItems, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) Recommends a list of bottom-rated items. |
RecommendationList |
recommendCrossSellForItem(IdentificationData idData, Item item, int numOfItems, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) Recommends a list of cross-sell items related to the specified item. |
RecommendationList |
recommendCrossSellForItems(IdentificationData idData, Item[] items, int numOfItems, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) Recommends a list of cross-sell items related to the specified items. |
RecommendationList |
recommendFromHotPicks(IdentificationData idData, int numOfItems, long[] hotPickGroups, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) Recommends a list of Hotpick items. |
RecommendationList |
recommendTopItems(IdentificationData idData, int numOfItems, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) Recommends a list of top-rated items. |
void |
removeItem(IdentificationData idData, DataItem item) Removes an item from the cache and from the RE schema, if it has already been archived. |
void |
removeItems(IdentificationData idData, DataItem[] items) Removes multiple items from the cache and from the RE schema, if they have already been archived. |
RecommendationList |
selectFromHotPicks(IdentificationData idData, int numOfItems, long[] hotPickGroups, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) Selects the specified number of items from a specified set of hot picks group. |
void |
setQueryTimeout(int nTimeout) Returns the number of seconds the JDBC driver will wait for the underlying SQL query to execute. |
void |
setVisitorToCustomer(IdentificationData idData, java.lang.String customerID) Changes the status of a visitor to that of customer during a live session. |
Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Method Detail |
public REProxyRT getProxy()
REProxyManager.getProxy
instead.REProxyManager
public java.lang.String getName()
REProxyRT
objectpublic int getQueryTimeout()
public void setQueryTimeout(int nTimeout)
public void createCustomerSession(java.lang.String customerID, java.lang.String appSessionID) throws StringTooLargeException, InvalidIDException, BadDBConnectionException, ErrorExecutingRE, REProxyInitException, ConnectionPoolIsFullException, NullParameterException
OP maintains the mapping between appSessionID
and customerID
. In subsequent calls, the calling application uses appSessionID
to identify the customer ID.
If the method completes successfully, a session record is inserted into the table RE_ACTIVE_USER in the RE schema and both IS_CUSTOMER and IS_ACTIVE flags are set to true.
customerID
- customer IDappSessionID
- session ID provided by the host applicationStringTooLargeException
- if any input string is too longInvalidIDException
- if any ID is invalidBadDBConnectionException
- if the obtained JDBC connection is not goodErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsConnectionPoolIsFullException
- if the JDBC connection pool reaches its maximum size and all connections are in useNullParameterException
- if non-null input parameter is set to nullpublic void createVisitorSession(java.lang.String visitorID, java.lang.String appSessionID) throws StringTooLargeException, BadDBConnectionException, InvalidIDException, ErrorExecutingRE, REProxyInitException, ConnectionPoolIsFullException, NullParameterException
OP maintains the mapping between appSessionID
and visitorID
, In subsequent calls, the calling application uses appSessionID
to identify the visitor session.
If the method completes successfully, a session record is inserted into the table RE_ACTIVE_USERin the RE schema, the IS_CUSTOMER flag is set to false, and the IS_ACTIVE flag is set to true.
visitorID
- ID assigned to a visitorappSessionID
- session ID provided by the host applicationStringTooLargeException
- if any input string is too longInvalidIDException
- if any ID is invalidBadDBConnectionException
- if the obtained JDBC connection is not goodErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsConnectionPoolIsFullException
- if the JDBC connection pool reaches its maximum size and all connections are in useNullParameterException
public void closeSession(IdentificationData idData) throws REProxyInitException, BadDBConnectionException, InvalidIDException, ErrorExecutingRE, ConnectionPoolIsFullException, NullParameterException
After this method is called, the profile data related to the closed session will be saved in the MTR and then purged from the RE by a data synchronization process that runs periodically. For more information about data synchronization, see the administrator's guide.
If the calling Web application does not call this method explicitly, the session can time out after a specified interval. The time-out flag and the time-out interval are both user-configurable parameters set in table RE_CONFIGURATION in the RE schema (see the administrator's guide). The application can also configure the RE to not time out any sessions. In this case, the calling Web application must close all sessions explicitly using this method. If sessions are not closed (and do not time out), the RE tables may fill up rapidly. Full RE tables can result in poor performance and eventually in failure of the RE.
See the administrator's guide for information about setting configuration parameters.
idData
- the user's identification data. When this method completes successfully, the IS_ACTIVE flag of the session is set to false.InvalidIDException
- if any ID is invalidBadDBConnectionException
- if the obtained JDBC connection is not validErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsNullParameterException
- if null is given to a non-null parameterConnectionPoolIsFullException
- if the JDBC connection pool reaches its maximum size and all connections are in usepublic RecommendationList recommendTopItems(IdentificationData idData, int numOfItems, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) throws BadDBConnectionException, InvalidIDException, NullParameterException, ErrorExecutingRE, REProxyInitException, ConnectionPoolIsFullException
numberOfItems
items with the highest degree of interest along the specified interest dimension. It answers questions such as Which are the N items that peson X is most likely to buy or like?
The rating calculation is based on the data mining model results and the user profile.
idData
- the user identification datanumOfItems
- the maximum number of recommendations to returntunings
- set of parameters that tunes the recommendation processfilters
- set of parameters that filters the recommendation resultsrecContent
- set of parameters that defines how the results shall be presentedBadDBConnectionException
- if the obtained JDBC connection is not usableInvalidIDException
- if any input ID is invalidNullParameterException
- if null is given to a non-null parameterErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsConnectionPoolIsFullException
- if the JDBC connection pool reaches its maximum size and all connections are in usepublic RecommendationList crossSellForItemFromHotPicks(IdentificationData idData, Item item, int numOfItems, long[] hotPickGroups, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) throws ArrayTooLargeException, NullParameterException, InvalidIDException, BadDBConnectionException, ErrorExecutingRE, REProxyInitException, ConnectionPoolIsFullException
idData
- the user identification dataitem
- the item the cross-sell is related tonumOfItems
- the maximum number of recommendations to returnhotPickGroups
- group ID(s) of hotpick group(s) to be handledtunings
- set of parameters that tunes the recommendation processfilters
- set of parameters that filters recommendation resultsrecContent
- set of parameters that defines how the results shall be presentedArrayTooLargeException
- if input array size exceeds the maximumBadDBConnectionException
- if the obtained JDBC connection is not usableInvalidIDException
- if any input ID is invalidNullParameterException
- if null is given to a non-null parameterErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsConnectionPoolIsFullException
- if the JDBC connection pool reaches its maximum size and all connections are in usepublic RecommendationList crossSellForItemsFromHotPicks(IdentificationData idData, Item[] items, int numOfItems, long[] hotPickGroups, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) throws ArrayTooLargeException, NullParameterException, InvalidIDException, BadDBConnectionException, ErrorExecutingRE, REProxyInitException, ConnectionPoolIsFullException
idData
- the user identification dataitems
- an array of Item
that the cross-sell item is related tonumOfItems
- the maximum number of recommendations to returnhotPickGroups
- group ID(s) of hotpick group(s) to be included in this recommendationtunings
- set of parameters that tunes the recommendation processfilters
- set of parameters that filters the recommendation resultsrecContent
- set of parameters that defines how the results shall be presentedArrayTooLargeException
- if input array size exceeds the maximumBadDBConnectionException
- if the obtained JDBC connection is not usableInvalidIDException
- if any input ID is invalidNullParameterException
- if null is given to a non-null parameterErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsConnectionPoolIsFullException
- if the JDBC connection pool reaches its maximum size and all connections are in usepublic RecommendationList selectFromHotPicks(IdentificationData idData, int numOfItems, long[] hotPickGroups, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) throws ArrayTooLargeException, NullParameterException, InvalidIDException, BadDBConnectionException, ErrorExecutingRE, REProxyInitException, ConnectionPoolIsFullException
idData
- the user identification datanumOfItems
- the maximum number of recommendations to returnhotPickGroups
- group ID(s) of Hotpick group(s) to be includedtunings
- set of parameters that tunes the selectionfilters
- set of parameters that filters the selectionrecContent
- set of parameters that defines how the results shall be presentedArrayTooLargeException
- if input array size exceeds the maximumBadDBConnectionException
- if the obtained JDBC connection is not usableInvalidIDException
- if any input ID is invalidNullParameterException
- if null is given to a non-null parameterErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsConnectionPoolIsFullException
- if the JDBC connection pool reaches its maximum size and all connections are in usepublic RecommendationList recommendCrossSellForItem(IdentificationData idData, Item item, int numOfItems, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) throws NullParameterException, InvalidIDException, BadDBConnectionException, ErrorExecutingRE, REProxyInitException, ConnectionPoolIsFullException
idData
- the user identification dataitem
- the item the cross-sell item is related tonumOfItems
- the maximum number of recommendations to returntunings
- set of parameters that tunes the recommendation processfilters
- set of parameters that filters recommendation resultsrecContent
- set of parameters that defines how the results shall be presentedBadDBConnectionException
- if the obtained JDBC connection is not usableInvalidIDException
- if any input ID is invalidNullParameterException
- if null is given to a non-null parameterErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsConnectionPoolIsFullException
- if the JDBC connection pool reaches its maximum size and all connections are in usepublic RecommendationList recommendCrossSellForItems(IdentificationData idData, Item[] items, int numOfItems, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) throws ArrayTooLargeException, NullParameterException, InvalidIDException, BadDBConnectionException, ErrorExecutingRE, REProxyInitException, ConnectionPoolIsFullException
idData
- the user identification dataitems
- an array of items the cross-sell is related tonumOfItems
- the maximum number of recommendations to returntunings
- set of parameters that tunes the recommendation processfilters
- set of parameters that filters recommendation resultsrecContent
- set of parameters that defines how the results shall be presentedArrayTooLargeException
- if input array size exceeds the maximumBadDBConnectionException
- if the obtained JDBC connection is not usableInvalidIDException
- if any input ID is invalidNullParameterException
- if null is given to a non-null parameterErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsConnectionPoolIsFullException
- if the JDBC connection pool reaches its maximum size and all connections are in usepublic RecommendationList recommendBottomItems(IdentificationData idData, int numOfItems, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) throws NullParameterException, BadDBConnectionException, InvalidIDException, ErrorExecutingRE, REProxyInitException, ConnectionPoolIsFullException
NumberOfItems
items with the lowest degree of interest along the specified interst dimension. The rating calculation is based on the data mining model results and the user profile. It is predicted that the user will most likely rate these items at the lower end of the specified interest dimension. It answers questions such as Which are the N items that person X is least likely to buy or like?idData
- the user identification datanumOfItems
- the maximum number of recommendations to returntunings
- set of parameters that tunes the recommendation processfilters
- set of parameters that filters recommendation resultsrecContent
- set of parameters that defines how the results shall be presentedBadDBConnectionException
- if the obtained JDBC connection is not usableInvalidIDException
- if any input ID is invalidNullParameterException
- if null is given to a non-null parameterErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsConnectionPoolIsFullException
- if the JDBC connection pool reaches its maximum size and all connections are in usepublic RecommendationList recommendFromHotPicks(IdentificationData idData, int numOfItems, long[] hotPickGroups, TuningSettings tunings, FilteringSettings filters, RecommendationContent recContent) throws ArrayTooLargeException, REProxyInitException, NullParameterException, BadDBConnectionException, InvalidIDException, ErrorExecutingRE, ConnectionPoolIsFullException
idData
- the user identification datanumOfItems
- the maximum number of recommendations to returnhotPickGroups
- group ID(s) of hotpick group(s) to be handledtunings
- set of parameters that tunes the recommendation processfilters
- set of parameters that filters recommendation resultsrecContent
- set of parameters that defines how the results shall be presentedArrayTooLargeException
- if input array size exceeds the maximumBadDBConnectionException
- if the obtained JDBC connection is not usableInvalidIDException
- if any input ID is invalidNullParameterException
- if null is given to a non-null parameterErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsConnectionPoolIsFullException
- if the JDBC connection pool reaches its maximum size and all connections are in usepublic float rateItem(IdentificationData idData, Item item, int taxonomyId, TuningSettings tunings, RecommendationContent recContent) throws NullParameterException, BadDBConnectionException, InvalidIDException, ErrorExecutingRE, REProxyInitException, ConnectionPoolIsFullException
idData
- the user identification dataitem
- the item to be ratedtaxonomyId
- ID of the taxonomy from which the rating is calculatedtunings
- set of parameters that tunes the recommendation processrecContent
- set of parameters that defines how the results shall be presentedBadDBConnectionException
- if the obtained JDBC connection is not usableInvalidIDException
- if any input ID is invalidNullParameterException
- if null is given to a non-null parameterErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsConnectionPoolIsFullException
- if the JDBC connection pool reaches its maximum size and all connections are in usepublic RecommendationList rateItems(IdentificationData idData, Item[] items, int taxonomyId, TuningSettings tunings, RecommendationContent recContent) throws ArrayTooLargeException, NullParameterException, BadDBConnectionException, InvalidIDException, ErrorExecutingRE, REProxyInitException, ConnectionPoolIsFullException
idData
- the user identification dataitems
- an array of items to be ratedtaxonomyId
- ID of the taxonomy from which ratings are calculatedtunings
- set of parameters that tunes the recommendation processrecContent
- set of parameters that defines how the results shall be presentedArrayTooLargeException
- if input array size exceeds the maximumBadDBConnectionException
- if the obtained JDBC connection is not usableInvalidIDException
- if any input ID is invalidNullParameterException
- if null is given to a non-null parameterErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsConnectionPoolIsFullException
- if the JDBC connection pool reaches its maximum size and all connections are in usepublic void addItem(IdentificationData idData, DataItem item) throws BufferIsFullException
idData
- the user identification dataitem
- the data to be addedBufferIsFullException
- if the cache buffer is fullpublic void addItems(IdentificationData idData, DataItem[] items) throws ArrayTooLargeException, BufferIsFullException
idData
- the user identification dataitems
- an array of items to be addedArrayTooLargeException
- if the items array exceeds maximum sizeBufferIsFullException
- if the cache buffer is fullpublic void removeItem(IdentificationData idData, DataItem item) throws BadDBConnectionException, InvalidIDException, ErrorExecutingRE, REProxyInitException, ConnectionPoolIsFullException, NullParameterException
idData
- the user identification dataitem
- the item to be removedInvalidIDException
- if any input ID is invalidBadDBConnectionException
- if the connection obtained is not usableErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsNullParameterException
- if null is given to a non-null parameterConnectionPoolIsFullException
- if the connection pool reaches maximum size and all connections are in usepublic void removeItems(IdentificationData idData, DataItem[] items) throws ArrayTooLargeException, BadDBConnectionException, InvalidIDException, ErrorExecutingRE, REProxyInitException, ConnectionPoolIsFullException, NullParameterException
idData
- the user identification dataitems
- an array of items to be removedArrayTooLargeException
- if items array exceeds the maximum (1024)InvalidIDException
- if any input ID is invalidBadDBConnectionException
- if the connection obtained is not usableErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsNullParameterException
- if null is given to a non-null parameterConnectionPoolIsFullException
- if the connection pool reaches maximum and all connections are in usepublic void setVisitorToCustomer(IdentificationData idData, java.lang.String customerID) throws InvalidIDException, BadDBConnectionException, ErrorExecutingRE, REProxyInitException, ConnectionPoolIsFullException, NullParameterException
idData
- user identificationcustomerID
- the new customer ID assigned to the user by the applicationInvalidIDException
- if any input ID is invalidBadDBConnectionException
- if the connection obtained is not usableErrorExecutingRE
- if PL/SQL execution failsREProxyInitException
- if reinitialization failsNullParameterException
- if null is given to a non-null parameterConnectionPoolIsFullException
- if the connection pool reaches maximum size and all connections are in usepublic void freePooledConnection(java.sql.Connection conn)
public java.sql.Connection getPooledConnection() throws BadDBConnectionException, REProxyInitException, ConnectionPoolIsFullException
BadDBConnectionException
REProxyInitException
ConnectionPoolIsFullException
|
OracleAS Personalization Java API Reference 10g Release 2 (10.1.2) B14053-01 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |