it.gotoandplay.smartfoxserver.extensions
Class ExtensionHelper

java.lang.Object
  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