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.. The chapter then

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

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:

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

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=””;

} }

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

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:

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

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=””;

} }

Enter date: <input type=”text” id=”date” />&nbsp;

<input type=”button” value=”Validate”

onclick=”clickCallback()” />

</form>

</body>

</html>

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:

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

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);

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

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!”);

<form id=”form1” runat=”server”>

<asp:ScriptManager runat=”server” ID=”ScriptManager1”/>

Enter date: <input type=”text” id=”date” />&nbsp;

<input type=”button” value=”Validate”

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

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

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);

(continued)

<form id=”form1” runat=”server”>

<asp:ScriptManager runat=”server” ID=”ScriptManager1”/>

Enter date: <input type=”text” id=”date” />&nbsp;

<input type=”button” value=”Validate”

Now take a look at the internal implementation of the argumentType function in the following code:

Error.argumentType = function(d, c, b, e){

var a = ”Sys.ArgumentTypeException: “ + (e ? e : “”);

f.popStackFrame();

return f};

The argumentType method first builds a string that contains the following:

❑ The error message:

❑ The string built in the first step

❑ An object literal that provides more information about the exception Note that this object tains the following properties: name , paramName , actualType , and expectedType :

var f = Error.create(a, {name : “Sys.ArgumentTypeException”, paramName : d, actualType : c, expectedType : b});

Finally, the exception calls the popStackFrame function on the Error object to reset the values of the

fileName and lineNumber properties (discussed previously)

ArgumentUndefinedException

The ASP.NET AJAX client-side framework includes an exception type named

Sys.ArgumentUndefined-Exception 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, does

not come with a constructor function and therefore cannot be instantiated using the new operator The

ASP.NET AJAX client-side framework includes a static method on the Error type named

argumentUndefined that instantiates this exception for you This method takes two arguments The

first argument is the name of the parameter that caused the exception The second argument is an

exception message that provides more information about the exception The internal implementation of

the argumentUndefined static method follows the same implementation pattern as any other static

method of the ASP.NET AJAX Framework’s Error type that instantiates an exception object

The method first builds a string that contains the exception message and the name of the parameter that

caused the exception, as follows:

var b = ”Sys.ArgumentUndefinedException: “ +

(c ? c : Sys.Res.argumentUndefined);

if(a)

b += “\n” + String.format(Sys.Res.paramName, a);

It then calls the Error object’s create static method, passing in two arguments, as shown in the

follow-ing code The first argument is the strfollow-ing built in the first step The second argument is the JavaScript

object literal that provides more information about the Sys.ArgumentUndefinedException exception

The validateInput function in the following example calls the argumentUndefined static method on

the Error type to raise a Sys.ArgumentUndefinedException exception when the end user enters an