org.apache.mahout.cf.taste.impl.model.jdbc
Class AbstractJDBCDataModel

java.lang.Object
  extended by org.apache.mahout.cf.taste.impl.common.jdbc.AbstractJDBCComponent
      extended by org.apache.mahout.cf.taste.impl.model.jdbc.AbstractJDBCDataModel
All Implemented Interfaces:
java.io.Serializable, Refreshable, DataModel, JDBCDataModel
Direct Known Subclasses:
AbstractBooleanPrefJDBCDataModel, GenericJDBCDataModel, MySQLJDBCDataModel

public abstract class AbstractJDBCDataModel
extends AbstractJDBCComponent
implements JDBCDataModel

An abstract superclass for JDBCDataModel implementations, providing most of the common functionality that any such implementation would need.

Performance will be a concern with any JDBCDataModel. There are going to be lots of simultaneous reads and some writes to one table. Make sure the table is set up optimally -- for example, you'll want to establish indexes.

You'll also want to use connection pooling of some kind. Most J2EE containers like Tomcat provide connection pooling, so make sure the DataSource it exposes is using pooling. Outside a J2EE container, you can use packages like Jakarta's DBCP to create a DataSource on top of your database whose Connections are pooled.

See Also:
Serialized Form

Field Summary
static java.lang.String DEFAULT_ITEM_ID_COLUMN
           
static java.lang.String DEFAULT_PREFERENCE_COLUMN
           
static java.lang.String DEFAULT_PREFERENCE_TABLE
           
static java.lang.String DEFAULT_PREFERENCE_TIME_COLUMN
           
static java.lang.String DEFAULT_USER_ID_COLUMN
           
 
Fields inherited from class org.apache.mahout.cf.taste.impl.common.jdbc.AbstractJDBCComponent
DEFAULT_DATASOURCE_NAME
 
Constructor Summary
protected AbstractJDBCDataModel(javax.sql.DataSource dataSource, java.lang.String getPreferenceSQL, java.lang.String getPreferenceTimeSQL, java.lang.String getUserSQL, java.lang.String getAllUsersSQL, java.lang.String getNumItemsSQL, java.lang.String getNumUsersSQL, java.lang.String setPreferenceSQL, java.lang.String removePreferenceSQL, java.lang.String getUsersSQL, java.lang.String getItemsSQL, java.lang.String getPrefsForItemSQL, java.lang.String getNumPreferenceForItemSQL, java.lang.String getNumPreferenceForItemsSQL, java.lang.String getMaxPreferenceSQL, java.lang.String getMinPreferenceSQL)
           
protected AbstractJDBCDataModel(javax.sql.DataSource dataSource, java.lang.String preferenceTable, java.lang.String userIDColumn, java.lang.String itemIDColumn, java.lang.String preferenceColumn, java.lang.String getPreferenceSQL, java.lang.String getPreferenceTimeSQL, java.lang.String getUserSQL, java.lang.String getAllUsersSQL, java.lang.String getNumItemsSQL, java.lang.String getNumUsersSQL, java.lang.String setPreferenceSQL, java.lang.String removePreferenceSQL, java.lang.String getUsersSQL, java.lang.String getItemsSQL, java.lang.String getPrefsForItemSQL, java.lang.String getNumPreferenceForItemSQL, java.lang.String getNumPreferenceForItemsSQL, java.lang.String getMaxPreferenceSQL, java.lang.String getMinPreferenceSQL)
           
 
Method Summary
protected  Preference buildPreference(java.sql.ResultSet rs)
           
protected  java.util.List<Preference> doGetPreferencesForItem(long itemID)
           
 FastByIDMap<FastIDSet> exportWithIDsOnly()
           
 FastByIDMap<PreferenceArray> exportWithPrefs()
          Hmm, should this exist elsewhere? seems like most relevant for a DB implementation, which is not in memory, which might want to export to memory.
 javax.sql.DataSource getDataSource()
           
 java.lang.String getItemIDColumn()
           
 LongPrimitiveIterator getItemIDs()
           
 FastIDSet getItemIDsFromUser(long id)
           
