/ext-4.1.0_b3/docs/source/Error.html

https://bitbucket.org/srogerf/javascript · HTML · 344 lines · 317 code · 27 blank · 0 comment · 0 complexity · 329b5098a62139190caa793028291805 MD5 · raw file

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