Apache Flex 4.16.0 API Reference | All Packages | All Classes | Index | Frames No Frames |
Channel

Package | mx.messaging
Class | public class Channel
Inheritance | Channel flash.events.EventDispatcher
Implements | IMXMLObject
Subclasses | PollingChannel

Language Version : | ActionScript 3.0

Product Versions : | BlazeDS 4, LCDS 3

Runtime Versions : | Flash Player 9, AIR 1.1

The Channel class is the base message channel class that all channels in the messaging system must extend.

Channels are specific protocol-based conduits for messages sent between MessageAgents and remote destinations. Preconfigured channels are obtained within the framework using the `ServerConfig.getChannel()` method. You can create a Channel directly using the `new` operator and add it to a ChannelSet directly.

Channels represent a physical connection to a remote endpoint. Channels are shared across destinations by default. This means that a client targetting different destinations may use the same Channel to communicate with these destinations.

Note: This class is for advanced use only. Use this class for creating custom channels like the existing RTMPChannel, AMFChannel, and HTTPChannel.

Public Properties

| Property | Defined By
--- | --- | ---
|  | authenticated : Boolean [read-only] Indicates if this channel is authenticated. | Channel
|  | channelSets : Array [read-only] Provides access to the ChannelSets connected to the Channel. | Channel
|  | connected : Boolean [read-only] Indicates whether this channel has established a connection to the remote destination. | Channel
|  | connectTimeout : int Provides access to the connect timeout in seconds for the channel. | Channel
|  | endpoint : String [read-only] Provides access to the endpoint for this channel. | Channel
|  | failoverURIs : Array Provides access to the set of endpoint URIs that this channel can attempt to failover to if the endpoint is clustered. | Channel
|  | id : String Provides access to the id of this channel. | Channel
|  | protocol : String [read-only] Provides access to the protocol that the channel uses. | Channel
|  | reconnecting : Boolean [read-only] Indicates whether this channel is in the process of reconnecting to an alternate endpoint. | Channel
|  | recordMessageSizes : Boolean [read-only] Channel property determines the level of performance information injection - whether we inject message sizes or not. | Channel
|  | recordMessageTimes : Boolean [read-only] Channel property determines the level of performance information injection - whether we inject timestamps or not. | Channel
|  | requestTimeout : int Provides access to the default request timeout in seconds for the channel. | Channel
|  | uri : String Provides access to the URI used to create the whole endpoint URI for this channel. | Channel

Protected Properties

| Property | Defined By
--- | --- | ---
|  | shouldBeConnected : Boolean [read-only] Indicates whether this channel should be connected to its endpoint. | Channel

Public Methods

| Method | Defined By
--- | --- | ---
|  | Channel(id:String = null, uri:String = null) Constructs an instance of a generic Channel that connects to the specified endpoint URI. | Channel
|  | applySettings(settings:XML):void Subclasses should override this method to apply any settings that may be necessary for an individual channel. | Channel
|  | connect(channelSet:ChannelSet):void Connects the ChannelSet to the Channel. | Channel
|  | disconnect(channelSet:ChannelSet):void Disconnects the ChannelSet from the Channel. | Channel
|  | logout(agent:MessageAgent):void Sends a CommandMessage to the server to logout if the Channel is connected. | Channel
|  | send(agent:MessageAgent, message:IMessage):void Sends the specified message to its target destination. | Channel
|  | setCredentials(credentials:String, agent:MessageAgent = null, charset:String = null):void Sets the credentials to the specified value. | Channel

Protected Methods

| Method | Defined By
--- | --- | ---
|  | applyClientLoadBalancingSettings(props:XML):void Applies the client load balancing urls if they exists. | Channel
|  | connectFailed(event:ChannelFaultEvent):void Processes a failed internal connect and dispatches the FAULT event for the channel. | Channel
|  | connectSuccess():void Processes a successful internal connect and dispatches the CONNECT event for the Channel. | Channel
|  | connectTimeoutHandler(event:TimerEvent):void Handles a connect timeout by dispatching a ChannelFaultEvent. | Channel
|  | disconnectFailed(event:ChannelFaultEvent):void Processes a failed internal disconnect and dispatches the FAULT event for the channel. | Channel
|  | disconnectSuccess(rejected:Boolean = false):void Processes a successful internal disconnect and dispatches the DISCONNECT event for the Channel. | Channel
|  | flexClientWaitHandler(event:PropertyChangeEvent):void Handles a change to the guard condition for managing initial Channel connect for the application. | Channel
|  | getMessageResponder(agent:MessageAgent, message:IMessage):MessageResponder Returns the appropriate MessageResponder for the Channel's send() method. | Channel
|  | internalConnect():void Connects the Channel to its endpoint. | Channel
|  | internalDisconnect(rejected:Boolean = false):void Disconnects the Channel from its endpoint. | Channel
|  | internalSend(messageResponder:MessageResponder):void Sends the Message out over the Channel and routes the response to the responder. | Channel

Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | channelConnect | Dispatched after the channel has connected to its endpoint. | Channel
|  | channelDisconnect | Dispatched after the channel has disconnected from its endpoint. | Channel
|  | channelFault | Dispatched after the channel has faulted. | Channel
|  | message | Dispatched when a channel receives a message from its endpoint. | Channel
|  | propertyChange | Dispatched when a property of the channel changes. | Channel

Protected Constants

| Constant | Defined By
--- | --- | ---
|  | CONNECT_TIMEOUT_SECONDS : String = connect-timeout-seconds [static] | Channel
|  | ENABLE_SMALL_MESSAGES : String = enable-small-messages [static] | Channel
|  | FALSE : String = false [static] | Channel
|  | RECORD_MESSAGE_SIZES : String = record-message-sizes [static] | Channel
|  | RECORD_MESSAGE_TIMES : String = record-message-times [static] | Channel
|  | REQUEST_TIMEOUT_SECONDS : String = request-timeout-seconds [static] | Channel
|  | SERIALIZATION : String = serialization [static] | Channel
|  | TRUE : String = true [static] | Channel

Property Detail

authenticated | property

`authenticated:Boolean` [read-only]

Indicates if this channel is authenticated.

This property can be used as the source for data binding.

Implementation
`public function get authenticated():Boolean`

channelSets | property |

`channelSets:Array` [read-only]

Language Version : | ActionScript 3.0

Product Versions : | BlazeDS 4, LCDS 3

Runtime Versions : | Flash Player 9, AIR 1.1

Provides access to the ChannelSets connected to the Channel.

Implementation
`public function get channelSets():Array`

connected | property |

`connected:Boolean` [read-only]

Language Version : | ActionScript 3.0

Product Versions : | BlazeDS 4, LCDS 3

Runtime Versions : | Flash Player 9, AIR 1.1

Indicates whether this channel has established a connection to the remote destination.

This property can be used as the source for data binding.

Implementation
`public function get connected():Boolean`

connectTimeout | property |

`connectTimeout:int`

Language Version : | ActionScript 3.0

Product Versions : | BlazeDS 4, LCDS 3

Runtime Versions : | Flash Player 9, AIR 1.1

Provides access to the connect timeout in seconds for the channel. A value of 0 or below indicates that a connect attempt will never be timed out on the client. For channels that are configured to failover, this value is the total time to wait for a connection to be established. It is not reset for each failover URI that the channel may attempt to connect to.

Implementation
`public function get connectTimeout():int`
`public function set connectTimeout(value:int):void`

endpoint | property |

`endpoint:String` [read-only]

Provides access to the endpoint for this channel. This value is calculated based on the value of the `uri` property.

Implementation
`public function get endpoint():String`

failoverURIs | property |

`failoverURIs:Array`

Provides access to the set of endpoint URIs that this channel can attempt to failover to if the endpoint is clustered.

This property is automatically populated when clustering is enabled. If you don't use clustering, you can set your own values.

Implementation
`public function get failoverURIs():Array`
`public function set failoverURIs(value:Array):void`

id | property |

`id:String`

Provides access to the id of this channel.

Implementation
`public function get id():String`
`public function set id(value:String):void`

protocol | property |

`protocol:String` [read-only]

Provides access to the protocol that the channel uses.

Note: Subclasses of Channel must override this method and return a string that represents their supported protocol. Examples of supported protocol strings are "rtmp", "http" or "https".

Implementation
`public function get protocol():String`

reconnecting | property |

`reconnecting:Boolean` [read-only]

Indicates whether this channel is in the process of reconnecting to an alternate endpoint.

This property can be used as the source for data binding.

Implementation
`public function get reconnecting():Boolean`

recordMessageSizes | property |

`recordMessageSizes:Boolean` [read-only]

Language Version : | ActionScript 3.0

Product Versions : | BlazeDS 4, LCDS 3

Runtime Versions : | Flash Player 9, AIR 1.1

Channel property determines the level of performance information injection - whether we inject message sizes or not.

Implementation
`public function get recordMessageSizes():Boolean`

recordMessageTimes | property |

`recordMessageTimes:Boolean` [read-only]

Language Version : | ActionScript 3.0

Product Versions : | BlazeDS 4, LCDS 3

Runtime Versions : | Flash Player 9, AIR 1.1

Channel property determines the level of performance information injection - whether we inject timestamps or not.

Implementation
`public function get recordMessageTimes():Boolean`

requestTimeout | property |

`requestTimeout:int`

Provides access to the default request timeout in seconds for the channel. A value of 0 or below indicates that outbound requests will never be timed out on the client.

Request timeouts are most useful for RPC style messaging that requires a response from the remote destination.

Implementation
`public function get requestTimeout():int`
`public function set requestTimeout(value:int):void`

shouldBeConnected | property |

`shouldBeConnected:Boolean` [read-only]

Indicates whether this channel should be connected to its endpoint. This flag is used to control when fail over should be attempted and when disconnect notification is sent to the remote endpoint upon disconnect or fault.

Implementation
`protected function get shouldBeConnected():Boolean`

uri | property |

`uri:String`

Provides access to the URI used to create the whole endpoint URI for this channel. The URI can be a partial path, in which case the full endpoint URI is computed as necessary.

Implementation
`public function get uri():String`
`public function set uri(value:String):void`
Constructor Detail

Channel | () | Constructor

`public function Channel(id:String = null, uri:String = null)`

Language Version : | ActionScript 3.0

Product Versions : | BlazeDS 4, LCDS 3

Runtime Versions : | Flash Player 9, AIR 1.1

Constructs an instance of a generic Channel that connects to the specified endpoint URI. Note: The Channel type should not be constructed directly. Instead create instances of protocol specific subclasses such as RTMPChannel or AMFChannel.

Parameters

| `id:String` (default = `null`)`` — The id of this channel.
| `uri:String` (default = `null`)`` — The endpoint URI for this channel.

Method Detail

applyClientLoadBalancingSettings | () | method

`protected function applyClientLoadBalancingSettings(props:XML):void`

Applies the client load balancing urls if they exists. It randomly picks a url from the set of client load balancing urls and sets it as the channel's main url; then it assigns the rest of the urls as the `failoverURIs` of the channel.

Parameters

| `props:XML` — The properties section of the XML fragment of the services-config.xml file for this channel.

applySettings | () | method |

`public function applySettings(settings:XML):void`

Subclasses should override this method to apply any settings that may be necessary for an individual channel. Make sure to call `super.applySettings()` to apply common settings for the channel. This method is used primarily in Channel subclasses.

Parameters

| `settings:XML` — XML fragment of the services-config.xml file for this channel.

connect | () | method |

`public final function connect(channelSet:ChannelSet):void`

Connects the ChannelSet to the Channel. If the Channel has not yet connected to its endpoint, it attempts to do so. Channel subclasses must override the `internalConnect()` method, and call the `connectSuccess()` method once the underlying connection is established.

Parameters

| `channelSet:ChannelSet` — The ChannelSet to connect to the Channel.

connectFailed | () | method |

`protected function connectFailed(event:ChannelFaultEvent):void`

Processes a failed internal connect and dispatches the `FAULT` event for the channel. If the Channel has `failoverURI` values, it will attempt to reconnect automatically by trying these URI values in order until a connection is established or the available values are exhausted.

Parameters

| `event:ChannelFaultEvent` — The ChannelFaultEvent for the failed connect.

connectSuccess | () | method |

`protected function connectSuccess():void`

Processes a successful internal connect and dispatches the `CONNECT` event for the Channel.

connectTimeoutHandler | () | method |

`protected function connectTimeoutHandler(event:TimerEvent):void`

Handles a connect timeout by dispatching a ChannelFaultEvent. Subtypes may overide this to shutdown the current connect attempt but must call `super.connectTimeoutHandler(event)`.

Parameters

| `event:TimerEvent` — The timer event indicating that the connect timeout has been reached.

disconnect | () | method |

`public final function disconnect(channelSet:ChannelSet):void`

Disconnects the ChannelSet from the Channel. If the Channel is connected to its endpoint and it has no more connected ChannelSets it will internally disconnect.

Channel subclasses need to override the `internalDisconnect()` method, and call the `disconnectSuccess()` method when the underlying connection has been terminated.

Parameters

| `channelSet:ChannelSet` — The ChannelSet to disconnect from the Channel.

disconnectFailed | () | method |

`protected function disconnectFailed(event:ChannelFaultEvent):void`

Processes a failed internal disconnect and dispatches the `FAULT` event for the channel.

Parameters

| `event:ChannelFaultEvent` — The ChannelFaultEvent for the failed disconnect.

disconnectSuccess | () | method |

`protected function disconnectSuccess(rejected:Boolean = false):void`

Processes a successful internal disconnect and dispatches the `DISCONNECT` event for the Channel. If the disconnect is due to a network failure and the Channel has `failoverURI` values, it will attempt to reconnect automatically by trying these URI values in order until a connection is established or the available values are exhausted.

Parameters

| `rejected:Boolean` (default = `false`)`` — True if the disconnect should skip any failover processing that would otherwise be attempted; false if failover processing should be allowed to run.

flexClientWaitHandler | () | method |

`protected function flexClientWaitHandler(event:PropertyChangeEvent):void`

Handles a change to the guard condition for managing initial Channel connect for the application. When this is invoked it means that this Channel is waiting to attempt to connect.

Parameters

| `event:PropertyChangeEvent` — The PropertyChangeEvent dispatched by the FlexClient singleton.

getMessageResponder | () | method |

`protected function getMessageResponder(agent:MessageAgent, message:IMessage):MessageResponder`

Returns the appropriate MessageResponder for the Channel's `send()` method. Must be overridden.

Parameters

| `agent:MessageAgent` — The MessageAgent sending the message.
| `message:IMessage` — The Message to send.

Returns

| `MessageResponder` — The MessageResponder to handle the result or fault.

Throws

| `flash.errors:IllegalOperationError` — If the Channel subclass does not override this method.

internalConnect | () | method |

`protected function internalConnect():void`

Connects the Channel to its endpoint. Must be overridden.

internalDisconnect | () | method |

`protected function internalDisconnect(rejected:Boolean = false):void`

Disconnects the Channel from its endpoint. Must be overridden.

Parameters

| `rejected:Boolean` (default = `false`)`` — True if the disconnect was due to a connection rejection or timeout and reconnection should not be attempted automatically; otherwise false.

internalSend | () | method |

`protected function internalSend(messageResponder:MessageResponder):void`

Sends the Message out over the Channel and routes the response to the responder. Must be overridden.

Parameters

| `messageResponder:MessageResponder` — The MessageResponder to handle the response.

logout | () | method |

`public function logout(agent:MessageAgent):void`

Sends a CommandMessage to the server to logout if the Channel is connected. Current credentials are cleared.

Parameters

| `agent:MessageAgent` — The MessageAgent to logout.

send | () | method |

`public function send(agent:MessageAgent, message:IMessage):void`

Sends the specified message to its target destination. Subclasses must override the `internalSend()` method to perform the actual send.

Parameters

| `agent:MessageAgent` — The MessageAgent that is sending the message.
| `message:IMessage` — The Message to send.

Throws

| `InvalidDestinationError` — If neither the MessageAgent nor the message specify a destination.

setCredentials | () | method |

`public function setCredentials(credentials:String, agent:MessageAgent = null, charset:String = null):void`

Sets the credentials to the specified value. If the credentials are non-null and the Channel is connected, this method also sends a CommandMessage to the server to login using the credentials.

Parameters

| `credentials:String` — The credentials string.
| `agent:MessageAgent` (default = `null`)`` — The MessageAgent to login, that will handle the login result.
| `charset:String` (default = `null`)`` — The character set encoding used while encoding the credentials. The default is null, which implies the legacy charset of ISO-Latin-1.

Throws

| `flash.errors:IllegalOperationError` — in two situations; if credentials have already been set and an authentication is in progress with the remote detination, or if authenticated and the credentials specified don't match the currently authenticated credentials.

Event Detail

channelConnect | Event

Event Object Type: `mx.messaging.events.ChannelEvent`
ChannelEvent.type property = `mx.messaging.events.ChannelEvent.CONNECT`

Dispatched after the channel has connected to its endpoint.

Channel and its subclasses issue a Channel.Connect.Failed code whenever there is an issue in a channel's connect attempts to a remote destination. An AMFChannel object issues Channel.Call.Failed code when the channel is already connected but it gets a Call.Failed code from its underlying NetConnection.

The CONNECT event type; indicates that the Channel connected to its endpoint.

The value of this constant is `"channelConnect"`.

The properties of the event object have the following values:

Property | Value
--- | ---
`bubbles` | false
`cancelable` | false
`channel` | The channel that generated this event.
`currentTarget` | The Object that defines the event listener that handles the event. For example, if you use `myButton.addEventListener()` to register an event listener, myButton is the value of the `currentTarget`.
`target` | The Object that dispatched the event; it is not always the Object listening for the event. Use the `currentTarget` property to always access the Object listening for the event.
`reconnecting` | Indicates whether the channel that generated this event is reconnecting.
`rejected` | Indicates whether the channel that generated this event was rejected. This would be true in the event that the channel has been disconnected due to inactivity and should not attempt to failover or connect on an alternate channel.

channelDisconnect | Event |

Event Object Type: `mx.messaging.events.ChannelEvent`
ChannelEvent.type property = `mx.messaging.events.ChannelEvent.DISCONNECT`

Language Version : | ActionScript 3.0

Product Versions : | BlazeDS 4, LCDS 3

Runtime Versions : | Flash Player 9, AIR 1.1

Dispatched after the channel has disconnected from its endpoint.

The DISCONNECT event type; indicates that the Channel disconnected from its endpoint.

The value of this constant is `"channelDisconnect"`.

The properties of the event object have the following values:

Property | Value
--- | ---
`bubbles` | false
`cancelable` | false
`channel` | The channel that generated this event.
`currentTarget` | The Object that defines the event listener that handles the event. For example, if you use `myButton.addEventListener()` to register an event listener, myButton is the value of the `currentTarget`.
`target` | The Object that dispatched the event; it is not always the Object listening for the event. Use the `currentTarget` property to always access the Object listening for the event.
`reconnecting` | Indicates whether the channel that generated this event is reconnecting.
`rejected` | Indicates whether the channel that generated this event was rejected. This would be true in the event that the channel has been disconnected due to inactivity and should not attempt to failover or connect on an alternate channel.

channelFault | Event |

Event Object Type: `mx.messaging.events.ChannelFaultEvent`
ChannelFaultEvent.type property = `mx.messaging.events.ChannelFaultEvent.FAULT`

Language Version : | ActionScript 3.0

Product Versions : | BlazeDS 4, LCDS 3

Runtime Versions : | Flash Player 9, AIR 1.1

Dispatched after the channel has faulted.

The FAULT event type; indicates that the Channel faulted.

The value of this constant is `"channelFault"`.

The properties of the event object have the following values:

Property | Value
--- | ---
`bubbles` | false
`cancelable` | false
`channel` | The Channel that generated this event.
`currentTarget` | The Object that defines the event listener that handles the event. For example, if you use `myButton.addEventListener()` to register an event listener, myButton is the value of the `currentTarget`.
`faultCode` | Provides destination-specific details of the failure.
`faultDetail` | Provides access to the destination-specific reason for the failure.
`faultString` | Provides access to the underlying reason for the failure if the channel did not raise the failure itself.
`reconnecting` | Indicates whether the channel that generated this event is reconnecting.
`rootCause` | Provides access to the underlying reason for the failure if the channel did not raise the failure itself.
`target` | The Object that dispatched the event; it is not always the Object listening for the event. Use the `currentTarget` property to always access the Object listening for the event.

message | Event |

Event Object Type: `mx.messaging.events.MessageEvent`
MessageEvent.type property = `mx.messaging.events.MessageEvent.MESSAGE`

Language Version : | ActionScript 3.0

Product Versions : | BlazeDS 4, LCDS 3

Runtime Versions : | Flash Player 9, AIR 1.1

Dispatched when a channel receives a message from its endpoint.

The MESSAGE event type; dispatched upon receipt of a message.

The value of this constant is `"message"`.

The properties of the event object have the following values:

Property | Value
--- | ---
`bubbles` | false
`cancelable` | false
`currentTarget` | The Object that defines the event listener that handles the event. For example, if you use `myButton.addEventListener()` to register an event listener, myButton is the value of the `currentTarget`.
`message` | The message associated with this event.
`target` | The Object that dispatched the event; it is not always the Object listening for the event. Use the `currentTarget` property to always access the Object listening for the event.

propertyChange | Event |

Event Object Type: `mx.events.PropertyChangeEvent`
PropertyChangeEvent.type property = `mx.events.PropertyChangeEvent.PROPERTY_CHANGE`

Language Version : | ActionScript 3.0

Product Versions : | BlazeDS 4, LCDS 3

Runtime Versions : | Flash Player 9, AIR 1.1

Dispatched when a property of the channel changes.

The `PropertyChangeEvent.PROPERTY_CHANGE` constant defines the value of the `type` property of the event object for a `PropertyChange` event.

The properties of the event object have the following values:

Property | Value
--- | ---
`bubbles` | Determined by the constructor; defaults to false.
`cancelable` | Determined by the constructor; defaults to false.
`kind` | The kind of change; PropertyChangeEventKind.UPDATE or PropertyChangeEventKind.DELETE.
`oldValue` | The original property value.
`newValue` | The new property value, if any.
`property` | The property that changed.
`source` | The object that contains the property that changed.
`currentTarget` | The Object that defines the event listener that handles the event. For example, if you use `myButton.addEventListener()` to register an event listener, myButton is the value of the `currentTarget`.
`target` | The Object that dispatched the event; it is not always the Object listening for the event. Use the `currentTarget` property to always access the Object listening for the event.

Constant Detail

CONNECT_TIMEOUT_SECONDS | Constant

`protected static const CONNECT_TIMEOUT_SECONDS:String = connect-timeout-seconds`

ENABLE_SMALL_MESSAGES | Constant |

`protected static const ENABLE_SMALL_MESSAGES:String = enable-small-messages`

FALSE | Constant |

`protected static const FALSE:String = false`

RECORD_MESSAGE_SIZES | Constant |

`protected static const RECORD_MESSAGE_SIZES:String = record-message-sizes`

RECORD_MESSAGE_TIMES | Constant |

`protected static const RECORD_MESSAGE_TIMES:String = record-message-times`

REQUEST_TIMEOUT_SECONDS | Constant |

`protected static const REQUEST_TIMEOUT_SECONDS:String = request-timeout-seconds`

SERIALIZATION | Constant |

`protected static const SERIALIZATION:String = serialization`

TRUE | Constant |

`protected static const TRUE:String = true`

Sun Mar 5 2017, 03:42 PM +11:00