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

    java.lang.Object
      org.apache.mahout.cf.taste.impl.common.jdbc.AbstractJDBCComponent
          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 `Connection`s 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 `Preference`s 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.