ASP.NET AJAX Programmer’s Reference - Chapter 3 doc

Built-In and Custom Exception Types The previous chapter discussed two important ASP.NET AJAX JavaScript Error type extension functions named create and popStackFrame . This chapter shows you how the ASP.NET AJAX client-side script framework uses these two JavaScript functions to provide you with a set of .NET- like exception types. The chapter then presents you with a recipe for developing your own custom exception types in the ASP.NET AJAX client-side framework, and shows you how to use the recipe to implement a custom exception type. ASP.NET AJAX Built-In Exception Types One of the great things about the .NET Framework is that it comes with a rich set of exception types that address different programming scenarios. For example, you can use the ArgumentNullException type in your method to raise an exception to inform the callers if your method does not accept null values for a particular parameter. Exception programming is one of the fundamental aspects of any modern programming framework. The ASP.NET AJAX client-side framework presents a rich set of exception types that emulate many of the .NET exception types to make client-side exception programming more like server-side .NET exception programming. This section provides in-depth coverage of the ASP.NET AJAX client-side framework’s built-in exception types. ArgumentException The .NET Framework comes with an exception type named ArgumentException . This exception is raised when a method is invoked and one of the parameters passed into the method does not meet the requirements that the method expects of the parameter. The .NET ArgumentException exposes a read-only property named ParamName that specifies the name of the parameter that caused the exception to occur. c03.indd 53c03.indd 53 8/20/07 5:50:28 PM8/20/07 5:50:28 PM Chapter 3: Built-In and Custom Exception Types 54 The ASP.NET AJAX client-side framework extends JavaScript to add support for a similar exception type named ArgumentException , which belongs to a namespace called Sys . (I discuss namespaces in future chapters.) This JavaScript ArgumentException exposes two properties named paramName and name . The name property, like the name property of any JavaScript exception, contains the string that uniquely identi- fies the exception type. The paramName property is the equivalent of the .NET ArgumentException type’s ParamName property. The ASP.NET AJAX client-side framework also extends the functionality of the JavaScript Error type to add support for a static method named argument that automatically creates an instance of the Sys.ArgumentException exception and returns the instance to its caller. The best way to understand what this function does is to take a look at its internal implementation: Error.argument = function(a, c) { var b = ”Sys.ArgumentException: “ + (c ? c : Sys.Res.argument); if(a) b += “\n” + String.format(Sys.Res.paramName, a); var d = Error.create(b, { name : “Sys.ArgumentException”, paramName : a}); d.popStackFrame(); return d; }; Notice that the argument static method takes two arguments. The first argument is a string that contains the name of the parameter that caused the exception to occur. The second argument is a string that con- tains the error message. The argument function internally calls the create static method discussed in Chapter 2 : var d = Error.create(b, { name : “Sys.ArgumentException”, paramName : a}); The create static method takes an object as its second parameter. This object provides extra information about the Error object being created. Note that the argument method passes an object literal as the sec- ond parameter of the create method. This object literal specifies the string that uniquely identifies the exception and the parameter that caused the exception. The Sys.ArgumentException does not come with a constructor function, so you cannot instantiate it using the new operator. Instead, you must use the argument static function of the JavaScript Error object to instantiate an instance of this exception. The validateInput function in the following page code raises a Sys.ArgumentException exception if the parameter passed into it does not meet the requirement specified in the regular expression. The clickCallback function catches this exception in its catch block and displays the value of the excep- tion object’s message property. c03.indd 54c03.indd 54 8/20/07 5:50:30 PM8/20/07 5:50:30 PM Chapter 3: Built-In and Custom Exception Types 55 <%@ Page Language=”C#” %> <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <html xmlns=”http://www.w3.org/1999/xhtml”> <head id=”Head1” runat=”server”> <title>Untitled Page</title> <script language=”javascript” type=”text/javascript”> function validateInput(input) { var reg = new RegExp(“(\\d\\d)[-/](\\d\\d)[-/](\\d\\d(?:\\d\\d)?)”); var date = reg.exec(input); if (date == null) { var err = Error.argument(“input”, “Invalid date!”); throw err; } } function clickCallback() { var date = document.getElementById(“date”); try { validateInput(date.value); } catch (e) { alert(e.message); date.value=””; } } </script> </head> <body> <form id=”form1” runat=”server”> <asp:ScriptManager runat=”server” ID=”ScriptManager1” /> Enter date: <input type=”text” id=”date” />&nbsp; <input type=”button” value=”Validate” onclick=”clickCallback()” /> </form> </body> </html> As Figure 3-1 shows, the message property displays the type of the exception (which in this case is Sys.ArgumentException ), the exception message, and the name of the parameter that caused the exception to occur. c03.indd 55c03.indd 55 8/20/07 5:50:31 PM8/20/07 5:50:31 PM Chapter 3: Built-In and Custom Exception Types 56 ArgumentNullException The .NET Framework includes an exception type named ArgumentNullException . This exception is raised when a method is invoked and one of the parameters passed into it is null . As you can see, ArgumentNullException is more specific than ArgumentException . The ASP.NET AJAX client-side framework follows this .NET pattern and introduces an exception type named Sys.ArgumentNullException , which is more specific than Sys.ArgumentException . Just like its .NET counterpart, Sys.ArgumentNullException is raised only when one of the parameters passed into a JavaScript function is null . The ASP.NET AJAX client-side framework also extends the JavaScript Error type to add support for a new static method named argumentNull , which hides the instantiation of the Sys.ArgumentNull Exception object from its callers. As the following code shows, the internal implementation of the argumentNull method is the same as the argument method: Error.argumentNull = function(a, c) { var b = ”Sys.ArgumentNullException: “ + (c ? c : Sys.Res.argumentNull); if(a) b += “\n” + String.format(Sys.Res.paramName, a); var d = Error.create(b, { name : “Sys.ArgumentNullException”, paramName : a }); d.popStackFrame(); return d; }; As you can see, the argumentNull static method takes the same arguments as the argument static method discussed in the previous section. The only difference between the two methods is the value part of the first name/value pair of the object literal passed into the Error type’s create static method. This value is a string that uniquely identifies an exception type for other exception types. The validateInput function in the following code uses the argumentNull static method of the Error object to create and raise a Sys.ArgumentNullException when the user does not enter a date into the text box. The clickCallback function catches this exception in its catch block and displays the value of the exception object’s message property. Figure 3-1 c03.indd 56c03.indd 56 8/20/07 5:50:32 PM8/20/07 5:50:32 PM Chapter 3: Built-In and Custom Exception Types 57 <%@ Page Language=”C#” %> <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <html xmlns=”http://www.w3.org/1999/xhtml”> <head id=”Head1” runat=”server”> <title>Untitled Page</title> <script language=”javascript” type=”text/javascript”> function validateInput(input) { if (input == null || input.trim() == “”) { var er = Error.argumentNull(“input”, “Date cannot be null!”); throw er; } var reg = new RegExp(“(\\d\\d)[-/](\\d\\d)[-/](\\d\\d(?:\\d\\d)?)”); var date = reg.exec(input); if (date == null) { var err = Error.argument(“input”,“Invalid date!”); throw err; } } function clickCallback() { var date = document.getElementById(“date”); try { validateInput(date.value); } catch (e) { alert(e.message); date.value=””; } } </script> </head> <body> <form id=”form1” runat=”server”> <asp:ScriptManager runat=”server” ID=”ScriptManager1” /> Enter date: <input type=”text” id=”date” />&nbsp; <input type=”button” value=”Validate” onclick=”clickCallback()” /> </form> </body> </html> c03.indd 57c03.indd 57 8/20/07 5:50:33 PM8/20/07 5:50:33 PM Chapter 3: Built-In and Custom Exception Types 58 As Figure 3-2 shows, the message property contains the exception type ( Sys.ArgumentNullException ), the exception message passed into the argumentNull function, and the name of the parameter that caused the exception to occur. Figure 3-2 ArgumentOutOfRangeException The .NET Framework includes an exception of type ArgumentOutOfRangeException . This exception is raised when a method is invoked and one of the parameters passed into it is out of the range of valid values. ArgumentOutOfRangeException features two important properties named ParamName and ActualValue , which contain the name and value of the parameter that caused the exception to occur, respectively. Following the same .NET pattern, the ASP.NET AJAX client-side script framework includes an exception of type Sys.ArgumentOutOfRangeException , which exposes the same two paramName and actual- Value properties. In addition, the ASP.NET AJAX client-side framework extends the JavaScript Error type to add support for a new static method named argumentOutOfRange that hides the instantiation of the Sys.ArgumentOutOfRangeException . The following code presents the internal implementation of this static method: Error.argumentOutOfRange = function(c, a, d) { var b=”Sys.ArgumentOutOfRangeException: “ + (d ? d : Sys.Res.argumentOutOfRange); if(c) b += “\n” + String.format(Sys.Res.paramName, c); if(typeof a !== “undefined” && a !== null) b += “\n” + String.format(Sys.Res.actualValue, a); var e = Error.create(b, {name : “Sys.ArgumentOutOfRangeException”, paramName : c, actualValue : a}); e.popStackFrame(); return e; }; The argumentOutOfRange method takes three arguments. The first and second arguments are the name and value of the parameter that caused the exception to occur. The third argument is the exception c03.indd 58c03.indd 58 8/20/07 5:50:33 PM8/20/07 5:50:33 PM Chapter 3: Built-In and Custom Exception Types 59 message that provides more information about the exception. The argumentOutOfRange method first creates a string that contains the values of the three arguments: var b=”Sys.ArgumentOutOfRangeException: “ + (d ? d : Sys.Res.argumentOutOfRange); if(c) b += “\n” + String.format(Sys.Res.paramName, c); if(typeof a !== “undefined” && a !== null) b += “\n” + String.format(Sys.Res.actualValue, a); Then, it calls the create static method of the JavaScript Error type, passing in two parameters to create the associated Error object. The first parameter is the previously mentioned string. The second parameter is a JavaScript object literal that contains information about the Sys.ArgumentOutOfRangeException exception. Finally, the argumentOutOfRange function calls the popStackFrame function to reset the val- ues of the Error object’s fileName and lineNumber properties (discussed in Chapter 2 ). As the boldfaced portion of the following code shows, if the date entered in the text box is not in the specified range, the validateInput function invokes the argumentOutOfRange function to create a Sys.ArgumentOutOfRangeException . The clickCallback function catches this exception in its catch block and displays the pop-up message shown in Figure 3-3 . The message property of the Error object displays the exception type ( Sys.ArgumentOutOfRangeException ), the exception message passed into the argumentOutOfRange function, and the name and value of the parameter that caused the exception to occur. <%@ Page Language=”C#” %> <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <html xmlns=”http://www.w3.org/1999/xhtml”> <head id=”Head1” runat=”server”> <title>Untitled Page</title> <script language=”javascript” type=”text/javascript”> function validateInput(input) { if (input == null || input.trim() == “”) { var er = Error.argumentNull(“input”,“Date cannot be null!”); throw er; } var reg = new RegExp(“(\\d\\d)[-](\\d\\d)[-](\\d\\d\\d\\d)”); var date = reg.exec(input); if (date == null) { var err = Error.argument(“input”,“Invalid date!”); throw err; } var ar = input.split(“-”); if (ar[2] < 1900 || ar[2] > 2008) (continued) c03.indd 59c03.indd 59 8/20/07 5:50:34 PM8/20/07 5:50:34 PM Chapter 3: Built-In and Custom Exception Types 60 { var err2=Error.argumentOutOfRange(“input”,input); throw err2; } } function clickCallback() { var date = document.getElementById(“date”); try { validateInput(date.value); } catch (e) { alert(e.message); date.value=””; } } </script> </head> <body> <form id=”form1” runat=”server”> <asp:ScriptManager runat=”server” ID=”ScriptManager1”/> Enter date: <input type=”text” id=”date” />&nbsp; <input type=”button” value=”Validate” onclick=”clickCallback()” /> </form> </body> </html> Figure 3-3 ArgumentTypeException When you implement a method in the .NET Framework with a given set of parameters of specific types, you can rest assured that the Framework will ensure that users call your method with only the types of parameters that your method expects. c03.indd 60c03.indd 60 8/20/07 5:50:34 PM8/20/07 5:50:34 PM Chapter 3: Built-In and Custom Exception Types 61 The ASP.NET AJAX client-side framework includes an exception type named Sys.ArgumentTypeEx ception that you can call from within your JavaScript functions to make programming against your functions more like programming against .NET methods. The Sys.ArgumentTypeException exception is raised when a method is invoked and one of the parameters passed into it is not of the type that the method expects. This exception, just like all other exceptions in the ASP.NET AJAX client-side framework, does not come with a constructor function. This means that you cannot use the new operator to instantiate it. Instead, the ASP.NET AJAX client-side framework includes a new static method named argumentType to the JavaScript Error type that auto- matically instantiates this exception under the hood. This method takes four arguments. The first, second, and third arguments contain the name, actual type, and expected type of the parameter that caused the exception to occur. The last argument is the excep- tion message that provides more information about the exception. The validateInput function in the following code throws a Sys.ArgumentTypeException exception when the input is not a valid date value. The clickCallback function then catches this exception in its catch block and displays the message shown in Figure 3-4 . Note that the catch block uses the value of the exception object’s name property to determine the type of the exception. <%@ Page Language=”C#” %> <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <html xmlns=”http://www.w3.org/1999/xhtml”> <head id=”Head1” runat=”server”> <title>Untitled Page</title> <script language=”javascript” type=”text/javascript”> function validateInput(input) { if (input == null || input.trim() == “”) { var er = Error.argumentNull(“input”,“Date cannot be null!”); throw er; } var reg = new RegExp(“(\\d\\d)[-/](\\d\\d)[-/](\\d\\d(?:\\d\\d)?)”); var date = reg.exec(input); if (date == null) { var err = Error.argumentType(“input”, null, Date, “Invalid type!”); throw err; } var ar = input.split(“-”); if (ar[2] < 1900 || ar[2] > 2008) { (continued) c03.indd 61c03.indd 61 8/20/07 5:50:35 PM8/20/07 5:50:35 PM Chapter 3: Built-In and Custom Exception Types 62 var err2=Error.argumentOutOfRange(“input”,input); throw err2; } } function clickCallback() { var date = document.getElementById(“date”); try { validateInput(date.value); } catch (e) { if (e.name == “Sys.ArgumentTypeException ”) alert(e.message + “\nExpected Type : “ + e.expectedType.getName()); else alert(e.message); date.value=””; } } </script> </head> <body> <form id=”form1” runat=”server”> <asp:ScriptManager runat=”server” ID=”ScriptManager1”/> Enter date: <input type=”text” id=”date” />&nbsp; <input type=”button” value=”Validate” onclick=”clickCallback()” /> </form> </body> </html> Figure 3-4 c03.indd 62c03.indd 62 8/20/07 5:50:36 PM8/20/07 5:50:36 PM [...]... 64 c 03. indd 64 8/20/07 5:50 :37 PM Chapter 3: Built-In and Custom Exception Types undefined value into the text box The clickCallback function then catches this exception and displays the pop-up message shown in Figure 3- 5 ... previously) 63 c 03. indd 63 8/20/07 5:50 :36 PM Chapter 3: Built-In and Custom Exception Types ArgumentUndefinedException The ASP.NET AJAX client-side framework includes an exception type named Sys.ArgumentUndefinedException This exception is raised when a function is invoked and one of the parameters passed into it is undefined This exception, like all other exceptions in the ASP.NET AJAX client-side framework,... parameters 68 c 03. indd 68 8/20/07 5:50 :39 PM Chapter 3: Built-In and Custom Exception Types that the function expects The clickCallback function catches this exception and displays the value of the Error object’s message property in the pop-up message box shown in Figure 3- 6 ... NET exception named NotImplementedException The ASP.NET AJAX client-side script framework provides you with the same type of exception, which is called Sys.NotImplementedException and exposes a single name property 66 c 03. indd 66 8/20/07 5:50 :38 PM Chapter 3: Built-In and Custom Exception Types It shouldn’t come as a surprise that the ASP.NET AJAX client-side framework also extends the Error object to... runat=”server”> (continued) 73 c 03. indd 73 8/20/07 5:50:41 PM Chapter 3: Built-In and Custom Exception Types Product Description Name:... category, and distributor to an internal collection Figure 3- 7 74 c 03. indd 74 8/20/07 5:50:41 PM Chapter 3: Built-In and Custom Exception Types If you attempt to add a product with the same name as an existing product, the pop-up message shown in Figure 3- 8 is displayed to warn you that the specified item already exists in the collection As Figure 3- 8 shows, the warning message also displays the names and... chapter provided you with an in-depth coverage of the ASP.NET AJAX built-in exception types It then gave you a recipe for building your own custom exception types and showed you how to use the recipe to implement a custom exception type named DuplicateItemException The ASP.NET AJAX JavaScript base type extensions and exception types are only part of the ASP.NET AJAX client-side framework The next chapter. .. use your custom exception in a page as shown in the following code: 72 c 03. indd 72 8/20/07 5:50:41 PM Chapter 3: Built-In and Custom Exception Types Untitled Page . previously). c 03. indd 63c 03. indd 63 8/20/07 5:50 :36 PM8/20/07 5:50 :36 PM Chapter 3: Built-In and Custom Exception Types 64 ArgumentUndefinedException The ASP. NET AJAX client-side framework. Figure 3- 1 c 03. indd 56c 03. indd 56 8/20/07 5:50 :32 PM8/20/07 5:50 :32 PM Chapter 3: Built-In and Custom Exception Types 57 <%@ Page Language=”C#” %> <!DOCTYPE html PUBLIC -/ /W3C//DTD. that your method expects. c 03. indd 60c 03. indd 60 8/20/07 5:50 :34 PM8/20/07 5:50 :34 PM Chapter 3: Built-In and Custom Exception Types 61 The ASP. NET AJAX client-side framework includes an exception