mx.messaging.Channel - Adobe® Flex® 4 Language Reference (Flex 4)

Package	mx.messaging
Class	public class Channel
Inheritance	Channel EventDispatcher Object
Implements	IMXMLObject
Subclasses	PollingChannel

Language Version:

ActionScript 3.0

Product Versions:

BlazeDS 4, LiveCycle Data Services 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

Hide Inherited Public Properties

Show Inherited 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
		constructor : Object A reference to the class object or constructor function for a given object instance.	Object
		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
		prototype : Object [static] A reference to the prototype object of a class or function object.	Object
		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

Hide Inherited Public Methods

Show Inherited 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
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.	EventDispatcher
		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
		dispatchEvent(event:Event):Boolean Dispatches an event into the event flow.	EventDispatcher
		hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event.	EventDispatcher
		hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined.	Object
		isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.	Object
		logout(agent:MessageAgent):void Sends a CommandMessage to the server to logout if the Channel is connected.	Channel
		propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable.	Object
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object.	EventDispatcher
		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
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations.	Object
		toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions.	Object
		toString():String Returns the string representation of the specified object.	Object
		valueOf():Object Returns the primitive value of the specified object.	Object
		willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.	EventDispatcher

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:flash.events: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

Click for more information on events

Hide Inherited Events

Show Inherited Events

	Summary	Defined By
activate	[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.	EventDispatcher
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
deactivate	[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.	EventDispatcher
message	Dispatched when a channel receives a message from its endpoint.	Channel
propertyChange	Dispatched when a property of the channel changes.	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. When this property is modified, it dispatches the propertyChange event.

Implementation
public function get authenticated():Boolean

channelSets

property

channelSets:Array [read-only]

Language Version:

ActionScript 3.0

Product Versions:

BlazeDS 4, LiveCycle Data Services 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, LiveCycle Data Services 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. When this property is modified, it dispatches the propertyChange event.

Implementation
public function get connected():Boolean

connectTimeout

property

connectTimeout:int

Language Version:

ActionScript 3.0

Product Versions:

BlazeDS 4, LiveCycle Data Services 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. When this property is modified, it dispatches the propertyChange event.

Implementation
public function get reconnecting():Boolean

recordMessageSizes

property

recordMessageSizes:Boolean [read-only]

Language Version:

ActionScript 3.0

Product Versions:

BlazeDS 4, LiveCycle Data Services 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, LiveCycle Data Services 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, LiveCycle Data Services 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:flash.events: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:flash.events: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

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

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
property ChannelEvent.type = 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
property ChannelEvent.type = mx.messaging.events.ChannelEvent.DISCONNECT

Language Version:

ActionScript 3.0

Product Versions:

BlazeDS 4, LiveCycle Data Services 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
property ChannelFaultEvent.type = mx.messaging.events.ChannelFaultEvent.FAULT

Language Version:

ActionScript 3.0

Product Versions:

BlazeDS 4, LiveCycle Data Services 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
property MessageEvent.type = mx.messaging.events.MessageEvent.MESSAGE

Language Version:

ActionScript 3.0

Product Versions:

BlazeDS 4, LiveCycle Data Services 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
property PropertyChangeEvent.type = mx.events.PropertyChangeEvent.PROPERTY_CHANGE

Language Version:

ActionScript 3.0

Product Versions:

BlazeDS 4, LiveCycle Data Services 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.