net.user1.union.api
Interface Server

All Superinterfaces:

AttributeHolder, EventProducer, RemoteEventProducer

public interface Server
extends AttributeHolder, RemoteEventProducer

The server is the container for all other objects in the server.

Method Summary

java.lang.String	changeAccountPassword(java.lang.String userID, java.lang.String oldPassword, java.lang.String newPassword) Change the password for an account
void	clearAccountCache() For efficiency Union uses a cache for recently used Accounts.
boolean	containsAccount(java.lang.String userID) Returns true if the server has an account (logged in or not) for the userID.
boolean	containsClient(java.lang.String clientID) Returns true if a client with the given ID exists on the server.
boolean	containsRoom(java.lang.String roomID) Returns true if a room with the given ID exists on the server.
java.lang.String	createAccount(java.lang.String userID, java.lang.String password) Create an account on the server.
Module	createModule(ModuleDef moduleDef) Creates the module based on the given ModuleDef.
Room	createRoom(RoomDef def) Creates a room based on the given RoomDef.
Account	getAccount(java.lang.String userID) Returns the account for the given userID.
Client	getClient(java.lang.String clientID) Gets the client with the given ID.
Client	getClientByUserID(java.lang.String userID) Gets the client with the given userID if the client is currently logged in.
java.util.Set<Client>	getClients() Return a set of the clients currently on the server.
Cluster	getCluster() Returns access to the Cluster API.
Request	getCurrentRequest() Get the current request being processed.
int	getLifetimeNumClients() Returns the total number of lifetime connections to the server.
int	getLifetimeNumRooms() Returns the total number of lifetime rooms created on the server.
Module	getModule(java.lang.String moduleID) Get the module with the given ID.
int	getNumClients() Returns the total number of clients on the server.
int	getNumClientsTotal(java.lang.String qualifier) Returns the total number of clients in the given qualifier.
int	getNumClientsUnique(java.lang.String qualifier) Returns the total number of unique clients in the given qualifier.
int	getNumRooms() Returns the total number of rooms on the server.
Room	getRoom(java.lang.String roomID) Gets a room that is on the server.
java.util.List<? extends Room>	getRooms() Get a list of all rooms on the server.
java.util.List<? extends Room>	getRooms(java.lang.String qualifier) Get a list of rooms on the server that are in the given qualifier.
Security	getSecurity() Returns access to the Security API.
long	getStartTime() Returns the System time (System.currenTimeMillis()) the server was started.
UPCProcessor	getUPCMessageProcessor() Returns access to the UPCMessageProcessor API.
java.util.List<java.lang.String>	getUsers() Returns a list of userIDs for all accounts on the server.
java.lang.String	getVersion() Returns the version of Union.
boolean	isAccountOnline(java.lang.String userID) Returns true if the account given by the userID is currently logged in.
boolean	isShutdown() Returns true if the server is shutdown.
java.lang.String	removeAccount(java.lang.String userID, java.lang.String password) Remove an account from the server.
void	sendMessage(Filter filter, java.lang.String message, java.lang.String... args) This generates a u7 which is sent to all clients on the server.
void	sendMessage(java.lang.String message, java.lang.String... args) This generates a u7 which is sent to all clients on the server.
void	shutdownModule(java.lang.String moduleID) Shuts down the module with the given ID.
java.lang.String	shutdownRoom(java.lang.String roomID, java.lang.String password) Shuts down the room and removes it from the Server.
void	shutdownServer() Stops the server.

Methods inherited from interface net.user1.union.core.attribute.AttributeHolder

getAttribute, getAttribute, getAttributes, getAttributes, getAttributesByScope, getAttributeValue, getAttributeValue, onChangeAttribute, onRemoveAttribute, removeAttribute, removeAttribute, setAttribute

Methods inherited from interface net.user1.union.core.event.RemoteEventProducer

addRemoteEventListener, dispatchRemoteEvent, dispatchRemoteEvent, getRemoteEventClassMap, removeRemoteEventListener

Methods inherited from interface net.user1.union.core.event.EventProducer

