it.gotoandplay.smartfoxserver.extensions
Class ExtensionHelper

java.lang.Object
  extended by it.gotoandplay.smartfoxserver.extensions.ExtensionHelper

public class ExtensionHelper
extends java.lang.Object

The ExtensionHelper class provides utility methods for server side extensions written in Java. It is reccomended to always keep a reference to the class in your Extension.

A good practice is to create such reference in the init() method of your extension:

 private ExtensionHelper helper;
 
 public void init()
 {
        helper = ExtensionHelper.instance();
 }
 


Field Summary
static int MOD_MESSAGE_TO_ROOM
           
static int MOD_MESSAGE_TO_USER
           
static int MOD_MESSAGE_TO_ZONE
           
 
Method Summary
 User canLogin(java.lang.String nick, java.lang.String pass, java.nio.channels.SocketChannel ch, java.lang.String zone)
          Checks if a connected client can log in the requested Zone.
 Room createRoom(Zone z, java.util.Map params, User creator, boolean sendUpdate, boolean broadcastEvent)
           Create a new dynamic room.
 Room createRoom(Zone z, java.util.Map params, User creator, java.util.HashMap roomVars, User varsOwner, boolean setOwnership, boolean sendUpdate, boolean broadcastEvent)
           Create a new dynamic room.
static void destroy()
           
 boolean destroyRoom(Zone zone, int roomId)
          Destroy a server room
 void disconnectUser(User u)
          Disconnects a client from the server
 void dispatchPrivateMessage(java.lang.String msg, Room r, User sender, User recipient)
          Dispatch a private message.
 void dispatchPublicMessage(java.lang.String msg, Room r, User u)
          Dispatch a public message.
 java.lang.String getGuestName()
          Return a guest name in the format of "guest_nn" where nn is an autoincrement integer
 User getUserByChannel(java.nio.channels.SocketChannel sc)
          Return a User object from its socket channel
 User getUserById(int id)
          Return a User object from its numeric id
 Zone getZone(java.lang.String zoneName)
          Return a Zone object from its name
static ExtensionHelper instance()
          Get an instance of the ExtensionHelper class
 boolean joinRoom(User usr, int currRoom, int newRoom, boolean leaveRoom, java.lang.String pword, boolean isSpectator, boolean broadcast)
          Join a room from a server side extension
 void leaveRoom(User u, int roomId, boolean broadcastEvent)
          Force a user to leave a room.
 void logoutUser(int id, boolean fireClientEvt, boolean fireInternalEvt)
          Logout a user from the current Zone
 void logoutUser(User user, boolean fireClientEvt, boolean fireInternalEvt)
          Logout a user from the current Zone
 void sendGenericMessage(java.lang.String message, java.nio.channels.SocketChannel sender, java.util.LinkedList channelList)
          Send a generic text or XML message.
 void sendModeratorMessage(java.lang.String message, User sender, int type, int id)
          Send a moderator message to a single user, a room or an entire Zone
 void sendRoomList(java.nio.channels.SocketChannel sc)
          Send a room list in default format (XML)
This will fire a onRoomListUpdate() event on the client.
 void setRoomVariable(Room r, User u, java.lang.String vn, java.lang.String vt, java.lang.String vv, boolean pr, boolean ps, boolean setOwnership, boolean broadcastAll)
          Deprecated.  
 void setRoomVariables(Room r, User u, java.util.HashMap vars, boolean setOwnership, boolean broadcastAll)
          Set one or more Room Variable
The vars parameter requires a HashMap of RoomVariables where the key is the variable name and the value is the RoomVariable object
 void setUserVariables(User u, java.util.HashMap vars, boolean broadcastAll)
          Set one or more User Variables.
 void switchSpectator(User u, int roomId, boolean brodcastEvent)
          Switch a spectator into a player, if possible (game rooms only)
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MOD_MESSAGE_TO_USER

public static final int MOD_MESSAGE_TO_USER
See Also:
Constant Field Values

MOD_MESSAGE_TO_ROOM

public static final int MOD_MESSAGE_TO_ROOM
See Also:
Constant Field Values

MOD_MESSAGE_TO_ZONE

public static final int MOD_MESSAGE_TO_ZONE
See Also:
Constant Field Values
Method Detail

instance

public static ExtensionHelper instance()
Get an instance of the ExtensionHelper class

Returns:
the instance of the ExtensionHelper

destroy

public static void destroy()

canLogin

public User canLogin(java.lang.String nick,
                     java.lang.String pass,
                     java.nio.channels.SocketChannel ch,
                     java.lang.String zone)
              throws it.gotoandplay.smartfoxserver.exceptions.LoginException