protected  long getLongColumn(java.sql.ResultSet rs, int position)
          Subclasses may wish to override this if ID values in the file are not numeric.
 float getMaxPreference()
           
 float getMinPreference()
           
 int getNumItems()
           
 int getNumUsers()
           
 int getNumUsersWithPreferenceFor(long... itemIDs)
           
 java.lang.String getPreferenceColumn()
           
 PreferenceArray getPreferencesForItem(long itemID)
           
 PreferenceArray getPreferencesFromUser(long id)
           
 java.lang.String getPreferenceTable()
           
 java.lang.Long getPreferenceTime(long userID, long itemID)
          Retrieves the time at which a preference value from a user and item was set, if known.
 java.lang.Float getPreferenceValue(long userID, long itemID)
          Retrieves the preference value for a single user and item.
 java.lang.String getUserIDColumn()
           
 LongPrimitiveIterator getUserIDs()
           
 boolean hasPreferenceValues()
           
 void refresh(java.util.Collection<Refreshable> alreadyRefreshed)
           Triggers "refresh" -- whatever that means -- of the implementation.
 void removePreference(long userID, long itemID)
           Removes a particular preference for a user.
protected  void setLongParameter(java.sql.PreparedStatement stmt, int position, long value)
          Subclasses may wish to override this if ID values in the file are not numeric.
 void setPreference(long userID, long itemID, float value)
           Sets a particular preference (item plus rating) for a user.
 
Methods inherited from class org.apache.mahout.cf.taste.impl.common.jdbc.AbstractJDBCComponent
advanceResultSet, checkNotNullAndLog, checkNotNullAndLog, getFetchSize, lookupDataSource
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_PREFERENCE_TABLE

public static final java.lang.String DEFAULT_PREFERENCE_TABLE
See Also:
Constant Field Values

DEFAULT_USER_ID_COLUMN

public static final java.lang.String DEFAULT_USER_ID_COLUMN
See Also:
Constant Field Values

DEFAULT_ITEM_ID_COLUMN

public static final java.lang.String DEFAULT_ITEM_ID_COLUMN
See Also:
Constant Field Values

DEFAULT_PREFERENCE_COLUMN

public static final java.lang.String DEFAULT_PREFERENCE_COLUMN
See Also:
Constant Field Values

DEFAULT_PREFERENCE_TIME_COLUMN

public static final java.lang.String DEFAULT_PREFERENCE_TIME_COLUMN
See Also:
Constant Field Values
Constructor Detail

AbstractJDBCDataModel

protected AbstractJDBCDataModel(javax.sql.DataSource dataSource,
                                java.lang.String getPreferenceSQL,
                                java.lang.String getPreferenceTimeSQL,
                                java.lang.String getUserSQL,
                                java.lang.String getAllUsersSQL,
                                java.lang.String getNumItemsSQL,
                                java.lang.String getNumUsersSQL,
                                java.lang.String setPreferenceSQL,
                                java.lang.String removePreferenceSQL,
                                java.lang.String getUsersSQL,
                                java.lang.String getItemsSQL,
                                java.lang.String getPrefsForItemSQL,
                                java.lang.String getNumPreferenceForItemSQL,
                                java.lang.String getNumPreferenceForItemsSQL,
                                java.lang.String getMaxPreferenceSQL,
                                java.lang.String getMinPreferenceSQL)

AbstractJDBCDataModel

protected AbstractJDBCDataModel(javax.sql.DataSource dataSource,
                                java.lang.String preferenceTable,
                                java.lang.String userIDColumn,
                                java.lang.String itemIDColumn,
                                java.lang.String preferenceColumn,
                                java.lang.String getPreferenceSQL,
                                java.lang.String getPreferenceTimeSQL,
                                java.lang.String getUserSQL,
                                java.lang.String getAllUsersSQL,
                                java.lang.String getNumItemsSQL,
                                java.lang.String getNumUsersSQL,
                                java.lang.String setPreferenceSQL,
                                java.lang.String removePreferenceSQL,
                                java.lang.String getUsersSQL,
                                java.lang.String getItemsSQL,
                                java.lang.String getPrefsForItemSQL,
                                java.lang.String getNumPreferenceForItemSQL,
                                java.lang.String getNumPreferenceForItemsSQL,
                                java.lang.String getMaxPreferenceSQL,
                                java.lang.String getMinPreferenceSQL)