addEventListener, dispatchEvent, getEventClassMap, removeEventListener

Method Detail

sendMessage

void sendMessage(java.lang.String message,
                 java.lang.String... args)

This generates a u7 which is sent to all clients on the server. It is similar to when a u57 is sent by a client.

Parameters:

message - the name of the message

args - the args to be sent with the message

sendMessage

void sendMessage(Filter filter,
                 java.lang.String message,
                 java.lang.String... args)

This generates a u7 which is sent to all clients on the server. It is similar to when a u57 is sent by a client. Only clients that meet the requirements in the Filter will receive the message.

Parameters:

filter - the filter to be used to determine if the client should receive the message

message - the name of the message

args - the args to be sent with the message

isShutdown

boolean isShutdown()

Returns true if the server is shutdown.

Returns:

true if the server is shutdown

getRoom

Room getRoom(java.lang.String roomID)
             throws RoomNotFoundException

Gets a room that is on the server.

Parameters:

roomID - the roomID of the room to get

Returns:

the room specified

Throws:

RoomNotFoundException

getRooms

java.util.List<? extends Room> getRooms()

Get a list of all rooms on the server.

Returns:

a list of all rooms on the server

getRooms

java.util.List<? extends Room> getRooms(java.lang.String qualifier)

Get a list of rooms on the server that are in the given qualifier. This method is not recursive and only rooms with the exact qualifier will be included. For example: given the qualifier "games" the room "games.Pong" will be included in the set but "games.team.Soccer" would not.

Parameters:

qualifier - the qualifier the rooms must have to be included in the set

Returns:

a list of rooms on the server that are in the given qualifier

createRoom

Room createRoom(RoomDef def)
                throws RoomAlreadyExistsException,
                       CreateRoomException

Creates a room based on the given RoomDef.

Parameters:

def - the definition of the room

Returns:

a reference to the room created

Throws:

RoomAlreadyExistsException

CreateRoomException

shutdownRoom

java.lang.String shutdownRoom(java.lang.String roomID,
                              java.lang.String password)
                              throws RoomNotFoundException

Shuts down the room and removes it from the Server.

Parameters:

roomID - the room to shutdown

password - the password for the room (only used if the room requires a password)

Returns:

Status.SUCCESS - the room was shutdown

Throws:

RoomNotFoundException

containsRoom

boolean containsRoom(java.lang.String roomID)

Returns true if a room with the given ID exists on the server.

Returns:

true if a room with the given ID exists on the server

containsClient

boolean containsClient(java.lang.String clientID)

Returns true if a client with the given ID exists on the server.

Returns:

true if a client with the given ID exists on the server.

getClients

java.util.Set<Client> getClients()

Return a set of the clients currently on the server.

Returns:

a set of the clients currently on the server

getClient

Client getClient(java.lang.String clientID)
                 throws ClientNotFoundException

Gets the client with the given ID.

Parameters:

clientID - the ID of the client to get

Returns:

the client with the given ID

Throws:

ClientNotFoundException

getClientByUserID

Client getClientByUserID(java.lang.String userID)
                         throws ClientNotFoundException

Gets the client with the given userID if the client is currently logged in. If no client is currently logged in with that userID a ClientNotFoundException is thrown.

Parameters:

userID - the uesrID of the client to get

Returns:

the client with the given userID

Throws:

ClientNotFoundException

createModule

Module createModule(ModuleDef moduleDef)
                    throws ModuleAlreadyExistsException,
                           CreateModuleException

Creates the module based on the given ModuleDef.

Parameters:

moduleDef - the ModuleDef to use when creating the module.

Returns:

the module that was created

Throws:

ModuleAlreadyExistsException

CreateModuleException

getModule

Module getModule(java.lang.String moduleID)
                 throws ModuleNotFoundException

Get the module with the given ID.

Parameters:

moduleID - the ID of the module to get

Returns:

the module with the given ID

Throws:

ModuleNotFoundException

shutdownModule

void shutdownModule(java.lang.String moduleID)
                    throws ModuleNotFoundException

Shuts down the module with the given ID.

Parameters:

