1////////////////////////////////////////////////////////////////////////////////
2//
3//  ADOBE SYSTEMS INCORPORATED
4//  Copyright 2005-2007 Adobe Systems Incorporated
5//  All Rights Reserved.
6//
7//  NOTICE: Adobe permits you to use, modify, and distribute this file
8//  in accordance with the terms of the license agreement accompanying it.
9//
10////////////////////////////////////////////////////////////////////////////////
11
12package mx.messaging.events
13{
14
15import flash.events.Event;
16import mx.messaging.Channel;
17
18/**
19 *  The ChannelEvent is used to propagate channel events within the messaging system.
20 *
21 *  @langversion 3.0
22 *  @playerversion Flash 9
23 *  @playerversion AIR 1.1
24 *  @productversion BlazeDS 4
25 *  @productversion LCDS 3
26 */
27public class ChannelEvent extends Event
28{
29    //--------------------------------------------------------------------------
30    //
31    // Static Constants
32    //
33    //--------------------------------------------------------------------------
34
35    /**
36     *  The CONNECT event type; indicates that the Channel connected to its
37     *  endpoint.
38     *  <p>The value of this constant is <code>"channelConnect"</code>.</p>
39     *
40     *  <p>The properties of the event object have the following values:</p>
41     *  <table class="innertable">
42     *     <tr><th>Property</th><th>Value</th></tr>
43     *     <tr><td><code>bubbles</code></td><td>false</td></tr>
44     *     <tr><td><code>cancelable</code></td><td>false</td></tr>
45     *     <tr><td><code>channel</code></td><td>The channel that generated this event.</td></tr>
46     *     <tr><td><code>currentTarget</code></td><td>The Object that defines the
47     *       event listener that handles the event. For example, if you use
48     *       <code>myButton.addEventListener()</code> to register an event listener,
49     *       myButton is the value of the <code>currentTarget</code>. </td></tr>
50     *     <tr><td><code>target</code></td><td>The Object that dispatched the event;
51     *       it is not always the Object listening for the event.
52     *       Use the <code>currentTarget</code> property to always access the
53     *       Object listening for the event.</td></tr>
54     *     <tr><td><code>reconnecting</code></td><td> Indicates whether the channel
55     *       that generated this event is reconnecting.</td></tr>
56     *     <tr><td><code>rejected</code></td><td> Indicates whether the channel that
57     *       generated this event was rejected. This would be true in the event that
58     *       the channel has been disconnected due to inactivity and should not attempt to
59     *       failover or connect on an alternate channel.</td></tr>
60     *  </table>
61     *  @eventType channelConnect
62     *
63     *  @langversion 3.0
64     *  @playerversion Flash 9
65     *  @playerversion AIR 1.1
66     *  @productversion BlazeDS 4
67     *  @productversion LCDS 3
68     */
69    public static const CONNECT:String = "channelConnect";
70
71    /**
72     *  The DISCONNECT event type; indicates that the Channel disconnected from its
73     *  endpoint.
74     *  <p>The value of this constant is <code>"channelDisconnect"</code>.</p>
75     *
76     *  <p>The properties of the event object have the following values:</p>
77     *  <table class="innertable">
78     *     <tr><th>Property</th><th>Value</th></tr>
79     *     <tr><td><code>bubbles</code></td><td>false</td></tr>
80     *     <tr><td><code>cancelable</code></td><td>false</td></tr>
81     *     <tr><td><code>channel</code></td><td>The channel that generated this event.</td></tr>
82     *     <tr><td><code>currentTarget</code></td><td>The Object that defines the
83     *       event listener that handles the event. For example, if you use
84     *       <code>myButton.addEventListener()</code> to register an event listener,
85     *       myButton is the value of the <code>currentTarget</code>. </td></tr>
86     *     <tr><td><code>target</code></td><td>The Object that dispatched the event;
87     *       it is not always the Object listening for the event.
88     *       Use the <code>currentTarget</code> property to always access the
89     *       Object listening for the event.</td></tr>
90     *     <tr><td><code>reconnecting</code></td><td> Indicates whether the channel
91     *       that generated this event is reconnecting.</td></tr>
92     *     <tr><td><code>rejected</code></td><td> Indicates whether the channel that
93     *       generated this event was rejected. This would be true in the event that
94     *       the channel has been disconnected due to inactivity and should not attempt to
95     *       failover or connect on an alternate channel.</td></tr>
96     *  </table>
97     *  @eventType channelDisconnect
98     *
99     *  @langversion 3.0
100     *  @playerversion Flash 9
101     *  @playerversion AIR 1.1
102     *  @productversion BlazeDS 4
103     *  @productversion LCDS 3
104     */
105    public static const DISCONNECT:String = "channelDisconnect";
106
107    //--------------------------------------------------------------------------
108    //
109    // Static Methods
110    //
111    //--------------------------------------------------------------------------
112
113    /**
114     *  Utility method to create a new ChannelEvent that doesn't bubble and
115     *  is not cancelable.
116     *
117     *  @param type The ChannelEvent type.
118     *
119     *  @param channel The Channel generating the event.
120     *
121     *  @param reconnecting Indicates whether the Channel is in the process of
122     *  reconnecting or not.
123     *
124     *  @param rejected Indicates whether the Channel's connection has been rejected,
125     *  which suppresses automatic reconnection.
126     *
127     *  @param connected Indicates whether the Channel that generated this event
128     *  is already connected.
129     *
130     *  @return New ChannelEvent.
131     *
132     *  @langversion 3.0
133     *  @playerversion Flash 9
134     *  @playerversion AIR 1.1
135     *  @productversion BlazeDS 4
136     *  @productversion LCDS 3
137     */
138    public static function createEvent(type:String, channel:Channel = null,
139            reconnecting:Boolean = false, rejected:Boolean = false, connected:Boolean = false):ChannelEvent
140    {
141        return new ChannelEvent(type, false, false, channel, reconnecting, rejected, connected);
142    }
143
144    //--------------------------------------------------------------------------
145    //
146    // Constructor
147    //
148    //--------------------------------------------------------------------------
149
150    /**
151     *  Constructs an instance of this event with the specified type and Channel
152     *  instance.
153     *
154     *  @param type The ChannelEvent type.
155     *
156     *  @param bubbles Specifies whether the event can bubble up the display
157     *  list hierarchy.
158     *
159     *  @param cancelable Indicates whether the behavior associated with the
160     *  event can be prevented; used by the RPC subclasses.
161     *
162     *  @param channel The Channel generating the event.
163     *
164     *  @param reconnecting Indicates whether the Channel is in the process of
165     *  reconnecting or not.
166     *
167     *  @param rejected Indicates whether the Channel's connection has been rejected,
168     *  which suppresses automatic reconnection.
169     *
170     *  @param connected Indicates whether the Channel that generated this event
171     *  is already connected.
172     *
173     *  @langversion 3.0
174     *  @playerversion Flash 9
175     *  @playerversion AIR 1.1
176     *  @productversion BlazeDS 4
177     *  @productversion LCDS 3
178     */
179    public function ChannelEvent(type:String, bubbles:Boolean = false, cancelable:Boolean = false,
180            channel:Channel = null, reconnecting:Boolean = false, rejected:Boolean = false,
181            connected:Boolean = false)
182    {
183        super(type, bubbles, cancelable);
184
185        this.channel = channel;
186        this.reconnecting = reconnecting;
187        this.rejected = rejected;
188        this.connected = connected;
189    }
190
191    //--------------------------------------------------------------------------
192    //
193    // Variables
194    //
195    //--------------------------------------------------------------------------
196
197    /**
198     *  The Channel that generated this event.
199     *
200     *  @langversion 3.0
201     *  @playerversion Flash 9
202     *  @playerversion AIR 1.1
203     *  @productversion BlazeDS 4
204     *  @productversion LCDS 3
205     */
206    public var channel:Channel;
207
208    /**
209     * Indicates whether the Channel that generated this event is already connected.
210     *
211     *  @langversion 3.0
212     *  @playerversion Flash 9
213     *  @playerversion AIR 1.1
214     *  @productversion BlazeDS 4
215     *  @productversion LCDS 3
216     */
217    public var connected:Boolean;
218
219    /**
220     *  Indicates whether the Channel that generated this event is reconnecting.
221     *
222     *  @langversion 3.0
223     *  @playerversion Flash 9
224     *  @playerversion AIR 1.1
225     *  @productversion BlazeDS 4
226     *  @productversion LCDS 3
227     */
228    public var reconnecting:Boolean;
229
230    /**
231     *  Indicates whether the Channel that generated this event was rejected.
232     *  This would be true in the event that the channel has been
233     *  disconnected due to inactivity and should not attempt to failover or
234     *  connect on an alternate channel.
235     *
236     *  @langversion 3.0
237     *  @playerversion Flash 9
238     *  @playerversion AIR 1.1
239     *  @productversion BlazeDS 4
240     *  @productversion LCDS 3
241     */
242    public var rejected:Boolean;
243
244    //--------------------------------------------------------------------------
245    //
246    // Properties
247    //
248    //--------------------------------------------------------------------------
249
250	//----------------------------------
251	//  channelId
252	//----------------------------------
253
254    /**
255     * @private
256     */
257    public function get channelId():String
258    {
259        if (channel != null)
260        {
261            return channel.id;
262        }
263        return null;
264    }
265
266    //--------------------------------------------------------------------------
267    //
268    // Overridden Methods
269    //
270    //--------------------------------------------------------------------------
271
272    /**
273     *  Clones the ChannelEvent.
274     *
275     *  @return Copy of this ChannelEvent.
276     *
277     *  @langversion 3.0
278     *  @playerversion Flash 9
279     *  @playerversion AIR 1.1
280     *  @productversion BlazeDS 4
281     *  @productversion LCDS 3
282     */
283    override public function clone():Event
284    {
285        return new ChannelEvent(type, bubbles, cancelable, channel, reconnecting, rejected, connected);
286    }
287
288    /**
289     *  Returns a string representation of the ChannelEvent.
290     *
291     *  @return String representation of the ChannelEvent.
292     *
293     *  @langversion 3.0
294     *  @playerversion Flash 9
295     *  @playerversion AIR 1.1
296     *  @productversion BlazeDS 4
297     *  @productversion LCDS 3
298     */
299    override public function toString():String
300    {
301        return formatToString("ChannelEvent", "channelId", "reconnecting", "rejected", "type", "bubbles", "cancelable", "eventPhase");
302    }
303}
304
305}