Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.starhope.appius.user
Class UserRecordSQLLoader

java.lang.Object
  extended by org.starhope.appius.user.UserRecordSQLLoader
All Implemented Interfaces:
SQLLoader<UserRecord>, UserRecordLoader, RecordLoader<UserRecord>, HasSubversionRevision
public class UserRecordSQLLoader
extends Object
implements SQLLoader<UserRecord>, UserRecordLoader

User Record

The User Record is the canonical storage for all things that describe a character in the game world; this is the “character sheet.” An User Record may describe a player-character, an NPC, or even a non-character that acts in some way like an user, e.g. an intelligent object driven by a script, which logically acts as an NPC, but is essentially not.

Every user-like object is required to implement AbstractUser, which provides an enormous number of accessor methods to the data defined by an UserRecord. While there is no requirement that any given Abstract User implementation must use a UserRecord for its backing store, it is extremely strongly recommended that they should do so.

Migration

If migrating with default (Tootsville™-like) table layouts from Appius 1.0 to Appius 1.1, you'll need to execute the following DDL instructions on your database server to update the table structures. Note that “avatarID” was never used by Appius Claudius Cæcus, however, the sample SQL table structures distributed with 0.8 through 1.0 had this column in place. (Appius has always used the avatarClass column exclusively.)

It is believed that removing the “classID” column should also be harmless, however, there may be some reference to it in the codebase still. The contents of the “classID” column have never been used by Appius directly, however, the contents of that column should indicate the version of Appius which last wrote to the database. Early versions of Appius (0.x.x) wrote a classID of -3; Appius 1.0.x wrote -4; and this series (1.1.x) writes -5. 

 ALTER TABLE users ADD COLUMN travelRate DECIMAL(5,2) UNSIGNED NOT NULL DEFAULT 100.00;
 ALTER TABLE users ADD COLUMN parentApprovedName ENUM('Y','N') NOT NULL DEFAULT 'N';
 ALTER TABLE users ADD COLUMN lastZoneName VARCHAR(50) NOT NULL DEFAULT '';
 ALTER TABLE users DROP COLUMN avatarID;

Author:
brpocock@star-hope.org, twheys@gmail.com, edward.winkelman@gmail.com

Field Summary
private static int CLASS_ID_CURRENT
          The Class ID for user records created or updated by this loader.
private static String SAVE_RECORD_SQL
          The SQL statement for inserting or updating user records
 
Constructor Summary
UserRecordSQLLoader()
           
 
Method Summary
 void changed(UserRecord changedRecord)
          accept a notification from a record that it has been changed.
protected static void fetch_avatarInfo(UserRecord userRecord, ResultSet resultSet)
          Fetch the user's avatar information from the database
protected static void fetch_chatColours(UserRecord userRecord, ResultSet resultSet)
          Fetch the chat colours for this user from the database
protected static void fetch_dobInfo(UserRecord userRecord, ResultSet resultSet)
          Fetch the user's date of birth and related information from the database record provided
protected static void fetch_language(UserRecord userRecord, ResultSet resultSet)
          Fetch the user's language and dialect information from the database record
protected static void fetch_laston(UserRecord userRecord)
          Fetch the user's last activity information from the database record
protected static void fetch_mailInfo(UserRecord userRecord, ResultSet resultSet)
          Fetch the user's eMail info from the database record
protected  void fetch_more(ResultSet resultSet)
          Fetch additional results fields from a database record — mostly intended to be overridden by derived classes
protected static void fetch_parentInfo(UserRecord userRecord, ResultSet resultSet)
          Fetch information about the user's parent (if any).
protected static void fetch_passwordResetInfo(UserRecord userRecord, ResultSet resultSet)
          Fetch the password reset question and answer from the provided database record.
protected static void fetch_permissionsInfo(UserRecord userRecord, ResultSet resultSet)
          Fetch the permissions-related portion of a user's record out of the SQL ResultSet.
protected static void fetch_userBasicInfo(UserRecord userRecord, ResultSet resultSet)
          Fetch the user's basic information: user ID, user name, and password — from the provided database record
 String getSubversionRevision()
           Return the Subversion revision level of this class's source code file, as supplied via the special "$Rev: " sequence.
 void initializeStorage(String storageURL)
          Initialize the database connection pool to be used for accessing user records.
 boolean isRealtime()
           
 UserRecord loadRecord(int id)
          Load the record with the given ID number from the storage system
 UserRecord loadRecord(String identifier)
          Load the data record identified from the storage system.
 void refresh(UserRecord record)
          Refreshes the record: Re-read the contents of the database into the given record.
