Packagenet.user1.reactor
Classpublic class ConnectionManager
InheritanceConnectionManager Inheritance flash.events.EventDispatcher

Since : Reactor 1.0.0

The ConnectionManager class manages all connections made by a Reactor appliction to Union Server. In most applications, the ConnectionManager class is not used directly. Instead, connections to Union Server are made via the Reactor class's connect() method, and disconnections are requested via the Reactor class's disconnect() method. However, ConnectionManager provides more control over the connection process than the Reactor class offers. Specifically, the ConnectionManager provides the following services:

To access the ConnectionManager for a Reactor application, use the Reactor class's getConnectionManager() method, as in:

   var reactor:Reactor = new Reactor();
   var connectionManager:ConnectionManager = reactor.getConnectionManager();
   

See also

Reactor.connect()
Reactor.disconnect()
Reactor.getConnectionManager()
ConnectionManagerEvent
IConnection
ConnectionEvent.SEND_DATA
ConnectionEvent.RECEIVE_DATA


Public Variables
 VariableDefined By
  DEFAULT_READY_TIMEOUT : int = 10000
[static]
ConnectionManager
Public Methods
 MethodDefined By
  
ConnectionManager
  
addConnection(connection:IConnection):void
Adds a new IConnection object to this ConnectionManager's connection list.
ConnectionManager
  
connect():void
Attempts to connect to Union Server using the currently specified list of connection objects.
ConnectionManager
  
disconnect():void
Terminates any open connection to the server.
ConnectionManager
  
dispose():void
Permanently disables this object and releases all of its resources.
ConnectionManager
  
If a connection is currently connected, getActiveConnection() returns that connection; otherwise, getActiveConnection() returns null.
ConnectionManager
  
getAffinity(host:String):String
Returns the actual server address that will be used when a connection to the specified host is requested.
ConnectionManager
  
Returns an integer indicating the number of times this ConnectionManager object has aborted an in-progress connection attempt since the last successful connection was made.
ConnectionManager
  
Returns an integer indicating the number of times this ConnectionManager object has attempted to connect to the server since the last successful connection was established.
ConnectionManager
  
Returns an integer indicating the number of failed connection attempts this ConnectionManager object has made since the last successful connection was established.
ConnectionManager
  
Returns a one-time snapshot of the ConnectionManager's connection list, as an Array.
ConnectionManager
  
Returns an integer representing the ConnectionManager's current state.
ConnectionManager
  
If a connection is currently in progress, getInProgressConnection() returns that connection; otherwise, getInProgressConnection() returns null.
ConnectionManager
  
Returns an integer indicating the number of times this ConnectionManager object has successfully established a valid connection to the server.
ConnectionManager
  
The maximum time each IConnection object allows for its setup phase to complete when attempting to connect to Union Server.
ConnectionManager
  
isReady():Boolean
Returns a Boolean indicating whether the ConnectionManager currently has an active connection to Union Server.
ConnectionManager
  
Removes all IConnection objects from this ConnectionManager's connection list.
ConnectionManager
  
removeConnection(connection:IConnection):Boolean
Removes the specified IConnection object from this ConnectionManager's connection list.
ConnectionManager
  
setGlobalAffinity(enabled:Boolean):void
Specifies whether the current client's ConnectionManager will use global server affinity or local server affinity.
ConnectionManager
  
setReadyTimeout(milliseconds:int):void
Sets the maximum time each IConnection object allows for its setup phase to complete when attempting to connect to Union Server.
ConnectionManager
Events
 Event Summary Defined By
   An event triggered when a connection attempt by the ConnectionManager begins.ConnectionManager
   An event triggered when the client closes an active connection.ConnectionManager
   An event triggered when a connection attempt by the ConnectionManager fails.ConnectionManager
   An event triggered when the ConnectionManager's state changes (e.g., from "CONNECTION_IN_PROGRESS" to "READY").ConnectionManager
   An event triggered when either the client or the server closes an active connection.ConnectionManager
   An event triggered when one of the IConnection objects in the ConnectionManager's connection list achieves a READY state.ConnectionManager
   An event triggered when the ConnectionManager selects an IConnection object for a connection attempt.ConnectionManager
   An event triggered when the server closes an active connection.ConnectionManager
Variable Descriptions
DEFAULT_READY_TIMEOUTvariable
public static var DEFAULT_READY_TIMEOUT:int = 10000

Constructor Description
ConnectionManager()Constructor
public function ConnectionManager(reactor:Reactor)



Parameters
reactor:Reactor
Method Descriptions
addConnection()method
public function addConnection(connection:IConnection):void

Since : Reactor 1.0.0

Adds a new IConnection object to this ConnectionManager's connection list. The connection list specifies the connections that should be attempted, in the order they were added, when connecting to Union Server. To connect to Union Server, use the Reactor class's connect() method or the ConnectionManager class's connect() method.

Parameters

connection:IConnection

See also

connect()method 
public function connect():void

Since : Reactor 1.0.0

Attempts to connect to Union Server using the currently specified list of connection objects. If any of the connections in the list succeeds, ConnectionManager dispatches the ConnectionManagerEvent.READY event, and the Reactor object dispatches a ReactorEvent.READY event. If, however, all of the connections in the list fail, ConnectionManager dispatches the ConnectionManagerEvent.CONNECT_FAILURE event, and the Reactor object dispatches a ReactorEvent.CLOSE event.

Applications that use ConnectionManager's connect() method directly must first add at least one IConnection object to the ConnectionManager. For example,

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

Once the connection has been added, connect() can be invoked, as follows:

     connectionManager.connect();
     

Connections are attempted in the order they were added to the connection list. For example, the following code instructs the ConnectionManager to attempt to connect an XMLSocketConnection to host "tryunion.com" on port 80. If that connection attempt fails, the ConnectionManager next attempts to connect the same port over HTTP.

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

Each time the ConnectionManager moves to the next connection in its list, it triggers the ConnectionManagerEvent.SELECT_CONNECTION event.

Note, however, that the ConnectionManager class's connect() method is not used directly by most applications. Instead, to connect to the server, applications typically use the Reactor class's more convenient connect() method, which delegates its work to the ConnectionManager class's connect() method. For example, the following single line of code is equivalent to the preceding four lines:

     reactor.connect("tryunion.com", 80);
     

However, note that while the Reactor class's version of connect() is less verbose than ConnectionManager's connect() method, it cannot specify multiple hosts for multiple connections.

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.

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 from Union Server, use disconnect(), not dispose().

See also

getActiveConnection()method 
public function getActiveConnection():IConnection

Since : Reactor 1.0.0

If a connection is currently connected, getActiveConnection() returns that connection; otherwise, getActiveConnection() returns null.

Returns
IConnection
getAffinity()method 
public function getAffinity(host:String):String

Since : Reactor 2.0.0

Returns the actual server address that will be used when a connection to the specified host is requested. When the current client connects to a Union Server cluster, and the specified host is a DNS server that forwards connection requests to a server node in the cluster, getAffinity() returns the address (public name or IP) of that server node. Similarly, when the current client connects to a DNS server that redirects to a Union Server instance, getAffinity() returns the address (public name or IP) of that instance. When the current client connects to a Union Server instance directly, the address returned by getAffinity() is always identical to the supplied host.

Parameters

host:String

Returns
String
getConnectAbortCount()method 
public function getConnectAbortCount():int

Since : Reactor 1.0.0

Returns an integer indicating the number of times this ConnectionManager object has aborted an in-progress connection attempt since the last successful connection was made.

Returns
int

See also

getConnectAttemptCount()method 
public function getConnectAttemptCount():int

Since : Reactor 1.0.0

Returns an integer indicating the number of times this ConnectionManager object has attempted to connect to the server since the last successful connection was established.

Returns
int

See also

getConnectFailedCount()method 
public function getConnectFailedCount():int

Since : Reactor 1.0.0

Returns an integer indicating the number of failed connection attempts this ConnectionManager object has made since the last successful connection was established. Whenever a successful connection is established, the connect-failed count returns to zero.

Returns
int

See also

getConnections()method 
public function getConnections():Array

Since : Reactor 1.0.0

Returns a one-time snapshot of the ConnectionManager's connection list, as an Array. Each element of the array is an IConnection object.

Returns
Array
getConnectionState()method 
public function getConnectionState():int

Since : Reactor 1.0.0

Returns an integer representing the ConnectionManager's current state. For a list of possible states, see the ConnectionState class.

Returns
int — An integer representing a connection state.

See also

getInProgressConnection()method 
public function getInProgressConnection():IConnection

Since : Reactor 1.0.0

If a connection is currently in progress, getInProgressConnection() returns that connection; otherwise, getInProgressConnection() returns null.

Returns
IConnection
getReadyCount()method 
public function getReadyCount():int

Since : Reactor 1.0.0

Returns an integer indicating the number of times this ConnectionManager object has successfully established a valid connection to the server. The count is increased when the ConnectionEvent.READY event occurs.

Returns
int

See also

getReadyTimeout()method 
public function getReadyTimeout():int

Since : Reactor 1.0.0

The maximum time each IConnection object allows for its setup phase to complete when attempting to connect to Union Server.

Returns
int

See also

isReady()method 
public function isReady():Boolean

Since : Reactor 1.0.0

Returns a Boolean indicating whether the ConnectionManager currently has an active connection to Union Server.

Returns
Boolean — Returns true if Reactor is currently connected to the server; false otherwise.
removeAllConnections()method 
public function removeAllConnections():void

Since : Reactor 1.0.0

Removes all IConnection objects from this ConnectionManager's connection list. Any connection that is currently open will be disconnected. Until new connections are added via addConnection(), subsequent calls to connect() or disconnect() will fail.

See also

removeConnection()method 
public function removeConnection(connection:IConnection):Boolean

Since : Reactor 1.0.0

Removes the specified IConnection object from this ConnectionManager's connection list. If the connection is currently open, it is disconnected before removal.

Parameters

connection:IConnection

Returns
Boolean

See also

setGlobalAffinity()method 
public function setGlobalAffinity(enabled:Boolean):void

Since : Reactor 2.0.0

Specifies whether the current client's ConnectionManager will use global server affinity or local server affinity. When enabled is true (default), server affinity is set to global, and the ConnectionManager uses the affinity value shared by all clients in the current environment. When enabled is false, server affinity is set to local, and the ConnectionManager for the current client maintains its own, individual server affinity.

For example, imagine a client application with two Reactor instances, both of which connect to a Union Server cluster. The cluster is accessed via a round-robin DNS server, pool.example.com, and server affinity is global. The first Reactor instance connects to pool.example.com, and is redirected to slave1.example.com. Upon connection, the affinity address slave1.example.com is assigned for host pool.example.com. Then the second Reactor instance connects. Because affinity is global, the second Reactor instance finds affinity address slave1.example.com for host pool.example.com, and connects directly to slave1.example.com, bypassing pool.example.com entirely.

Now imagine the same application with server affinity set to local. The first Reactor instance connects to pool.example.com, and is redirected to slave1.example.com as before. Upon connection, the affinity address slave1.example.com is assigned for host pool.example.com. Then the second Reactor instance connects. Because affinity is local, the second Reactor instance has no affinity established for pool.example.com, and therefore connects to pool.example.com, not slave1.example.com. The pool.example.com DNS server redirects the second Reactor instance to slave2.example.com. Upon connection, the affinity address slave2.example.com is assigned for host pool.example.com in the second Reactor instance's affinity map. For the duration specified by the server's affinity configuration, the first Reactor instance communicates with slave1.example.com and the second Reactor instance communicates with slave2.example.com. Compare with the preceding global affinity example, where the first Reactor instance and the second Reactor instance both communicate with slave1.example.com.

Parameters

enabled:Boolean

setReadyTimeout()method 
public function setReadyTimeout(milliseconds:int):void

Since : Reactor 1.0.0

Sets the maximum time each IConnection object allows for its setup phase to complete when attempting to connect to Union Server. When an IConnection object attempts to connect to Union Server, it starts a "handshake" process during which client setup tasks (such as issuing a client ID) are performed. If the setup tasks are not completed within an allowed limit known as the "ready timeout," then the IConnection object considers the setup process a failure and automatically aborts the connection attempt. If, on the other hand, the client setup process completes within the ready-timeout limit, then the IConnection object considers the setup process a success and triggers a ConnectionEvent.READY event indicating that the connection is ready for use. The ready timeout defaults to 10 seconds, but can be changed via the setReadyTimeout() method.

Once an IConnection object achieves a ready state, Reactor continues to monitor the connection to the server by sending regular heartbeat messages. By default, one heartbeat message is sent every 10 seconds, but the heartbeat message frequency is configurable via ConnectionMonitor's setHeartbeatFrequency() method. If Union Server takes longer than 60 seconds (by default) to respond to single heartbeat, Reactor will automatically disconnect. To change the duration that Reactor will tolerate for a heartbeat response, use ConnectionMonitor's setConnectionTimeout() method.

Parameters

milliseconds:int — The time within which a connection must achieve a ready state, in milliseconds.

See also


Example
The following code lengthens the default ready timeout to 20 seconds. As a result, Reactor will automatically disconnect from Union Server when the client-setup process does not complete within 20 seconds.
     var reactor:Reactor = new Reactor();
     reactor.getConnectionManager().setReadyTimeout(20000);
     
Event Detail
BEGIN_CONNECT Event
Event Object Type: ConnectionManagerEvent
ConnectionManagerEvent.type variable = net.user1.reactor.ConnectionManagerEvent.BEGIN_CONNECT

An event triggered when a connection attempt by the ConnectionManager begins. The ConnectionManagerEvent.BEGIN_CONNECT event is followed by a ConnectionManagerEvent.SELECT_CONNECTION event, which indicates the specific IConnection object the ConnectionManager will use for its connection attempt.

See also

