com.electrotank.electroserver4.extensions.api
Class ElectroServerApiImpl

java.lang.Object
  com.electrotank.electroserver4.extensions.api.ElectroServerApiImpl

All Implemented Interfaces:

ElectroServerApi

Direct Known Subclasses:

EventApiImpl, PluginApiImpl

public abstract class ElectroServerApiImpl
extends Object
implements ElectroServerApi

The ElectroServerApiImpl provides functionality to all custom code and allows the various extensions to interact with the server directly. This API is extended by "function" specific APIs that are used to provide functionality for given components, ie. events, plugins, managed objects, etc. This class and its children classes are provided to extensions automatically and before the first call is made.

Method Summary

Object	acquireManagedObject(String factoryName, EsObjectRO parameters) Acquires a managed object from the specified managed object factory.
boolean	addBuddy(String userName, String buddyName, EsObjectRO esObject) Adds a buddy to the specified user's buddy list.
RoomResponse	addUsersToRoom(int zoneId, int roomId, String password, Collection<UserConfig> userConfigs) Adds the users defined in the UserConfig collection to the specified room.
RoomResponse	addUsersToRoom(int zoneId, int roomId, String password, UserConfig[] userConfigs) Adds the users defined in the UserConfig array to the specified room.
LanguageFilterResponse	applyLanguageFilterToString(String languageFilterName, String stringToTest) Used to call one of the configured language filters to determine if a given string is valid or not.
void	banUserFromRoom(String userName, int zoneId, int roomId, int duration, String reason) Used to kick and ban a user from a room with a specified message.
HttpResults	blockAndCallUrl(String url, boolean isPOST, Map<String,String> parameters) Calls a URL and blocks the current thread of execution until a response is recieved or a global timeout is reached.
EsObject	callRoomPlugin(int zoneId, int roomId, String pluginName, EsObjectRO parameters) Used to invoke the interop method on the designated server-level plugin.
EsObject	callServerPlugin(String pluginName, EsObjectRO parameters) Used to invoke the interop method on the designated server-level plugin.
void	callUrl(String url, boolean isPOST, Map<String,String> parameters, HttpCallback callback) Calls a URL asynchronously and invokes the callback once the call completes.
void	callUrlFromScript(String url, boolean isPOST, Map<String,String> parameters, String callbackName) Calls a URL asynchronously and invokes the method defined by the callback name once the call completes.
void	cancelScheduledExecution(int id) Cancels the scheduled execution identified by the ID.
GameManagerResponse	createGameForUsers(String gameType, Collection<String> users, String zoneName, String password, boolean locked, boolean hidden, EsObject gameDetails) Used to directly create a game for the identified users via the GameManager.
GameManagerResponse	createGameForUsers(String gameType, String[] users, String zoneName, String password, boolean locked, boolean hidden, EsObject gameDetails) Used to directly create a game for the identified users via the GameManager.
UserVariableResponse	createOrUpdateUserVariable(String userName, String name, EsObject value) Creates or updates a user variable as needed.
RoomResponse	createRoom(int zoneId, RoomConfiguration roomConfig, Collection<UserConfig> userConfigs) Creates a room in the specified zone using the supplied room configuration.
RoomResponse	createRoom(int zoneId, RoomConfiguration roomConfig, UserConfig[] userConfigs) Creates a room in the specified zone using the supplied room configuration.
RoomResponse	createRoomInNamedZone(String zoneName, boolean joinExistingZone, RoomConfiguration roomConfig, Collection<UserConfig> userConfigs) Creates a room in the specified zone using the supplied room configuration.
RoomResponse	createRoomInNamedZone(String zoneName, boolean joinExistingZone, RoomConfiguration roomConfig, UserConfig[] userConfigs) Creates a room in the specified zone using the supplied room configuration.
RoomVariableResponse	createRoomVariable(int zoneId, int roomId, String name, EsObject value, boolean locked) Creates a room variable in the specified room.
RoomVariableResponse	createRoomVariableForUser(int zoneId, int roomId, String name, EsObject value, boolean locked, String username, boolean persistent) Creates a room variable in the specified room, tied to a given user.
ExtensionBoundUserServerVariableResponse	deleteExtensionBoundUserServerVariable(String userName, String variableName) Deletes an extension-bound user server variable.
RoomVariableResponse	deleteRoomVariable(int zoneId, int roomId, String name) Deletes the specified room variable.
UserServerVariableResponse	deleteUserServerVariable(String userName, String variableName) Deletes a given user server variable from the specified user.
UserVariableResponse	deleteUserVariable(String userName, String name) Deletes the specified user variable.
void	destroyRoom(int zoneId, int roomId) Destroys the room specified by the room and zone IDs.
ExtensionBoundUserServerVariableResponse	getExtensionBoundUserServerVariable(String userName, String variableName) Looks up and returns an extension-bound user server variable.
String	getExtensionName() Used to get the name of the extension that contains this component.
EsFileSystemApi	getFileSystemApi() Used to access the file system API functionality of the server.
String	getHandle() Used to get the handle of this extension component.
org.slf4j.Logger	getLogger() Acquires a logger for the current component.
String	getName() Used to the get the name of this extension component.
Plugin	getRoomPlugin(int zoneId, int roomId, String pluginName) Used to get a reference to another room plugin based on the zone ID and room ID and plugin name.
Collection<RoomValue>	getRoomsInZone(int zoneId) Looks up and returns all the rooms in a given zone.
Collection<RoomValue>	getRoomsInZoneByName(String zoneName) Looks up and returns all the rooms in a given zone.
ReadOnlyRoomVariable	getRoomVariable(int zoneId, int roomId, String name) Looks up and returns a specific room variable.
Collection<ReadOnlyRoomVariable>	getRoomVariables(int zoneId, int roomId) Looks up and returns all room variables in a given room.
Plugin	getServerPlugin(String pluginName) Used to get a reference to a server level plugin in the same extension, based on the plugin name.
UserValue	getUser(String userName) Used to return details on the specified user.
protected com.electrotank.electroserver4.entities.User	getUserByUserName(String userName)
protected com.electrotank.electroserver4.entities.ConnectedUser	getUserFromName(String userName)
UserServerVariableResponse	getUserServerVariable(String userName, String variableName) Looks up and returns a user server variable.
Collection<UserValue>	getUsersInRoom(int zoneId, int roomId) Looks up and returns all the users in a given room.
ReadOnlyUserVariable	getUserVariable(String userName, String name) Looks up and returns a specific user variable.
Collection<ReadOnlyUserVariable>	getUserVariables(String userName) Looks up and returns all the user variables for a given user.
Collection<ZoneValue>	getZones() Looks up and returns all the zones on the server.
boolean	isUserLoggedIn(String userName) Determines if a user is currently logged in or not.
void	kickUserFromRoom(String userName, int zoneId, int roomId, String reason) Used to kick a user from a room with a specified message.
void	kickUserFromServer(String userName, EsObjectRO reason) Used to kick a user from the server directly.
void	registerGameConfiguration(String gameType, GameConfiguration configuration) Used to register a GameConfiguration with the server so that it can be used in conjunction with the GameManager.
void	releaseManagedObject(String factoryName, Object object) Releases a managed object back to the specified factory.
boolean	removeBuddy(String userName, String buddyName) Removes a buddy from the specified user's buddy list.
int	scheduleExecution(int interval, int numberOfTimes, ScheduledCallback callback) Schedules execution of the callback's method at the defined interval.
int	scheduleExecutionFromScript(int interval, int numberOfTimes, String callbackName) Schedules execution of the callback's method at the defined interval.
PluginPublicMessageResponse	sendPluginMessageToRoom(int zoneId, int roomId, EsObjectRO variables) Sends a plugin message to all users in a room.
PluginPublicMessageResponse	sendPluginMessageToRooms(Map<Integer,Collection<Integer>> zoneRoomCombos, EsObjectRO variables) Sends a plugin message to a group of rooms.
PluginPublicMessageResponse	sendPluginMessageToServer(EsObjectRO variables) Sends a plugin message to the entire server.
PluginPrivateMessageResponse	sendPluginMessageToUser(String userName, EsObjectRO variables) Sends a plugin message to a user.
PluginPrivateMessageResponse	sendPluginMessageToUsers(Collection<String> userNames, EsObjectRO variables) Sends a plugin message to a group of users.
PluginPrivateMessageResponse	sendPluginMessageToUsers(String[] userNames, EsObjectRO variables) Sends a plugin message to a group of users.
PluginPublicMessageResponse	sendPluginMessageToZone(int zoneId, EsObjectRO variables) Sends a plugin message to all users in a zone.
PluginPublicMessageResponse	sendPluginMessageToZones(Collection<Integer> zoneIds, EsObjectRO variables) Sends a plugin message to a group of zones.
PluginPublicMessageResponse	sendPluginMessageToZones(int[] zoneIds, EsObjectRO variables) Sends a plugin message to a group of zones.
ExtensionBoundUserServerVariableResponse	setExtensionBoundUserServerVariable(String userName, String variableName, Object variableValue) Sets an extension-bound user server variable on a given user.
UserServerVariableResponse	setUserServerVariable(String userName, String variableName, EsObject variableValue) Sets a user server variable on a given user.
RoomVariableResponse	updateRoomVariable(int zoneId, int roomId, String name, boolean valueUpdated, EsObject value, boolean lockStatusUpdated, boolean locked) Updates the specified room variable.

