Package com.smartfoxserver.entities

Class SFSRoom

java.lang.Object
com.smartfoxserver.entities.SFSRoom
All Implemented Interfaces:
Room
Direct Known Subclasses:
MMORoom, SFSGame
public class SFSRoom extends Object implements Room

Overview

The Room object is used to organize and group Users in the the current Zone. Rooms can be created for chatting, playing games, exchanging images and documents, collaborate on shared projects etc ...

Users can join one or more Room and start interacting with other people and players in those same Rooms. Rooms can be organized in Room Groups. A Group is nothing more than a unique (String) tag that is assigned to each Room. By assigning a Room to a specific Room Group you will be able to separate Rooms in different categories and avoiding to mix all of them together, especially when the application has thousands of Rooms.

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

Services

There are several different types of Rooms:
  • SFSRoom: the most basic type of Room, allows to chat and play games. Players can join freely unless the Room is configured to be private.
  • SFSGame: a more advanced Room type dedicate to games, allows to use Invitations and the match-making system to find the appropriate players for the specific requirements of the Game. E.g.: you can define specific criteria such as ranking or experience level or any other custom parameter and the use these to match Users that could play in the Room
  • MMORoom a special type of Room where events are only propagated in an Area-Of-Interest (AoI) around the player using a coordinate system. This allows to have 100s or 1000s of players in the same Room interacting and playing, while optimizing the traffic from all the event updates.

Rooms provide lots of useful services for the application security:

  • User management with auto-banning and kicking with specific rules
  • Bad Words filtering
  • Anti-Flood filtering
  • Manager player IDs for Game Rooms
  • State synchronization across all players
Finally Rooms are extensible via the use of a server side Extension which allow Rooms to receive custom requests from their Users and implement custom game logic.
See Also:

  • Field Details

    • logger

      protected org.slf4j.Logger logger

  • Constructor Details

    • SFSRoom

      public SFSRoom(String name)

    • SFSRoom

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

  • Method Details

    • getId

      public int getId()
      Return the unique Room Id
      Specified by:
      getId in interface Room
      Returns:
      the unique Room id

    • getGroupId

      public String getGroupId()
      Get the Room Group Id.
      Specified by:
      getGroupId in interface Room
      Returns:
      the group Id

    • setGroupId

      public void setGroupId(String groupId)
      Specified by:
      setGroupId in interface Room

    • getName

      public String getName()
      Get the room name
      Specified by:
      getName in interface Room
      Returns:
      the room name

    • setName

      public void setName(String name)
      Specified by:
      setName in interface Room

    • getPassword

      public String getPassword()
      Get the Room password.
      Specified by:
      getPassword in interface Room
      Returns:
      the room password, null if no password is used
      See Also:

    • setPassword

      public void setPassword(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

    • getOwnerName

      public String getOwnerName()
      Description copied from interface: Room
      Returns the name of user that created the Room.

      If the owner is the server itself the name will be "[server]"

      Specified by:
      getOwnerName in interface Room
      Returns:

    • isOwnedBy

      public boolean isOwnedBy(User user)
      Description copied from interface: Room
      Return true if the Room is owned by the provided User object.

      The owner of a Room is the User that created it. Rooms created by the server will always return false;

      Specified by:
      isOwnedBy in interface Room
      Parameters:
      user - the User to check
      Returns:
      true if the Room is owned by the provided User object

    • setOwner

      public void setOwner(User owner)
      Specified by:
      setOwner in interface Room

    • getUserManager

      public com.smartfoxserver.entities.managers.IUserManager getUserManager()
      Specified by:
      getUserManager in interface Room

    • setUserManager

      public void setUserManager(com.smartfoxserver.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, 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:

    • setAutoRemoveMode

      public void setAutoRemoveMode(SFSRoomRemoveMode autoRemoveMode)
      Specified by:
      setAutoRemoveMode in interface Room

    • getPlayersList

      public 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 Object getProperty(Object key)
      Get any custom property attached to this Room.
      Specified by:
      getProperty in interface Room
      Parameters:
      key -
      Returns:
      the value

    • getProperties

      public ConcurrentMap<Object,Object> getProperties()
      Get the map with all Room properties
      Specified by:
      getProperties in interface Room
      Returns:
      the map with all User properties

    • getSize

      public RoomSize getSize()
      Return the current Room size
      Specified by:
      getSize in interface Room
      Returns:
      the current Room size
      See Also:

    • removeProperty

      public void removeProperty(Object key)
      Removes a custom property
      Specified by:
      removeProperty in interface Room
      Parameters:
      key - the name of the property

    • getSpectatorsList

      public 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(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 List<User> getUserList()
      Get all Users in the Room
      Specified by:
      getUserList in interface Room
      Returns:
      all Users in the Room

    • getSessionList

      public 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(String varName)
      Get a Room Variable
      Specified by:
      getVariable in interface Room
      Parameters:
      varName - the name of the variable
      Returns:
      the variable
      See Also:

    • getVariables

      public 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 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(Object key)
      Checks whether a custom property exists or not
      Specified by:
      containsProperty in interface Room
      Parameters:
      key - the name of the property
      Returns:
      true if the property exists

    • removeVariable

      public void removeVariable(String varName)
      Specified by:
      removeVariable in interface Room

    • removeVariablesCreatedByUser

      public List<RoomVariable> removeVariablesCreatedByUser(User user)
      Specified by:
      removeVariablesCreatedByUser in interface Room

    • removeVariablesCreatedByUser

      public List<RoomVariable> removeVariablesCreatedByUser(User user, boolean isLeaveRoom)
      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(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:

    • 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
      Parameters:
      useWordsFilter -

    • setProperty

      public void setProperty(Object key, Object value)
      Attach a custom (server-side only) property to the Room object
      Specified by:
      setProperty in interface Room
      Parameters:
      key - the property name
      value - the property value

    • setVariables

      public void setVariables(List<RoomVariable> variables)
      Specified by:
      setVariables in interface Room

    • setVariables

      public void setVariables(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

    • isAllowOwnerInvitations

      public boolean isAllowOwnerInvitations()
      True if the Room allows only its creator to send JoinRoomInvitations. If false, any non spectator User joined in the Room can invite other people.
      Specified by:
      isAllowOwnerInvitations in interface Room
      Returns:
      True if the Room allows only its creator to send JoinRoomInvitations. If false, any non spectator User joined in the Room can invite other people.

    • setAllowOwnerInvitations

      public void setAllowOwnerInvitations(boolean flag)
      Set to true if the Room allows only its creator to send JoinRoomInvitations. Use false if any non spectator User joined in the Room can invite other people.
      Specified by:
      setAllowOwnerInvitations in interface Room
      Parameters:
      flag - true if the Room allows only its creator to send JoinRoomInvitations. Use false if any non spectator User joined in the Room can invite other people.

    • isSuppressUserList

      public boolean isSuppressUserList()
      Specified by:
      isSuppressUserList in interface Room

    • setSuppressUserList

      public void setSuppressUserList(boolean value)
      Specified by:
      setSuppressUserList in interface Room

    • enableAudioManager

      public void enableAudioManager()
      Specified by:
      enableAudioManager in interface Room

    • getAudioManager

      public com.smartfoxserver.entities.managers.IAudioManager getAudioManager()
      Specified by:
      getAudioManager in interface Room

    • isAudioStreamingAllowed

      public boolean isAudioStreamingAllowed()
      Returns true if audio streaming is allowed in the current Room.
      Specified by:
      isAudioStreamingAllowed in interface Room
      Returns:
      true if audio streaming is allowed

    • destroy

      public void destroy()
      Specified by:
      destroy in interface Room

    • setVariable

      public void setVariable(RoomVariable roomVariable, boolean overrideOwnership) throws SFSVariableException
      Specified by:
      setVariable in interface Room
      Throws:
      SFSVariableException

    • containsVariable

      public boolean containsVariable(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(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

    • banUser

      public void banUser(User user, int timeInterval, TimeUnit timeUnit)
      Specified by:
      banUser in interface Room

    • isJoinAllowed

      public boolean isJoinAllowed(User user)
      Description copied from interface: Room
      Returns false if the provided User is not allowed to join this Room. In such case the User must have been previously banned from this Room and the ban is not expired yet.
      Specified by:
      isJoinAllowed in interface Room
      Parameters:
      user - the User to check
      Returns:
      false if the User is not allowed to join, true otherwise

    • unbanUser

      public void unbanUser(User user)
      Specified by:
      unbanUser in interface Room

    • getBannedUserIds

      public Collection<String> getBannedUserIds()
      Returns the id of every User currently banned in this Room.

      By default the 'user id' is the User's name, which is unique in the Zone. However certain application do not consistently associate the same User name to the same User when they login. For example, this happens when an email address is used for logging in rather than the user name. In those case the User name might be different on every Session and thus the banning system would not work.

      Specified by:
      getBannedUserIds in interface Room
      Returns:
      the User id (default is the user name)

    • 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 String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class 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 String getDump()
      Specified by:
      getDump in interface Room

    • getAdminHelper

      public com.smartfoxserver.util.IAdminHelper getAdminHelper()

    • setAdminHelper

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

    • getPlayerIdGeneratorClassName

      public String getPlayerIdGeneratorClassName()
      Specified by:
      getPlayerIdGeneratorClassName in interface Room

    • setProperties

      public void setProperties(Map<Object,Object> props)