protected  UserRecord reload(ResultSet resultSet, UserRecord userRecord)
          WRITEME: Document this method brpocock@star-hope.org
 void removeRecord(UserRecord record)
           
 void saveRecord(UserRecord r)
          Save a record back to the storage system
protected  UserRecord set(ResultSet resultSet)
          WRITEME: Document this method brpocock@star-hope.org
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CLASS_ID_CURRENT

private static final int CLASS_ID_CURRENT
The Class ID for user records created or updated by this loader. For debugging purposes only; the classID column is no longer read.

See Also:
Constant Field Values

SAVE_RECORD_SQL

private static final String SAVE_RECORD_SQL
The SQL statement for inserting or updating user records

See Also:
Constant Field Values
Constructor Detail

UserRecordSQLLoader

public UserRecordSQLLoader()
Method Detail

fetch_avatarInfo

protected static void fetch_avatarInfo(UserRecord userRecord,
                                       ResultSet resultSet)
                                throws SQLException
Fetch the user's avatar information from the database

Parameters:
userRecord - The UserRecord being serviced
resultSet - database record to interpret
Throws:
SQLException - if the record can't be interpreted

fetch_chatColours

protected static void fetch_chatColours(UserRecord userRecord,
                                        ResultSet resultSet)
                                 throws SQLException
Fetch the chat colours for this user from the database

Parameters:
userRecord - The UserRecord being serviced
resultSet - database record to interpret
Throws:
SQLException - if the record can't be interpreted

fetch_dobInfo

protected static void fetch_dobInfo(UserRecord userRecord,
                                    ResultSet resultSet)
                             throws SQLException
Fetch the user's date of birth and related information from the database record provided

Parameters:
userRecord - The UserRecord being serviced
resultSet - database record to interpret
Throws:
SQLException - if the record can't be interpreted

fetch_language

protected static void fetch_language(UserRecord userRecord,
                                     ResultSet resultSet)
                              throws SQLException
Fetch the user's language and dialect information from the database record

Parameters:
userRecord - The UserRecord being serviced
resultSet - the database record from which to be loaded
Throws:
SQLException - if the record can't be interpreted

fetch_laston

protected static void fetch_laston(UserRecord userRecord)
                            throws SQLException
Fetch the user's last activity information from the database record

Parameters:
userRecord - record being loaded
Throws:
SQLException - if the record can't be interpreted.

fetch_mailInfo

protected static void fetch_mailInfo(UserRecord userRecord,
                                     ResultSet resultSet)
                              throws SQLException
Fetch the user's eMail info from the database record

Parameters:
userRecord - The UserRecord being serviced
resultSet - database record to interpret
Throws:
SQLException - if the record can't be interpreted

fetch_parentInfo

protected static void fetch_parentInfo(UserRecord userRecord,
                                       ResultSet resultSet)
                                throws SQLException
Fetch information about the user's parent (if any).

Parameters:
userRecord - The UserRecord being serviced
resultSet - database record to interpret
Throws:
SQLException - if the record can't be interpreted

fetch_passwordResetInfo

protected static void fetch_passwordResetInfo(UserRecord userRecord,
                                              ResultSet resultSet)
                                       throws SQLException
Fetch the password reset question and answer from the provided database record.

Parameters:
userRecord - The UserRecord being serviced
resultSet - the database record
Throws:
SQLException - If the records can't be found, or are in an invalid format of some kind

fetch_permissionsInfo

protected static void fetch_permissionsInfo(UserRecord userRecord,
                                            ResultSet resultSet)
                                     throws SQLException
Fetch the permissions-related portion of a user's record out of the SQL ResultSet. Used while populating the record from the database.

Parameters:
userRecord - The UserRecord being serviced
resultSet - The ResultSet being used to set the user up.
Throws:
SQLException - if the data in the record can't be interpreted.

fetch_userBasicInfo

protected static void fetch_userBasicInfo(UserRecord userRecord,
                                          ResultSet resultSet)
                                   throws SQLException
Fetch the user's basic information: user ID, user name, and password — from the provided database record

Parameters:
userRecord - The UserRecord being serviced
resultSet - database record to interpret
Throws:
SQLException - if the record can't be interpreted

changed

public void changed(UserRecord changedRecord)
Description copied from interface: RecordLoader
accept a notification from a record that it has been changed.

