com.smartfoxserver.v2.entities
Class SFSRoom

java.lang.Object
  com.smartfoxserver.v2.entities.SFSRoom

All Implemented Interfaces:

Room

Direct Known Subclasses:

SFSGame

public class SFSRoom
extends java.lang.Object
implements Room

Overview

The Room object is the main tool to organize and group Users in the application. Rooms can be created for chatting, playing games, exchanging images and audio files, sharing documents, collaboratively work on shared resources and a lot more.

Each Room can contain any number of Users and can be organized in Room Groups. A Group is nothing more than a unique String ID that is assigned to each Room. By assigning different Group IDs to different Rooms you will be able to separate Rooms in different "departments" avoiding to mix all Rooms together, especially when the application will create thousands of Rooms.

An example of grouping Rooms is separating the lobby Rooms from the chat and game Rooms. You could define three different groups called "Lobby", "Chat", "Game" and assign your Rooms to one of these groups at the time of the Room creation.

Services

In SmartFoxServer 2X Rooms are extremely versatile. They offer the same basic features already known in SmartFoxServer 1.x plus they add dozens of new fine-tuning option that will help you configure them exactly the way you need them. The new features allow you to:

• Organize Rooms in Room Groups
• Rename Rooms at runtime
• Resize Rooms at runtime
• Lock/Unlock Rooms at runtime with a password
• Hide Room visibility
• Broadcast Room Variables outside of the Room itself
• Decide which Room Variables are server-side only and which will be auto-updated to each client
• Configure Events and Permissions for each Room on a fine-grained level.
• Configure the life-cycle of a Room (when it gets removed and how)
• Join any Room from client side without the need of having it in the local room list
• Optimize the client room list by deciding which Room Groups the User will listen event for

Also each Room provides a number of essential services:

• User management
• Words filtering
• Anti-Flood filtering
• Manager player IDs for Game ROoms
• Event dispatching

Finally each Room is fully extensible via the use of a server side Extension which allow to process client requests, server events and more. The Extension is attached to the Room itself and initialized as soon as the Room is ready. The Extension can take control of the Room and interact with the server via the server side API.

Advanced Game features

Room objects provide the ability to manage games with custom logic very easily by plugging custom logic via Extensions. The new SFS2X framework also provides a new type of Room called SFSGame which delivers advanced gaming features, such as an invitation system, game matching, user matching, game start/stop auto-notifications and more...

See Also:

User, SFSGame, SFSApi, BaseSFSExtension, SFSExtension

Field Summary

protected org.slf4j.Logger

logger

Constructor Summary

SFSRoom(java.lang.String name)

SFSRoom(java.lang.String name, java.lang.Class<?> customPlayerIdGeneratorClass)

Method Summary

