15.2. Using the Error Class

The ASP.NET AJAX Script Library includes several useful classes with respect to debugging and testing, including the Error and Sys.Debug classes. The Error class extends the native JavaScript Error object and allows more specific error objects and messages to be created for a given error. It is used extensively throughout the ASP.NET AJAX Library debug scripts to test that the correct number of parameters are passed to functions, passed parameter types match up with the expected types, types aren't undefined, functions are fully implemented, and much more. The Error class is used sparingly in the release version of the ASP.NET AJAX Library scripts so that file sizes are minimized as much as possible.

The Error class has several different functions that can be used to create specific types of errors. The majority of the functions that can be called to create error objects relate specifically to function parameters, but others exist that are used by classes such as the PageRequestManager class. All of the Error class's available functions are shown in the following table.

Function NameDescription
argument(paramName, message)Used to create a Sys.ArgumentException object with the name of the function parameter that caused the exception, as well as the specified error message.
argumentNull(paramName, message)Used to create a Sys.ArgumentNullExeption object with the name of the function parameter that caused the exception, as well as the specified error message.
argumentOutOfRange(paramName, actualValue,message)Used to create a Sys.OutOfRangeArgumentException object. It accepts three parameters, including the parameter name, the actual value the parameter, and the error message.
argumentType(paramName, actualType, expectedType, message)Used to create a Sys.ArgumentTypeException object. Can be used when a parameter passed to a function is not the proper type. It accepts four parameters, including the parameter name, actual type passed for the parameter, the expected type of the parameter, and the error message.
argumentUndefined(paramName, message)Used to create a Sys.ArgumentUndefinedException object with the name of the function parameter that caused the exception as well as the specified error message.
create(message,errorInfo)Used to create a new instance of an Error object with the specified message and extended information about the error. The errorInfo object passed must contain a name field containing a string that identifies the error. An example of creating an errorInfo parameter is: Error.create(a, {name:"Sys.ArgumentTypeException",paramName:d,actualType:c,expectedType:b})
invalidOperation(message)Used to create a Sys.InvalidOperationException with the specified error message.
format(message)Used to raise a Sys.FormatException exception when the format of an argument does not meet the parameter specifications of the invoked method.
notImplemented(message)Used to create a Sys.NotImplementedException object with the specified error message.
parameterCount(message)Used to create a Sys.ParameterCountException object with the specified error message. Used to validate the number of parameters passed to a function.
popStackFrame()Used to update the fileName and lineNumber fields of the Error object instance to indicate where the Error was thrown. This solves problems in browsers that assign values to the fileName and lineNumber fields based upon where the Error object was created rather than where it was thrown.

You can use the Error object to raise specific types of errors when invalid parameters are passed to a function, when calls are made to functions that aren't fully implemented, or when you need to ensure that the correct line number and filename show up when errors are raised.

Listing 15-5 shows an example of using the Error object's argumentType, popStackFrame, and notImplemented functions with a custom script that defines an Album class.

Example 15-5. Using the Error object
Wrox.ASPAJAX.Samples.Album.prototype = {

    //Additional code removed for brevity

    addSong: function(song)

{
        /// <value type="Wrox.ASPAJAX.Samples.Song"></value>
        if (Object.getTypeName(song) != 'Wrox.ASPAJAX.Samples.Song')
        {
            var e = Error.argumentType('song', Object.getType(song),
              Wrox.ASPAJAX.Samples.Song,"Wrox.ASPAJAX.Samples.Song required!");
            e.popStackFrame();
            throw e;
        }
        Array.add(this._songs,song);
    },
    rateSong: function(song,rating)
    {
        throw Error.notImplemented("rateSong() has not yet been implemented");
    }

    //Additional code removed for brevity

}

The first use of the Error object is in the definition for the addSong function in Listing 15-5. This function accepts a Wrox.ASPAJAX.Samples.Song object as a parameter. If a Song parameter type is not passed, a call is made to the Error.argumentType function to create a Sys.ArgumentTypeException error object. This function accepts the name of the parameter in error (song in this example), the actual parameter type passed, the expected parameter type, and the error message that should be shown to the caller. Once the Error object is created, a call is made to popStackFrame to ensure that the line number and filename are properly reported to the caller. In some browsers, the line number is reported at the location that the error was created rather than the location where it was actually thrown. The popStackFrame function remedies this problem and ensures that the line number and filename are reported correctly.

The Error object is also used in the definition for the rateSong function in Listing 15-5. Because this function is not yet implemented, a call is made to the Error.notImplemented function, and the error message that the caller should see is passed as a parameter. Listing 15-6 shows calls to the Album class's addSong and rateSong methods and demonstrates how to catch returned errors.

Example 15-6. Catching Error object instances
function RateSong()
{
    var album = new Wrox.ASPAJAX.Samples.Album();
    var song = new Wrox.ASPAJAX.Samples.Song(3,$get("txtSong"));
    try
    {
        //Should pass song object here but demonstrate using Error object in Album
        //to verify proper parameter type is passed
        album.addSong(album);
    }
    catch(e)
    {

alert(e.message);
    }
    try
    {
        //rateSong() not implemented
        album.rateSong(song,$get("txtSongRating"));
        alert("Song rated!");
    }
    catch(e)
    {
        alert(e.message);
    }
 }

Now that you've seen how the ASP.NET AJAX Script Library's Error class can be used, let's take a look at the Sys.Debug class and see how it can be used to write error messages and identify the reason they occurred.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset