PageRenderTime 5ms CodeModel.GetById 65ms app.highlight 12ms RepoModel.GetById 1ms app.codeStats 0ms

/examples/coffeeratings/public/coffeeratings-client/lib/extjs/src/lang/Error.js

https://bitbucket.org/rlora/rolando-js-webtrends-course
JavaScript | 349 lines | 100 code | 28 blank | 221 comment | 23 complexity | f3bb0751e8e10a232c0a250e103402d4 MD5 | raw file
  1/*
  2This file is part of Ext JS 4.2
  3
  4Copyright (c) 2011-2013 Sencha Inc
  5
  6Contact:  http://www.sencha.com/contact
  7
  8GNU General Public License Usage
  9This file may be used under the terms of the GNU General Public License version 3.0 as
 10published by the Free Software Foundation and appearing in the file LICENSE included in the
 11packaging of this file.
 12
 13Please review the following information to ensure the GNU General Public License version 3.0
 14requirements will be met: http://www.gnu.org/copyleft/gpl.html.
 15
 16If you are unsure which license is appropriate for your use, please contact the sales department
 17at http://www.sencha.com/contact.
 18
 19Build date: 2013-03-11 22:33:40 (aed16176e68b5e8aa1433452b12805c0ad913836)
 20*/
 21//@tag foundation,core
 22//@require ../class/Loader.js
 23
 24/**
 25 * @author Brian Moeskau <brian@sencha.com>
 26 * @docauthor Brian Moeskau <brian@sencha.com>
 27 *
 28 * A wrapper class for the native JavaScript Error object that adds a few useful capabilities for handling
 29 * errors in an Ext application. When you use Ext.Error to {@link #raise} an error from within any class that
 30 * uses the Ext 4 class system, the Error class can automatically add the source class and method from which
 31 * the error was raised. It also includes logic to automatically log the error to the console, if available,
 32 * with additional metadata about the error. In all cases, the error will always be thrown at the end so that
 33 * execution will halt.
 34 *
 35 * Ext.Error also offers a global error {@link #handle handling} method that can be overridden in order to
 36 * handle application-wide errors in a single spot. You can optionally {@link #ignore} errors altogether,
 37 * although in a real application it's usually a better idea to override the handling function and perform
 38 * logging or some other method of reporting the errors in a way that is meaningful to the application.
 39 *
 40 * At its simplest you can simply raise an error as a simple string from within any code:
 41 *
 42 * Example usage:
 43 *
 44 *     Ext.Error.raise('Something bad happened!');
 45 *
 46 * If raised from plain JavaScript code, the error will be logged to the console (if available) and the message
 47 * displayed. In most cases however you'll be raising errors from within a class, and it may often be useful to add
 48 * additional metadata about the error being raised.  The {@link #raise} method can also take a config object.
 49 * In this form the `msg` attribute becomes the error description, and any other data added to the config gets
 50 * added to the error object and, if the console is available, logged to the console for inspection.
 51 *
 52 * Example usage:
 53 *
 54 *     Ext.define('Ext.Foo', {
 55 *         doSomething: function(option){
 56 *             if (someCondition === false) {
 57 *                 Ext.Error.raise({
 58 *                     msg: 'You cannot do that!',
 59 *                     option: option,   // whatever was passed into the method
 60 *                     'error code': 100 // other arbitrary info
 61 *                 });
 62 *             }
 63 *         }
 64 *     });
 65 *
 66 * If a console is available (that supports the `console.dir` function) you'll see console output like:
 67 *
 68 *     An error was raised with the following data:
 69 *     option:         Object { foo: "bar"}
 70 *         foo:        "bar"
 71 *     error code:     100
 72 *     msg:            "You cannot do that!"
 73 *     sourceClass:   "Ext.Foo"
 74 *     sourceMethod:  "doSomething"
 75 *
 76 *     uncaught exception: You cannot do that!
 77 *
 78 * As you can see, the error will report exactly where it was raised and will include as much information as the
 79 * raising code can usefully provide.
 80 *
 81 * If you want to handle all application errors globally you can simply override the static {@link #handle} method
 82 * and provide whatever handling logic you need. If the method returns true then the error is considered handled
 83 * and will not be thrown to the browser. If anything but true is returned then the error will be thrown normally.
 84 *
 85 * Example usage:
 86 *
 87 *     Ext.Error.handle = function(err) {
 88 *         if (err.someProperty == 'NotReallyAnError') {
 89 *             // maybe log something to the application here if applicable
 90 *             return true;
 91 *         }
 92 *         // any non-true return value (including none) will cause the error to be thrown
 93 *     }
 94 *
 95 */
 96Ext.Error = Ext.extend(Error, {
 97    statics: {
 98        /**
 99         * @property {Boolean} ignore
100         * Static flag that can be used to globally disable error reporting to the browser if set to true
101         * (defaults to false). Note that if you ignore Ext errors it's likely that some other code may fail
102         * and throw a native JavaScript error thereafter, so use with caution. In most cases it will probably
103         * be preferable to supply a custom error {@link #handle handling} function instead.
104         *
105         * Example usage:
106         *
107         *     Ext.Error.ignore = true;
108         *
109         * @static
110         */
111        ignore: false,
112
113        /**
114         * @property {Boolean} notify
115         * Static flag that can be used to globally control error notification to the user. Unlike
116         * Ex.Error.ignore, this does not effect exceptions. They are still thrown. This value can be
117         * set to false to disable the alert notification (default is true for IE6 and IE7).
118         *
119         * Only the first error will generate an alert. Internally this flag is set to false when the
120         * first error occurs prior to displaying the alert.
121         *
122         * This flag is not used in a release build.
123         *
124         * Example usage:
125         *
126         *     Ext.Error.notify = false;
127         *
128         * @static
129         */
130        //notify: Ext.isIE6 || Ext.isIE7,
131
132        /**
133         * Raise an error that can include additional data and supports automatic console logging if available.
134         * You can pass a string error message or an object with the `msg` attribute which will be used as the
135         * error message. The object can contain any other name-value attributes (or objects) to be logged
136         * along with the error.
137         *
138         * Note that after displaying the error message a JavaScript error will ultimately be thrown so that
139         * execution will halt.
140         *
141         * Example usage:
142         *
143         *     Ext.Error.raise('A simple string error message');
144         *
145         *     // or...
146         *
147         *     Ext.define('Ext.Foo', {
148         *         doSomething: function(option){
149         *             if (someCondition === false) {
150         *                 Ext.Error.raise({
151         *                     msg: 'You cannot do that!',
152         *                     option: option,   // whatever was passed into the method
153         *                     'error code': 100 // other arbitrary info
154         *                 });
155         *             }
156         *         }
157         *     });
158         *
159         * @param {String/Object} err The error message string, or an object containing the attribute "msg" that will be
160         * used as the error message. Any other data included in the object will also be logged to the browser console,
161         * if available.
162         * @static
163         */
164        raise: function(err){
165            err = err || {};
166            if (Ext.isString(err)) {
167                err = { msg: err };
168            }
169
170            var method = this.raise.caller,
171                msg;
172
173            if (method) {
174                if (method.$name) {
175                    err.sourceMethod = method.$name;
176                }
177                if (method.$owner) {
178                    err.sourceClass = method.$owner.$className;
179                }
180            }
181
182            if (Ext.Error.handle(err) !== true) {
183                msg = Ext.Error.prototype.toString.call(err);
184
185                Ext.log({
186                    msg: msg,
187                    level: 'error',
188                    dump: err,
189                    stack: true
190                });
191
192                throw new Ext.Error(err);
193            }
194        },
195
196        /**
197         * Globally handle any Ext errors that may be raised, optionally providing custom logic to
198         * handle different errors individually. Return true from the function to bypass throwing the
199         * error to the browser, otherwise the error will be thrown and execution will halt.
200         *
201         * Example usage:
202         *
203         *     Ext.Error.handle = function(err) {
204         *         if (err.someProperty == 'NotReallyAnError') {
205         *             // maybe log something to the application here if applicable
206         *             return true;
207         *         }
208         *         // any non-true return value (including none) will cause the error to be thrown
209         *     }
210         *
211         * @param {Ext.Error} err The Ext.Error object being raised. It will contain any attributes that were originally
212         * raised with it, plus properties about the method and class from which the error originated (if raised from a
213         * class that uses the Ext 4 class system).
214         * @static
215         */
216        handle: function(){
217            return Ext.Error.ignore;
218        }
219    },
220
221    // This is the standard property that is the name of the constructor.
222    name: 'Ext.Error',
223
224    /**
225     * Creates new Error object.
226     * @param {String/Object} config The error message string, or an object containing the
227     * attribute "msg" that will be used as the error message. Any other data included in
228     * the object will be applied to the error instance and logged to the browser console, if available.
229     */
230    constructor: function(config){
231        if (Ext.isString(config)) {
232            config = { msg: config };
233        }
234
235        var me = this;
236
237        Ext.apply(me, config);
238
239        me.message = me.message || me.msg; // 'message' is standard ('msg' is non-standard)
240        // note: the above does not work in old WebKit (me.message is readonly) (Safari 4)
241    },
242
243    /**
244     * Provides a custom string representation of the error object. This is an override of the base JavaScript
245     * `Object.toString` method, which is useful so that when logged to the browser console, an error object will
246     * be displayed with a useful message instead of `[object Object]`, the default `toString` result.
247     *
248     * The default implementation will include the error message along with the raising class and method, if available,
249     * but this can be overridden with a custom implementation either at the prototype level (for all errors) or on
250     * a particular error instance, if you want to provide a custom description that will show up in the console.
251     * @return {String} The error message. If raised from within the Ext 4 class system, the error message will also
252     * include the raising class and method names, if available.
253     */
254    toString: function(){
255        var me = this,
256            className = me.sourceClass ? me.sourceClass : '',
257            methodName = me.sourceMethod ? '.' + me.sourceMethod + '(): ' : '',
258            msg = me.msg || '(No description provided)';
259
260        return className + methodName + msg;
261    }
262});
263
264/*
265 * Create a function that will throw an error if called (in debug mode) with a message that
266 * indicates the method has been removed.
267 * @param {String} suggestion Optional text to include in the message (a workaround perhaps).
268 * @return {Function} The generated function.
269 * @private
270 */
271Ext.deprecated = function (suggestion) {
272    //<debug>
273    if (!suggestion) {
274        suggestion = '';
275    }
276
277    function fail () {
278        Ext.Error.raise('The method "' + fail.$owner.$className + '.' + fail.$name + 
279                '" has been removed. ' + suggestion);
280    }
281
282    return fail;
283    //</debug>
284    return Ext.emptyFn;
285};
286
287/*
288 * This mechanism is used to notify the user of the first error encountered on the page. This
289 * was previously internal to Ext.Error.raise and is a desirable feature since errors often
290 * slip silently under the radar. It cannot live in Ext.Error.raise since there are times
291 * where exceptions are handled in a try/catch.
292 */
293//<debug>
294(function () {
295    var timer, errors = 0,
296        win = Ext.global,
297        msg;
298
299    if (typeof window === 'undefined') {
300        return; // build system or some such environment...
301    }
302
303    // This method is called to notify the user of the current error status.
304    function notify () {
305        var counters = Ext.log.counters,
306            supports = Ext.supports,
307            hasOnError = supports && supports.WindowOnError; // TODO - timing
308
309        // Put log counters to the status bar (for most browsers):
310        if (counters && (counters.error + counters.warn + counters.info + counters.log)) {
311            msg = [ 'Logged Errors:',counters.error, 'Warnings:',counters.warn,
312                        'Info:',counters.info, 'Log:',counters.log].join(' ');
313            if (errors) {
314                msg = '*** Errors: ' + errors + ' - ' + msg;
315            } else if (counters.error) {
316                msg = '*** ' + msg;
317            }
318            win.status = msg;
319        }
320
321        // Display an alert on the first error:
322        if (!Ext.isDefined(Ext.Error.notify)) {
323            Ext.Error.notify = Ext.isIE6 || Ext.isIE7; // TODO - timing
324        }
325        if (Ext.Error.notify && (hasOnError ? errors : (counters && counters.error))) {
326            Ext.Error.notify = false;
327
328            if (timer) {
329                win.clearInterval(timer); // ticks can queue up so stop...
330                timer = null;
331            }
332
333            alert('Unhandled error on page: See console or log');
334            poll();
335        }
336    }
337
338    // Sets up polling loop. This is the only way to know about errors in some browsers
339    // (Opera/Safari) and is the only way to update the status bar for warnings and other
340    // non-errors.
341    function poll () {
342        timer = win.setInterval(notify, 1000);
343    }
344
345    // window.onerror sounds ideal but it prevents the built-in error dialog from doing
346    // its (better) thing.
347    poll();
348}());
349//</debug>