void	addUser(User user)
void	addUser(User user, boolean asSpectator)
boolean	containsProperty(java.lang.Object key)
boolean	containsUser(java.lang.String name) Checks if the specified User is joined in the Room
boolean	containsUser(User user) Checks if the specified User is joined in the Room
boolean	containsVariable(java.lang.String varName) Checks if a certain Room Variable name exists
boolean	equals(java.lang.Object obj)
com.smartfoxserver.v2.util.IAdminHelper	getAdminHelper()
SFSRoomRemoveMode	getAutoRemoveMode() Return the auto-remove mode of the Room
int	getCapacity() Return the capacity of the Room (maximum number of clients that can be contained).
java.lang.String	getDump() Get a dump of all Room attributes/settings.
ISFSExtension	getExtension() Get the extension connected to this Room, if any
java.lang.String	getGroupId() Get the Room Group Id.
int	getId() Return the unique Room Id
long	getLifeTime() Obtain the time of existence of the Room
int	getMaxRoomVariablesAllowed() Return the maximum number of Room Variables allowed in the Room.
int	getMaxSpectators() Return the maximum number of Spectators allowed in the Room.
int	getMaxUsers() Return the maximum number of Users allowed in the Room.
java.lang.String	getName() Get the room name
User	getOwner() Get the owner of the Room (the user that created it)
java.lang.String	getPassword() Get the Room password.
java.util.List<User>	getPlayersList() For Game Rooms: get all Players in the Room (same as all User without the Spectators)
java.lang.Object	getProperty(java.lang.Object key)
ISFSArray	getRoomVariablesData(boolean globalsOnly)
java.util.List<ISession>	getSessionList() Get all the User Sessions in the Room
RoomSize	getSize() Return the current Room size
java.util.List<User>	getSpectatorsList() For Game Rooms: get all Spectators in the Room (same as all User without the Players)
User	getUserById(int id)
User	getUserByName(java.lang.String name)
User	getUserByPlayerId(int playerId) Get the User currently having the specified playerId (Game Room only)
User	getUserBySession(ISession session)
java.util.List<User>	getUserList() Get all Users in the Room
ISFSArray	getUserListData()
com.smartfoxserver.v2.entities.managers.IUserManager	getUserManager()
RoomVariable	getVariable(java.lang.String varName) Get a Room Variable
java.util.List<RoomVariable>	getVariables() Get the full list of Room Variables in the Room
int	getVariablesCount() Get the total amount of Room Variables for this Room
java.util.List<RoomVariable>	getVariablesCreatedByUser(User user) Get a list of Room Variables created by a specific User
Zone	getZone() Get the Zone managing this Room.
boolean	isActive() Return true if the Room is active in the Zone.
boolean	isDynamic() Checks if the Room was created dynamically (at runtime)
boolean	isEmpty() Checks whether the Room is empty
boolean	isFlagSet(SFSRoomSettings flag) Checks whether a certain Room Setting is set
boolean	isFull() Checks whether the Room is full.
boolean	isGame() Checks if this is a Game Room
boolean	isHidden() Checks if the Game is hidden.
boolean	isPasswordProtected() Checks if the Room requires a password for joining it
boolean	isPublic() Returns true if the Room has public access, in other words it doesn't require a password.
boolean	isUseWordsFilter() Check if the word filter is used in this Room (applied to Public Messages)
void	removeProperty(java.lang.Object key)
void	removeUser(User user)
void	removeVariable(java.lang.String varName)
java.util.List<RoomVariable>	removeVariablesCreatedByUser(User user)
void	setActive(boolean flag)
void	setAdminHelper(com.smartfoxserver.v2.util.IAdminHelper helper)
void	setAutoRemoveMode(SFSRoomRemoveMode autoRemoveMode)
void	setCapacity(int maxUser, int maxSpectators)
void	setDynamic(boolean dynamic)
void	setExtension(ISFSExtension extension)
void	setFlag(SFSRoomSettings flag, boolean state)
void	setFlags(java.util.Set<SFSRoomSettings> settings)
void	setGame(boolean game)
void	setGame(boolean game, java.lang.Class<? extends IPlayerIdGenerator> customPlayerIdGeneratorClass)
void	setGroupId(java.lang.String groupId)
void	setHidden(boolean hidden)
void	setMaxRoomVariablesAllowed(int max)
void	setMaxSpectators(int maxSpectators)
void	setMaxUsers(int maxUsers)
void	setName(java.lang.String name)
void	setOwner(User owner)
void	setPassword(java.lang.String password)
void	setProperty(java.lang.Object key, java.lang.Object value)
void	setUserManager(com.smartfoxserver.v2.entities.managers.IUserManager userManager)
void	setUseWordsFilter(boolean useWordsFilter) Toggle the word filter in this Room (applied to Public Messages)
void	setVariable(RoomVariable roomVariable)
void	setVariable(RoomVariable roomVariable, boolean overrideOwnership)
void	setVariables(java.util.List<RoomVariable> variables)
void	setVariables(java.util.List<RoomVariable> variables, boolean overrideOwnership)
void	setZone(Zone zone)
void	switchPlayerToSpectator(User user)
void	switchSpectatorToPlayer(User user)
ISFSArray	toSFSArray(boolean globalRoomVarsOnly)
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

logger

protected org.slf4j.Logger logger

Constructor Detail

SFSRoom

public SFSRoom(java.lang.String name)

SFSRoom

public SFSRoom(java.lang.String name,
               java.lang.Class<?> customPlayerIdGeneratorClass)

Method Detail

getId

public int getId()

Return the unique Room Id

Specified by:

getId in interface Room

Returns:

the unique Room id

getGroupId

public java.lang.String getGroupId()

Get the Room Group Id.

Specified by:

getGroupId in interface Room

Returns:

the group Id

setGroupId

public void setGroupId(java.lang.String groupId)