Methods inherited from class java.lang.Object

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

Method Detail

addBuddy

public boolean addBuddy(String userName,
                        String buddyName,
                        EsObjectRO esObject)

Description copied from interface: ElectroServerApi

Adds a buddy to the specified user's buddy list. This method only works if the user (not the buddy) is currently online. The boolean returned will indicate success or failure. The associated EsObject is provided as a convenience that allows the developer to associate meta-data with the relationship. A good example of this might be group information.

Specified by:

addBuddy in interface ElectroServerApi

Parameters:

userName - user name of the user whose buddy list the buddy should be added

buddyName - user name of the buddy to be added

esObject - optional meta-data to be associated with the buddy

Returns:

true if the addition was successful, false otherwise

See Also:

removeBuddy

removeBuddy

public boolean removeBuddy(String userName,
                           String buddyName)

Description copied from interface: ElectroServerApi

Removes a buddy from the specified user's buddy list. This method only works if the user (not the buddy) is currently online. The boolean returned will indicate success or failure.

Specified by:

removeBuddy in interface ElectroServerApi

Parameters:

userName - user name of the user whose buddy list the buddy should be removed

buddyName - user name of the buddy to be removed

Returns:

true if the removal was successful, false otherwise

See Also:

addBuddy, EsObject

applyLanguageFilterToString

