add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / lang / Error.js

/**\r
 * A helper class for the native JavaScript Error object that adds a few useful capabilities for handling\r
 * errors in an application. When you use Ext.Error to {@link #raise} an error from within any class that\r
 * uses the Class System, the Error class can automatically add the source class and method from which\r
 * the error was raised. It also includes logic to automatically log the error to the console, if available,\r
 * with additional metadata about the error. In all cases, the error will always be thrown at the end so that\r
 * execution will halt.\r
 *\r
 * Ext.Error also offers a global error {@link #handle handling} method that can be overridden in order to\r
 * handle application-wide errors in a single spot. You can optionally {@link #ignore} errors altogether,\r
 * although in a real application it's usually a better idea to override the handling function and perform\r
 * logging or some other method of reporting the errors in a way that is meaningful to the application.\r
 *\r
 * At its simplest you can simply raise an error as a simple string from within any code:\r
 *\r
 * Example usage:\r
 *\r
 *     Ext.raise('Something bad happened!');\r
 *\r
 * If raised from plain JavaScript code, the error will be logged to the console (if available) and the message\r
 * displayed. In most cases however you'll be raising errors from within a class, and it may often be useful to add\r
 * additional metadata about the error being raised.  The {@link #raise} method can also take a config object.\r
 * In this form the `msg` attribute becomes the error description, and any other data added to the config gets\r
 * added to the error object and, if the console is available, logged to the console for inspection.\r
 *\r
 * Example usage:\r
 *\r
 *     Ext.define('Ext.Foo', {\r
 *         doSomething: function(option){\r
 *             if (someCondition === false) {\r
 *                 Ext.raise({\r
 *                     msg: 'You cannot do that!',\r
 *                     option: option,   // whatever was passed into the method\r
 *                     'error code': 100 // other arbitrary info\r
 *                 });\r
 *             }\r
 *         }\r
 *     });\r
 *\r
 * If a console is available (that supports the `console.dir` function) you'll see console output like:\r
 *\r
 *     An error was raised with the following data:\r
 *     option:         Object { foo: "bar"}\r
 *         foo:        "bar"\r
 *     error code:     100\r
 *     msg:            "You cannot do that!"\r
 *     sourceClass:   "Ext.Foo"\r
 *     sourceMethod:  "doSomething"\r
 *\r
 *     uncaught exception: You cannot do that!\r
 *\r
 * As you can see, the error will report exactly where it was raised and will include as much information as the\r
 * raising code can usefully provide.\r
 *\r
 * If you want to handle all application errors globally you can simply override the static {@link #handle} method\r
 * and provide whatever handling logic you need. If the method returns true then the error is considered handled\r
 * and will not be thrown to the browser. If anything but true is returned then the error will be thrown normally.\r
 *\r
 * Example usage:\r
 *\r
 *     Ext.Error.handle = function(err) {\r
 *         if (err.someProperty == 'NotReallyAnError') {\r
 *             // maybe log something to the application here if applicable\r
 *             return true;\r
 *         }\r
 *         // any non-true return value (including none) will cause the error to be thrown\r
 *     }\r
 *\r
 * @class Ext.Error\r
 */\r
(function() {\r
// @define Ext.lang.Error\r
// @define Ext.Error\r
// @require Ext\r
\r
    function toString() {\r
        var me = this,\r
            cls = me.sourceClass,\r
            method = me.sourceMethod,\r
            msg = me.msg;\r
\r
        if (method) {\r
            if (msg) {\r
                method += '(): ';\r
                method += msg;\r
            } else {\r
                method += '()';\r
            }\r
        }\r
\r
        if (cls) {\r
            method = method ? (cls + '.' + method) : cls;\r
        }\r
        \r
        return method || msg || '';\r
    }\r
\r
    Ext.Error = function(config) {\r
        if (Ext.isString(config)) {\r
            config = { msg: config };\r
        }\r
\r
        var error = new Error();\r
\r
        Ext.apply(error, config);\r
\r
        error.message = error.message || error.msg; // 'message' is standard ('msg' is non-standard)\r
        // note: the above does not work in old WebKit (me.message is readonly) (Safari 4)\r
\r
        error.toString = toString;\r
\r
        return error;\r
    };\r
\r
    Ext.apply(Ext.Error, {\r
        /**\r
         * @property {Boolean} ignore\r
         * Static flag that can be used to globally disable error reporting to the browser if set to true\r
         * (defaults to false). Note that if you ignore Ext errors it's likely that some other code may fail\r
         * and throw a native JavaScript error thereafter, so use with caution. In most cases it will probably\r
         * be preferable to supply a custom error {@link #handle handling} function instead.\r
         *\r
         * Example usage:\r
         *\r
         *     Ext.Error.ignore = true;\r
         *\r
         * @static\r
         */\r
        ignore: false,\r
\r
        /**\r
         * This method is called internally by {@link Ext#raise}. Application code should\r
         * call {@link Ext#raise} instead of calling this method directly.\r
         *\r
         * @static\r
         * @deprecated 6.0.0 Use {@link Ext#raise} instead.\r
         */\r
        raise: function(err) {\r
            err = err || {};\r
            if (Ext.isString(err)) {\r
                err = { msg: err };\r
            }\r
\r
            var me = this,\r
                method = me.raise.caller,\r
                msg, name;\r
\r
            if (method === Ext.raise) {\r
                method = method.caller;\r
            }\r
            if (method) {\r
                if (!err.sourceMethod && (name = method.$name)) {\r
                    err.sourceMethod = name;\r
                }\r
                if (!err.sourceClass && (name = method.$owner) && (name = name.$className)) {\r
                    err.sourceClass = name;\r
                }\r
            }\r
\r
            if (me.handle(err) !== true) {\r
                msg = toString.call(err);\r
\r
                //<debug>\r
                Ext.log({\r
                    msg: msg,\r
                    level: 'error',\r
                    dump: err,\r
                    stack: true\r
                });\r
                //</debug>\r
\r
                throw new Ext.Error(err);\r
            }\r
        },\r
\r
        /**\r
         * Globally handle any Ext errors that may be raised, optionally providing custom logic to\r
         * handle different errors individually. Return true from the function to bypass throwing the\r
         * error to the browser, otherwise the error will be thrown and execution will halt.\r
         *\r
         * Example usage:\r
         *\r
         *     Ext.Error.handle = function(err) {\r
         *         if (err.someProperty == 'NotReallyAnError') {\r
         *             // maybe log something to the application here if applicable\r
         *             return true;\r
         *         }\r
         *         // any non-true return value (including none) will cause the error to be thrown\r
         *     }\r
         *\r
         * @param {Object} err The error being raised. It will contain any attributes that were originally\r
         * raised with it, plus properties about the method and class from which the error originated\r
         * (if raised from a class that uses the Class System).\r
         * @static\r
         */\r
        handle: function () {\r
            return this.ignore;\r
        }\r
    });\r
})();\r
\r
/**\r
 * Create a function that will throw an error if called (in debug mode) with a message that\r
 * indicates the method has been removed.\r
 * @param {String} suggestion Optional text to include in the message (a workaround perhaps).\r
 * @return {Function} The generated function.\r
 * @private\r
 */\r