Specified by:

setGroupId in interface Room

getName

public java.lang.String getName()

Get the room name

Specified by:

getName in interface Room

Returns:

the room name

setName

public void setName(java.lang.String name)

Specified by:

setName in interface Room

getPassword

public java.lang.String getPassword()

Get the Room password.

Specified by:

getPassword in interface Room

Returns:

the room password, null if no password is used

See Also:

Room.isPasswordProtected()

setPassword

public void setPassword(java.lang.String password)

Specified by:

setPassword in interface Room

isPasswordProtected

public boolean isPasswordProtected()

Checks if the Room requires a password for joining it

Specified by:

isPasswordProtected in interface Room

Returns:

true if the Room requires a password

isPublic

public boolean isPublic()

Returns true if the Room has public access, in other words it doesn't require a password.

Specified by:

isPublic in interface Room

Returns:

true id the Room is public and doesn't require a password

getMaxUsers

public int getMaxUsers()

Return the maximum number of Users allowed in the Room.

Specified by:

getMaxUsers in interface Room

Returns:

the max number of users allowed in the Room

setMaxUsers

public void setMaxUsers(int maxUsers)

Specified by:

setMaxUsers in interface Room

getMaxSpectators

public int getMaxSpectators()

Return the maximum number of Spectators allowed in the Room.

Specified by:

getMaxSpectators in interface Room

Returns:

the max number of spectators allowed in the Room

setMaxSpectators

public void setMaxSpectators(int maxSpectators)

Specified by:

setMaxSpectators in interface Room

getOwner

public User getOwner()

Get the owner of the Room (the user that created it)

Specified by:

getOwner in interface Room

Returns:

the owner of the Room, it can be null if the Room was created by the Server itself

setOwner

public void setOwner(User owner)

Specified by:

setOwner in interface Room

getUserManager

public com.smartfoxserver.v2.entities.managers.IUserManager getUserManager()

Specified by:

getUserManager in interface Room

setUserManager

public void setUserManager(com.smartfoxserver.v2.entities.managers.IUserManager userManager)

Specified by:

setUserManager in interface Room

getZone

public Zone getZone()

Get the Zone managing this Room.

Specified by:

getZone in interface Room

Returns:

the Zone that contains the Room

setZone

public void setZone(Zone zone)

Specified by:

setZone in interface Room

isDynamic

public boolean isDynamic()

Checks if the Room was created dynamically (at runtime)

Specified by:

isDynamic in interface Room

Returns:

true if the Room was created dynamically

setDynamic

public void setDynamic(boolean dynamic)

Specified by:

setDynamic in interface Room

isGame

public boolean isGame()

Checks if this is a Game Room

Specified by:

isGame in interface Room

Returns:

true if this is a Game Room

setGame

public void setGame(boolean game,
                    java.lang.Class<? extends IPlayerIdGenerator> customPlayerIdGeneratorClass)

Specified by:

setGame in interface Room

setGame

public void setGame(boolean game)

Specified by:

setGame in interface Room

isHidden

public boolean isHidden()

Checks if the Game is hidden. The hidden attribute doesn't change the Room normal behavior however it provides a flag that can be used on the client side to hide it from the Room List

Specified by:

isHidden in interface Room

Returns:

true if the Room is 'hidden'

setHidden

public void setHidden(boolean hidden)

Specified by:

setHidden in interface Room

isActive

public boolean isActive()

Return true if the Room is active in the Zone. When a Room is not active it will refuse any join request

Specified by:

isActive in interface Room

Returns:

true if the Room is active

setActive

public void setActive(boolean flag)

Specified by:

setActive in interface Room

getAutoRemoveMode

public SFSRoomRemoveMode getAutoRemoveMode()

Return the auto-remove mode of the Room

Specified by:

getAutoRemoveMode in interface Room

Returns:

the auto-remove mode of the Room

See Also:

SFSRoomRemoveMode

setAutoRemoveMode

public void setAutoRemoveMode(SFSRoomRemoveMode autoRemoveMode)

Specified by:

setAutoRemoveMode in interface Room

getPlayersList

public java.util.List<User> getPlayersList()

For Game Rooms: get all Players in the Room (same as all User without the Spectators)

Specified by:

getPlayersList in interface Room

Returns:

all Players in the Room

