ElectroServerApi (ElectroServer 4

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.electrotank.electroserver4.extensions.api
Interface ElectroServerApi

All Known Subinterfaces:: EventApi, ManagedObjectFactoryApi, PluginApi

All Known Implementing Classes:: ElectroServerApiImpl, EventApiImpl, PluginApiImpl

public interface ElectroServerApi

The foundation of all server-side API code in ElectroServer 4. Any server-side, custom-code in any language supported will have access to all methods defined in this interface. Any specific extension component from plugin to event-handler will be able to access a specific implementor of the ElectroServerApi by calling the getApi() method on the component. The api will be available to the component by the time the lifecycle "init" method is invoked.

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.
`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.

Method Detail

addBuddy

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

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.

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

boolean removeBuddy(String userName,
                    String buddyName)

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.

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

acquireManagedObject

Object acquireManagedObject(String factoryName,
                            EsObjectRO parameters)

Acquires a managed object from the specified managed object factory. Any code using this method will be limited to managed object factories defined in the same extension as this component. Managed object factories are not accessible across extensions because they return raw objects rather then safer objects (like EsObject) - see the ElectroServer 4 Manual for an overview of the class loader proces and why separation of extensions is required.

The parameters object will be passed directly to the managed object factory. In practice, it is used to provide additional information to the factory in helping it return the appropriate object. A good example might be a connection pooling factory and the parameters object contains the name of the pool to use.

Parameters:: factoryName - name of the managed object factory as it is defined in the specific extension.xml file.; parameters - optional EsObject that will be passed
Returns:: object returned from the factory
See Also:: releaseManagedObject, ManagedObjectFactory, EsObject, ElectroServer 4 Manual

releaseManagedObject

void releaseManagedObject(String factoryName,
                          Object object)

Releases a managed object back to the specified factory. Any code using this method will be limited to managed object factories defined in the same extension as this component. Managed object factories are not accessible across extensions because they return raw objects rather then safer objects (like EsObject) - see the ElectroServer 4 Manual for an overview of the class loader proces and why separation of extensions is required.

Parameters:: factoryName - the factory's name; object - the object to release
See Also:: acquireManagedObject, ManagedObjectFactory, EsObject, ElectroServer 4 Manual

getLogger

org.slf4j.Logger getLogger()

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.

Returns:: SLF4J Logger interface for the current component

applyLanguageFilterToString

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. 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.

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

blockAndCallUrl

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. This is a synchronous call. This method is capable of simulating either a GET or POST request directly based on the value of the isPOST boolean. The result of this call is an instance of the HttpResults object. This object contains a variety of methods to interact with the data directly as bytes, convert it to a string, or to even parse the results into a name/value pair map (like LoadVars in Flash).

Parameters:: url - address of the page to call; isPOST - true if sending a POST request, false if sending a GET request; parameters - map of name/value parameters to the be sent to the address. Ignored for GET requests
Returns:: object indicating sucess or failure of the call as well as any returned data
See Also:: callUrl, callUrlFromScript, HttpResults, HttpCallback

callUrl

void callUrl(String url,
             boolean isPOST,
             Map<String,String> parameters,
             HttpCallback callback)

Calls a URL asynchronously and invokes the callback once the call completes. This method is capable of simulating either a GET or POST request directly based on the value of the isPOST boolean. The result of this call is an instance of the HttpResults object. This object contains a variety of methods to interact with the data directly as bytes, convert it to a string, or to even parse the results into a name/value pair map (like LoadVars in Flash).

Parameters:: url - address of the page to call; isPOST - true if sending a POST request, false if sending a GET request; parameters - map of name/value parameters to the be sent to the address. Ignored for GET requests; callback - callback to be invoked once this method completes either successfully or not
See Also:: blockAndCallUrl, callUrlFromScript, HttpResults, HttpCallback

callUrlFromScript

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. This method is capable of simulating either a GET or POST request directly based on the value of the isPOST boolean. The result of this call is an instance of the HttpResults object. This object contains a variety of methods to interact with the data directly as bytes, convert it to a string, or to even parse the results into a name/value pair map (like LoadVars in Flash).

NOTE: THIS IS ONLY CALLABLE FROM A SCRIPT COMPONENT!

Parameters:: url - address of the page to call; isPOST - true if sending a POST request, false if sending a GET request; parameters - map of name/value parameters to the be sent to the address. Ignored for GET requests; callbackName - callback to be invoked once this method completes either successfully or not
See Also:: blockAndCallUrl, callUrl, HttpResults, HttpCallback

scheduleExecution

int scheduleExecution(int interval,
                      int numberOfTimes,
                      ScheduledCallback callback)

Schedules execution of the callback's method at the defined interval. The callback will execute the specified number of times before stopping. To execute a callback once, numberOfTimes needs to be set to 1. To execute the callback indefinitely, then numberOfTimes should be set to -1. The first execution will occur after the interval has passed. All subsequent executions will occur after the interval has passed. The interval's duration is measured in milliseconds.

This method uses the server-wide ScheduledExecutorService which shares the global thread pool. This ensures best possible performance and scalability. The global thread pool settings are configurable in the web-based administration console.

This method is designed to respect server lifecycle events. To that end, if the server stops the extension component for any reason, all scheduled executions are canceled. The returned ID is used to cancel a scheduled execution directly via the cancelScheduledExecution method.

For example:

            int id = getApi().scheduleExecution(durationInMilliseconds,
                    numberOfTimesToRepeat,
                    new ScheduledCallback() {

                        public void scheduledCallback() {
                            ... lines to be executed ...
                        }
                    });

Parameters:: interval - duration (ms) until the execution is called as well as the duration between subsequent executions; numberOfTimes - number of times to execute the callback, -1 is used to indicate indefinite execution; callback - callback to invoke on the schedule
Returns:: ID that represents this scheduled execution
See Also:: scheduleExecutionFromScript, cancelScheduledExecution

scheduleExecutionFromScript

int scheduleExecutionFromScript(int interval,
                                int numberOfTimes,
                                String callbackName)

Schedules execution of the callback's method at the defined interval. The callback will execute the specified number of times before stopping. To execute a callback once, numberOfTimes needs to be set to 1. To execute the callback to execute indefinitely, then numberOfTimes should be set to -1. The first execution will occur after the interval has passed. All subsequent executions will occur after the interval has passed. The interval's duration is measured in milliseconds.

NOTE: THIS IS ONLY CALLABLE FROM A SCRIPT COMPONENT!

Parameters:: interval - duration (ms) until the execution is called as well as the duration between subsequent executions; numberOfTimes - number of times to execute the callback. -1 is used to indicate indefinite execution; callbackName - name of the callback method to invoke on the schedule
Returns:: ID that represents this scheduled execution
See Also:: scheduleExecution, cancelScheduledExecution

cancelScheduledExecution

void cancelScheduledExecution(int id)

Cancels the scheduled execution identified by the ID. This method stops any future callback execution but does not or fail the callback if it's currently running.

Parameters:: id - ID of the scheduled execution to cancel
See Also:: scheduleExecution, scheduleExecutionFromScript

addUsersToRoom

RoomResponse addUsersToRoom(int zoneId,
                            int roomId,
                            String password,
                            Collection<UserConfig> userConfigs)

Adds the users defined in the UserConfig collection to the specified room. From the user's standpoint, this method behaves the same as if the user joined the room directly. The RoomResponse returned from this call provides details on the status of the call.

Parameters:: zoneId - zone ID for the specific room; roomId - room ID for the specific room; password - password of the room; userConfigs - configuration collection of the users to join the specified room
Returns:: response indicating the status of the call with details for each user
See Also:: RoomResponse, UserConfig

addUsersToRoom

RoomResponse addUsersToRoom(int zoneId,
                            int roomId,
                            String password,
                            UserConfig[] userConfigs)

Adds the users defined in the UserConfig array to the specified room. From the user's standpoint, this method behaves the same as if the user joined the room directly. The RoomResponse returned from this call provides details on the status of the call.

Parameters:: zoneId - zone ID for the specific room; roomId - room ID for the specific room; password - password of the room; userConfigs - configuration array of the users to join the specified room
Returns:: response indicating the status of the call with details for each user
See Also:: RoomResponse, UserConfig

createRoom

RoomResponse createRoom(int zoneId,
                        RoomConfiguration roomConfig,
                        Collection<UserConfig> userConfigs)

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.

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

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

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.

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

createRoomInNamedZone

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

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

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

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

destroyRoom

void destroyRoom(int zoneId,
                 int roomId)

Destroys the room specified by the room and zone IDs. Any users in the room will be notified that the room is destroyed.

Parameters:: zoneId - the zone ID; roomId - the room ID
See Also:: createRoom, createRoomInNamedZone

createRoomVariable

RoomVariableResponse createRoomVariable(int zoneId,
                                        int roomId,
                                        String name,
                                        EsObject value,
                                        boolean locked)

Creates a room variable in the specified room.

Parameters:: zoneId - the zone ID; roomId - the room ID; name - the name of the variable; value - the value of the variable; locked - a boolean indicating if the variable is locked or not
Returns:: a response indicating the status of the call
See Also:: createRoomVariableForUser, updateRoomVariable, deleteRoomVariable, RoomVariableResponse, EsObject

createRoomVariableForUser

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.

Parameters:: zoneId - the zone ID; roomId - the room ID; name - the name of the variable; value - the value of the variable; locked - a boolean indicating if the variable is locked or not; username - name of the user tied to the variable; persistent - is this a persistent variable
Returns:: a response indicating the status of the call
See Also:: createRoomVariable, updateRoomVariable, deleteRoomVariable, RoomVariableResponse, EsObject

updateRoomVariable

RoomVariableResponse updateRoomVariable(int zoneId,
                                        int roomId,
                                        String name,
                                        boolean valueUpdated,
                                        EsObject value,
                                        boolean lockStatusUpdated,
                                        boolean locked)

Updates the specified room variable.

Parameters:: zoneId - the zone ID; roomId - the room ID; name - the name of the variable; valueUpdated - a boolean indicating if the variable was updated; value - the value of the variable; lockStatusUpdated - a boolean indicating if the lock has been changed; locked - the value of the lock
Returns:: a response indicating the status of the call
See Also:: createRoomVariable, createRoomVariableForUser, deleteRoomVariable, RoomVariableResponse, EsObject

deleteRoomVariable

RoomVariableResponse deleteRoomVariable(int zoneId,
                                        int roomId,
                                        String name)

Deletes the specified room variable.

Parameters:: zoneId - the zone ID; roomId - the room ID; name - the name of the variable
Returns:: a response indicating the status of the call
See Also:: createRoomVariable, createRoomVariableForUser, updateRoomVariable, RoomVariableResponse

getExtensionBoundUserServerVariable

ExtensionBoundUserServerVariableResponse getExtensionBoundUserServerVariable(String userName,
                                                                             String variableName)

Looks up and returns an extension-bound user server variable. The user must be logged in, so this will not work inside a LoginEventHandler.

Parameters:: userName - the user name; variableName - the variable name
Returns:: a response indicating the status of the call and, if successful, a read-only extension-bound user server variable
See Also:: setExtensionBoundUserServerVariable, deleteExtensionBoundUserServerVariable, ExtensionBoundUserServerVariableResponse

setExtensionBoundUserServerVariable

ExtensionBoundUserServerVariableResponse setExtensionBoundUserServerVariable(String userName,
                                                                             String variableName,
                                                                             Object variableValue)

Sets an extension-bound user server variable on a given user. The user must be logged in, so this will not work inside a LoginEventHandler.

Parameters:: userName - the user name; variableName - the variable name; variableValue - the variable value
Returns:: a response indicating the status of the call
See Also:: getExtensionBoundUserServerVariable, deleteExtensionBoundUserServerVariable, ExtensionBoundUserServerVariableResponse

deleteExtensionBoundUserServerVariable

ExtensionBoundUserServerVariableResponse deleteExtensionBoundUserServerVariable(String userName,
                                                                                String variableName)

Deletes an extension-bound user server variable. The user must be logged in, so this will not work inside a LoginEventHandler.

Parameters:: userName - the user name; variableName - the variable name
Returns:: a response indicating the status of the call
See Also:: getExtensionBoundUserServerVariable, setExtensionBoundUserServerVariable, ExtensionBoundUserServerVariableResponse

getUserServerVariable

UserServerVariableResponse getUserServerVariable(String userName,
                                                 String variableName)

Looks up and returns a user server variable. The user must be logged in, so this will not work inside a LoginEventHandler.

Parameters:: userName - the user name; variableName - the variable name
Returns:: a response indicating the status of the call and, if successful, a read-only user server variable
See Also:: setUserServerVariable, deleteUserServerVariable, UserServerVariableResponse

setUserServerVariable

UserServerVariableResponse setUserServerVariable(String userName,
                                                 String variableName,
                                                 EsObject variableValue)

Sets a user server variable on a given user. The user must be logged in, so this will not work inside a LoginEventHandler.

Parameters:: userName - the user name; variableName - the variable name; variableValue - the variable value
Returns:: a response indicating the status of the call
See Also:: getUserServerVariable, deleteUserServerVariable, UserServerVariableResponse, EsObject

deleteUserServerVariable

UserServerVariableResponse deleteUserServerVariable(String userName,
                                                    String variableName)

Deletes a given user server variable from the specified user. The user must be logged in, so this will not work inside a LoginEventHandler.

Parameters:: userName - the user name; variableName - the variable name
Returns:: a response indicating the status of the call
See Also:: getUserServerVariable, setUserServerVariable, UserServerVariableResponse

createOrUpdateUserVariable

UserVariableResponse createOrUpdateUserVariable(String userName,
                                                String name,
                                                EsObject value)

Creates or updates a user variable as needed. The user must be logged in, so this will not work inside a LoginEventHandler.

Parameters:: userName - the user name; name - the variable name; value - the variable value
Returns:: a response indicating the status of the call
See Also:: deleteUserVariable, getUserVariable, getUserVariables, UserVariableResponse, EsObject

deleteUserVariable

UserVariableResponse deleteUserVariable(String userName,
                                        String name)

Deletes the specified user variable. The user must be logged in, so this will not work inside a LoginEventHandler.

Parameters:: userName - the user name; name - the variable name
Returns:: a response indicating the status of the call
See Also:: createOrUpdateUserVariable, getUserVariable, getUserVariables, UserVariableResponse

getUserVariable

ReadOnlyUserVariable getUserVariable(String userName,
                                     String name)

Looks up and returns a specific user variable. This method will return null if the user variable isn't found. The user must be logged in, so this will not work inside a LoginEventHandler.

Parameters:: userName - the user name; name - the variable name
Returns:: a read-only user variable or null if it wasn't found
See Also:: getUserVariables, ReadOnlyUserVariable

getUserVariables

Collection<ReadOnlyUserVariable> getUserVariables(String userName)

Looks up and returns all the user variables for a given user. The user must be logged in, so this will not work inside a LoginEventHandler.

Parameters:: userName - the user name
Returns:: a collection of read-only user variables
See Also:: getUserVariable, ReadOnlyUserVariable

getHandle

String getHandle()

Used to get the handle of this extension component.

Returns:: the handle of this component

getName

String getName()

Used to the get the name of this extension component.

Returns:: the name of this component

getExtensionName

String getExtensionName()

Used to get the name of the extension that contains this component.

Returns:: the name of the extension

getFileSystemApi

EsFileSystemApi getFileSystemApi()

Used to access the file system API functionality of the server.

Returns:: the FileSystemAPI
See Also:: EsFileSystemApi

getRoomVariable

ReadOnlyRoomVariable getRoomVariable(int zoneId,
                                     int roomId,
                                     String name)

Looks up and returns a specific room variable.

Parameters:: zoneId - the zone ID; roomId - the room ID; name - the variable name
Returns:: a read-only room variable
See Also:: getRoomVariables, ReadOnlyRoomVariable

getRoomVariables

Collection<ReadOnlyRoomVariable> getRoomVariables(int zoneId,
                                                  int roomId)

Looks up and returns all room variables in a given room.

Parameters:: zoneId - the zone ID; roomId - the room ID
Returns:: a collection of all room variables in the room
See Also:: getRoomVariable, ReadOnlyRoomVariable

getZones

Collection<ZoneValue> getZones()

Looks up and returns all the zones on the server.

Returns:: a collection of read-only zones
See Also:: ZoneValue

getRoomsInZone

Collection<RoomValue> getRoomsInZone(int zoneId)

Looks up and returns all the rooms in a given zone.

Parameters:: zoneId - the zone ID
Returns:: a collection of read-only rooms
See Also:: getRoomsInZoneByName, RoomValue

getRoomsInZoneByName

Collection<RoomValue> getRoomsInZoneByName(String zoneName)

Looks up and returns all the rooms in a given zone.

Parameters:: zoneName - the zone name
Returns:: a collection of read-only rooms
See Also:: getRoomsInZone, RoomValue

getRoomPlugin

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. This can be used as a clean replacement for the Plugin Interop ability. Once the plugin reference is available, the plugin can get cast to its original type allowing for direct calls to be made.

NOTE: This can only be called from a Java plugin to access another Java plugin from the same extension.

Parameters:: zoneId - the zone ID; roomId - the room ID; pluginName - the name of the plugin
Returns:: the designated Plugin
See Also:: getServerPlugin, Plugin

getServerPlugin

Plugin getServerPlugin(String pluginName)

Used to get a reference to a server level plugin in the same extension, based on the plugin name. This can be used as a clean replacement for the Plugin Interop ability. Once the plugin reference is available, the plugin can get cast to its original type allowing for direct calls to be made.

NOTE: This can only be called from a Java plugin to access another Java plugin from the same extension.

Parameters:: pluginName - the name of the server-level plugin
Returns:: the designated Plugin
See Also:: getRoomPlugin, Plugin

callRoomPlugin

EsObject callRoomPlugin(int zoneId,
                        int roomId,
                        String pluginName,
                        EsObjectRO parameters)

Used to invoke the interop method on the designated server-level plugin. This method is the primary way for a plugin to interact with another plugin in a different extension. While this can be used with plugins in the same extension, it's simpler to use the getRoomPlugin or getServerPlugin methods unless script plugins are involved (see the note on those methods for details).

The designated plugin must implement the PluginInterop interface or extend a base class that does this already (like BasePlugin).

Note: This can be used to send data between script and Java plugins.

Parameters:: zoneId - the zone ID; roomId - the room ID; pluginName - the name of the plugin; parameters - the parameters to pass to the "interop" method of the plugin
Returns:: the results of the "interop" method on the designated plugin
See Also:: callServerPlugin, getRoomPlugin, getServerPlugin, BasePlugin, PluginInterop, EsObject

callServerPlugin

EsObject callServerPlugin(String pluginName,
                          EsObjectRO parameters)

The designated plugin must implement the PluginInterop interface or extend a base class that does this already (like BasePlugin).

Note: This can be used to send data between script and Java plugins.

Parameters:: pluginName - the plugin name; parameters - the parameters to pass to the "interop" method of the plugin
Returns:: the results of the "interop" method on the designated plugin
See Also:: callRoomPlugin, getRoomPlugin, getServerPlugin, BasePlugin, PluginInterop, EsObject

getUser

UserValue getUser(String userName)

Used to return details on the specified user. This method retuns null if a user with the specified name is not found.

Parameters:: userName - the name of the user
Returns:: a UserValue containing data on the user or null of the user was not found
See Also:: getUsersInRoom, UserValue

isUserLoggedIn

boolean isUserLoggedIn(String userName)

Determines if a user is currently logged in or not.

Parameters:: userName - the users name
Returns:: a boolean indicating if the user is logged in

getUsersInRoom

Collection<UserValue> getUsersInRoom(int zoneId,
                                     int roomId)

Looks up and returns all the users in a given room.

Parameters:: zoneId - the zone ID; roomId - the room ID
Returns:: a collection of read-only user
See Also:: getUser, UserValue

kickUserFromRoom

void kickUserFromRoom(String userName,
                      int zoneId,
                      int roomId,
                      String reason)

Used to kick a user from a room with a specified message. When invoked, the user specified will recieve the message as part of the kick message from the server. Any users in the room will also be notified that the user was kicked along with the message.

Parameters:: userName - the name of the user to kick; zoneId - the zone ID; roomId - the ID of the room containing the user; reason - the reason the user was kicked
See Also:: banUserFromRoom, kickUserFromServer

banUserFromRoom

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. When invoked, the user specified will recieve the message as part of the ban message from the server. Any users in the room will also be notified that the user was banned along with the message.

In addition to being kicked, the user is unable to re-enter the room until the specified duration has elapsed. Duration is measured in seconds.

Parameters:: userName - the name of the user to kick; zoneId - the zone ID; roomId - the ID of the room containing the user; duration - (seconds) how long the user should be banned or -1 for an indefinite ban; reason - the reason the user was kicked
See Also:: kickUserFromRoom, kickUserFromServer

kickUserFromServer

void kickUserFromServer(String userName,
                        EsObjectRO reason)

Used to kick a user from the server directly. If the user is connected to multiple gateways, they will be disconnected sequentially from each.

Parameters:: userName - the name of the user to kick; reason - the reason the user was kicked
See Also:: kickUserFromRoom, banUserFromRoom

registerGameConfiguration

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. Before any game can be created with the GameManager it must be registered. The game type is required to identify the specific game configuration for future calls.

When the GameManager is used to find or create a game, it will use the game type to find the correct GameConfiguration. Then it will use the GameConfiguration to create the specific zone/room configuration the game needs.

For details on using the GameManager, see the ElectroServer 4 Manual, Game Manager.

Parameters:: gameType - the game type to associate with this configuration; configuration - the GameConfiguration for this game type
See Also:: GameConfiguration

createGameForUsers

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. Once this game is created, it will behave just as though it were created via clients.

The hidden, locked, and gameDetails parameters all relate to the state of the game once creation is complete. Locked is used to prevent users from joining the game once it is created. Hidden is used to show or hide the game from the game list retrieved from the GameManager. GameDetails are used to provide extra information to the GameManager for searching and identifying the game.

For details on using the GameManager, see the ElectroServer 4 Manual, Game Manager.

Parameters:: gameType - the game type to create; users - a Collection of users to join to the game; zoneName - the name of the zone in which to create the game room - this zone will be created if needed; password - the password to establish on the game room, this password will be needed for any users to enter later; locked - if the game room is to be locked initially (this can be changed later if needed); hidden - if the game room is to be hidden initially (this can be changed later if needed); gameDetails - the custom details of the game that are to be made available to the GameManager (this can be changed later if needed)
Returns:: a response indicating the success or failure of this call
See Also:: GameManagerResponse, EsObject

createGameForUsers

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. Once this game is created, it will behave just as though it were created via clients.

For details on using the GameManager, see the ElectroServer 4 Manual, Game Manager.

Parameters:: gameType - the game type to create; users - an array of users to join to the game; zoneName - the name of the zone in which to create the game room - this zone will be created if needed; password - the password to establish on the game room, this password will be needed for any users to enter later; locked - if the game room is to be locked initially (this can be changed later if needed); hidden - if the game room is to be hidden initially (this can be changed later if needed); gameDetails - the custom details of the game that are to be made available to the GameManager (this can be changed later if needed)
Returns:: a response indicating the success or failure of this call
See Also:: GameManagerResponse, EsObject

sendPluginMessageToRoom

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

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

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

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

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

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

sendPluginMessageToServer

PluginPublicMessageResponse sendPluginMessageToServer(EsObjectRO variables)

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

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

sendPluginMessageToUser

PluginPrivateMessageResponse sendPluginMessageToUser(String userName,
                                                     EsObjectRO variables)

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

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

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

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

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

sendPluginMessageToUsers

PluginPrivateMessageResponse sendPluginMessageToUsers(String[] userNames,
                                                      EsObjectRO variables)

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

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

sendPluginMessageToZone

PluginPublicMessageResponse sendPluginMessageToZone(int zoneId,
                                                    EsObjectRO variables)

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

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

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

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

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

sendPluginMessageToZones

PluginPublicMessageResponse sendPluginMessageToZones(int[] zoneIds,
                                                     EsObjectRO variables)

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

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

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.electrotank.electroserver4.extensions.api Interface ElectroServerApi

addBuddy

removeBuddy

acquireManagedObject

releaseManagedObject

getLogger

applyLanguageFilterToString

blockAndCallUrl

callUrl

callUrlFromScript

scheduleExecution

scheduleExecutionFromScript

cancelScheduledExecution

addUsersToRoom

addUsersToRoom

createRoom

createRoom

createRoomInNamedZone

createRoomInNamedZone

destroyRoom

createRoomVariable

createRoomVariableForUser

updateRoomVariable

deleteRoomVariable

getExtensionBoundUserServerVariable

setExtensionBoundUserServerVariable

deleteExtensionBoundUserServerVariable

getUserServerVariable

setUserServerVariable

deleteUserServerVariable

createOrUpdateUserVariable

deleteUserVariable

getUserVariable

getUserVariables

getHandle

getName

getExtensionName

getFileSystemApi

getRoomVariable

getRoomVariables

getZones

getRoomsInZone

getRoomsInZoneByName

getRoomPlugin

getServerPlugin

callRoomPlugin

callServerPlugin

getUser

isUserLoggedIn

getUsersInRoom

kickUserFromRoom

banUserFromRoom

kickUserFromServer

registerGameConfiguration

createGameForUsers

createGameForUsers

sendPluginMessageToRoom

sendPluginMessageToRooms

sendPluginMessageToServer

sendPluginMessageToUser

sendPluginMessageToUsers

sendPluginMessageToUsers

sendPluginMessageToZone

sendPluginMessageToZones

sendPluginMessageToZones

com.electrotank.electroserver4.extensions.api
Interface ElectroServerApi