fromErrorEvents

Creates an Observable sequence from any of several error event values of an IEventDispatcher.

static function fromErrorEvent(dispatcher : IEventDispatcher, eventNames : Array, 
    useCapture : Boolean = false, priority : int = 0, errorMap : Function = null) : IObservable.<*>

The useCapture and priority arguments will be used when adding an event listener to dispatcher.

If supplied, errorMap has the signature: function (event : Event) : Error

Remarks

The event listeners will be added when a subscription starts and removed if the subscription is cancelled.

fromErrorEvents is usually merged with another sequence that provides success values. For example urlLoader merges events (like IOErrorEvent and SecurityEvent) using fromErrorEvents with successful values triggered by Event.COMPLETE.

If errorMap if supplied, it will be used to map Event values to Error values before being thrown. Otherwise, the default error map will be used, which supports mapping ErrorEvent, IOErrorEvent and SecurityErrorEvent to Error, IOError and SecurityError, respectively.

The returned sequence does not complete

The returned sequence errors when any of the subscribed events are dispatched.

Marble Diagrams

"error"          ────
"io_error"       ────o
"security error" ────|
                     │
output           ────x/

Return Value

IObservable.<*>

Examples

/*
 * NOTE: Observable.urlLoader should be used to load content (rather than this example)
 * as it supports cancellation, multiple error types and throttling concurrent requests
 */

var loader : URLLoader = new URLLoader();

var errors : IObservable = Observable.fromErrorEvents(loader, [IOError.IO_ERROR, SecurityError.SECURITY_ERROR]);

var success : IObservable = Observable.fromEvent(loader, Error.COMPLETE)
    .take(1) // We should complete after the first success event
    .map(function(ev:Event) : Object { return loader.data; });

var dataOrError : IObservable = success.merge(errors);

dataOrError.subscribe(
    function(data : Object) : void { trace("Data successfully loaded"); },
    null,
    function(error : Error) : void { trace("An error occurred: " + error.message); }
    );

// Out will either be:
// Data successfully loaded (if successful)
// or
// An error occurred: <error message> (if unsuccessful)