TileProviderError.js

define([
        './defaultValue',
        './defined',
        './formatError'
    ], function(
        defaultValue,
        defined,
        formatError) {
    'use strict';

    /**
     * Provides details about an error that occurred in an {@link ImageryProvider} or a {@link TerrainProvider}.
     *
     * @alias TileProviderError
     * @constructor
     *
     * @param {ImageryProvider|TerrainProvider} provider The imagery or terrain provider that experienced the error.
     * @param {String} message A message describing the error.
     * @param {Number} [x] The X coordinate of the tile that experienced the error, or undefined if the error
     *        is not specific to a particular tile.
     * @param {Number} [y] The Y coordinate of the tile that experienced the error, or undefined if the error
     *        is not specific to a particular tile.
     * @param {Number} [level] The level of the tile that experienced the error, or undefined if the error
     *        is not specific to a particular tile.
     * @param {Number} [timesRetried=0] The number of times this operation has been retried.
     * @param {Error} [error] The error or exception that occurred, if any.
     */
    function TileProviderError(provider, message, x, y, level, timesRetried, error) {
        /**
         * The {@link ImageryProvider} or {@link TerrainProvider} that experienced the error.
         * @type {ImageryProvider|TerrainProvider}
         */
        this.provider = provider;

        /**
         * The message describing the error.
         * @type {String}
         */
        this.message = message;

        /**
         * The X coordinate of the tile that experienced the error.  If the error is not specific
         * to a particular tile, this property will be undefined.
         * @type {Number}
         */
        this.x = x;

        /**
         * The Y coordinate of the tile that experienced the error.  If the error is not specific
         * to a particular tile, this property will be undefined.
         * @type {Number}
         */
        this.y = y;

        /**
         * The level-of-detail of the tile that experienced the error.  If the error is not specific
         * to a particular tile, this property will be undefined.
         * @type {Number}
         */
        this.level = level;

        /**
         * The number of times this operation has been retried.
         * @type {Number}
         * @default 0
         */
        this.timesRetried = defaultValue(timesRetried, 0);

        /**
         * True if the failed operation should be retried; otherwise, false.  The imagery or terrain provider
         * will set the initial value of this property before raising the event, but any listeners
         * can change it.  The value after the last listener is invoked will be acted upon.
         * @type {Boolean}
         * @default false
         */
        this.retry = false;

        /**
         * The error or exception that occurred, if any.
         * @type {Error}
         */
        this.error = error;
    }

    /**
     * Handles an error in an {@link ImageryProvider} or {@link TerrainProvider} by raising an event if it has any listeners, or by
     * logging the error to the console if the event has no listeners.  This method also tracks the number
     * of times the operation has been retried and will automatically retry if requested to do so by the
     * event listeners.
     *
     * @param {TileProviderError} previousError The error instance returned by this function the last
     *        time it was called for this error, or undefined if this is the first time this error has
     *        occurred.
     * @param {ImageryProvider|TerrainProvider} provider The imagery or terrain provider that encountered the error.
     * @param {Event} event The event to raise to inform listeners of the error.
     * @param {String} message The message describing the error.
     * @param {Number} x The X coordinate of the tile that experienced the error, or undefined if the
     *        error is not specific to a particular tile.
     * @param {Number} y The Y coordinate of the tile that experienced the error, or undefined if the
     *        error is not specific to a particular tile.
     * @param {Number} level The level-of-detail of the tile that experienced the error, or undefined if the
     *        error is not specific to a particular tile.
     * @param {TileProviderError~RetryFunction} retryFunction The function to call to retry the operation.  If undefined, the
     *        operation will not be retried.
     * @param {Error} [errorDetails] The error or exception that occurred, if any.
     * @returns {TileProviderError} The error instance that was passed to the event listeners and that
     *          should be passed to this function the next time it is called for the same error in order
     *          to track retry counts.
     */
    TileProviderError.handleError = function(previousError, provider, event, message, x, y, level, retryFunction, errorDetails) {
        var error = previousError;
        if (!defined(previousError)) {
            error = new TileProviderError(provider, message, x, y, level, 0, errorDetails);
        } else {
            error.provider = provider;
            error.message = message;
            error.x = x;
            error.y = y;
            error.level = level;
            error.retry = false;
            error.error = errorDetails;
            ++error.timesRetried;
        }

        if (event.numberOfListeners > 0) {
            event.raiseEvent(error);
        } else {
            console.log('An error occurred in "' + provider.constructor.name + '": ' + formatError(message));
        }

        if (error.retry && defined(retryFunction)) {
            retryFunction();
        }

        return error;
    };

    /**
     * Handles success of an operation by resetting the retry count of a previous error, if any.  This way,
     * if the error occurs again in the future, the listeners will be informed that it has not yet been retried.
     *
     * @param {TileProviderError} previousError The previous error, or undefined if this operation has
     *        not previously resulted in an error.
     */
    TileProviderError.handleSuccess = function(previousError) {
        if (defined(previousError)) {
            previousError.timesRetried = -1;
        }
    };

    /**
     * A function that will be called to retry the operation.
     * @callback TileProviderError~RetryFunction
     */

    return TileProviderError;
});