public LanguageFilterResponse applyLanguageFilterToString(String languageFilterName,
                                                          String stringToTest)

Description copied from interface: ElectroServerApi

Used to call one of the configured language filters to determine if a given string is valid or not. The filter used will behave exactly as it does normally except it doesn't take any action against the user if a string fails. The response object contains all the details on the sucess of the call. Of particular interest is the success or failure boolean, which is used to determine if the call was successful. If the call failed, check the error status with the getError method on the response object. Finally, if the call was sucessful, the isStringValid method is used to determine if the string passed or failed the test.

Specified by:

applyLanguageFilterToString in interface ElectroServerApi

Parameters:

languageFilterName - the name of the language filter to invoke

stringToTest - the string to test with the selected langauge filter

Returns:

a response object containing all the details of the call

See Also:

LanguageFilterResponse

getLogger

public org.slf4j.Logger getLogger()

Description copied from interface: ElectroServerApi

Acquires a logger for the current component. The logger returned is an interface in the SLF4J framework. Javadocs for the Logger interface can be found here: http://www.slf4j.org/api/org/slf4j/Logger.html

The logging framework for extensions allows for a great deal of flexibility. When getLogger is called, it returns a Logger interface with a custom logger hierarchy. The format of the hierarchy looks like this: Extensions.<extension_name>.<component_type>.<component_handle> Component types will be "ManagedObjectFactories", "Plugins", or "EventHandlers". So a specific example might be: Extensions.MyGameExtension.Plugins.MyGamePlugin

By configuring the logging configuration file in the server config directory, the developer has complete control over the logging levels and ouput format of log messages for all extensions, or individual extensions or even single components.

Specified by:

getLogger in interface ElectroServerApi

Returns:

SLF4J Logger interface for the current component

sendPluginMessageToUser

public PluginPrivateMessageResponse sendPluginMessageToUser(String userName,
                                                            EsObjectRO variables)

Description copied from interface: ElectroServerApi

Sends a plugin message to a user. With the associated EsObject, almost anything can be sent.

Specified by:

sendPluginMessageToUser in interface ElectroServerApi

Parameters:

userName - the name of the user

variables - the EsObject to send as part of the message

Returns:

a response indicating the status of the delivery

See Also:

sendPluginMessageToRoom, sendPluginMessageToRooms, sendPluginMessageToServer, sendPluginMessageToUsers, sendPluginMessageToZone, sendPluginMessageToZones, PluginPublicMessageResponse, EsObjectRO

sendPluginMessageToUsers

public PluginPrivateMessageResponse sendPluginMessageToUsers(String[] userNames,
                                                             EsObjectRO variables)

Description copied from interface: ElectroServerApi

Sends a plugin message to a group of users. With the associated EsObject, almost anything can be sent.

Specified by:

sendPluginMessageToUsers in interface ElectroServerApi

Parameters:

userNames - an array of user names that should receive this mesage

variables - the EsObject to send as part of the message

Returns:

a response indicating the status of the delivery

See Also:

sendPluginMessageToRoom, sendPluginMessageToRooms, sendPluginMessageToServer, sendPluginMessageToUser, sendPluginMessageToZone, sendPluginMessageToZones, PluginPublicMessageResponse, EsObjectRO

sendPluginMessageToUsers

public PluginPrivateMessageResponse sendPluginMessageToUsers(Collection<String> userNames,
                                                             EsObjectRO variables)

Description copied from interface: ElectroServerApi

Sends a plugin message to a group of users. With the associated EsObject, almost anything can be sent.

Specified by:

sendPluginMessageToUsers in interface ElectroServerApi

Parameters:

userNames - a Collection of user names that should receive this mesage

variables - the EsObject to send as part of the message

Returns:

a response indicating the status of the delivery

See Also:

sendPluginMessageToRoom, sendPluginMessageToRooms, sendPluginMessageToServer, sendPluginMessageToUser, sendPluginMessageToZone, sendPluginMessageToZones, PluginPublicMessageResponse, EsObjectRO

sendPluginMessageToServer

public PluginPublicMessageResponse sendPluginMessageToServer(EsObjectRO variables)

Description copied from interface: ElectroServerApi

Sends a plugin message to the entire server. With the associated EsObject, almost anything can be sent.

Specified by:

sendPluginMessageToServer in interface ElectroServerApi

Parameters:

variables - the EsObject to send as part of the message

Returns:

a response indicating the status of the delivery

See Also:

sendPluginMessageToRoom, sendPluginMessageToRooms, sendPluginMessageToUser, sendPluginMessageToUsers, sendPluginMessageToZone, sendPluginMessageToZones, PluginPublicMessageResponse, EsObjectRO

sendPluginMessageToZone

public PluginPublicMessageResponse sendPluginMessageToZone(int zoneId,
                                                           EsObjectRO variables)

Description copied from interface: ElectroServerApi

Sends a plugin message to all users in a zone. With the associated EsObject, almost anything can be sent.

Specified by:

sendPluginMessageToZone in interface ElectroServerApi

Parameters:

zoneId - the zone ID

variables - the EsObject to send as part of the message

Returns:

a response indicating the status of the delivery

See Also:

sendPluginMessageToRoom, sendPluginMessageToRooms, sendPluginMessageToServer, sendPluginMessageToUser, sendPluginMessageToUsers, sendPluginMessageToZones, PluginPublicMessageResponse, EsObjectRO

sendPluginMessageToZones

public PluginPublicMessageResponse sendPluginMessageToZones(int[] zoneIds,
                                                            EsObjectRO variables)

Description copied from interface: ElectroServerApi

Sends a plugin message to a group of zones. With the associated EsObject, almost anything can be sent.

Specified by:

sendPluginMessageToZones in interface ElectroServerApi

Parameters:

zoneIds - an array of zone IDs

variables - the EsObject to send as part of the message

Returns:

a response indicating the status of the delivery

See Also:

sendPluginMessageToRoom, sendPluginMessageToRooms, sendPluginMessageToServer, sendPluginMessageToUser, sendPluginMessageToUsers, sendPluginMessageToZone, PluginPublicMessageResponse, EsObjectRO

sendPluginMessageToZones

public PluginPublicMessageResponse sendPluginMessageToZones(Collection<Integer> zoneIds,
                                                            EsObjectRO variables)

Description copied from interface: ElectroServerApi

Sends a plugin message to a group of zones. With the associated EsObject, almost anything can be sent.

Specified by:

sendPluginMessageToZones in interface ElectroServerApi

Parameters:

zoneIds - a Collection of zone IDs

variables - the EsObject to send as part of the message

Returns:

a response indicating the status of the delivery

See Also:

sendPluginMessageToRoom, sendPluginMessageToRooms, sendPluginMessageToServer, sendPluginMessageToUser, sendPluginMessageToUsers, sendPluginMessageToZone, PluginPublicMessageResponse, EsObjectRO

sendPluginMessageToRoom

public PluginPublicMessageResponse sendPluginMessageToRoom(int zoneId,
                                                           int roomId,
                                                           EsObjectRO variables)

Description copied from interface: ElectroServerApi

Sends a plugin message to all users in a room. With the associated EsObject, almost anything can be sent.

Specified by:

sendPluginMessageToRoom in interface ElectroServerApi

Parameters:

zoneId - the zone ID

roomId - the room ID

variables - the EsObject to send as part of the message

Returns:

a response indicating the status of the delivery

See Also:

sendPluginMessageToRooms, sendPluginMessageToServer, sendPluginMessageToUser, sendPluginMessageToUsers, sendPluginMessageToZone, sendPluginMessageToZones, PluginPublicMessageResponse, EsObjectRO

sendPluginMessageToRooms

public PluginPublicMessageResponse sendPluginMessageToRooms(Map<Integer,Collection<Integer>> zoneRoomCombos,
                                                            EsObjectRO variables)

Description copied from interface: ElectroServerApi

Sends a plugin message to a group of rooms. With the associated EsObject, almost anything can be sent.

Specified by:

sendPluginMessageToRooms in interface ElectroServerApi

Parameters:

zoneRoomCombos - a map containing the zone ID as a key tied to a list of room IDs

variables - the EsObject to send as part of the message

Returns:

a response indicating the status of the delivery

See Also:

sendPluginMessageToRoom, sendPluginMessageToServer, sendPluginMessageToUser, sendPluginMessageToUsers, sendPluginMessageToZone, sendPluginMessageToZones, PluginPublicMessageResponse, EsObjectRO

createRoomInNamedZone

public RoomResponse createRoomInNamedZone(String zoneName,
                                          boolean joinExistingZone,
                                          RoomConfiguration roomConfig,
                                          UserConfig[] userConfigs)

Description copied from interface: ElectroServerApi

Creates a room in the specified zone using the supplied room configuration. Once the room is created, the users are joined via the user configuration array. The RoomResponse returned from this call provides details on the status of the call.

Specified by:

createRoomInNamedZone in interface ElectroServerApi

Parameters:

zoneName - the zone name

joinExistingZone - boolean indicating if the room should join an existing zone if it exists

roomConfig - the room configuration to use for this new room

userConfigs - the configuration of users to join this room

Returns:

a response indicating the status of the call

See Also:

createRoom, destroyRoom, RoomResponse, RoomConfiguration, UserConfig

createRoomInNamedZone

public RoomResponse createRoomInNamedZone(String zoneName,
                                          boolean joinExistingZone,
                                          RoomConfiguration roomConfig,
                                          Collection<UserConfig> userConfigs)

Description copied from interface: ElectroServerApi

Creates a room in the specified zone using the supplied room configuration. Once the room is created, the users are joined via the user configuration collection. The RoomResponse returned from this call provides details on the status of the call.

Specified by:

createRoomInNamedZone in interface ElectroServerApi

Parameters:

zoneName - the zone name

joinExistingZone - boolean indicating if the room should join an existing zone if it exists

roomConfig - the room configuration to use for this new room

userConfigs - the configuration of users to join this room

Returns:

a response indicating the status of the call

See Also:

createRoom, destroyRoom, RoomResponse, RoomConfiguration, UserConfig

createRoom

public RoomResponse createRoom(int zoneId,
                               RoomConfiguration roomConfig,
                               UserConfig[] userConfigs)

Description copied from interface: ElectroServerApi

Creates a room in the specified zone using the supplied room configuration. Once the room is created, the users are joined via the user configuration array. The RoomResponse returned from this call provides details on the status of the call.

Specified by:

createRoom in interface ElectroServerApi

Parameters:

zoneId - the zone id

roomConfig - the room configuration to use for this new room

userConfigs - the configuration of users to join this room

Returns:

a response indicating the status of the call

See Also:

createRoomInNamedZone, destroyRoom, RoomResponse, RoomConfiguration, UserConfig

createRoom

public Ro