CFEngine API

org.recommender.server
Interface CFEngine

All Superinterfaces:
java.rmi.Remote
All Known Implementing Classes:
CFEngineImpl

public interface CFEngine
extends java.rmi.Remote

Describes the interface for the CF Engine. Contains methods that will be invoked by remote clients of the CF Engine (CFEngineClient) and will be implemented by the implementation class (CFEngineImpl) and created by a CF Engine server (CFEngineServer).

Since:
JDK 1.2

Method Summary
 float getErrRating()
          Get the error rating for the current server configuration.
 ItemRating[] getItemRatingList(int itemID)
          Return an array of all known ratings for the given item.
 float getMaxRating()
          Get the maximum rating allowed for the current server configuration.
 float getMinRating()
          Get the minimum rating allowed for the current server configuration.
 int getNextItemId()
           
 int getNextUserId()
           
 ItemPrediction getPredictedRating(int userID, int itemID)
          Get a user's predicted rating for an item.
 ItemPrediction[] getPredictedRatingList(int userID, int[] itemID)
          Gets predicted ratings for a list of items.
 ItemRating getRating(int userID, int itemID)
          Retrieves one user's rating for a given item.
 ItemRating[] getRatingList(int userID, int[] itemIDs)
          Retrieves the ratings by the user for a list of given items.
 ItemPrediction[] getRecommendations(int curUser, int number, int offset)
          Get ten items with high predicted ratings for current user.
 ItemPrediction[] getRecommendationsByType(int curUser, int number, int offset, int type)
          Get top n recommendations for current user of specific type.
 java.lang.String getStatistics()
           
 ItemRating[] getUserRatingList(int userID)
          Return an array of all known ratings for the given user.
 void removeRating(int user, int item)
          Removes rating from both database and cache.
 void removeRatingList(int user, int[] itemIDs)
          Removes list of ratings from users profile.
 void setRating(int user, int item, float rating)
          Add new rating to both database and the cache.
 int setRatingList(ItemRating[] newRatings)
          Add a list of new ItemRatings to both database and the cache.
 void shutdown()
          Shuts the server down.
 java.lang.String test()
          Test whether the CFEngine is alive on the host.
 

Method Detail

test

public java.lang.String test()
                      throws java.rmi.RemoteException
Test whether the CFEngine is alive on the host. Useful to test if an RMI connection was successful. If this method doesn't throw an exception, then the server was successfully contacted.

Returns:
String
Throws:
java.rmi.RemoteException

setRating

public void setRating(int user,
                      int item,
                      float rating)
               throws java.rmi.RemoteException,
                      CFIllegalParameterException,
                      CFInternalErrorException
Add new rating to both database and the cache. The rating is added immediately to the memory cache, and there may be a short delay before it reaches the database. If the server crashes before the rating is written to the database that rating may be lost. Note: If rating for the same (user, item) already exists, it replaces it.

Parameters:
user -
item -
rating -
Throws:
java.rmi.RemoteException - Thrown upon client/server connection error
CFIllegalParameterException - Throws exception for out of range user,item, or rating
CFInternalErrorException

setRatingList

public int setRatingList(ItemRating[] newRatings)
                  throws java.rmi.RemoteException,
                         CFIllegalListParameterException,
                         CFInternalErrorException
Add a list of new ItemRatings to both database and the cache. Like setRating(), if a rating already exists for a given (user, item), it will be replaced if you specify a new rating for the same (user, item) pair. While ratings are written as fast as possible to the database, they are not guranteed, and if the server crashes, the most recently sent ratings may be lost.

Parameters:
newRatings - a list of new ratings wanted to add
Returns:
numSuccess Returns the number of new ratings that were successfully added to the database
Throws:
java.rmi.RemoteException - Thrown upon client/server connection error
CFIllegalListParameterException - Throws exception if ItemRating[] has invalid contents
CFInternalErrorException

removeRating

public void removeRating(int user,
                         int item)
                  throws java.rmi.RemoteException,
                         CFIllegalParameterException,
                         CFInternalErrorException
Removes rating from both database and cache. If rating doesn't exist, it just returns.

Parameters:
user -
item -
Throws:
java.rmi.RemoteException - Thrown upon client/server connection error
CFIllegalParameterException - Throws exception for out of range user or item
CFInternalErrorException

removeRatingList

public void removeRatingList(int user,
                             int[] itemIDs)
                      throws java.rmi.RemoteException,
                             CFIllegalListParameterException,
                             CFInternalErrorException
Removes list of ratings from users profile. Ratings that do not exist are just ignored.

Parameters:
user -
itemIDs -
Throws:
java.rmi.RemoteException - Thrown upon client/server connection error
CFIllegalListParameterException - Throws exception if userID or itemID are invalid
CFInternalErrorException

getRating

public ItemRating getRating(int userID,
                            int itemID)
                     throws java.rmi.RemoteException,
                            CFIllegalParameterException,
                            CFInternalErrorException
Retrieves one user's rating for a given item. If the user has not rated the item, returns an ItemRating with an ErrRating. @see getErrRating()

Parameters:
userID -
itemID -
Returns:
rating
Throws:
java.rmi.RemoteException - Throws exception when connection to server is lost
CFIllegalParameterException - Throws exception if userID or Item ID are out of range
CFInternalErrorException

getRatingList

public ItemRating[] getRatingList(int userID,
                                  int[] itemIDs)
                           throws java.rmi.RemoteException,
                                  CFIllegalListParameterException,
                                  CFInternalErrorException
Retrieves the ratings by the user for a list of given items. If the user has not rated the item, returns an ItemRating with an ErrRating. @see getErrRating()

Parameters:
userID -
itemIDs -
Returns:
Throws:
java.rmi.RemoteException
CFIllegalListParameterException - Throws exception if userID or itemID[] are invalid
CFInternalErrorException

getPredictedRating

public ItemPrediction getPredictedRating(int userID,
                                         int itemID)
                                  throws java.rmi.RemoteException,
                                         CFIllegalParameterException,
                                         CFInternalErrorException
Get a user's predicted rating for an item. If the CFEngine algorithm cannot predict a rating for any reason, returns an ItemPrediction with an ErrRating. @see getErrRating(). The most common reason for not being able to predict a rating is not having enough information

Parameters:
userID -
itemID -
Returns:
predictedRating
Throws:
java.rmi.RemoteException - Thrown upon client/server connection error
CFIllegalParameterException - Thrown if userID or itemID are out of range
CFInternalErrorException

getRecommendations

public ItemPrediction[] getRecommendations(int curUser,
                                           int number,
                                           int offset)
                                    throws java.rmi.RemoteException,
                                           CFIllegalParameterException,
                                           CFInternalErrorException
Get ten items with high predicted ratings for current user. This method is not guaranteed to be optimal. It may not return the items with the absolutely highest predicted ratings. However, the results it returns should be pretty close. Returns array of size equal to the number of valid predictions in the range requested. If there are no valid recommendations in the specified range, returns 0 length array.

Parameters:
curUser - User to get recommendations for.
number - Number of recommendations to be retrieved.
offset - Returns number of recommendations, starting at the offset
Returns:
ItemPrediction[]
Throws:
java.rmi.RemoteException - Thrown upon client/server connection error
CFIllegalParameterException - Throws exception for invalid curUser, number or offset
CFInternalErrorException

getPredictedRatingList

public ItemPrediction[] getPredictedRatingList(int userID,
                                               int[] itemID)
                                        throws java.rmi.RemoteException,
                                               CFIllegalListParameterException,
                                               CFInternalErrorException
Gets predicted ratings for a list of items. If the server is unable to predict a rating for any reason for a given item, the predicted value will be set to the ErrRating. @see getErrRating()

Parameters:
userID -
itemID - a list of items
Returns:
predictions
Throws:
java.rmi.RemoteException - Thrown upon client/server connection error
CFIllegalListParameterException - Throws exception if userID or itemID[] are invalid
CFInternalErrorException

getUserRatingList

public ItemRating[] getUserRatingList(int userID)
                               throws java.rmi.RemoteException,
                                      CFIllegalParameterException
Return an array of all known ratings for the given user. Note: returns 0 length array if there are no ratings.

Parameters:
userID -
Returns:
an array of itemIDs
Throws:
java.rmi.RemoteException - Thrown upon client/server connection error
CFIllegalParameterException - Throws exception if userID is invalid

getItemRatingList

public ItemRating[] getItemRatingList(int itemID)
                               throws java.rmi.RemoteException,
                                      CFIllegalParameterException
Return an array of all known ratings for the given item. Note: returns 0 length array if there are no ratings.

Parameters:
itemID -
Returns:
an array of userID
Throws:
java.rmi.RemoteException - Thrown upon client/server connection error
CFIllegalParameterException - Throws exception if itemID is out of range

shutdown

public void shutdown()
              throws java.rmi.RemoteException
Shuts the server down.

Throws:
java.rmi.RemoteException

getRecommendationsByType

public ItemPrediction[] getRecommendationsByType(int curUser,
                                                 int number,
                                                 int offset,
                                                 int type)
                                          throws java.rmi.RemoteException,
                                                 CFIllegalParameterException,
                                                 CFInternalErrorException
Get top n recommendations for current user of specific type. Returns array of size equal to the number of valid predictions in the range requested. If there are no valid recommendations in the specified range, returns 0 length array.

Parameters:
curUser - User to get recommendations for.
number - Number of recommendations to be retrieved.
offset - Returns number of recommendations, starting at the offset
type - Catagory to gat recommendations from.
Returns:
ItemPrediction[]
Throws:
java.rmi.RemoteException - Thrown upon client/server connection error
CFIllegalParameterException - Throws exception if curUser,number,offset, or type are out of range
CFInternalErrorException

getMaxRating

public float getMaxRating()
                   throws java.rmi.RemoteException
Get the maximum rating allowed for the current server configuration. This may be useful if you have clients that can adapt to multiple rating ranges.

Returns:
max
Throws:
java.rmi.RemoteException - Thrown upon client/server connection error

getMinRating

public float getMinRating()
                   throws java.rmi.RemoteException
Get the minimum rating allowed for the current server configuration. This may be useful if you have clients that can adapt to multiple rating ranges

Returns:
min
Throws:
java.rmi.RemoteException - Thrown upon client/server connection error

getErrRating

public float getErrRating()
                   throws java.rmi.RemoteException
Get the error rating for the current server configuration. This is the rating that will be returned when a rating or prediction is not available.

Returns:
error rating
Throws:
java.rmi.RemoteException - Thrown upon client/server connection error

getNextUserId

public int getNextUserId()
                  throws java.rmi.RemoteException,
                         CFInternalErrorException
Returns:
An unused integer userid that is guaranteed to be unique now and in the future
java.rmi.RemoteException
CFInternalErrorException

getNextItemId

public int getNextItemId()
                  throws java.rmi.RemoteException,
                         CFInternalErrorException
Returns:
An unused integer itemid that is guaranteed to be unique now and in the future
java.rmi.RemoteException
CFInternalErrorException

getStatistics

public java.lang.String getStatistics()
                               throws java.rmi.RemoteException
Returns:
A string describing key runtime statistics of the CFEngine server, such as cache hit rate
Throws:
java.rmi.RemoteException

CFEngine API

Copyright © 2003 - Oregon State University www.orst.edu