Packagenet.user1.reactor
Classpublic class Reactor
InheritanceReactor Inheritance flash.events.EventDispatcher

Since : Reactor 1.0.0

The Reactor class is the root class of every Reactor client application. It provides basic tools for connecting to Union server, and gives the application access to the core Reactor system modules, including: To connect a client application to Union server, use the Reactor class's connect() method, as in:
  var reactor:Reactor = new Reactor();
  reactor.connect("tryunion.com", 80)
  

After connect() has executed, Reactor waits for the server to accept the connection request. Once the server responds and the Reactor object completes all required connection setup tasks, the Reactor object triggers a ReactorEvent.READY event, indicating that client/server communications can begin. Client applications must wait for the Reactor.READY event before communicating with the server.

As a best practice, always register for the Reactor.READY before invoking connect(), as follows:

  var reactor:Reactor = new Reactor();
  // Register first...
  reactor.addEventListener(ReactorEvent.READY, 
                           readyListener);
  // ...then connect
  reactor.connect("tryunion.com", 80); 
  
Application startup code is typically placed in a Reactor.READY listener. For example,
  private function readyListener (e:ReactorEvent):void {
    // The connection is ready for use, so it's now safe to communicate with
    // the server. For example, this code makes a new chat room:
    chatRoom = reactor.getRoomManager().createRoom("examples.chat");
  
    // And this code joins the new room
    chatRoom.join();
  }
  

See also

ReactorEvent.READY


Public Methods
 MethodDefined By
  
Reactor(configURL:String, traceLogMessages:Boolean = true)
Constructor; initializes new Reactor instances.
Reactor
  
connect(host:String = null, ... ports):void
The connect() method attempts to connect to Union Server at the specified host and ports.
Reactor
  
Instructs Reactor to use persistent socket connections only when attempting to connect to specified hosts and ports.
Reactor
  
Disables statistics tracking for this Reactor object.
Reactor
  
disconnect():void
Terminates any open connection to the server.
Reactor
  
dispose():void
Permanently disables this object and releases all of its resources.
Reactor
  
Instructs Reactor to automatically try connecting via HTTP when it is unable to establish a persistent socket connection over all specified hosts and ports.
Reactor
  
Enables statistics tracking for this Reactor object.
Reactor
  
Returns a reference to the application's AccountManager instance, which is automatically created by Reactor; the AccountManager class provides a set of services relating to registering and logging-in user accounts.
Reactor
  
Returns a reference to the application's ClientManager instance, which is automatically created by Reactor; the ClientManager class creates and provides access to Client instances.
Reactor
  
Returns a reference to the application's ConnectionManager instance, which is automatically created by Reactor; the ConnectionManager class is used to establish a connection to the server.
Reactor
  
Returns a reference to the application's ConnectionMonitor instance, which manages heartbeat (ping) and automatic disconnection and reconnection services.
Reactor
  
Returns a reference to the application debugging log, which describes operations occurring on the client, and can show low-level client/server communications.
Reactor
  
Returns a reference to the application's MessageManager instance, which is automatically created by Reactor; the MessageManager class provides a set of services relating to sending messages to and receiving messages from the server.
Reactor
  
Returns a reference to the application's RoomManager, which is created automatically by Reactor; the RoomManager class is used to create, destroy, observe, join, and access rooms.
Reactor
  
Returns a reference to the application's Server instance, which is automatically created by Reactor; the Server class provides access to global server data and functions.
Reactor
  
getSessionID():String
The Union session ID for this Reactor instance, if available.
Reactor
  
Returns a reference to a Statistics object for this connection, which provides metrics such as KB/second transfer rate and number of messages sent and received.
Reactor
  
Returns a reference to the application's System class, whose static variables provide Reactor version information.
Reactor
  
Indicates whether Reactor will automatically try connecting via HTTP when it is unable to establish a persistent socket connection over all specified hosts and ports.
Reactor
  
isReady():Boolean
Returns a Boolean indicating whether Reactor currently has an active, fully initialized connection to the server.
Reactor
  
loadConfig(configURL:String):void
Loads the client-configuration file.
Reactor
  
secureConnect(host:String = null, ... ports):void
The secureConnect() method is identical to the connect() method, except that it uses an encrypted connection (TLS or SSL) rather than an unencrypted connection.
Reactor
  
Returns a reference to the application's own IClient object (i.e., the "current client").
Reactor
  
setServer(host:String, ... ports):void
Specifies the host and port for future connection attempts.
Reactor
  
updateSnapshot(snapshot:Snapshot):void
Updates the specified snapshot object with the latest information available on the server.
Reactor
Events
 Event Summary Defined By
   Dispatched when either the connection to the server is lost or a connection attempt fails.Reactor
   Dispatched when the client attempts to connect to Union Server, but the connection is refused.Reactor
   Dispatched when the client connects to a Union Server that conforms to a version of the UPC specification that does not match the client's UPC version.Reactor
   Dispatched when a connection to the server has been established and fully initialized.Reactor
Constructor Description
Reactor()Constructor
public function Reactor(configURL:String, traceLogMessages:Boolean = true)

Since : Reactor 1.0.0

Constructor; initializes new Reactor instances.

Parameters
configURL:String — The URL of a client-configuration file. When the file finishes loading, the client automatically attempts to connect to the server. Note that the configuration file need not be loaded at construction time, it can be loaded later via Reactor's loadConfig() method. For configuration file details, see loadConfig().
 
traceLogMessages:Boolean (default = true) — A flag indicating whether to enable logging to the output console.

See also

Method Descriptions
connect()method
public function connect(host:String = null, ... ports):void

Since : Reactor 1.0.0

The connect() method attempts to connect to Union Server at the specified host and ports. If no host and ports are specified, Reactor attempts to connect using the ConnectionManager's current list of hosts and ports.

When an external configuration file (e.g., config.xml) is used with the Reactor constructor, the Reactor object automatically connects to the server, so no call to connect() is required. When Reactor is constructed without a configuration file, connect() must be called manually after construction, as in:

   reactor = new Reactor();
   reactor.connect("tryunion.com", 80);
   

When a connection succeeds and the Reactor object has been fully initialized, a ReactorEvent.READY event is triggered. A ReactorEvent.READY listener typically starts the application in motion, often by creating or joining rooms. Lower-level connection events can be handled via the application's ConnectionManager.

The connect() method does not require any special policy file configuration for socket connections. By default, Union Server automatically provides Flash Player with the required policy file over the port specified in the connect() call. However, server administrators must be sure to correctly specify the desired allowed domains and ports in the server-side policy.xml file.

Reactor's connect() method is a convenience wrapper for the ConnectionManager class's addConnection() and connect() methods. Each time Reactor's connect() is called, all existing ConnectionManager connections are first closed and removed. Then, Reactor automatically creates a new XMLSocketConnection object for each host/port combination specified via the host and ports parameters of Reactor's connect() method. Next, Reactor adds each XMLSocketConnection object to the ConnectionManager's list of connections. If Reactor's automatic HTTP failover feature is enabled, backup HTTPConnections for the specified ports are also created. For example, consider the following connection code:

   reactor = new Reactor();
   reactor.connect("tryunion.com", 80, 443);
   

In the default case, where automatic HTTP failover is enabled, the preceding code is equivalent to the following code:

   var connectionManager:ConnectionManager = reactor.getConnectionManager();
   connectionManager.addConnection(new XMLSocketConnection("tryunion.com", 80));
   connectionManager.addConnection(new XMLSocketConnection("tryunion.com", 443));
   connectionManager.addConnection(new HTTPConnection("tryunion.com", 80));
   connectionManager.addConnection(new HTTPConnection("tryunion.com", 443));
   connectionManager.connect();
   

In the preceding code, note that the HTTPConnection objects are added after the XMLSocketConnection objects, which means that the ConnectionManager will exhaust all potential means of establishing a persistent socket connection before resorting to an HTTP connection. HTTP connections are less responsive than persistent socket connections, but have a higher chance of connecting from behind a firewall.

Parameters

host:String (default = null) — The string name or IP address of the domain on which Union Server is running. For example, "tryunion.com" or "192.233.42.1". To indicate the current domain (i.e., the domain from which the .swf file was downloaded), use the empty string (""). To indicate the machine on which the .swf file is actually running (requires that the server and the .swf file both reside on the same machine) use "localhost". Note, however, that for multi-IP machines where the server has been configured to run on a single IP only, attempts to connect to "localhost" will always fail. When the server is not configured to listen for connections on all local IP addresses, a specific name or IP must always be specified for host.
 
... ports — A list of integer ports over which Reactor should attempt to connect to Union Server. Reactor will attempt to connect over the ports in the order specified. For example, if ports is set to 9100, 80, 443, then Reactor will first attempt to connect to Union over port 9100; if the connection fails, Reactor will automatically next attempt to connect over port 80, if that fails, Reactor will attempt to connect to port 443. All ports must be greater than or equal to 1024 unless a policy file is configured to allow connections to ports under 1024. To add multiple hosts (not just multiple ports) to Reactor's list of failover connections, use ConnectionManager's addConnection() method. Wherever possible, to allow maximum connection success by Union clients, Union Server should be run on port 80.

See also

disableHTTPFailover()method 
public function disableHTTPFailover():void

Since : Reactor 1.0.0

Instructs Reactor to use persistent socket connections only when attempting to connect to specified hosts and ports. When HTTP failover is disabled, Reactor does not automatically attempt to establish backup HTTP connections if all persistent socket connection attempts fail.

See also

disableStatistics()method 
public function disableStatistics():void

Since : Reactor 1.0.0

Disables statistics tracking for this Reactor object.

See also

disconnect()method 
public function disconnect():void

Since : Reactor 1.0.0

Terminates any open connection to the server. If the disconnection attempt succeeds, ConnectionManager dispatches the ConnectionManagerEvent.CLIENT_KILL_CONNECT and ConnectionManagerEvent.DISCONNECT events, and the Reactor object dispatches a ReactorEvent.CLOSE event.

The Reactor class's disconnect() method is a convenience wrapper for the ConnectionManager class's disconnect() method.

See also

dispose()method 
public function dispose():void

Since : Reactor 1.0.0

Permanently disables this object and releases all of its resources. Once dispose() is called, the object can never be used again. Use dispose() only when purging an object from memory, as is required when unloading a .swf file. To simply disconnect a Reactor object, use disconnect().

See also

enableHTTPFailover()method 
public function enableHTTPFailover():void

Since : Reactor 1.0.0

Instructs Reactor to automatically try connecting via HTTP when it is unable to establish a persistent socket connection over all specified hosts and ports. HTTP failover is enabled by default. HTTP connections are less responsive than persistent socket connections, but have a higher chance of connecting from behind a firewall. For the most granular control over connection sequence, type, hosts, and ports, use the ConnectionManager class directly.

See also

enableStatistics()method 
public function enableStatistics():void

Since : Reactor 1.0.0

Enables statistics tracking for this Reactor object. To retrieve statistics, use the getStatistics() method.

See also

getAccountManager()method 
public function getAccountManager():AccountManager

Since : Reactor 1.0.0

Returns a reference to the application's AccountManager instance, which is automatically created by Reactor; the AccountManager class provides a set of services relating to registering and logging-in user accounts. For complete details see the main class entry for the AccountManager class.

Returns
AccountManager

See also

getClientManager()method 
public function getClientManager():ClientManager

Since : Reactor 1.0.0

Returns a reference to the application's ClientManager instance, which is automatically created by Reactor; the ClientManager class creates and provides access to Client instances. Client instances store information about clients on the server, including client attributes, IP address, ping time, and connection time. For complete details see the main class entry for the ClientManager class.

Returns
ClientManager

See also

getConnectionManager()method 
public function getConnectionManager():ConnectionManager

Since : Reactor 1.0.0

Returns a reference to the application's ConnectionManager instance, which is automatically created by Reactor; the ConnectionManager class is used to establish a connection to the server. For complete details see the main class entry for the ConnectionManager class.

Returns
ConnectionManager

See also