Specified by:
changed in interface RecordLoader<UserRecord>
Parameters:
changedRecord - the record that has been changed
See Also:
RecordLoader.changed(org.starhope.appius.util.DataRecord)

fetch_more

protected void fetch_more(ResultSet resultSet)
                   throws SQLException
Fetch additional results fields from a database record — mostly intended to be overridden by derived classes

Parameters:
resultSet - the user record
Throws:
SQLException - if the record can't be interpreted

getSubversionRevision

public String getSubversionRevision()
Description copied from interface: HasSubversionRevision

Return the Subversion revision level of this class's source code file, as supplied via the special "$Rev: " sequence.

As an example,the Subversion revision string for this file is "$Rev: 1968 $" 

 
 @Override
 public String getSubversionRevision () {
        return "$Rev: ";
 }

Specified by:
getSubversionRevision in interface HasSubversionRevision
Returns:
The Subversion revision level for this class's source code file.
See Also:
HasSubversionRevision.getSubversionRevision()

initializeStorage

public void initializeStorage(String storageURL)
                       throws NotReadyException
Initialize the database connection pool to be used for accessing user records. The “storageURL” parameter is ignored

Specified by:
initializeStorage in interface RecordLoader<UserRecord>
Parameters:
storageURL - A URL or identifier of the storage engine. The syntax is specific to the RecordLoader implementation.
Throws:
NotReadyException - if the database can't be accessed
See Also:
RecordLoader.initializeStorage(java.lang.String)

isRealtime

public boolean isRealtime()
Specified by:
isRealtime in interface RecordLoader<UserRecord>
Returns:
true, if this is a type that requires realtime performance on changes. Note that I/O bound storage such as SQL database saves and file writes will generally return false, whereas RPC mirroring will probably want to return true, unless latency is not an issue.
See Also:
RecordLoader.isRealtime()

loadRecord

public UserRecord loadRecord(int id)
Description copied from interface: RecordLoader
Load the record with the given ID number from the storage system

Specified by:
loadRecord in interface RecordLoader<UserRecord>
Parameters:
id - the ID number for the record
Returns:
the data record in question
See Also:
RecordLoader.loadRecord(int)

loadRecord

public UserRecord loadRecord(String identifier)
Description copied from interface: RecordLoader
Load the data record identified from the storage system. The format and interpretation of the identifier is specific to the data record type, but must be a guaranteed-unique

Specified by:
loadRecord in interface RecordLoader<UserRecord>
Parameters:
identifier - the identifier for the record
Returns:
the data record in question
See Also:
RecordLoader.loadRecord(java.lang.String)

refresh

public void refresh(UserRecord record)
Description copied from interface: RecordLoader
Refreshes the record: Re-read the contents of the database into the given record. This is a rather cruel hack to work around some of the legacy tools in Tootsville™ that aren't hooked into the game server properly, and might be fiddling around with the SQL backing-store directly. This works together with e.g. SimpleDataRecord.checkStale() to try to reload data when it might have been changed: it's trading elegance and efficiency for expediency, but eventually, it should be removed.

Specified by:
refresh in interface RecordLoader<UserRecord>
Parameters:
record - the record to be reloaded.
See Also:
RecordLoader.refresh(org.starhope.appius.util.DataRecord)

reload

protected UserRecord reload(ResultSet resultSet,
                            UserRecord userRecord)
                     throws SQLException
WRITEME: Document this method brpocock@star-hope.org

Parameters:
resultSet - WRITEME
userRecord - WRITEME
Returns:
WRITEME
Throws:
SQLException - WRITEME

removeRecord

public void removeRecord(UserRecord record)
Specified by:
removeRecord in interface RecordLoader<UserRecord>
Parameters:
record - Record to be deleted/removed
See Also:
RecordLoader.removeRecord(org.starhope.appius.util.DataRecord)

saveRecord

public void saveRecord(UserRecord r)
Description copied from interface: RecordLoader
Save a record back to the storage system

Specified by:
saveRecord in interface RecordLoader<UserRecord>
Parameters:
r - the record to be saved
See Also:
RecordLoader.saveRecord(org.starhope.appius.util.DataRecord)

set

protected UserRecord set(ResultSet resultSet)
                  throws SQLException
WRITEME: Document this method brpocock@star-hope.org

Parameters:
resultSet - WRITEME
Returns:
userRecord The UserRecord been loaded
Throws:
SQLException - WRITEME
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD