PageRenderTime 33ms CodeModel.GetById 5ms app.highlight 14ms RepoModel.GetById 1ms app.codeStats 0ms

/archesproject/arches/Media/js/ui_frameworks/ext-4.0.2a/src/core/src/lang/Error.js

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