Registers a listener to be notified when messages of the specified type are sent to the room. Room messages can be sent via Room.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.addMessageListener method, which offers more listening options, but also has a more complex API.
A message name, such as "CHAT" or "PROJECTILE_FIRED". When a message by this name is received, the specified listener will be executed.
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()).
Returns true if the specified client is in this room, false otherwise.
The clientID to check. Use undefined for the current client
Returns true if the specified client is observing this room, false otherwise.
The clientID to check.
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.
The name of the attribute to delete. Must not contain &, ", ', <, >, or Tokens.RS.
Permanently disables this object. The object cannot be reused. The dispose() method's purpose is to put this object into a state in which it can be garbage collected (for example, before a .swf file is unloaded).
The Room class's dispose() method is invoked automatically when the Orbiter.dispose method is invoked.
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.
The name of the attribute whose value should be retrieved. Must not contain &, ", ', <, >, or Tokens.RS.
The string value of the attribute, or null if the attribute does not exist or has been deleted.
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.
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.setClientClass method, Room.setDefaultClientClass method, and ClientManager.setDefaultClientClass.
Returns the class used as the default class for clients in this room.
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 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 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 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 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 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 the qualifier part of this room's ID. For example, if the room's fully qualified is "examples.chat", this method returns "examples".
Returns this room's fully qualified ID. For example, "examples.chat".
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 this room's simple ID. For example, if the room's fully qualified is "examples.chat", this method returns "chat".
Returns a string indicating the current synchronization state of this room. For details, see the SynchronizationState class.
Returns a Boolean indicating whether the specified listener function is currently registered to receive message notifications via this room for the specified message.
The string ID of a Union message.
A function or method.
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.setUpdateLevels method). Updates from the server trigger individual room events, such as RoomEvent.ADD_OCCUPANT and AttributeEvent.UPDATE.
The optional string password used to enter the room.
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.
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.
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.observeRoom method.
The room's password.
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.
Asks the server to remove this room. This method delegates its work to RoomManager.removeRoom. See that method for complete details.
Unregisters a message listener previously registered via addMessageListener().
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.
The name of the message to send.
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).
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.
Sends the specified message to this room's server-side modules.
The name of the message to send.
The message arguments, specified as dynamic instance variables on a generic object.
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.
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 http://www.unionplatform.com/?page_id=837.
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.
The name of the attribute. Must not contain &, ", ', <, >, or Tokens.RS.
The value of the attribute. Must be a string. Must not contain Tokens.RS.
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.
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.
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.
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. Orbiter 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.setClientClass method. Or, the custom class can be specified on a per-room basis via the Room.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.setDefaultClientClass.
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.
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.
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.
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.
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, an Orbiter client could send a message named "CHAT" to all occupants of a given room
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.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.
Clients that do not wish to be notified when other clients join or leave the room can opt-out of notifications using the Room.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.observeRoom method or Room.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 Orbiter 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.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.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.setUpdateLevels method.
To create a new server-side room, use the RoomManager.createRoom method. To remove a server-side room use the RoomManager.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 Orbiter, 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.setRoomClass method.