Checks if a connected client can log in the requested Zone.
If the Zone is full, or a user with the same name already exist a LoginException will be thrown.
Before logging in a Zone a client has a very limited set of actions that can perform with the server.
Once the login phase is successfully passed, a User object is created and added to the Zone allowing the user to interact with the server.

Parameters:
nick - the nickname you want to use to log in
pass - an optional password
ch - the SocketChannel of the connected client
zone - the zone name
Returns:
a User object
Throws:
it.gotoandplay.smartfoxserver.exceptions.LoginException - if there are problems with the login

dispatchPublicMessage

public void dispatchPublicMessage(java.lang.String msg,
                                  Room r,
                                  User u)
Dispatch a public message.
This method is usually invoked when handling a "pubMsg" internal event.
The server fires the event when a client has requested to send a public message in his current room.
You can handle the message before it gets dispatched, log it, process it and finally dispatch it to the room.

Parameters:
msg - the message
r - the target room
u - the sender user

dispatchPrivateMessage

public void dispatchPrivateMessage(java.lang.String msg,
                                   Room r,
                                   User sender,
                                   User recipient)
Dispatch a private message.
This method is usually invoked when handling a "privMsg" internal event.
The server fires the event when a client has requested to send a private message to another user
You can handle the message before it gets dispatched, log it, process it and finally dispatch it to the user.

Parameters:
msg - the message
r - the room of the sender
sender - the sender user
recipient - the recipient user

getGuestName

public java.lang.String getGuestName()
Return a guest name in the format of "guest_nn" where nn is an autoincrement integer

Returns:
the guest name

getUserByChannel

public User getUserByChannel(java.nio.channels.SocketChannel sc)
Return a User object from its socket channel

Parameters:
sc - a valid socket channel
Returns:
the User object

getUserById

public User getUserById(int id)
Return a User object from its numeric id

Parameters:
id - a valid user id
Returns:
the User object

logoutUser

public void logoutUser(int id,
                       boolean fireClientEvt,
                       boolean fireInternalEvt)
Logout a user from the current Zone

Parameters:
id - the user id

logoutUser

public void logoutUser(User user,
                       boolean fireClientEvt,
                       boolean fireInternalEvt)
Logout a user from the current Zone

Parameters:
user - the User object

sendGenericMessage

public void sendGenericMessage(java.lang.String message,
                               java.nio.channels.SocketChannel sender,
                               java.util.LinkedList channelList)
Send a generic text or XML message.
This method is rarely used, but it can be usefull for sending modified versions of the server system messages.

Parameters:
message - string or xml message
sender - the sender channel (can be null)
channelList - a list of recipient channels

createRoom

public Room createRoom(Zone z,
                       java.util.Map params,
                       User creator,
                       boolean sendUpdate,
                       boolean broadcastEvent)
                throws it.gotoandplay.smartfoxserver.exceptions.ExtensionHelperException

Create a new dynamic room.

The params parameter can contain the following keys:

name   the room name
pwd   the room password (optional)
maxU   max number of users
maxS   max number of spectators (optional for game rooms)
isGame   a boolean flag. If true the room is a game room
isLimbo   a boolean flag. If true the room is in "Limbo mode"
uCount   a boolean flag. If true the room will receive the uCount update messages.
xtName   The name of the extension that will be attached to the room
xtClass   The name of the class (Java) or script (Actionscript) to load as extension.
The file extension should only be specified for Actionscript files (.as)

Parameters:
z - the Zone where the room will be created
params - a Map of params: name,pwd,maxU,maxS,isGame
creator - the "owner" of the room. null = Server owned
sendUpdate - send a default xml update to clients?
broadcastEvent - TRUE = broadcast event to all, FALSE = only Server scope (for admin)
Returns:
The new room
Throws:
it.gotoandplay.smartfoxserver.exceptions.ExtensionHelperException

createRoom

public Room createRoom(Zone z,
                       java.util.Map params,
                       User creator,
                       java.util.HashMap roomVars,
                       User varsOwner,
                       boolean setOwnership,
                       boolean sendUpdate,
                       boolean broadcastEvent)
                throws it.gotoandplay.smartfoxserver.exceptions.ExtensionHelperException

Create a new dynamic room.
Additionally create any number of room variables in the new room

The params parameter can contain the following keys:

name   the room name
pwd   the room password (optional)
maxU   max number of users
maxS   max number of spectators (optional for game rooms)
isGame   a boolean flag. If true the room is a game room
isLimbo   a boolean flag. If true the room is in "Limbo mode"
uCount   a boolean flag. If true the room will receive the uCount update messages.
xtName   The name of the extension that will be attached to the room
xtClass   The name of the class (Java) or script (Actionscript) to load as extension.
The file extension should only be specified for Actionscript files (.as)

