com.electrotank.electroserver.plugins.utilities
Class BaseExtensionHelper

java.lang.Object
  com.electrotank.electroserver.plugins.utilities.BaseExtensionHelper

Direct Known Subclasses:

EventHelper, PluginHelper

public class BaseExtensionHelper

extends Object

The BaseExtensionHelper is a class that exposes internal functionality of ElectroServer to extensions. While the functionality listed here is available to both plugins and event handlers, in practice you will use the appropriate subclass like PluginHelper.

Constructor Summary

BaseExtensionHelper(String name, People people, Places places)
The is an interally-used constructor.

Method Summary

void	ban(String userName, long expires) Bans the user from the server for the specified period.
Map	callRemotePlugin(String pluginName, Map parameters) Calls a remote server-level plugin specified by the name.
Map	callRemoteRoomPlugin(String zoneName, String roomName, String pluginName, Map parameters) Calls a remote room-level plugin specified by the name.
void	config(String message) Creates a "config" entry in the server log file.
boolean	createDirectory(String path) Creates the directory and all needed parent directories specified by the path.
int	createRoom(String doc) Progamatically creates a room with no users in it.
boolean	createRoomVariable(String zoneName, String roomName, boolean locked, String name, String data) Creates a room variable in a given zone/room combination.
boolean	createUserVariable(String userName, String variableName, String variableValue) Creates a user variable for the specified user.
boolean	deleteDirectory(String path) Deletes the directory specified by the path.
boolean	deleteFile(String path) Deletes the file specified by the path.
boolean	deleteRoomVariable(String zoneName, String roomName, String name) Deletes a given room variable from the system.
boolean	deleteUserVariable(String userName, String variableName) Deletes the specified user variable.
boolean	doesDirectoryExist(String path) Determines if a directory exists.
boolean	doesFileExist(String path) Determines if a file exists.
void	fine(String message) Creates a "fine" entry in the server log file.
void	finer(String message) Creates a "finer" entry in the server log file.
void	finest(String message) Creates a "finest" entry in the server log file.
ZoneStub[]	getAllZones() Gets all zones on the server.
double	getCpuPercentUsed()
int	getLoggedInUserCount() Returns a count of all users currently logged into the server.
Logger	getLogger() Returns the server-wide logger that can be used to log anything needed
String	getName() Returns the name of the extension (plugin or event handler)
long	getPhysicalMemoryAvailable()
RoomStub[]	getRoomsInZone(String zoneName) Gets all rooms in a given zone.
RoomVariable[]	getRoomVariables(String zoneName, String roomName) Gets all room variables for a zone/room combination.Updating the RoomVariable objects returned by this call will NOT update the actual room variables.
long	getServerTime() Gets the current time of the server.
Object	getUserServerVariable(String userName, Object key) Returns the specified user server variable.
Object	getUserServerVariable(String userName, Object key, Object defaultValue) Returns the specified user server variable.
UserStub[]	getUsersInRoom(String zoneName, String roomName) Returns a list of users from a given zone/room combination.
UserVariable[]	getUserVariables(String userName) Returns all user variables associated with the specified user.
Map	getUserVariablesAsMap(String userName) Gets a Map of all user variables tied to this user.
void	info(String message) Creates a "info" entry in the server log file.
boolean	isDirectory(String path) Determines if the specified path is a directory.
boolean	isFile(String path) Determines if the specified path is a file.
boolean	isUserLoggedIn(String userName) Determines if the user is logged in or not.
void	kick(String userName) Kicks the user specified from the server.
int	moveToRoom(String userName, String zone, String room, String roomPassword, boolean numbered) Moves a user into a room progamatically.
String	readFile(String fileName) Reads the specified file and returns the contents as a String.
void	removeUserServerVariable(String userName, Object key) Removes a user server variable from a given user.
void	sendPrivateMessage(String userName, String message, Map variables) Sends a private message to the userName.
void	sendPrivateMessgeToMany(String[] users, String message, Map variables) Sends a private message to the specified users.
boolean	sendPublicMessageToRoom(String zoneName, String roomName, String message, Map variables) Sends a plugin message to the given zone/room combination.
boolean	sendPublicMessageToServer(String message, Map variables) Sends a public message to the entire server.
boolean	sendPublicMessageToZone(String zoneName, String message, Map variables) Sends a public message to a zone.
void	setUserServerVariable(String userName, Object key, Object value) Sets a variable on a user.
void	severe(String message) Creates a "severe" entry in the server log file.
boolean	stringContainsVulgarity(String testString) Tests the given string for vulgarity using the LanguageFilter and the settings initialized in the configuration.xml file.
boolean	updateRoomVariable(String zoneName, String roomName, boolean locked, String name, String data) Updates a given user variables settings and values.
boolean	updateUserVariable(String userName, String variableName, String variableValue) Updates a given user variable with the new data.
void	warning(String message) Creates a "warning" entry in the server log file.
boolean	writeFile(String fileName, String data, boolean append) Writes a file to the specified location.

