net.user1.union.api
Interface Datasource

public interface Datasource

A Datasource saves/retrieves persistent information on the server.

Method Summary

boolean	containsAccount(java.lang.String userID) Asks the datasource if the account exists for the given userID.
java.lang.String	createAccount(java.lang.String userID, java.lang.String password) Create an account on the server.
java.util.List<java.lang.String>	getAccounts() Returns a list of the userIDs for all persistent accounts.
java.lang.String	getPassword(java.lang.String userID) Return the password for the given userID.
boolean	init(DatasourceContext ctx) Called when the datasource is initialized by the server.
void	loadAccount(Account account) Load the account fields from the persistent storage.
void	loadAccountGlobalAttributes(Account account) The datasource should load any global attributes it has for the account by setting them on the account.
void	loadAccountRoomAttributes(Account account, java.lang.String roomID) Load the account attributes for the specified room.
void	loadAllAccountAttributes(Account account) The datasource should load all account attributes it has for the account.
void	loadRoomAttributes(Room room) Called when a room is created.
void	loadServerAttributes(Server server) Called when the server starts.
java.lang.String	removeAccount(java.lang.String userID) Remove an account.
void	removeAccountAttribute(Account account, Attribute attribute) Remove an account attribute.
void	removeRoomAttribute(Room room, Attribute attribute) Remove a room attribute.
void	removeServerAttribute(Attribute attribute) Remove a server attribute.
java.lang.String	saveAccount(Account account) Save an existing account to the server.
void	saveAccountAttribute(Account account, Attribute attribute) Save an account attribute.
void	saveRoomAttribute(Room room, Attribute attribute) Save a room attribute.
void	saveServerAttribute(Attribute attribute) Save a server attribute.
void	shutdown() Called when the datasource is shutdown.

Method Detail

init

boolean init(DatasourceContext ctx)

Called when the datasource is initialized by the server.

Parameters:

ctx - a context for the Datasource to run in

Returns:

false if the datasource failed to initialize, otherwise true.

shutdown

void shutdown()

Called when the datasource is shutdown. Use this method to cleanup any resources created by the datasource.

createAccount

java.lang.String createAccount(java.lang.String userID,
                               java.lang.String password)
                               throws DatasourceException

Create an account on the server.

Parameters:

userID - the userID for the account

password - the password of the account

Returns:

Status.SUCCESS - the account was created

Throws:

DatasourceException - an Exception occurred in the datasource

containsAccount

boolean containsAccount(java.lang.String userID)
                        throws DatasourceException

Asks the datasource if the account exists for the given userID.

Parameters:

userID - the userID of the account

Returns:

true if the datasource contains the account with the userID

Throws:

DatasourceException - an Exception occurred in the datasource

saveAccount

java.lang.String saveAccount(Account account)
                             throws DatasourceException

Save an existing account to the server. Called when an account has changed (eg. an account has become a moderator).

Parameters:

account - - the account to save

Returns:

Status.SUCCESS - the account was saved

Throws:

DatasourceException - an Exception occurred in the datasource

getPassword

java.lang.String getPassword(java.lang.String userID)
                             throws DatasourceException

Return the password for the given userID.

Parameters:

userID - the userID of the account

Throws:

DatasourceException - an Exception occurred in the datasource

loadAllAccountAttributes

void loadAllAccountAttributes(Account account)
                              throws DatasourceException

The datasource should load all account attributes it has for the account.

Parameters:

account -

Throws:

DatasourceException

loadAccountGlobalAttributes

void loadAccountGlobalAttributes(Account account)
                                 throws DatasourceException

The datasource should load any global attributes it has for the account by setting them on the account.

Parameters:

account - the account that has logged in

Throws:

DatasourceException - an Exception occurred in the datasource

loadAccountRoomAttributes

void loadAccountRoomAttributes(Account account,
                               java.lang.String roomID)
                               throws DatasourceException

Load the account attributes for the specified room. Called when the accont joins the room or if the scoped attributes are requested.

Parameters:

account - the account for the client

roomID - the ID of the room (i.e. the scope)

Throws:

DatasourceException

saveAccountAttribute

void saveAccountAttribute(Account account,
                          Attribute attribute)
                          throws DatasourceException

Save an account attribute.

Parameters:

account - the account

attribute - the attribute to save

Throws:

DatasourceException - an Exception occurred in the datasource

removeAccountAttribute

void removeAccountAttribute(Account account,
                            Attribute attribute)
                            throws DatasourceException

Remove an account attribute.

Parameters:

account - the account

attribute - the attribute to remove

Throws:

DatasourceException - an Exception occurred in the datasource

loadAccount

void loadAccount(Account account)
                 throws DatasourceException

Load the account fields from the persistent storage. Note: this does not apply to attributes which are loaded in a separate call. Load direct Account information only (eg. moderator status).

Parameters:

account - - the account to load

Throws:

DatasourceException - an Exception occurred in the datasource

removeAccount

java.lang.String removeAccount(java.lang.String userID)
                               throws DatasourceException

Remove an account.

Parameters:

userID - the userID of the account

password - the password of the account

Returns:

Status.SUCCESS - the account was removed

Throws:

DatasourceException - an Exception occurred in the datasource

getAccounts

java.util.List<java.lang.String> getAccounts()
                                             throws DatasourceException

Returns a list of the userIDs for all persistent accounts.

Returns:

a list of the userIDs for all persistent accounts

Throws:

DatasourceException - an Exception occurred in the datasource

loadRoomAttributes

void loadRoomAttributes(Room room)
                        throws DatasourceException

Called when a room is created. The datasource should set any persistent attribtues it has for the room. Datasources that have a record for the room can set a room attribute that saves the primary key for the room record rather than looking up the record each time. Non-existence for the attribute would then also indicate that the datasource needs to save the room record. Datasources that do not have a room record, and therefore no room attributes, can simply return from this method.

Parameters:

room - the room

Throws:

DatasourceException

saveRoomAttribute

void saveRoomAttribute(Room room,
                       Attribute attribute)
                       throws DatasourceException

Save a room attribute.

Parameters:

room - the room

attribute - the attribute to save

Throws:

DatasourceException - an Exception occurred in the datasource

removeRoomAttribute

void removeRoomAttribute(Room room,
                         Attribute attribute)
                         throws DatasourceException

Remove a room attribute.

Parameters:

room - the room

attribute - the attribute to remove

Throws:

DatasourceException - an Exception occurred in the datasource

saveServerAttribute

void saveServerAttribute(Attribute attribute)
                         throws DatasourceException

Save a server attribute.

Parameters:

room - the room

Throws:

DatasourceException - an Exception occurred in the datasource

removeServerAttribute

void removeServerAttribute(Attribute attribute)
                           throws DatasourceException

Remove a server attribute.

Parameters:

attribute - the attribute to remove

Throws:

DatasourceException - an Exception occurred in the datasource

loadServerAttributes

void loadServerAttributes(Server server)
                          throws DatasourceException

Called when the server starts. The datasource should set any persistent server attributes it has.

Parameters:

server - the server

Throws:

DatasourceException