Method Detail

getDataSource

public javax.sql.DataSource getDataSource()
Specified by:
getDataSource in interface JDBCDataModel
Returns:
the DataSource that this instance is using

getPreferenceTable

public java.lang.String getPreferenceTable()

getUserIDColumn

public java.lang.String getUserIDColumn()

getItemIDColumn

public java.lang.String getItemIDColumn()

getPreferenceColumn

public java.lang.String getPreferenceColumn()

getUserIDs

public LongPrimitiveIterator getUserIDs()
                                 throws TasteException
Specified by:
getUserIDs in interface DataModel
Returns:
all user IDs in the model, in order
Throws:
TasteException - if an error occurs while accessing the data

getPreferencesFromUser

public PreferenceArray getPreferencesFromUser(long id)
                                       throws TasteException
Specified by:
getPreferencesFromUser in interface DataModel
Parameters:
id - ID of user to get prefs for
Returns:
user's preferences, ordered by item ID
Throws:
NoSuchUserException - if there is no such user
TasteException - if an error occurs while accessing the data

exportWithPrefs

public FastByIDMap<PreferenceArray> exportWithPrefs()
                                             throws TasteException
Description copied from interface: JDBCDataModel
Hmm, should this exist elsewhere? seems like most relevant for a DB implementation, which is not in memory, which might want to export to memory.

Specified by:
exportWithPrefs in interface JDBCDataModel
Returns:
all user preference data
Throws:
TasteException

exportWithIDsOnly

public FastByIDMap<FastIDSet> exportWithIDsOnly()
                                         throws TasteException
Specified by:
exportWithIDsOnly in interface JDBCDataModel
Throws:
TasteException

getItemIDsFromUser

public FastIDSet getItemIDsFromUser(long id)
                             throws TasteException
Specified by:
getItemIDsFromUser in interface DataModel
Parameters:
id - ID of user to get prefs for
Returns:
IDs of items user expresses a preference for
Throws:
NoSuchUserException - if there is no such user
TasteException - if an error occurs while accessing the data

getPreferenceValue

public java.lang.Float getPreferenceValue(long userID,
                                          long itemID)
                                   throws TasteException
Description copied from interface: DataModel
Retrieves the preference value for a single user and item.

Specified by:
getPreferenceValue in interface DataModel
Parameters:
userID - user ID to get pref value from
itemID - item ID to get pref value for
Returns:
preference value from the given user for the given item or null if none exists
Throws:
NoSuchUserException - if the user does not exist
TasteException - if an error occurs while accessing the data

getPreferenceTime

public java.lang.Long getPreferenceTime(long userID,
                                        long itemID)
                                 throws TasteException
Description copied from interface: DataModel
Retrieves the time at which a preference value from a user and item was set, if known. Time is expressed in the usual way, as a number of milliseconds since the epoch.

Specified by:
getPreferenceTime in interface DataModel
Parameters:
userID - user ID for preference in question
itemID - item ID for preference in question
Returns:
time at which preference was set or null if no preference exists or its time is not known
Throws:
NoSuchUserException - if the user does not exist
TasteException - if an error occurs while accessing the data

getItemIDs

public LongPrimitiveIterator getItemIDs()
                                 throws TasteException
Specified by:
getItemIDs in interface DataModel
Returns:
a LongPrimitiveIterator of all item IDs in the model, in order
Throws:
TasteException - if an error occurs while accessing the data

getPreferencesForItem

public PreferenceArray getPreferencesForItem(long itemID)
                                      throws TasteException
Specified by:
getPreferencesForItem in interface DataModel
Parameters:
itemID - item ID
Returns:
all existing Preferences expressed for that item, ordered by user ID, as an array
Throws:
NoSuchItemException - if the item does not exist
TasteException - if an error occurs while accessing the data

doGetPreferencesForItem