Parameters:
z - the Zone where the room will be created
params - a Map of params: name,pwd,maxU,maxS,isGame
creator - the "owner" of the room. null = Server owned
roomVars - an HashMap of variables to set on the newly created room (null if not needed)
varsOwner - the owner of the variables
setOwnership - the setOwnership flag for the roomVars
sendUpdate - send a default xml update?
broadcastEvent - TRUE = broadcast event to all, FALSE = only Server scope (for admin)
Returns:
The new room
Throws:
it.gotoandplay.smartfoxserver.exceptions.ExtensionHelperException

joinRoom

public boolean joinRoom(User usr,
                        int currRoom,
                        int newRoom,
                        boolean leaveRoom,
                        java.lang.String pword,
                        boolean isSpectator,
                        boolean broadcast)
                 throws it.gotoandplay.smartfoxserver.exceptions.ExtensionHelperException
Join a room from a server side extension

Parameters:
usr - the User object
currRoom - the id of the current room where the user is in
newRoom - the id of the room that the user wants to join
leaveRoom - if true the user will leave the current room once he successfully joined the new one
pword - an optional password for the room
isSpectator - if true the user is joined as spectator (for game rooms only)
broadcast - if true the onJoinRoom event is fired back to all clients (reccomended)
Returns:
true if the room was successfully joined
Throws:
it.gotoandplay.smartfoxserver.exceptions.ExtensionHelperException

sendModeratorMessage

public void sendModeratorMessage(java.lang.String message,
                                 User sender,
                                 int type,
                                 int id)
Send a moderator message to a single user, a room or an entire Zone

Parameters:
message - the text message
sender - the sender user
type - the type of message (ExtensionHelper.MOD_MESSAGE_TO_ constants)
id - the id of the recipient user or room. In case of a Zone message it will be ignored and the message will be sent to the current Zone.

sendRoomList

public void sendRoomList(java.nio.channels.SocketChannel sc)
Send a room list in default format (XML)
This will fire a onRoomListUpdate() event on the client.

Parameters:
sc - The SocketChannel that will receive the list

setRoomVariable

public void setRoomVariable(Room r,
                            User u,
                            java.lang.String vn,
                            java.lang.String vt,
                            java.lang.String vv,
                            boolean pr,
                            boolean ps,
                            boolean setOwnership,
                            boolean broadcastAll)
Deprecated. 

Set a room variable

Parameters:
r - the Room
u - the User
vn - the var name
vt - the var type
vv - the var value
pr - private flag
ps - persistent flag
setOwnership - setOwnership flag (will set the variable owner to the User who sent the request)
broadcastAll - if true the onRoomVariablesUpdate() event will be fired (reccomended)

setRoomVariables

public void setRoomVariables(Room r,
                             User u,
                             java.util.HashMap vars,
                             boolean setOwnership,
                             boolean broadcastAll)
Set one or more Room Variable
The vars parameter requires a HashMap of RoomVariables where the key is the variable name and the value is the RoomVariable object

Parameters:
r - the target room, where variables should be set
u - the user, owner of the variables
vars - a java.util.HashMap of RoomVariables
setOwnership - setOwnership flag (will set the variable owner to the User who sent the request)
broadcastAll - if true the onRoomVariablesUpdate() event will be fired (recommended)

setUserVariables

public void setUserVariables(User u,
                             java.util.HashMap vars,
                             boolean broadcastAll)
Set one or more User Variables.
The vars parameter requires a HashMap of UserVariables where the key is the variable name and the value is the UserVariable

Parameters:
vars - a map of UserVariables
u - the User object
broadcastAll - if true the onUserVariablesUpdate() event will be fired (reccomended)

getZone

public Zone getZone(java.lang.String zoneName)
Return a Zone object from its name

Parameters:
zoneName - the name of the zone
Returns:
the Zone object

leaveRoom

public void leaveRoom(User u,
                      int roomId,
                      boolean broadcastEvent)
Force a user to leave a room. Works only when the user is logged in more than one room at a time (multi-room mode)

Parameters:
u - the user
roomId - the id of the room to leave
broadcastEvent - if true, the response event is fired (reccomended)

switchSpectator

public void switchSpectator(User u,
                            int roomId,
                            boolean brodcastEvent)
Switch a spectator into a player, if possible (game rooms only)

Parameters:
u - the user
roomId - the target room id
brodcastEvent - if true, the response event is fired (reccomended)

disconnectUser

public void disconnectUser(User u)
Disconnects a client from the server

Parameters:
u - the user to kick

destroyRoom

public boolean destroyRoom(Zone zone,
                           int roomId)
Destroy a server room

Parameters:
zone - the zone
roomId - the roomId
Returns:
true if room was destroyed