13.4 NetConnection Debugger | Flash Remoting: The Definitive Guide

The NetConnection Debugger panel is a Flash movie itself. It is implemented as a Flash panel extension to Flash MX and is installed when you install the Flash Remoting components . The NetConnection debugger reports all connections, input, and output from the Flash movie to the server. Any arguments sent to the movie are exposed in the panel, and any response from the server is shown as well. This includes all error messages from the server.

The NetConnection debugger is available only during authoring time. Errors that occur in the application after the movie has been compiled and deployed will not be reported . It is up to you as the author of the Flash application to address the errors during authoring time so that the end user experience is without error.

The NetConnection Debugger panel must be opened from the Window menu in Flash before testing the movie for it to become active. To invoke it, open the NetConnection Debugger panel and choose Control Test Movie. The Control Debug Movie option invokes the Flash interactive debugger, not the NetConnection debugger, although the latter will also be active if it was previously open. Be sure to include the line #include "NetDebug.as " in your code if you've previously omitted it.

13.4.1 Parts of the Debugger

The NetConnection debugger, shown in Figure 13-4, consists of three panels in the main section of the debugger and two smaller panels below. The three main panels are:

Events: Shows the client/server event that occurs, along with an icon representing the type of event (such as a Flash icon for an event from Flash), the event name , and brief summary of information about the event.
Summary: Allows you to drill down from the Events panel to display a summary of a particular event, which usually includes the request and response information.
Details: Allows you to drill down even farther to get more specific details about an event, including some header information.

Figure 13-4. The NetConnection debugger for Flash Remoting

All events that occur between the client and the server are shown in this panel. A typical session consists of the following:

A connection to the Flash Remoting gateway
A call to a remote method
The HTTP request headers
The AMF request headers
The AMF method call
The AMF response upon a successful method call, or the AMF status upon failure
The onResult or onStatus event
The AMF response headers

All of this information is displayed in a formatted fashion in the NetConnection debugger. In addition, you can create your own events to display by using the methods of the NetDebug API, which will be discussed shortly.

If you are passing complex ActionScript objects to the server, the NetConnection debugger displays the object and its properties. Likewise, complex objects or recordsets returned from the server are also displayed in their entirety. If remote methods aren't returning the expected results, you can see exactly what is coming back from the server to help track down any errors in your code.

The bottom section of the NetConnection debugger contains the Filters and Preferences panes. The Filters pane allows you to set filters, which are used to limit the information that is displayed. By default, all events are subscribed to, but you can uncheck the events that you don't want to display. In most situations, the filter is not needed, but if you are calling many methods you may want to suppress some of the output.

The Preferences pane allows you to specify the number of events to display before old events are discarded. In addition, you can limit the length of arrays that will be displayed. Remember, the NetConnection Debugger panel is a Flash panel, so it is subject to the limitations of Flash. Large amounts of data will tend to drag down performance, so the panel defaults to displaying a maximum of 10 array elements, 25 events, and 500 total lines. The font size can also be adjusted.

To debug Flash Communication Server (FlashCom) applications, a username and password can be supplied. For more information on FlashCom, see http://www.macromedia.com/desdev/mx/flashcom.

13.4.2 Using the NetConnection Debugger

The following line adds the classes required to use the NetConnection debugger:

 #include "NetDebug.as"

Simply add the preceding line to your Flash movie, and open the NetConnection Debugger panel using Window NetConnection Debugger. If you commented out the #include statement during the earlier example using the Flash interactive debugger, uncomment it now to reactivate NetConnection debugging. For a ColdFusion Server, more debugging information is available if you turn on debugging in the ColdFusion Administrator. To do so, you need to know the IP address of the client machine where your Flash authoring environment is running from. If you are using a local ColdFusion Server, this is usually at the localhost IP address of 127.0.0.1. Figure 13-5 shows the debugging IP address settings of the ColdFusion Administrator.

Figure 13-5. Setting up debugging IP addresses in the ColdFusion Administrator

We will go through a typical debugging session by testing a Flash Remoting application that was developed in an earlier chapter. A few key errors can be introduced so that you can see what effect they have on the debugging information presented in the NetConnection debugger.