Methods inherited from class java.lang.Object

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

Constructor Detail

BaseExtensionHelper

public BaseExtensionHelper(String name,
                           People people,
                           Places places)

The is an interally-used constructor.

Parameters:

name - the name of the extension using this instance of the helper

people - a reference to the people object of the server

places - a reference to the places object of the server

Method Detail

kick

public void kick(String userName)

Kicks the user specified from the server.

Parameters:

userName - name of the user to kick

ban

public void ban(String userName,
                long expires)

Bans the user from the server for the specified period. Using -1 will ensure the user is permamently banned.

Parameters:

userName - name of the user to kick

expires - length of time (in milliseconds) that the user should be banned

setUserServerVariable

public void setUserServerVariable(String userName,
                                  Object key,
                                  Object value)

Sets a variable on a user. This variable is NOT the same as a "UserVariable", which is set by a user and visible to other users. User Server Variables are only visible to all plugins and event handlers and are not broadcast out to clients. In practice, this might be anything that is globally interesting to other plugins and handlers. For example, a login event handler could validate a user against a database and then store the users database ID as a User Server Variable.

Parameters:

userName - The username of the user this variable will be associated with

key - The name to use as an identifier for this variable

value - The variable to store.

removeUserServerVariable

public void removeUserServerVariable(String userName,
                                     Object key)

Removes a user server variable from a given user.

Parameters:

userName - The name of the user

key - The name of the variable to remove

getUserServerVariable

public Object getUserServerVariable(String userName,
                                    Object key)

Returns the specified user server variable.

Parameters:

userName - The name of the user

key - The name of the variable

Returns:

The variable itself unless it's not found, then null is returned

getUserServerVariable

public Object getUserServerVariable(String userName,
                                    Object key,
                                    Object defaultValue)

Returns the specified user server variable. If it's not found, it will return the defaultValue specified.

Parameters:

userName - The name of the user

key - The name of the variable

defaultValue - A value to be used if the variable is not found

Returns:

The variable itself unless it's not found, then defaultValue is returned

sendPrivateMessgeToMany

public void sendPrivateMessgeToMany(String[] users,
                                    String message,
                                    Map variables)

Sends a private message to the specified users.

Parameters:

users - string array representing the names of users to receive this message

message - text of the message to send

variables - variables to be sent along with the message

sendPrivateMessage

public void sendPrivateMessage(String userName,
                               String message,
                               Map variables)

Sends a private message to the userName.

Parameters:

userName - name of the userName to receive this message

message - text of the message to send

variables - variables to be sent along with the message

isUserLoggedIn

public boolean isUserLoggedIn(String userName)

Determines if the user is logged in or not.

Parameters:

userName - The username to use

Returns:

True if the user is logged in, false otherwise

callRemotePlugin

public Map callRemotePlugin(String pluginName,
                            Map parameters)
                     throws PluginException

Calls a remote server-level plugin specified by the name. This functionality is also known as Plugin Interoperability. Please see the article on http://www.electrotank.com/electroserver for more details.

Parameters:

pluginName - name of the server-level plugin to call

parameters - map of the parameters to be passed to the plugin

Returns:

map containing the response from the plugin

Throws:

PluginException - thrown if there is an error in executing the request

callRemoteRoomPlugin

public Map callRemoteRoomPlugin(String zoneName,
                                String roomName,
                                String pluginName,
                                Map parameters)
                         throws PluginException

Calls a remote room-level plugin specified by the name. This functionality is also known as Plugin Interoperability. Please see the article on http://www.electrotank.com/electroserver for more details.

Parameters:

zoneName - name of the zone containg the room and plugin to call

roomName - name of the room containg the plugin to call

pluginName - name of the server-level plugin to call

parameters - map of the parameters to be passed to the plugin

Returns:

map containing the response from the plugin

Throws:

PluginException - thrown if there is an error in executing the request

writeFile

public boolean writeFile(String fileName,
                         String data,
                         boolean append)

Writes a file to the specified location. The file will be created if it doesn't exist regardless of the append value.

Parameters:

fileName - path and name of the file to write to

data - the data to be written to the file

append - appends the data to the file if it exists

Returns:

true if the operation was successful.

readFile

public String readFile(String fileName)