getProperty

public java.lang.Object getProperty(java.lang.Object key)

Specified by:

getProperty in interface Room

getSize

public RoomSize getSize()

Return the current Room size

Specified by:

getSize in interface Room

Returns:

the current Room size

See Also:

RoomSize

removeProperty

public void removeProperty(java.lang.Object key)

Specified by:

removeProperty in interface Room

getSpectatorsList

public java.util.List<User> getSpectatorsList()

For Game Rooms: get all Spectators in the Room (same as all User without the Players)

Specified by:

getSpectatorsList in interface Room

Returns:

all Spectators in the Room

getUserById

public User getUserById(int id)

Specified by:

getUserById in interface Room

Parameters:

id - the User id

Returns:

the User with the provided id, null if no User was found in the Room

getUserByName

public User getUserByName(java.lang.String name)

Specified by:

getUserByName in interface Room

Parameters:

name - the User name

Returns:

the User with the provided name, null if no User was found in the Room

getUserBySession

public User getUserBySession(ISession session)

Specified by:

getUserBySession in interface Room

Parameters:

session - the User session

Returns:

the User with the provided session, null if no User was found in the Room

getUserByPlayerId

public User getUserByPlayerId(int playerId)

Get the User currently having the specified playerId (Game Room only)

Specified by:

getUserByPlayerId in interface Room

Parameters:

playerId - the player id

Returns:

the User, null if no User exists with that player id

getUserList

public java.util.List<User> getUserList()

Get all Users in the Room

Specified by:

getUserList in interface Room

Returns:

all Users in the Room

getSessionList

public java.util.List<ISession> getSessionList()

Get all the User Sessions in the Room

Specified by:

getSessionList in interface Room

Returns:

all the User Sessions in the Room

getVariablesCount

public int getVariablesCount()

Get the total amount of Room Variables for this Room

Specified by:

getVariablesCount in interface Room

Returns:

the total amount of Room Variables for this Room

getVariable

public RoomVariable getVariable(java.lang.String varName)

Get a Room Variable

Specified by:

getVariable in interface Room

Parameters:

varName - the name of the variable

Returns:

the variable

See Also:

SFSRoomVariable

getVariables

public java.util.List<RoomVariable> getVariables()

Get the full list of Room Variables in the Room

Specified by:

getVariables in interface Room

Returns:

the complete list of Room Variables in the Room

getVariablesCreatedByUser

public java.util.List<RoomVariable> getVariablesCreatedByUser(User user)

Get a list of Room Variables created by a specific User

Specified by:

getVariablesCreatedByUser in interface Room

Parameters:

user - the User

Returns:

list of Room Variables created by the provided User

containsProperty

public boolean containsProperty(java.lang.Object key)

Specified by:

containsProperty in interface Room

removeVariable

public void removeVariable(java.lang.String varName)

Specified by:

removeVariable in interface Room

removeVariablesCreatedByUser

public java.util.List<RoomVariable> removeVariablesCreatedByUser(User user)

Specified by:

removeVariablesCreatedByUser in interface Room

getCapacity

public int getCapacity()

Return the capacity of the Room (maximum number of clients that can be contained). In a Game Room this value is the sum of the maxUser + maxSpectators

Specified by:

getCapacity in interface Room

Returns:

the Room capacity

setCapacity

public void setCapacity(int maxUser,
                        int maxSpectators)

Specified by:

setCapacity in interface Room

setMaxRoomVariablesAllowed

public void setMaxRoomVariablesAllowed(int max)

Specified by:

setMaxRoomVariablesAllowed in interface Room

getMaxRoomVariablesAllowed

public int getMaxRoomVariablesAllowed()

Return the maximum number of Room Variables allowed in the Room.

Specified by:

getMaxRoomVariablesAllowed in interface Room

Returns:

the max number of Room Variables allowed in the Room

setFlags

public void setFlags(java.util.Set<SFSRoomSettings> settings)

Specified by:

setFlags in interface Room

isFlagSet

public boolean isFlagSet(SFSRoomSettings flag)

Checks whether a certain Room Setting is set

Specified by:

isFlagSet in interface Room

Parameters:

flag - the flag

Returns:

true if the flag is set

See Also:

SFSRoomSettings

setFlag

public void setFlag(SFSRoomSettings flag,
                    boolean state)