CLIENT_KILL_CONNECT Event  
Event Object Type: ConnectionManagerEvent
ConnectionManagerEvent.type variable = net.user1.reactor.ConnectionManagerEvent.CLIENT_KILL_CONNECT

An event triggered when the client closes an active connection. The ConnectionManagerEvent.CLIENT_KILL_CONNECT event is always followed by the ConnectionManagerEvent.DISCONNECT event.

See also

CONNECT_FAILURE Event  
Event Object Type: ConnectionManagerEvent
ConnectionManagerEvent.type variable = net.user1.reactor.ConnectionManagerEvent.CONNECT_FAILURE

An event triggered when a connection attempt by the ConnectionManager fails. Common causes of connection failures are:

The ConnectionManagerEvent.CONNECT_FAILURE event is triggered by the ConnectionManager class when the ConnectionManager has attempted to connect using all of the connections in its connection list, and none of them successfully achieved a "ready" state. As a convenience, when a connection attempt fails, the Reactor object also dispatches a ReactorEvent.CLOSE event.

See also

CONNECTION_STATE_CHANGE Event  
Event Object Type: ConnectionManagerEvent
ConnectionManagerEvent.type variable = net.user1.reactor.ConnectionManagerEvent.CONNECTION_STATE_CHANGE

An event triggered when the ConnectionManager's state changes (e.g., from "CONNECTION_IN_PROGRESS" to "READY"). For a list of possible states, see the ConnectionState class.

The following example code registers for the CONNECTION_STATE_CHANGE event, and displays the ConnectionManager's new connection state in the output console.

     // Event registration
     reactor.getConnectionManager().addEventListener(
                         ConnectionManagerEvent.CONNECTION_STATE_CHANGE, 
                         connectionStateChangeListener);
     
     // Event listener definition
     function connectionStateChangeListener (e:ConnectionManagerEvent):void {
       trace("New connection state: " + getStateName(ConnectionManager(e.target).getConnectionState()));
     }
     
     // Helper function to translate numeric state codes to human-readable strings
     function getStateName (state:int):String {
       switch (state) {
         case -1:
           return "UNKNOWN";
         case 0:
           return "NOT_CONNECTED";
         case 1:
           return "READY";
         case 2:
           return "CONNECTION_IN_PROGRESS";
         case 3:
           return "DISCONNECTION_IN_PROGRESS";
         case 4:
           return "LOGGED_IN";
         default:
           return "UNRECOGNIZED STATE";
       }
     }
     

See also

DISCONNECT Event  
Event Object Type: ConnectionManagerEvent
ConnectionManagerEvent.type variable = net.user1.reactor.ConnectionManagerEvent.DISCONNECT

An event triggered when either the client or the server closes an active connection. The ConnectionManagerEvent.DISCONNECT is always preceded by either the ConnectionManagerEvent.CLIENT_KILL_CONNECT event or the ConnectionManagerEvent.SERVER_KILL_CONNECT, which indicate whether the client or the server instigated the disconnection.

See also

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

An event triggered when one of the IConnection objects in the ConnectionManager's connection list achieves a READY state. As a convenience, the ConnectionManagerEvent.READY event, in turn, always triggers a ReactorEvent.READY event. To retrieve a reference to the underlying IConnection object that achieved the ready state, use ConnectionManager's getActiveConnection() method.

See also

SELECT_CONNECTION Event  
Event Object Type: ConnectionManagerEvent
ConnectionManagerEvent.type variable = net.user1.reactor.ConnectionManagerEvent.SELECT_CONNECTION

An event triggered when the ConnectionManager selects an IConnection object for a connection attempt. Immediately after selecting the connection, the ConnectionManager attempts to connect it. Next, that individual IConnection object dispatches its own ConnectionEvent events indicating whether it was able to connect to Union. If the individual IConnection object cannot connect, the ConnectionManager automatically moves to the next available IConnection object. If any of the IConnection objects in the ConnectionManager's list successfully connects, then ConnectionManager triggers a ConnectionManagerEvent.READY event. If, on the other hand, none of the IConnection objects connects, the ConnectionManager triggers a ConnectionManagerEvent.CONNECT_FAILURE event, indicating that it could not establish a connection via any of the IConnection objects in its list.

To add a new IConnection object to the ConnectionManager's connection list, use ConnectionManager's addConnection() method.

See also

SERVER_KILL_CONNECT Event  
Event Object Type: ConnectionManagerEvent
ConnectionManagerEvent.type variable = net.user1.reactor.ConnectionManagerEvent.SERVER_KILL_CONNECT

An event triggered when the server closes an active connection. The ConnectionManagerEvent.SERVER_KILL_CONNECT event is always followed by the ConnectionManagerEvent.DISCONNECT event.

See also