Packagenet.user1.reactor
Classpublic class Room
InheritanceRoom Inheritance flash.events.EventDispatcher

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

RoomManager
RoomClassRegistry.setRoomClass()


Public Methods
 MethodDefined 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
  
getClient(id:String):IClient
Returns the occupant or observer with the specified id.
Room
  
Returns the class used as the default class for clients in this room.
Room
  
Returns the number of clients known to be observing this room at the time of the call.
Room
  
Returns the number of clients known to be in this room at the time of the call.
Room
  
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
  
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
  
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
  
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
  
Sends a "stop observing room" request to the server.
Room
  
toString():String
[override] Provides a string representation of this object.
Room
Events
 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
Constructor Description
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.

Parameters
id:String
 
roomManager:RoomManager
 
messageManager:MessageManager
 
clientManager:ClientManager
 
accountManager:AccountManager
 
log:Logger
Method Descriptions
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


Example
The following code registers a listener to receive custom messages of type "CHAT" sent to theRoom:
theRoom.addMessageListener("CHAT", chatMessageListener);
Here is the corresponding registered listener. Notice that the listener's first parameter's datatype is IClient, as required by Reactor's messaging API. The fromClient parameter receives a reference to an IClient object representing the client that sent the message.
     protected function chatMessageListener (fromClient:IClient,
                                             messageText:String):void {
       // Code to display the message on screen goes here
     }
     
A "CHAT" message is sent to the room as follows:
theRoom.sendMessage("CHAT", true, null, messageText);
Note that in a real-world application, the custom message name "CHAT" would typically be assigned to a constant such as Messages.CHAT.
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()).

Returns
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()).

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

Returns
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]);
     }

Returns
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

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

Returns
Class

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.

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

Returns
int
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).

Returns
Array

See also

getObservers()
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).

Returns
Array

See also

getObserverIDs()
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).

Returns
Array

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

Returns
Array

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

Returns
String

See also

getRoomID()method 
public function getRoomID():String

Since : Reactor 1.0.0

Returns this room's fully qualified ID. For example, "examples.chat".

Returns
String
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().

Returns
RoomSettings

See also

setRoomSettings()
RoomMangaer.createRoom()
RoomSettings
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".

Returns
String

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.

Returns
String

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.

Returns
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


Example
The following code shows how to create a room named "lobby" and then join it.
     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


Example
The following code sends a custom message called "CHAT" to all clients in and observing theRoom, including the sender.
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)


Example
    // 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


Example
The following code changes a room's password to "newpass" and sets its maximum occupant limit to 200.
     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.

Returns
String
Event Detail
ADD_OBSERVER Event
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: AttributeEvent
AttributeEvent.type variable = net.user1.reactor.AttributeEvent.DELETE

Dispatched when an attribute is deleted.

See also

DELETE_CLIENT_ATTRIBUTE Event  
Event Object Type: RoomEvent
RoomEvent.type variable = 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:

Then, pass the UpdateLevels object to one of the following methods:

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  
Event Object Type: AttributeEvent
AttributeEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: AttributeEvent
AttributeEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: RoomEvent
RoomEvent.type variable = 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  
Event Object Type: AttributeEvent
AttributeEvent.type variable = net.user1.reactor.AttributeEvent.UPDATE

Dispatched when an attribute changes or is set for the first time.

See also

UPDATE_CLIENT_ATTRIBUTE Event  
Event Object Type: RoomEvent
RoomEvent.type variable = 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:

Then, pass the UpdateLevels object to one of the following methods:

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