Specified by:

setFlag in interface Room

isUseWordsFilter

public boolean isUseWordsFilter()

Check if the word filter is used in this Room (applied to Public Messages)

Specified by:

isUseWordsFilter in interface Room

Returns:

true if the word filter is used in this Room (applied to Public Messages)

setUseWordsFilter

public void setUseWordsFilter(boolean useWordsFilter)

Toggle the word filter in this Room (applied to Public Messages)

Specified by:

setUseWordsFilter in interface Room

setProperty

public void setProperty(java.lang.Object key,
                        java.lang.Object value)

Specified by:

setProperty in interface Room

setVariables

public void setVariables(java.util.List<RoomVariable> variables)

Specified by:

setVariables in interface Room

setVariables

public void setVariables(java.util.List<RoomVariable> variables,
                         boolean overrideOwnership)

Specified by:

setVariables in interface Room

setVariable

public void setVariable(RoomVariable roomVariable)
                 throws SFSVariableException

Specified by:

setVariable in interface Room

Throws:

SFSVariableException

setVariable

public void setVariable(RoomVariable roomVariable,
                        boolean overrideOwnership)
                 throws SFSVariableException

Specified by:

setVariable in interface Room

Throws:

SFSVariableException

containsVariable

public boolean containsVariable(java.lang.String varName)

Checks if a certain Room Variable name exists

Specified by:

containsVariable in interface Room

Parameters:

varName - the variable name

Returns:

true if a Room Variable with the provided name exists

containsUser

public boolean containsUser(java.lang.String name)

Checks if the specified User is joined in the Room

Specified by:

containsUser in interface Room

Parameters:

name - the User name

Returns:

true if the User is present (joined) in this Room

containsUser

public boolean containsUser(User user)

Checks if the specified User is joined in the Room

Specified by:

containsUser in interface Room

Parameters:

user - the User

Returns:

true if the User is present (joined) in this Room

addUser

public void addUser(User user)
             throws SFSJoinRoomException

Specified by:

addUser in interface Room

Throws:

SFSJoinRoomException

addUser

public void addUser(User user,
                    boolean asSpectator)
             throws SFSJoinRoomException

Specified by:

addUser in interface Room

Throws:

SFSJoinRoomException

removeUser

public void removeUser(User user)

Specified by:

removeUser in interface Room

switchPlayerToSpectator

public void switchPlayerToSpectator(User user)
                             throws SFSRoomException

Specified by:

switchPlayerToSpectator in interface Room

Throws:

SFSRoomException

switchSpectatorToPlayer

public void switchSpectatorToPlayer(User user)
                             throws SFSRoomException

Specified by:

switchSpectatorToPlayer in interface Room

Throws:

SFSRoomException

getLifeTime

public long getLifeTime()

Obtain the time of existence of the Room

Specified by:

getLifeTime in interface Room

Returns:

the time of existence of the Room in milliseconds

isEmpty

public boolean isEmpty()

Checks whether the Room is empty

Specified by:

isEmpty in interface Room

Returns:

true if the Room is empty

isFull

public boolean isFull()

Checks whether the Room is full. In game rooms this check will return true only if all player slots are taken.

Specified by:

isFull in interface Room

Returns:

true if the Room is full

getUserListData

public ISFSArray getUserListData()

Specified by:

getUserListData in interface Room

getRoomVariablesData

public ISFSArray getRoomVariablesData(boolean globalsOnly)

Specified by:

getRoomVariablesData in interface Room

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

getExtension

public ISFSExtension getExtension()

Get the extension connected to this Room, if any

Specified by:

getExtension in interface Room

Returns:

the extension attached to this Room, null if no extension exists

setExtension

public void setExtension(ISFSExtension extension)

Specified by:

setExtension in interface Room

toSFSArray

public ISFSArray toSFSArray(boolean globalRoomVarsOnly)

Specified by:

toSFSArray in interface Room

getDump

public java.lang.String getDump()

Get a dump of all Room attributes/settings. Useful for debugging

Specified by:

getDump in interface Room

Returns:

a dump of all Room attributes/settings

getAdminHelper

public com.smartfoxserver.v2.util.IAdminHelper getAdminHelper()

setAdminHelper

public void setAdminHelper(com.smartfoxserver.v2.util.IAdminHelper helper)