Ext.deprecated = function (suggestion) {\r
    //<debug>\r
    if (!suggestion) {\r
        suggestion = '';\r
    }\r
\r
    function fail () {\r
        Ext.raise('The method "' + fail.$owner.$className + '.' + fail.$name +\r
                  '" has been removed. ' + suggestion);\r
    }\r
\r
    return fail;\r
    //</debug>\r
    return Ext.emptyFn;\r
};\r
\r
/**\r
 * Raise an error that can include additional data and supports automatic console logging\r
 * if available. You can pass a string error message or an object with the `msg` attribute\r
 * which will be used as the error message. The object can contain any other name-value\r
 * attributes (or objects) to be logged along with the error.\r
 *\r
 * Note that after displaying the error message a JavaScript error will ultimately be\r
 * thrown so that execution will halt.\r
 *\r
 * Example usage:\r
 *\r
 *     Ext.raise('A simple string error message');\r
 *\r
 *     // or...\r
 *\r
 *     Ext.define('Ext.Foo', {\r
 *         doSomething: function(option){\r
 *             if (someCondition === false) {\r
 *                 Ext.raise({\r
 *                     msg: 'You cannot do that!',\r
 *                     option: option,   // whatever was passed into the method\r
 *                     code: 100 // other arbitrary info\r
 *                 });\r
 *             }\r
 *         }\r
 *     });\r
 *\r
 * @param {String/Object} err The error message string, or an object containing the\r
 * attribute "msg" that will be used as the error message. Any other data included in the\r
 * object will also be logged to the browser console, if available.\r
 * @method raise\r
 * @member Ext\r
 */\r
Ext.raise = function () {\r
    Ext.Error.raise.apply(Ext.Error, arguments);\r
};\r
\r
/*\r
 * This mechanism is used to notify the user of the first error encountered on the page. In\r
 * most cases errors go unobserved especially on IE. This mechanism pushes this information\r
 * to the status bar so that users don't miss it.\r
 */\r
//<debug>\r
(function () {\r
    if (typeof window === 'undefined') {\r
        return; // build system or some such environment...\r
    }\r
\r
    var last = 0,\r
        // This method is called to notify the user of the current error status.\r
        notify = function() {\r
            var cnt = Ext.log && Ext.log.counters,\r
                n = cnt && (cnt.error + cnt.warn + cnt.info + cnt.log),\r
                msg;\r
\r
            // Put log counters to the status bar (for most browsers):\r
            if (n && last !== n) {\r
                msg = [];\r
                if (cnt.error) {\r
                    msg.push('Errors: ' + cnt.error);\r
                }\r
                if (cnt.warn) {\r
                    msg.push('Warnings: ' + cnt.warn);\r
                }\r
                if (cnt.info) {\r
                    msg.push('Info: ' + cnt.info);\r
                }\r
                if (cnt.log) {\r
                    msg.push('Log: ' + cnt.log);\r
                }\r
                window.status = '*** ' + msg.join(' -- ');\r
                last = n;\r
            }\r
        };\r
\r
    // window.onerror sounds ideal but it prevents the built-in error dialog from doing\r
    // its (better) thing.\r
    setInterval(notify, 1000);\r
}());\r
//</debug>\r