Reads the specified file and returns the contents as a String.

Parameters:

fileName - path and name of the file to read

Returns:

contents of the file

isDirectory

public boolean isDirectory(String path)

Determines if the specified path is a directory.

Parameters:

path - the path to check

Returns:

true if the specified path is a directory

isFile

public boolean isFile(String path)

Determines if the specified path is a file.

Parameters:

path - the path to check

Returns:

true if the specified path is a file

doesFileExist

public boolean doesFileExist(String path)

Determines if a file exists.

Parameters:

path - the path/name of the file to check

Returns:

true if the specified file exists

doesDirectoryExist

public boolean doesDirectoryExist(String path)

Determines if a directory exists.

Parameters:

path - the path/name of the file to check

Returns:

true if the directory exists

createDirectory

public boolean createDirectory(String path)

Creates the directory and all needed parent directories specified by the path.

Parameters:

path - the path/name of the directory to create

Returns:

true if the operation suceeded.

deleteDirectory

public boolean deleteDirectory(String path)

Deletes the directory specified by the path.

Parameters:

path - path of the directory to delete

Returns:

true if the operation suceeded

deleteFile

public boolean deleteFile(String path)

Deletes the file specified by the path.

Parameters:

path - the path/name of the file to delete

Returns:

true if the operation was a success.

getServerTime

public long getServerTime()

Gets the current time of the server. This is just a wrapper for System.currentTimeMillis().

Returns:

A long representing a millisecond time

severe

public void severe(String message)

Creates a "severe" entry in the server log file.

Parameters:

message - the contents to enter into the log

warning

public void warning(String message)

Creates a "warning" entry in the server log file.

Parameters:

message - the contents to enter into the log

info

public void info(String message)

Creates a "info" entry in the server log file.

Parameters:

message - the contents to enter into the log

config

public void config(String message)

Creates a "config" entry in the server log file.

Parameters:

message - the contents to enter into the log

fine

public void fine(String message)

Creates a "fine" entry in the server log file.

Parameters:

message - the contents to enter into the log

finer

public void finer(String message)

Creates a "finer" entry in the server log file.

Parameters:

message - the contents to enter into the log

finest

public void finest(String message)

Creates a "finest" entry in the server log file.

Parameters:

message - the contents to enter into the log

getName

public String getName()

Returns the name of the extension (plugin or event handler)

Returns:

the name of the extension

getLogger

public Logger getLogger()

Returns the server-wide logger that can be used to log anything needed

Returns:

the server-wide logger

getUserVariables

public UserVariable[] getUserVariables(String userName)

Returns all user variables associated with the specified user.

Parameters:

userName - the name of the user

Returns:

an array of all user variables associated with this user

getUserVariablesAsMap

public Map getUserVariablesAsMap(String userName)

Gets a Map of all user variables tied to this user. Both the key and the value are strings.

Parameters:

userName - the name of the user to use when looking for the variables.

Returns:

a Map containing all the user variables tied to this user.

createUserVariable

public boolean createUserVariable(String userName,
                                  String variableName,
                                  String variableValue)

Creates a user variable for the specified user. This will broadcast the data to the user as soon as the method returns. The variable name and value have to be strings as the data is sent over the wire. You are free to use an encoding scheme like WDDX to store more sophisticated data if you wish.

Parameters:

userName - the name of the user

variableName - the name of the variable

variableValue - the value of the variable

Returns:

true if the variable was created properly. False will be return if the user doesn't exist.

updateUserVariable

public boolean updateUserVariable(String userName,
                                  String variableName,
                                  String variableValue)

Updates a given user variable with the new data. This will broadcast the data to the user as soon as the method returns.

Parameters:

userName - the name of the user

variableName - the name of the variable

variableValue - the value of the variable

Returns:

true if the variable was updated properly. False would be returned if the user or variable doesn't exist.

deleteUserVariable

public boolean deleteUserVariable(String userName,
                                  String variableName)

Deletes the specified user variable. This will broadcast the data to the user as soon as the method returns.

Parameters:

userName - the name of the user

variableName - the name of the variable

Returns:

true if the variable was deleted properly. False would be returned if the user or variable doesn't exist.

getRoomVariables

public RoomVariable[] getRoomVariables(String zoneName,
                                       String roomName)

Gets all room variables for a zone/room combination.Updating the RoomVariable objects returned by this call will NOT update the actual room variables. You need to use the updateRoomVariables call instead.

Parameters:

zoneName - the name of the zone

roomName - the name of the room

Returns:

an array of all room variables for the zone/room combination. This will be null if the zone and/or room doesn't exist.

createRoomVariable

public boolean createRoomVariable(String zoneName,
                                  String roomName,
                                  boolean locked,
                                  String name,
                                  String data)

Creates a room variable in a given zone/room combination. Room variables created with this method are always persistent. You must ensure the variables are removed properly or a resource leak could occur.

Parameters:

zoneName - the name of the zone

roomName - the name of the room

locked - true if this room variable is locked and can't be changed without unlocking

name - the name of the room variable

data - the value of the variable

Returns:

false if the zone or room doesn't exist, otherwise true

updateRoomVariable

public boolean updateRoomVariable(String zoneName,
                                  String roomName,
                                  boolean locked,
                                  String name,
                                  String data)

Updates a given user variables settings and values.

Parameters:

zoneName - the name of the zone

roomName - the name of the room

locked - true if this varlable is locked, false otherwise

name - the name of the room variable to edit

data - the value of the room variable

Returns:

false if the zone or room doesn't exist, otherwise true

deleteRoomVariable

public boolean deleteRoomVariable(String zoneName,
                                  String roomName,
                                  String name)

Deletes a given room variable from the system.

Parameters:

zoneName - the name of the zone

roomName - the name of the room

name - the name of the room variable to delete

Returns:

false if the zone or room doesn't exist, otherwise true

sendPublicMessageToRoom

public boolean sendPublicMessageToRoom(String zoneName,
                                       String roomName,
                                       String message,
                                       Map variables)

Sends a plugin message to the given zone/room combination.

Parameters:

zoneName - the name of the zone

roomName - the name of the room

message - the message to send

variables - variables associated with the message

Returns:

false if the room doesn't exist, otherwise true

sendPublicMessageToZone

public boolean sendPublicMessageToZone(String zoneName,
                                       String message,
                                       Map variables)

Sends a public message to a zone.

Parameters:

zoneName - the name of the zone

message - the message to send

variables - variables associated with the message

Returns:

false if the zone doesn't exist, otherwise true

sendPublicMessageToServer

public boolean sendPublicMessageToServer(String message,
                                         Map variables)

Sends a public message to the entire server.

Parameters:

message - the message to send

variables - variables associated with the message

Returns:

true if the message was sent successfuly.

getAllZones

public ZoneStub[] getAllZones()

Gets all zones on the server.

Returns:

an array of ZoneStub objects that each represent a zone

getRoomsInZone

public RoomStub[] getRoomsInZone(String zoneName)

Gets all rooms in a given zone.

Parameters:

zoneName - the name of the zone.

Returns:

an array of RoomStub objects if the zone was located. If the zone was not found, then null is returned.

getUsersInRoom

public UserStub[] getUsersInRoom(String zoneName,
                                 String roomName)

Returns a list of users from a given zone/room combination.

Parameters:

zoneName - the name of the zone

roomName - the name of the room

Returns:

an array of UserStub objects if the zone/room combination exist, null otherwise.

getLoggedInUserCount

public int getLoggedInUserCount()

Returns a count of all users currently logged into the server.

Returns:

the count of the currently logged in users.

createRoom

public int createRoom(String doc)

Progamatically creates a room with no users in it. This method takes an XML string that follows the same create-room XML used by ElectroServer clients. Due to the number of possible responses, this method returns an integer to indicate the results:
0 - Successfully created the room
1 - Invalid parameters were passed in
2 - Room already exists
3 - Failed creating the room. One common cause for this is when a plugin errors while the room is instantiating it.

Parameters:

doc - the XML string containing the room definition.

Returns:

a status code to indicate the results.

moveToRoom

public int moveToRoom(String userName,
                      String zone,
                      String room,
                      String roomPassword,
                      boolean numbered)

Moves a user into a room progamatically. Due to the number of possible responses, this method returns an integer to indicate the results:
0 - Successfully joined the room
1 - Zone doesn't exist
2 - Room doesn't exist
3 - Invalid room password
4 - Room full
5 - User doesn't exist

Parameters:

userName - the username of the user to move.

zone - the name of the zone in which the room resides.

room - the name of the room.

roomPassword - the password for the room.

numbered - a flag to indicate if this user should be numbered or not.

Returns:

a status code for the results of this call.

getPhysicalMemoryAvailable

public long getPhysicalMemoryAvailable()

getCpuPercentUsed

public double getCpuPercentUsed()

stringContainsVulgarity

public boolean stringContainsVulgarity(String testString)

Tests the given string for vulgarity using the LanguageFilter and the settings initialized in the configuration.xml file.

Parameters:

testString - the string to test.

Returns:

true if the string contains vulgarity, false otherwise.