13.4.2.1 Debugging a connection

The connection to the Flash Remoting adapter is one of the first things you might have to debug. If the connection to the adapter fails, you are dead in the water. This is also one of the areas that is not covered by the debugger. If the connection fails and you don't have error-handling code in your Flash movie, the movie will just appear to freeze and the NetConnection debugger will not show anything wrong.

The physical connection to Flash Remoting is not actually made until you call a remote method of your service. Only then can you track an error in the connection. Connection errors do not occur when the NetConnection object is instantiated , as you saw in the "A Debugging Session" exercise using the Flash interactive debugger earlier in the chapter. Errors also don't occur when the service is set up in your Flash movie.

Connection errors can be trapped in one of three locations:

_global.System.onStatus event handler
NetConnection.onStatus event handler
Your_connection.onStatus event handler

A bad connection usually means that the URL is bad. It can also mean that a server is down temporarily. You can handle errors like these in one of the events shown previously, usually with a message box to the user or by redirecting the user to an error page. A typical onStatus( ) method might look like this:

 my_conn.onStatus = function (error) {   _root.getURL("http://localhost/myConnectionErrorPage.html"); }

Try debugging the connection in searchProducts.fla by using this code. First, try the code with a working connection; then, stop the movie and change the URL to a nonexistent URL. Try the movie again. You'll find that the onStatus event is triggered when you make the call to the service.

You can also check the URL of the Flash Remoting adapter from a browser. If you type the URL in a browser, you should see a blank page if the adapter is working at that URL. Connection errors can be more difficult to track down if they are sporadic. In such cases, there is little you can do other than trap the error and give the user a message or an alternative.

13.4.2.2 Debugging method calls

Each remote method call in your Flash Remoting application should have its own error-handling code. The onStatus( ) handler for the method call can give you some information about an error, but in the debugging phase of application development you should use the NetConnection debugger to get more information about the errors. The debugger shows a full stack trace (a list of the functions or methods that are called) from the server, which can be extremely useful in tracking an error.

Debugging helps track logical or intermittent errors, as well as the more obvious connection errors. An application can seem to work fine but deliver erroneous results in certain situations. In these cases, the NetConnection debugger can help you to pinpoint the problems by showing all raw results as they come from the server. As you build your application, you should document exactly what each method does, what it requires, and what it returns. If something deviates from your plan, you can address it when debugging.

Debugging is the systematic challenging of your assumptions. Instead of assuming something is working correctly, verify its operation by manually inspecting the information provided in the debugger. If something isn't working as expected, the problem often started earlier in your code. Examine the arguments submitted to each remote method call and the results passed back. Keep working backward in your application until you find where the errors originated. Depending on the point in your application at which failure occurs, it might be easier to start at the beginning and verify each step as you move forward than to follow the logic backward from the end.

13.4.2.3 Validating user data

Applications that depend on user-supplied data are frequently the hardest types of applications to debug, because you never know what a user might attempt to do with the application or when malicious users might prey on your application. Making the application bullet-proof to user input is one aspect of debugging. Sometimes, the best way to debug an application that requires user-supplied data is to test the application with various users, including users who don't know what they are doing. Ideally, you'll have a mix of skilled beta testers, clueless newbies, and some average users in between. If they can all use your application without errors, you are usually in good shape. Needless to say, validating all user-supplied data is essential.

Validation on the Flash client using ActionScript should be used only as a first line of defense against bad data. Your server methods should each contain validation routines to guard against bad user data or malicious attack as well.

13.4.2.4 System errors

Using the onStatus event of the connection object will trap connection errors, and onStatus events of your methods will trap errors in the methods, but there can be other types of general system errors that don't fall into these two categories. For example, this general error message occurred on an ASP.NET example and was not trapped by a connection error handler or a method error handler:

"Object reference not set to an instance of an object."

For this type of error, you can fall back on the generic system error trapping:

 _global.System.onStatus = function(error) {   _root.getURL("http://localhost/mySystemErrorPage.html"); }

Attempting to invoke a method that doesn't exist will throw a general system error.