getConnectionMonitor()method 
public function getConnectionMonitor():ConnectionMonitor

Since : Reactor 1.0.0

Returns a reference to the application's ConnectionMonitor instance, which manages heartbeat (ping) and automatic disconnection and reconnection services.

Returns
ConnectionMonitor

See also

getLog()method 
public function getLog():Logger

Since : Reactor 1.0.0

Returns a reference to the application debugging log, which describes operations occurring on the client, and can show low-level client/server communications.

Returns
Logger

See also

net.reactor.logger.Logger
getMessageManager()method 
public function getMessageManager():MessageManager

Since : Reactor 1.0.0

Returns a reference to the application's MessageManager instance, which is automatically created by Reactor; the MessageManager class provides a set of services relating to sending messages to and receiving messages from the server. For complete details see the main class entry for the MessageManager class.

Returns
MessageManager

See also

getRoomManager()method 
public function getRoomManager():RoomManager

Since : Reactor 1.0.0

Returns a reference to the application's RoomManager, which is created automatically by Reactor; the RoomManager class is used to create, destroy, observe, join, and access rooms.

Returns
RoomManager

See also

getServer()method 
public function getServer():Server

Since : Reactor 1.0.0

Returns a reference to the application's Server instance, which is automatically created by Reactor; the Server class provides access to global server data and functions. For complete details see the main class entry for the Server class.

Returns
Server

See also

getSessionID()method 
public function getSessionID():String

Since : Reactor 1.0.0

The Union session ID for this Reactor instance, if available.

Returns
String
getStatistics()method 
public function getStatistics():Statistics

Since : Reactor 1.0.0

Returns a reference to a Statistics object for this connection, which provides metrics such as KB/second transfer rate and number of messages sent and received. Due to the performance cost associated with statistics tracking, the returned Statistics object returned by getStatistics() is disabled by default, and provides no data. To enable statistics tracking, invoke the Reactor class's enableStatistics() method.

Returns
Statistics

See also

getSystem()method 
public function getSystem():System

Since : Reactor 1.0.0

Returns a reference to the application's System class, whose static variables provide Reactor version information.

Returns
System

See also

isHTTPFailoverEnabled()method 
public function isHTTPFailoverEnabled():Boolean

Since : Reactor 1.0.0

Indicates whether Reactor will automatically try connecting via HTTP when it is unable to establish a persistent socket connection over all specified hosts and ports.

Returns
Boolean

See also

isReady()method 
public function isReady():Boolean

Since : Reactor 1.0.0

Returns a Boolean indicating whether Reactor currently has an active, fully initialized connection to the server.

Returns
Boolean — true if the client is in a ready state; false otherwise.

See also

loadConfig()method 
public function loadConfig(configURL:String):void

Since : Reactor 1.0.0

Loads the client-configuration file. When the file load completes, the client automatically attempts to connect to the server using the settings specified by the configuration file. The configuration file has the following format:

     <?xml version="1.0"?>
     <config>
       <connections>
         <connection host="hostNameOrIP1" port="portNumber1" type="connectionType1" senddelay="milliseconds1" secure="false"/>
         <connection host="hostNameOrIP2" port="portNumber2" type="connectionType2" senddelay="milliseconds2" secure="false" />
         ...
         <connection host="hostNameOrIPn" port="portNumbern" type="connectionTypen" senddelay="millisecondsn" secure="false" />
       </connections>
       <autoreconnectfrequency minms="minfrequency" maxms="maxfrequency" delayfirstattempt="false" maxattempts="numAttempts">frequency</autoreconnectfrequency>
       <connectiontimeout>duration</connectiontimeout>
       <heartbeatfrequency>frequency</heartbeatfrequency>
       <readytimeout>timeout</readytimeout>
       <loglevel>level</loglevel>
     </config>
     