protected java.util.List<Preference> doGetPreferencesForItem(long itemID)
                                                      throws TasteException
Throws:
TasteException

getNumItems

public int getNumItems()
                throws TasteException
Specified by:
getNumItems in interface DataModel
Returns:
total number of items known to the model. This is generally the union of all items preferred by at least one user but could include more.
Throws:
TasteException - if an error occurs while accessing the data

getNumUsers

public int getNumUsers()
                throws TasteException
Specified by:
getNumUsers in interface DataModel
Returns:
total number of users known to the model.
Throws:
TasteException - if an error occurs while accessing the data

getNumUsersWithPreferenceFor

public int getNumUsersWithPreferenceFor(long... itemIDs)
                                 throws TasteException
Specified by:
getNumUsersWithPreferenceFor in interface DataModel
Parameters:
itemIDs - item IDs to check for
Returns:
the number of users who have expressed a preference for all of the items
Throws:
TasteException - if an error occurs while accessing the data

setPreference

public void setPreference(long userID,
                          long itemID,
                          float value)
                   throws TasteException
Description copied from interface: DataModel

Sets a particular preference (item plus rating) for a user.

Specified by:
setPreference in interface DataModel
Parameters:
userID - user to set preference for
itemID - item to set preference for
value - preference value
Throws:
NoSuchItemException - if the item does not exist
NoSuchUserException - if the user does not exist
TasteException - if an error occurs while accessing the data

removePreference

public void removePreference(long userID,
                             long itemID)
                      throws TasteException
Description copied from interface: DataModel

Removes a particular preference for a user.

Specified by:
removePreference in interface DataModel
Parameters:
userID - user from which to remove preference
itemID - item to remove preference for
Throws:
NoSuchItemException - if the item does not exist
NoSuchUserException - if the user does not exist
TasteException - if an error occurs while accessing the data

refresh

public void refresh(java.util.Collection<Refreshable> alreadyRefreshed)
Description copied from interface: Refreshable

Triggers "refresh" -- whatever that means -- of the implementation. The general contract is that any should always leave itself in a consistent, operational state, and that the refresh atomically updates internal state from old to new.

Specified by:
refresh in interface Refreshable
Parameters:
alreadyRefreshed - s that are known to have already been refreshed as a result of an initial call to a method on some object. This ensure that objects in a refresh dependency graph aren't refreshed twice needlessly.

hasPreferenceValues

public boolean hasPreferenceValues()
Specified by:
hasPreferenceValues in interface DataModel
Returns:
true iff this implementation actually stores and returns distinct preference values; that is, if it is not a 'boolean' DataModel

getMaxPreference

public float getMaxPreference()
Specified by:
getMaxPreference in interface DataModel
Returns:
the maximum preference value that is possible in the current problem domain being evaluated. For example, if the domain is movie ratings on a scale of 1 to 5, this should be 5. While a Recommender may estimate a preference value above 5.0, it isn't "fair" to consider that the system is actually suggesting an impossible rating of, say, 5.4 stars. In practice the application would cap this estimate to 5.0. Since evaluators evaluate the difference between estimated and actual value, this at least prevents this effect from unfairly penalizing a Recommender

getMinPreference

public float getMinPreference()
Specified by:
getMinPreference in interface DataModel
See Also:
DataModel.getMaxPreference()

buildPreference

protected Preference buildPreference(java.sql.ResultSet rs)
                              throws java.sql.SQLException
Throws:
java.sql.SQLException

getLongColumn

protected long getLongColumn(java.sql.ResultSet rs,
                             int position)
                      throws java.sql.SQLException
Subclasses may wish to override this if ID values in the file are not numeric. This provides a hook by which subclasses can inject an IDMigrator to perform translation.

Throws:
java.sql.SQLException

setLongParameter

protected void setLongParameter(java.sql.PreparedStatement stmt,
                                int position,
                                long value)
                         throws java.sql.SQLException
Subclasses may wish to override this if ID values in the file are not numeric. This provides a hook by which subclasses can inject an IDMigrator to perform translation.

Throws:
java.sql.SQLException


Copyright © 2008-2010 The Apache Software Foundation. All Rights Reserved.