moduleID - the ID of the module to be shutdown

Throws:

ModuleNotFoundException

getVersion

java.lang.String getVersion()

Returns the version of Union.

Returns:

the version of Union

getStartTime

long getStartTime()

Returns the System time (System.currenTimeMillis()) the server was started.

Returns:

the System time the server was started

getNumClients

int getNumClients()

Returns the total number of clients on the server.

Returns:

the total number of clients on the server

getNumClientsTotal

int getNumClientsTotal(java.lang.String qualifier)

Returns the total number of clients in the given qualifier. Clients can be counted more than once if they are in multiple rooms. For example, if a single client is in all 3 rooms games.chess1, games.chess2, and games.chess3 then getNumClientsTotal("games.*") will return 3.

Parameters:

qualifier - the qualifier in which the count is done

Returns:

the total number of clients in the given qualifier

getNumClientsUnique

int getNumClientsUnique(java.lang.String qualifier)

Returns the total number of unique clients in the given qualifier. For example, if a single client is in all 3 rooms games.chess1, games.chess2, and games.chess3 then getNumClientsUnique("games.*") will return 1.

Parameters:

qualifier - the qualifier in which the count is done

Returns:

the total number of unique clients in the given qualifier

getNumRooms

int getNumRooms()

Returns the total number of rooms on the server.

Returns:

the total number of rooms on the server

getLifetimeNumClients

int getLifetimeNumClients()

Returns the total number of lifetime connections to the server.

Returns:

the total number of lifetime connections to the server

getLifetimeNumRooms

int getLifetimeNumRooms()

Returns the total number of lifetime rooms created on the server.

Returns:

the total number of lifetime rooms created on the server

getCurrentRequest

Request getCurrentRequest()

Get the current request being processed.

Returns:

the current request

containsAccount

boolean containsAccount(java.lang.String userID)

Returns true if the server has an account (logged in or not) for the userID.

Parameters:

userID - the userID for the account

Returns:

true if the server has an account

getAccount

Account getAccount(java.lang.String userID)
                   throws AccountNotFoundException

Returns the account for the given userID. When accessing an account through the this method you MUST call dispose() when finished working with the Account. If dispose is not called then the Account will stay in the internal account cache causing a memory leak.

Parameters:

userID - the userID for the account

Returns:

the account

Throws:

AccountNotFoundException

isAccountOnline

boolean isAccountOnline(java.lang.String userID)

Returns true if the account given by the userID is currently logged in.

Parameters:

userID -

Returns:

createAccount

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

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

removeAccount

java.lang.String removeAccount(java.lang.String userID,
                               java.lang.String password)

Remove an account from the server.

Parameters:

userID - the userID of the account

password - the password of the account

Returns:

Status.SUCCESS - the account was removed

clearAccountCache

void clearAccountCache()

For efficiency Union uses a cache for recently used Accounts. If there are changes to an Account not done by the Account API, for example you change an Account Attribute in the database directly, a call to clearAccountCache will guarantee that the Account data is loaded directly from the datasource the next time the Account is loaded. Calling clearAccountCache() will not update an Account referenced through a Client that is already logged in.

getUsers

java.util.List<java.lang.String> getUsers()

Returns a list of userIDs for all accounts on the server.

Returns:

a list of userIDs for all accounts on the server

changeAccountPassword

java.lang.String changeAccountPassword(java.lang.String userID,
                                       java.lang.String oldPassword,
                                       java.lang.String newPassword)

Change the password for an account

Parameters:

userID - the userID of the account

oldPassword - the old password for the account

newPassword - the new password for the account

Returns:

Status.SUCCESS - the password was changed

shutdownServer

void shutdownServer()

Stops the server.

getSecurity

Security getSecurity()

Returns access to the Security API.

Returns:

access to the Security API

getUPCMessageProcessor

UPCProcessor getUPCMessageProcessor()

Returns access to the UPCMessageProcessor API.

Returns:

access to the UPCMessageProcessor API

getCluster

Cluster getCluster()

Returns access to the Cluster API.

Returns:

access to the Cluster API