Package | net.user1.reactor |
Class | public class Room |
Inheritance | Room ![]() |
Since : | Reactor 1.0.0 |
The Room class represents a Union room, which is a place for clients to engage in group communication. When a client sends a message to a room, all other clients that are conceptually "in" the room (known as the room's "occupants") receive the message. For example, a Reactor client could send a message named "CHAT" to all occupants of a given room using the following code:
theRoom.sendMessage("CHAT", true, "Union is fun!");
In the preceding code, theRoom is a reference to a Room object, "CHAT" is
the message name, true
means "echo the message to the sender if
the sender is in the room," and "Union is fun!" is the message's first and
only argument.
Clients join rooms via the Room class's join() method or the RoomManager class's joinRoom() method, as in:
// Join the room whose roomID is "examples.chat" reactor.getRoomManager().joinRoom("examples.chat"); // Join the room object referenced by theRoom theRoom.join();
Clients can join more than one room at a time. For example, a single client can play a game in one room while chatting in another and reviewing employee salaries at a managers' meeting in yet another.
Clients leave rooms via Room's leave() method. (The RoomManager class does not define a separate leaveRoom() method because client applications can always retrieve a reference to a previously joined room, and, hence, can always use Room's leave() method.) When the current client joins a room, the room dispatches a RoomEvent.JOIN event. When the current client leaves a room, the room dispatches a RoomEvent.LEAVE event.
By default, when the current client is in a room, and other clients join or leave that room, the room dispatches the RoomEvent.ADD_OCCUPANT and RoomEvent.REMOVE_OCCUPANT events. For example, the following code displays a debugging message every time a client joins a room:
theRoom.addEventListener(RoomEvent.ADD_OCCUPANT, addOccupantListener); public function addOccupantListener (e:RoomEvent):void { trace("A client joined the room. The client's clientID is: " + e.getClient().getClientID()); }
Clients that do not wish to be notified when other clients join or leave the room can opt-out of notifications using the Room class's setUpdateLevels() method.
By default, a client does not receive messages sent to rooms it is not in. However, clients can spectate the activity of a room by asking to "observe" it via either RoomManager's observeRoom() method or Room's observe() method. A client observing a room is given all the same updates as the room's occupants, but does not appear in the room's occupant list. Observation is often used to create applications with spectation, such as people watching a game of chess or fans spectating a celebrity chat.
Each specific Room instance in Reactor is a reflection of an actual server-side Java Room object in Union Server. When a client joins or observes a room, Union server automatically sends that client a summary of the room's state, and subsequently pushes updates to the client when the room's state changes. The amount of information pushed to each client by Union Server is determined by the client's "room update levels" settings, which can be set via the Room class's join(), observe(), and setUpdateLevels() methods.
A room can store information using room attributes, which are shareable, multiuser variables that are accessible to all occupants and observers of the room. To create a room attribute or assign a room attribute a new value, use the Room class's setAttribute() method. In the default case, when a shared room attribute's value changes, all clients are notified via the AttributeEvent.UPDATE event. However, clients that do not wish to be notified when a room attribute changes can opt-out of notifications using the Room class's setUpdateLevels() method.
To create a new server-side room with ActionScript, use the RoomManager class's createRoom() method. To remove a server-side room with ActionScript, use the RoomManager class's removeRoom() method. When a room is removed from the server, all clients are forced to leave the room. As a result, the RoomEvent.LEAVE event occurs.
In Reactor, rooms are represented by Room objects by default, but applications
can specify custom Room subclasses for individual rooms, and implement application
logic in those classes. For example, a Room subclass might represent a chat
room that handles chat messages. Or a Room subclass might be a game room that
implements custom gameplay. To assign the class for a specific room, use the
RoomClassRegistry's setRoomClass() method. For example, the following code
assigns the class ChessRoom
as the class for the room with the
roomID "games.chess":
var registry:RoomClassRegistry = reactor.getRoomManager().getRoomClassRegistry(); registry.setRoomClass("games.chess", ChessRoom);
See also
Method | Defined By | ||
---|---|---|---|
Room(id:String, roomManager:RoomManager, messageManager:MessageManager, clientManager:ClientManager, accountManager:AccountManager, log:Logger)
Initializes new Room instances. | Room | ||
addMessageListener(message:String, listener:Function):void
Registers a listener to be notified when messages of the specified type
are sent to the room. | Room | ||
clientIsInRoom(clientID:String = null):Boolean
Returns true if the specified client is in this room, false otherwise. | Room | ||
clientIsObservingRoom(clientID:String = null):Boolean
Returns true if the specified client is observing this room, false otherwise. | Room | ||
deleteAttribute(attrName:String):void
Deletes the specified room attribute from the server. | Room | ||
getAttribute(attrName:String):String
Returns the current local value of the specified room attribute. | Room | ||
getAttributes():Object
Returns an object whose properties represent the names and values of the
shared attributes for this room. | Room | ||
Returns the occupant or observer with the specified id. | Room | ||
getDefaultClientClass():Class
Returns the class used as the default class for clients in this room. | Room | ||
getNumObservers():int
Returns the number of clients known to be observing this room at the time
of the call. | Room | ||
getNumOccupants():int
Returns the number of clients known to be in this room at the time
of the call. | Room | ||
getObserverIDs():Array
Returns the IDs of all clients currently observing the room, as an array. | Room | ||
getObservers():Array
Returns an array of objects representing all clients currently
observing the room. | Room | ||
getOccupantIDs():Array
Returns the IDs of all clients currently in the room, as an array. | Room | ||
getOccupants():Array
Returns an array of objects representing all clients currently
in the room. | Room | ||
getQualifier():String
Returns the qualifier part of this room's ID. | Room | ||
getRoomID():String
Returns this room's fully qualified ID. | Room | ||
Returns a RoomSettings object describing the settings for this room,
including the maximum number of occupants and whether the room is
automatically removed when the last occupant leaves. | Room | ||
getSimpleRoomID():String
Returns this room's simple ID. | Room | ||
getSyncState():String
Returns a string indicating the current synchronization state
of this room. | Room | ||
hasMessageListener(message:String, listener:Function):Boolean
Returns a Boolean indicating whether the specified listener function
is currently registered to receive message notifications via this room
for the specified message. | Room | ||
join(password:String = null, updateLevels:UpdateLevels = null):void
Asks the server to place the current client in the server-side room
represented by this Room object. | Room | ||
leave():void
Asks the server to remove the current client from the server-side room
represented by this Room object. | Room | ||
observe(password:String = null, updateLevels:UpdateLevels = null):void
Sends an "observe room" request to the server; if successful, the
current client begins spectating the room's activity, and will
receiving updates about the room and its occupants. | Room | ||
remove(password:String = null):void
Asks the server to remove this room. | Room | ||
removeMessageListener(message:String, listener:Function):void
Unregisters a message listener previously registered via addMessageListener(). | Room | ||
sendMessage(messageName:String, includeSelf:Boolean = false, filters:IFilter = null, ... rest):void
Sends a message to clients in and observing this room. | Room | ||
sendModuleMessage(messageName:String, messageArguments:Object = null):void
Sends the specified message to this room's server-side modules. | Room | ||
setAttribute(attrName:String, attrValue:String, isShared:Boolean = true, isPersistent:Boolean = false, evaluate:Boolean = false):void
Asks the server to set an attribute for this room. | Room | ||
setDefaultClientClass(defaultClass:Class):void
Assigns a class to use as the default class for clients in this room. | Room | ||
setRoomSettings(settings:RoomSettings):void
Assigns new settings for the room. | Room | ||
setUpdateLevels(updateLevels:UpdateLevels):void
Specifies the amount of information the current client will receive from
the server about this room while in or observing this room. | Room | ||
stopObserving():void
Sends a "stop observing room" request to the server. | Room | ||
toString():String [override]
Provides a string representation of this object. | Room |
Event | Summary | Defined By | ||
---|---|---|---|---|
Dispatched when a client observes a room and the following two conditions are met: 1) the current client is in or observing the room, 2) the current client has enabled "observer-list" updates for the room (observer-list updates are disabled by default). | Room | |||
Dispatched when a client joins a room and the following two conditions are met: 1) the current client is in or observing the room, 2) the current client has enabled "occupant-list" updates for the room (occupant-list updates are enabled by default). | Room | |||
Dispatched when an attribute is deleted. | Room | |||
Dispatched when the current client is in or observing the room, and an attribute in which the current client has expressed interest is removed from any of the room's occupants or observers. | Room | |||
Dispatched when the result of an attempt to delete an attribute is received. | Room | |||
Dispatched when the current client successfully joins a room, either in response to server-side code or in response to an earlier request made by the current client to join the room. | Room | |||
Dispatched when the result of an earlier room-join request by the current client is received. | Room | |||
Dispatched when the current client successfully leaves a room, either in response to server-side code or in response to an earlier request made by the current client to leave the room. | Room | |||
Dispatched when the result of an earlier room-leave request by the current client is received. | Room | |||
Dispatched when the current client successfully observes a room, either in response to server-side code or in response to an earlier request made by the current client to observe the room. | Room | |||
Dispatched when the result of an earlier observe-room request by the current client is received. | Room | |||
Dispatched when the number of occupants in a room changes while the current client is in or observing the room and the current client has enabled either "occupant-list" updates or "occupant-count" updates for the room (note that occupant-list updates are enabled by default). | Room | |||
Dispatched when the number of observers in a room changes while the current client is in or observing the room and the current client has enabled either "observer-list" updates or "observer-count" updates for the room (note that neither are enabled by default). | Room | |||
Dispatched when a client stops observing a room and the following two conditions are met: 1) the current client is in or observing the room, 2) the current client has enabled "observer-list" updates for the room (observer-list updates are disabled by default). | Room | |||
Dispatched when a client leaves a room and the following two conditions are met: 1) the current client is in or observing the room, 2) the current client has enabled "occupant-list" updates for the room (occupant-list updates are enabled by default). | Room | |||
Dispatched when a room that was previously known to the current client becomes unknown. | Room | |||
Dispatched when the result of an attempt to set an attribute is received. | Room | |||
Dispatched when the current client succesfully stops observing a room, either in response to server-side code or in response to an earlier request made by the current client to stop observing the room. | Room | |||
Dispatched when the result of an earlier stop-observing-room request by the current client is received. | Room | |||
Dispatched when the room has been synchronized to match the state of the server. | Room | |||
Dispatched when an attribute changes or is set for the first time. | Room | |||
Dispatched when the current client is in or observing the room, and an attribute in which the current client has expressed interest changes on any of the room's occupants or observers. | Room |
Room | () | Constructor |
public function Room(id:String, roomManager:RoomManager, messageManager:MessageManager, clientManager:ClientManager, accountManager:AccountManager, log:Logger)
Since : | Reactor 1.0.0 |
Initializes new Room instances.
Parametersid:String | |
roomManager:RoomManager | |
messageManager:MessageManager | |
clientManager:ClientManager | |
accountManager:AccountManager | |
log:Logger |
addMessageListener | () | method |
public function addMessageListener(message:String, listener:Function):void
Since : | Reactor 1.0.0 |
Registers a listener to be notified when messages of the specified type are sent to the room. Room messages can be sent via Room's sendMessage() method or RoomManager's sendMessage() method, or by a server-side module. Note, however, that message listeners for a given room will not be triggered on clients that have chosen to ignore messages for that room. See setUpdateLevels().
For a lower-level alternative to Room's addMessageListener() method, see MessageManager's addMessageListener() method, which offers more listening options, but also has a more complex API.
Parameters
message:String — A message name, such as "CHAT" or "PROJECTILE_FIRED". When
a message by this name is received, the specified listener
will be executed.
| |
listener:Function — The function to be executed when the specified message is
received. The listener's first parameter's datatype must be
IClient. Subsequent parameters receive the message's
arguments (sent via sendMessage()).
|
See also
theRoom.addMessageListener("CHAT", chatMessageListener);
protected function chatMessageListener (fromClient:IClient, messageText:String):void { // Code to display the message on screen goes here }
theRoom.sendMessage("CHAT", true, null, messageText);
clientIsInRoom | () | method |
public function clientIsInRoom(clientID:String = null):Boolean
Since : | Reactor 1.0.0 |
Returns true if the specified client is in this room, false otherwise.
Parameters
clientID:String (default = null ) — The clientID to check. Use null for the current client
(null is a convenience alternative to
reactor.self().getClientID()).
|
Boolean |
clientIsObservingRoom | () | method |
public function clientIsObservingRoom(clientID:String = null):Boolean
Since : | Reactor 1.0.0 |
Returns true if the specified client is observing this room, false otherwise.
Parameters
clientID:String (default = null ) — The clientID to check. Use null for the current client
(null is a convenience alternative to
reactor.self().getClientID()).
|
Boolean |
See also
deleteAttribute | () | method |
public function deleteAttribute(attrName:String):void
Since : | Reactor 1.0.0 |
Deletes the specified room attribute from the server. When a room attribute is deleted, the AttributeEvent.DELETE event is triggered on all clients in or observing the room with sufficiently verbose update levels (see UpdateLevels' sharedRoomAttributes and allRoomAttributes variables). If the room attribute could not be found on the server, no update is sent to any client. An attempt to delete a non-existent attribute triggers an AttributeEvent.DELETE_RESULT on the client that attempted to delete the attribute.
Parameters
attrName:String — The name of the attribute to delete. Must not contain
&, ", ', <, >, or Tokens.RS.
|
See also
getAttribute | () | method |
public function getAttribute(attrName:String):String
Since : | Reactor 1.0.0 |
Returns the current local value of the specified room attribute. The local
value is the most recent value that exists on the client, but depending
on network timing, a different value may actually exist on the server.
The getAttribute() method returns null
for any attribute
that does not exist on the client and for any attribute that existed once
but has since been deleted.
Parameters
attrName:String — The name of the attribute whose value should be retrieved.
Must not contain &, ", ', <, >, or Tokens.RS.
|
String — The string value of the attribute, or null if the
attribute does not exist or has been deleted.
|
See also
getAttributes | () | method |
public function getAttributes():Object
Since : | Reactor 1.0.0 |
Returns an object whose properties represent the names and values of the shared attributes for this room. The object is a copy of the current attributes; changes that occur after the call to getAttributes() are not reflected by the object. To read the properties of the object returned by getAttributes(), use a for-in loop. For example, the following code prints the attributes for a room to the debugging console:
var roomAttrs:Object = room.getAttributes(); for (var attrName:String in roomAttrs) { trace("Attribute: " + attrName + " has the value: " + roomAttrs[attrName]); }
Object |
See also
getClient | () | method |
public function getClient(id:String):IClient
Returns the occupant or observer with the specified id. The returned client will be an instance of either the built-in Client class, or a custom client class. For information on custom client classes, see the Client class's setClientClass() method, Room's setDefaultClientClass() method, and ClientManager's setDefaultClientClass().
Parameters
id:String |
IClient |
See also
getDefaultClientClass | () | method |
public function getDefaultClientClass():Class
Since : | Reactor 1.0.0 |
Returns the class used as the default class for clients in this room.
ReturnsClass |
See also
getNumObservers | () | method |
public function getNumObservers():int
Since : | Reactor 1.0.0 |
Returns the number of clients known to be observing this room at the time of the call. If the current client's update levels for this room do not include either "observer list" or "observer count", then the observer count is unknown, and getNumObservers() returns 0.
Returnsint |
getNumOccupants | () | method |
public function getNumOccupants():int
Since : | Reactor 1.0.0 |
Returns the number of clients known to be in this room at the time of the call. If the current client's update levels for this room do not include either "occupant list" or "occupant count", then the occupant count is unknown, and getNumOccupants() returns 0.
Returnsint |
getObserverIDs | () | method |
public function getObserverIDs():Array
Since : | Reactor 1.0.0 |
Returns the IDs of all clients currently observing the room, as an array. The array is a one-time copy of the list of clients observing the room, and is not synchronized with the actual observer list (which may change as clients continue to observe and stop observing the room).
ReturnsArray |
See also
getObservers | () | method |
public function getObservers():Array
Since : | Reactor 1.0.0 |
Returns an array of objects representing all clients currently observing the room. The array is a one-time snapshot of clients observing the room, and is not synchronized with the actual observer list (which may change as clients continue to observe and stop observing the room).
ReturnsArray |
See also
getOccupantIDs | () | method |
public function getOccupantIDs():Array
Since : | Reactor 1.0.0 |
Returns the IDs of all clients currently in the room, as an array. The array is a one-time copy of the list of clients in the room, and is not synchronized with the actual occupant list (which may change as clients continue to join and leave the room).
ReturnsArray |
See also
getOccupants | () | method |
public function getOccupants():Array
Since : | Reactor 1.0.0 |
Returns an array of objects representing all clients currently in the room. The array is a one-time snapshot of clients in the room, and is not synchronized with the actual occupant list (which may change as clients continue to join and leave the room).
ReturnsArray |
See also
getQualifier | () | method |
public function getQualifier():String
Since : | Reactor 1.0.0 |
Returns the qualifier part of this room's ID. For example, if the room's fully qualified is "examples.chat", this method returns "examples".
ReturnsString |
See also
getRoomID | () | method |
public function getRoomID():String
Since : | Reactor 1.0.0 |
Returns this room's fully qualified ID. For example, "examples.chat".
ReturnsString |
getRoomSettings | () | method |
public function getRoomSettings():RoomSettings
Since : | Reactor 1.0.0 |
Returns a RoomSettings object describing the settings for this room, including the maximum number of occupants and whether the room is automatically removed when the last occupant leaves. The returned object is a one-time snapshot, and is not updated after the call to getRoomSettings().
ReturnsRoomSettings |
See also
getSimpleRoomID | () | method |
public function getSimpleRoomID():String
Since : | Reactor 1.0.0 |
Returns this room's simple ID. For example, if the room's fully qualified is "examples.chat", this method returns "chat".
ReturnsString |
See also
getSyncState | () | method |
public function getSyncState():String
Since : | Reactor 1.0.0 |
Returns a string indicating the current synchronization state of this room. For details, see the SynchronizationState class.
ReturnsString |
See also
hasMessageListener | () | method |
public function hasMessageListener(message:String, listener:Function):Boolean
Since : | Reactor 1.0.0 |
Returns a Boolean indicating whether the specified listener function is currently registered to receive message notifications via this room for the specified message.
Parameters
message:String — The string ID of a Union message.
| |
listener:Function — A function or method.
|
Boolean |
See also
join | () | method |
public function join(password:String = null, updateLevels:UpdateLevels = null):void
Since : | Reactor 1.0.0 |
Asks the server to place the current client in the server-side room represented by this Room object. When result of the attempt is received, the room triggers a RoomEvent.JOIN_RESULT event. If the attempt succeeds, the room triggers a RoomEvent.JOIN event. Once the client joins the room it is kept synchronized with the server-side state of the room in accordance with the current client's update levels for the room (see the Room class's setUpdateLevels() method). Updates from the server trigger individual room events, such as RoomEvent.ADD_OCCUPANT and AttributeEvent.UPDATE.
Parameters
password:String (default = null ) — The optional string password used to enter the room.
| |
updateLevels:UpdateLevels (default = null ) — Specifies the client's update levels for the room,
which dictate the amount of information the client receives
about the room while it is in or observing the room. See the
UpdateLevels class for details.
|
See also
var room:Room = reactor.getRoomManager().createRoom("lobby"); room.join();
leave | () | method |
public function leave():void
Since : | Reactor 1.0.0 |
Asks the server to remove the current client from the server-side room represented by this Room object. When the result of the attempt is received, the room triggers a RoomEvent.LEAVE_RESULT event. If the request succeeds, the room triggers a RoomEvent.LEAVE event.
See also
observe | () | method |
public function observe(password:String = null, updateLevels:UpdateLevels = null):void
Since : | Reactor 1.0.0 |
Sends an "observe room" request to the server; if successful, the current client begins spectating the room's activity, and will receiving updates about the room and its occupants. The observe() method is a pass-through to RoomManager's observeRoom() method; see that method for more information.
Parameters
password:String (default = null ) — Specifies the client's update levels for the room,
which dictate the amount of information the client receives
about the room while it is in or observing the room. See the
UpdateLevels class for details.
| |
updateLevels:UpdateLevels (default = null )
|
See also
remove | () | method |
public function remove(password:String = null):void
Since : | Reactor 1.0.0 |
Asks the server to remove this room. This method delegates its work to RoomManager.removeRoom(). See that method for complete details.
Parameters
password:String (default = null )
|
See also
removeMessageListener | () | method |
public function removeMessageListener(message:String, listener:Function):void
Since : | Reactor 1.0.0 |
Unregisters a message listener previously registered via addMessageListener().
Parameters
message:String | |
listener:Function |
See also
sendMessage | () | method |
public function sendMessage(messageName:String, includeSelf:Boolean = false, filters:IFilter = null, ... rest):void
Since : | Reactor 1.0.0 |
Sends a message to clients in and observing this room. To send a message to clients in multiple rooms, use the RoomManager class's sendMessage() method. To send the message to all clients on the server, use the Server class's sendMessage() method.
To receive the message, recipient clients normally register a
message listener via the Room class's addMessageListener() method.
However, the message can also be received by listeners registered via
MessageManager's addMessageListener() method. Message listeners
registered via someRoom.addMessageListener()
are
triggered when the specified message is sent to
someRoom
only, which is normally the desired
behaviour. Message listeners registered via MessageManager's
addMessageListener() method are triggered when the specified message is
sent to any room. For a complete description of the difference
between MessageManager's addMessageListener() method Room's
addMessageListener(), see the entry for MessageManager's
addMessageListener() method.
Clients that prefer not to receive messages for a room can opt-out of messages via the Room class's setUpdateLevels() method.
Parameters
messageName:String — The name of the message to send.
| |
includeSelf:Boolean (default = false ) — Indicates whether to send the message to the current
client (i.e., the client that invoked sendMessage()).
Defaults to false (don't echo to the sender).
| |
filters:IFilter (default = null ) — Specifies one or more filters for the message. A
filter specifies a requirement that each client must
meet in order to receive the message. For example, a
filter might indicate that only those clients with
the attribute "team" set to "red" should receive the
message. For complete details, see the Filter class.
If filters is null, all interested clients in the room
receive the message.
| |
... rest — An optional comma-separated list of string arguments for
the message. These will be passed to any listeners
registered to receive the message. See
Room's addMessageListener() method.
|
See also
theRoom.sendMessage("CHAT", true, null, messageText);
sendModuleMessage | () | method |
public function sendModuleMessage(messageName:String, messageArguments:Object = null):void
Since : | Reactor 1.0.0 |
Sends the specified message to this room's server-side modules. For information on room modules, see Union Server's modules documentation.
Parameters
messageName:String | |
messageArguments:Object (default = null )
|
// Send message "submitAnswer" with argument "answer" set to "green". var messageArguments:Object = new Object(); messageArguments.answer = "green"; theRoom.sendModuleMessage("submitAnswer", messageArguments); // Same thing, but using object-literal syntax. theRoom.sendModuleMessage("submitAnswer", {answer:"green"});
setAttribute | () | method |
public function setAttribute(attrName:String, attrValue:String, isShared:Boolean = true, isPersistent:Boolean = false, evaluate:Boolean = false):void
Since : | Reactor 1.0.0 |
Asks the server to set an attribute for this room. An attribute is a like a variable for the room with the added benefit that it can be automatically shared with all clients in the room. Room attributes are intended to store information about the room's environment, such as the highscore in a game room or the position of the furniture in a virtual house.
If setAttribute() is called with isShared
set to
true
, then by default the attribute value is
automatically propagated to all clients in the room. Clients can respond
to the changing of a shared room-attribute value via the
AttributeEvent.UPDATE event. Clients that do not wish to receive the
attribute update can use setUpdateLevels() to opt out of the notification.
When the current client sets a room attribute, it will not be able to access that attribute's new value until the AttributeEvent.UPDATE occurs. For example, the following erroneous code sets an attribute on a new room and then immediately attempts to access that attribute value. The server has not yet processed the attribute assignment, so locally the attribute value is null:
// INCORRECT! This code does not wait for an AttributeEvent.UPDATE event. room = reactor.getRoomManager().createRoom("meetingRoom"); room.setAttribute("age", "56"); trace(room.getAttribute()); // Outputs: null
By contrast, the following code accesses the value of "age" from within an AttributeEvent.UPDATE event listener, so the server has processed the attribute assignment, and the output is "56". Note also that in order to receive an AttributeEvent.UPDATE event for a room, the client must be in or observing the room.
// CORRECT. This code waits for the AttributeEvent.UPDATE event. room = reactor.getRoomManager().createRoom("meetingRoom"); room.join(); room.addEventListener(AttributeEvent.UPDATE, attributeUpdateListener); room.setAttribute("age", "56"); function attributeUpdateListener (e:AttributeEvent):void { if (e.getChangedAttr().name == "age") { trace(room.getAttribute("age")); } }
To delete a room attribute use deleteAttribute().
Room attributes can be saved to a database on the server via Union's built-in
attribute-persistence feature. To save a room attribute, set the
isPersistent
parameter of setAttribute() to true.
By default, Union Server includes support for persistent room attributes
via a light-weight built-in database called
Apache Derby. Because Derby is
built-in to Union Server, Union's persistent room-attribute feature
can be used without any special configuration or additional installation.
However, developers who prefer to use another database or arbitrary
data source can customize or fully replace Union's built-in database.
For information on customizing Union's persistence
data source, see Union Server Persistence.
Note that internally, a reserved character is used to separate attributes during transmission to and from the server. The reserved character is assigned to the Tokens.RS static variable, and defaults to the pipe character, "|". Application code must not use that character in the name or value of an attribute.
Parameters
attrName:String — The name of the attribute. Must not contain
&, ", ', <, >, or Tokens.RS.
| |
attrValue:String — The value of the attribute. Must be a string. Must not
contain Tokens.RS.
| |
isShared:Boolean (default = true ) — If true, all interested clients in the room on which this attribute is
set are notified when the attribute changes. If false, the attribute value is
stored on the server but clients in the room are not automatically notified of
its existence nor of its value. Clients wishing to retrieve a non-shared room
attribute must...##[explain what clients have to do here].
| |
isPersistent:Boolean (default = false ) — If true, causes the attribute to be stored in a server-side
database. Attributes stored in the database are known as "persistent attributes".
Persistent attributes are saved even after the server shuts down. When the
server restarts, if the room on which the persistent attribute was stored
is created again, the persistent attribute is automatically loaded. If
the persistent attribute is also shared, then clients that join the room are
automatically informed of the attribute name and value.
| |
evaluate:Boolean (default = false ) — If true, the server will evaluate the attrValue as a mathematical
expression before assigning the attribute its new value.
Within the expression, the token "%v" means "substitute
the attribute's current value". For example, the following
code adds one to an existing attribute "visits":
theRoom.setAttribute("visits", "%v+1", true, false, true); .
When evaluate is true, attrValue can contain the following
characters only: the numbers 0-9, ., /, +, -, %, v.
|
See also
setDefaultClientClass | () | method |
public function setDefaultClientClass(defaultClass:Class):void
Since : | Reactor 1.0.0 |
Assigns a class to use as the default class for clients in this room. By default, all clients are represented by instances of the Client class, which implements IClient. Reactor applications can, however, choose to represent clients with a custom class. The custom client class can be specified on a per-client basis via the Client class's setClientClass() method. Or, the custom class can be specified on a per-room basis via the Room class's setDefaultClientClass() method. When a class has been specified via setDefaultClientClass() for a room, it is used as the client class for any client retrieved via the room's getClient() method, unless the client specifies a custom class via the Client class's setClientClass() method, which overrides Room's setDefaultClientClass(). To set the custom class for a client globally, use the ClientManager class's setDefaultClientClass().
Parameters
defaultClass:Class — The default client class for this room. The class is
normally a descendant of CustomClient, but can be any class that
implements the IClient interface.
|
See also
setRoomSettings | () | method |
public function setRoomSettings(settings:RoomSettings):void
Since : | Reactor 1.0.0 |
Assigns new settings for the room. For a list of available room settings, see the RoomSettings class. To change a room setting, the current client must have sufficient privileges. By default, a room's creator is authorized to change room settings. To allow other types of clients (such as moderators) to change room settings, define a remote-client security rule as described in Union Server's security documentation.
Parameters
settings:RoomSettings — The room's new settings. Any RoomSettings variables that
are null are not changed.
|
See also
var settings:RoomSettings = new RoomSettings(); settings.password = "newpass"; settings.maxClients = 200; room.setRoomSettings(settings);
setUpdateLevels | () | method |
public function setUpdateLevels(updateLevels:UpdateLevels):void
Since : | Reactor 1.0.0 |
Specifies the amount of information the current client will receive from the server about this room while in or observing this room. For details, see the UpdateLevels class.
Parameters
updateLevels:UpdateLevels |
See also
stopObserving | () | method |
public function stopObserving():void
Since : | Reactor 1.0.0 |
Sends a "stop observing room" request to the server. If successful, the current client stops observing the room, and is no longer sent updates about the room's activity.
See also
toString | () | method |
override public function toString():String
Since : | Reactor 1.0.0 |
Provides a string representation of this object.
ReturnsString |
ADD_OBSERVER | Event |
RoomEvent
net.user1.reactor.RoomEvent.ADD_OBSERVER
Dispatched when a client observes a room and the following two conditions are met: 1) the current client is in or observing the room, 2) the current client has enabled "observer-list" updates for the room (observer-list updates are disabled by default). To enable or disable observer-list updates for a room, set the observerList variable on an UpdateLevels object, and pass that object to one of the following methods:
For example, the following code enables observer-list updates for the Room object referenced by theRoom:
var updateLevels:UpdateLevels = new UpdateLevels(); updateLevels.observerList = true; theRoom.setUpdateLevels(updateLevels);
See also
ADD_OCCUPANT | Event |
RoomEvent
net.user1.reactor.RoomEvent.ADD_OCCUPANT
Dispatched when a client joins a room and the following two conditions are met: 1) the current client is in or observing the room, 2) the current client has enabled "occupant-list" updates for the room (occupant-list updates are enabled by default). To enable or disable occupant-list updates for a room, set the occupantList variable on an UpdateLevels object, and pass that object to one of the following methods:
For example, the following code disables occupant-list updates for the Room object referenced by theRoom:
var updateLevels:UpdateLevels = new UpdateLevels(); updateLevels.occupantList = false; theRoom.setUpdateLevels(updateLevels);
See also
DELETE | Event |
AttributeEvent
net.user1.reactor.AttributeEvent.DELETE
Dispatched when an attribute is deleted.
See also
DELETE_CLIENT_ATTRIBUTE | Event |
RoomEvent
net.user1.reactor.RoomEvent.DELETE_CLIENT_ATTRIBUTE
Dispatched when the current client is in or observing the room, and an attribute in which the current client has expressed interest is removed from any of the room's occupants or observers. Specifically, RoomEvent.DELETE_CLIENT_ATTRIBUTE is triggered when any of the following occurs:
To enable or disable occupant or observer attribute updates for a room, first, set any of the following variables on an UpdateLevels object:
For example, the following code disables all shared attribute updates for occupants of the room referenced by theRoom:
var updateLevels:UpdateLevels = new UpdateLevels(); updateLevels.sharedOccupantAttributesRoom = false; updateLevels.sharedOccupantAttributesGlobal = false; theRoom.setUpdateLevels(updateLevels);
See also
DELETE_RESULT | Event |
AttributeEvent
net.user1.reactor.AttributeEvent.DELETE_RESULT
Dispatched when the result of an attempt to delete an attribute is received. To determine the result of the attempt, use getStatus(), which has the following possible return values:
See also
JOIN | Event |
RoomEvent
net.user1.reactor.RoomEvent.JOIN
Dispatched when the current client successfully joins a room, either in response to server-side code or in response to an earlier request made by the current client to join the room.
Note that the RoomEvent.JOIN event applies to the current client only. To be notified when any client joins a room, register for the RoomEvent.ADD_OCCUPANT event.
See also
JOIN_RESULT | Event |
RoomEvent
net.user1.reactor.RoomEvent.JOIN_RESULT
Dispatched when the result of an earlier room-join request by the current client is received. To determine the result of the request, use getStatus(), which has the following possible return values:
If the room-join request was successful, the RoomEvent.JOIN event will also be triggered.
See also
LEAVE | Event |
RoomEvent
net.user1.reactor.RoomEvent.LEAVE
Dispatched when the current client successfully leaves a room, either in response to server-side code or in response to an earlier request made by the current client to leave the room.
Note that the RoomEvent.LEAVE event applies to the current client only. To be notified when any client leaves a room, register for the RoomEvent.REMOVE_OCCUPANT event.
See also
LEAVE_RESULT | Event |
RoomEvent
net.user1.reactor.RoomEvent.LEAVE_RESULT
Dispatched when the result of an earlier room-leave request by the current client is received. To determine the result of the request, use getStatus(), which has the following possible return values:
If the leave-join request was successful, the RoomEvent.LEAVE event will also be triggered.
See also
OBSERVE | Event |
RoomEvent
net.user1.reactor.RoomEvent.OBSERVE
Dispatched when the current client successfully observes a room, either in response to server-side code or in response to an earlier request made by the current client to observe the room. Note that RoomEvent.OBSERVE applies to the current client only; to be notified when other clients observe the room, register for the RoomEvent.ADD_OBSERVER event.
See also
OBSERVE_RESULT | Event |
RoomEvent
net.user1.reactor.RoomEvent.OBSERVE_RESULT
Dispatched when the result of an earlier observe-room request by the current client is received. To determine the result of the request, use getStatus(), which has the following possible return values:
See also
OCCUPANT_COUNT | Event |
RoomEvent
net.user1.reactor.RoomEvent.OCCUPANT_COUNT
Dispatched when the number of occupants in a room changes while the current client is in or observing the room and the current client has enabled either "occupant-list" updates or "occupant-count" updates for the room (note that occupant-list updates are enabled by default). To enable or disable occupant-list updates or occupant-count updates for a room, set either the occupantList variable or the occupantCount variable (respectively) on an UpdateLevels object, and pass that object to one of the following methods:
For example, the following code disables occupant-list updates and enables occupant-count updates for the Room object referenced by theRoom:
var updateLevels:UpdateLevels = new UpdateLevels(); updateLevels.occupantList = false; updateLevels.occupantCount = true; theRoom.setUpdateLevels(updateLevels);
See also
OSERVER_COUNT | Event |
RoomEvent
net.user1.reactor.RoomEvent.OBSERVER_COUNT
Dispatched when the number of observers in a room changes while the current client is in or observing the room and the current client has enabled either "observer-list" updates or "observer-count" updates for the room (note that neither are enabled by default). To enable or disable observer-list updates or observer-count updates for a room, set either the observerList variable or the observerCount variable (respectively) on an UpdateLevels object, and pass that object to one of the following methods:
For example, the following code enables observer-count updates for the Room object referenced by theRoom:
var updateLevels:UpdateLevels = new UpdateLevels(); updateLevels.observerCount = true; theRoom.setUpdateLevels(updateLevels);
See also
REMOVE_OBSERVER | Event |
RoomEvent
net.user1.reactor.RoomEvent.REMOVE_OBSERVER
Dispatched when a client stops observing a room and the following two conditions are met: 1) the current client is in or observing the room, 2) the current client has enabled "observer-list" updates for the room (observer-list updates are disabled by default). To enable or disable observer-list updates for a room, set the observerList variable on an UpdateLevels object, and pass that object to one of the following methods:
For example, the following code enables observer-list updates for the Room object referenced by theRoom:
var updateLevels:UpdateLevels = new UpdateLevels(); updateLevels.observerList = true; theRoom.setUpdateLevels(updateLevels);
See also
REMOVE_OCCUPANT | Event |
RoomEvent
net.user1.reactor.RoomEvent.REMOVE_OCCUPANT
Dispatched when a client leaves a room and the following two conditions are met: 1) the current client is in or observing the room, 2) the current client has enabled "occupant-list" updates for the room (occupant-list updates are enabled by default). To enable or disable occupant-list updates for a room, set the occupantList variable on an UpdateLevels object, and pass that object to one of the following methods:
For example, the following code disables occupant-list updates for the Room object referenced by theRoom:
var updateLevels:UpdateLevels = new UpdateLevels(); updateLevels.occupantList = false; theRoom.setUpdateLevels(updateLevels);
See also
REMOVED | Event |
RoomEvent
net.user1.reactor.RoomEvent.REMOVED
Dispatched when a room that was previously known to the current client becomes unknown. A room is known when it is cached, joined, observed, or watched by the current client. For information on the current client's room cache, see RoomManager's disposeCachedRooms() method.
See also
SET_RESULT | Event |
AttributeEvent
net.user1.reactor.AttributeEvent.SET_RESULT
Dispatched when the result of an attempt to set an attribute is received. To determine the result of the attempt, use getStatus(), which has the following possible return values:
See also
STOP_OBSERVING | Event |
RoomEvent
net.user1.reactor.RoomEvent.STOP_OBSERVING
Dispatched when the current client succesfully stops observing a room, either in response to server-side code or in response to an earlier request made by the current client to stop observing the room.
See also
STOP_OBSERVING_RESULT | Event |
RoomEvent
net.user1.reactor.RoomEvent.STOP_OBSERVING_RESULT
Dispatched when the result of an earlier stop-observing-room request by the current client is received. To determine the result of the request, use getStatus(), which has the following possible return values:
See also
SYNCHRONIZE | Event |
RoomEvent
net.user1.reactor.RoomEvent.SYNCHRONIZE
Dispatched when the room has been synchronized to match the state of the server. A room is synchronized when the current client joins or observes it.
See also
UPDATE | Event |
AttributeEvent
net.user1.reactor.AttributeEvent.UPDATE
Dispatched when an attribute changes or is set for the first time.
See also
UPDATE_CLIENT_ATTRIBUTE | Event |
RoomEvent
net.user1.reactor.RoomEvent.UPDATE_CLIENT_ATTRIBUTE
Dispatched when the current client is in or observing the room, and an attribute in which the current client has expressed interest changes on any of the room's occupants or observers. Specifically, RoomEvent.UPDATE_CLIENT_ATTRIBUTE is triggered when any of the following occurs:
To enable or disable occupant or observer attribute updates for a room, first, set any of the following variables on an UpdateLevels object:
For example, the following code enables room-scoped shared-attribute updates for observers of the room referenced by theRoom:
var updateLevels:UpdateLevels = new UpdateLevels(); updateLevels.sharedObserverAttributesRoom = true; theRoom.setUpdateLevels(updateLevels);
See also