The tags and attributes in the preceding XML document have the following meaning: For example, the following configuration file connects to Union Server running at tryunion.com, on port 80, with a log level of DEBUG.
     <?xml version="1.0"?>
     <config>
       <connections>
         <connection host="tryunion.com" port="80" />
       </connections>
       <logLevel>DEBUG</logLevel>
       <autoreconnectfrequency minms="10000" maxms="30000" delayfirstattempt="true" maxattempts="4"/>
       <connectiontimeout>30000</connectiontimeout>
       <heartbeatfrequency>10000</heartbeatfrequency>
       <readytimeout>5000</readytimeout>
     </config>
     

Parameters

configURL:String

secureConnect()method 
public function secureConnect(host:String = null, ... ports):void

Since : Reactor 2.1.0

The secureConnect() method is identical to the connect() method, except that it uses an encrypted connection (TLS or SSL) rather than an unencrypted connection. Before secureConnect() can be used, Union Server must be configured to accept client communications over a secure gateway, which includes the installation of a server-side security certificate. For instructions on configuring Union Server for secure communications, see Union Server's documentation at http://unionplatform.com.

Starting with Reactor 2.1.0, Reactor supports encrypted communications over HTTP (i.e., using Flash Player's native HTTPS support), but does not support encryption over persistent TCP/IP sockets.

To create an encrypted HTTP connection manually, use the SecureHTTPConnection class. No corresponding SecureXMLSocketConnection class is yet available.

The following code demonstrates how to establish a secure connection to port 443 on tryunion.com.

   reactor = new Reactor();
   reactor.secureConnect("tryunion.com", 443);
   

Parameters

host:String (default = null)
 
... ports

See also

self()method 
public function self():IClient

Since : Reactor 1.0.0

Returns a reference to the application's own IClient object (i.e., the "current client").

Returns
IClient — An IClient instance.
setServer()method 
public function setServer(host:String, ... ports):void

Since : Reactor 1.0.0

Specifies the host and port for future connection attempts. The setServer() method does not attempt to open a new connection; to connect after specifying the server, use Reactor's connect() method.

Parameters

host:String — The string name or IP address of the domain on which Union Server is running. For more details, see the connect() method.
 
... ports — A list of integer ports over which Reactor should attempt to connect to Union Server. For more details, see the port parameter of the connect() method.

See also

updateSnapshot()method 
public function updateSnapshot(snapshot:Snapshot):void

Since : Reactor 1.0.0

Updates the specified snapshot object with the latest information available on the server. For details on snapshots, see the Snapshot class.

Parameters

snapshot:Snapshot — The snapshot object to be updated. Must be an instance of any Snapshot subclass (e.g., ClientListSnapshot).

See also

Snapshot
Event Detail
CLOSE Event
Event Object Type: ReactorEvent
ReactorEvent.type variable = net.user1.reactor.ReactorEvent.CLOSE

Dispatched when either the connection to the server is lost or a connection attempt fails. Individual events for connection failure and connection closure can be handled separately via the ConnectionManager class or any class that implements IConnection.

See also

CONNECT_REFUSED Event  
Event Object Type: ReactorEvent
ReactorEvent.type variable = net.user1.reactor.ReactorEvent.CONNECT_REFUSED

Dispatched when the client attempts to connect to Union Server, but the connection is refused. To determine why the client connection was refused, use getConnectionRefusal().

See also

PROTOCOL_INCOMPATIBLE Event  
Event Object Type: ReactorEvent
ReactorEvent.type variable = net.user1.reactor.ReactorEvent.PROTOCOL_INCOMPATIBLE

Dispatched when the client connects to a Union Server that conforms to a version of the UPC specification that does not match the client's UPC version.

The UPC specification version takes format: majorNumber.minorNumber.revisionNumber. For example, in the version number 1.2.0, the majorNumber is 1, the minorNumber is 2, and the revisionNumber is 0. If the client's majorNumber, minorNumber, and revisionNumber all match the server's majorNumber, minorNumber, and revisionNumber, the server is considered compatible with the client. Otherwise:

The UPC specification is available at http://unionplatform.com/specs/upc/.

See also

READY Event  
Event Object Type: ReactorEvent
ReactorEvent.type variable = net.user1.reactor.ReactorEvent.READY

Dispatched when a connection to the server has been established and fully initialized. After READY occurs, the Reactor client can begin communicating freely with the server.

See also