Flash Remoting

Flash Remoting enables invocation of server-side methods from a client-side ActionScript object, also known as a proxy object. Using Flash Remoting, methods within a Cold Fusion component, .NET, or a J2EE class can be called.

Flash Remoting uses the Hypertext Transfer Protocol (HTTP) and AMF. Flash Remoting can be a more efficient solution for transferring large amounts of data because AMF is a binary protocol that consumes much less bandwidth than SOAP. In addition, much of the transformation from XML to Flash objects occurs on the server rather than the client, which frees up client-side resources.

Flash Remoting consists of a server-side element that runs on ColdFusion, the Microsoft .NET framework, or a J2EE server. This server-side component does the data translation. For example, it will take a query in ColdFusion, a dataset in .NET, or a ResultSet in Java and translate it into a Flash data structure called a RecordSet object. The server-side component will also take an array, which is a string from any of those languages, and translate this server-side data structure into a native Flash object of approximately the same type. Flash Remoting also consists of a client-side piece that can be downloaded from Macromedia at www.macromedia.com/software/flashRemoting/downloads/ components /.

The client-side piece of Flash Remoting enables the creation of a proxy server-side object within the Flash Player (located within the NetServices.as class).

N OTE

At the time this book published, the Flash Remoting components had not yet been updated for ActionScript 2.0. Therefore, you must include the old ActionScript 1.0 class at the top of your FLA file, as in ActionScript 1.0. Macromedia is planning to rewrite the Flash Remoting components in ActionScript 2.0.

In addition, the client-side download also provides tools for debugging within the NetBug class and managing data within the Flash Player through the RecordSet class.

An overview of the entire process is shown in Figure 14.13.

Figure 14.13. Flash Remoting enables the creation of client/server solutions where some processing is done on the server and some is done on the client.

Benefits of Flash Remoting

What advantages does Flash Remoting offer over Web Services and XML? The biggest advantage that Flash Remoting offers is performance. Whenever you use Web Services and XML, the Flash Player has to parse the XML and validate the XML against the schema. This takes time. Flash Remoting sends binary data down the wire and this data not only consumes less bandwidth (XML data or WSDL data is basically raw text data), but also is easier for the Flash Player to handle.

Flash Remoting exposes server-side methods and represents a clear delineation between server development and Flash development. With Flash Remoting, it is very easy to divide up teams of programmers. It also is generally easier on the server-side to build methods and objects instead of having to build Web Services.

Using Flash Remoting

As of the publishing of this book, the Flash Remoting classes have been written in ActionScript 1.0. Macromedia is planning to completely rewrite all the classes to follow best practices in ActionScript 2.0 as well as build a Remoting Connector component that will work with visual data bindings.

For now, we will be discussing the version 1 remoting components, which can be installed in Flash MX 2004. To use Flash Remoting is to include the appropriate remoting files at the top of your ActionScript code. This can be done using the Actions panel after the remoting components have been installed. The NetServices class contains the core remoting functionality and also includes the RecordSet class, which helps manage data. All FLAs that implement Flash Remoting should have the following included:

 #include NetServices.as 

C aution

If you include the NetBug class, which enables the built-in Remoting debugger, it is essential that this class be removed from any production server as there is an inherent security risk because it exposes data.

Examine Figure 14.14.

Figure 14.14. The Actions panel after the remoting components have been installed.

Creating a Gateway Connection

To use Flash Remoting, you must connect to the server-side piece. This is done by creating a gateway connection to the application server using the static method createGatewayConnection of the NetServices class. This object establishes the bidirectional connection between the Flash Player and the Flash Remoting service at the server. Note that the connection is not made until the server-side method is actually called.

To establish a connection with both Cold Fusion and Java application servers, you would use the following code:

 #include "NetServices.as" var myCon :Object = createGatewayConnection ("http://localhost}/  flashservices/gateway  "); 

To establish a connection using Microsoft .NET, you would use the following code:

 #include "NetServices.as" var myCon :Object = createGateWayConnection ("http://localhost/  flashRemoting/gateway.aspx  "); 

Creating a Responder Object

To catch the data from the server, it is a best practice to create a responder object, as shown in the following code:

 var myResponder :Object = new Object(); 

It is possible to send the results of the server-side call to a movie clip, including the main timeline, but this can result in less maintainable code. Note that it is possible to send the results to any object in Flash, and it can be useful to build custom responder classes.

Building a Client-Side Proxy Object

The server-side object will need to be referenced in the Flash Player. This is done by creating an ActionScript proxy object; this is a client-side representation of the server-side object whose methods you are going to call. This object will have all the server-side methods of the object on the server, but Flash will be able to reference the proxy object. After you have created the proxy object in Flash, you can use this object to invoke server-side methods.

Creating the proxy object is done through the getService method of the NetServices class; this method requires one parameter, which is the package name on the server. The following code shows how a Cold Fusion object is referenced by the getService () method. "oopAS.examples" is the path or package to the Cold Fusion object with the name of myServerObject .

 var proxyObject :Object = myCon.getService ("oopAS.examples.myServerObject"); 

Calling the Server-Side Method from ActionScript

After the proxy object has been set up using the getService method, you can call methods of that object just as you call methods on a regular Flash object. To do this, you just specify the name of the proxy object and the name of the server-side method you want to call. You also need to specify the name of the object where the results will be returned as the first parameter of the method call. Any additional parameters that the server-side method needs can be sent after the first method call. In the following code, the results of the method call will be sent to the myResponder object, and the contents of the id text field will be sent to the server-side object as a method parameter:

 proxyObject.myServerMethod (myResponder, id.text); 

Dealing with the Results from the Server-Side Call

After the method has been called and the last byte of data has been received from the server, the Flash Player automatically calls the onResult event, which is similar to the result event/listener you have worked with in Web Services and XML.

N OTE

Remoting can also call responder methods on the Flash side with the same name as the server-side method, but with the _Result suffix. These methods are called when the last byte of data bas been received from the server, as shown in the following code:

 myServerMethod_Result = function (serverData) { //code } 

However, these responder methods must be attached to MovieClip objects; you have already looked at the disadvantages of hanging code off movie clip timelines rather than using class-based development.

The object returned from the server will be passed as a parameter to the onResult event, as shown in the following code:

 myResponder.onResult = function (serverData) { //code } 

You can manipulate the server-side object that is returned, just as you could with any other ActionScript object. If you are using remoting with version 2 components, you could easily link the returned item with a DataSet object. Remember that a Cold Fusion query, a .NET dataset, or a Java ResultSet is automatically translated by Flash Remoting into a RecordSet object. The RecordSet object implements the dataProvider API, which means you can link the recordSet to the dataProvider of the version 2 dataset, as shown in the following code:

 myResponder.onResult = function (serverData) {       mydataset.dataProvider = serverData; } 

If you are returning an Array of Objects from the Remoting service, you would link the items property of the dataset.

Data Translation in Flash Remoting

The data translation in Flash Remoting varies by platform. As discussed, queries returned will translate into a recordSet in Flash. A recordSet appears as shown in Figure 14.15.

Figure 14.15. A visual representation of the Flash RecordSet object.

The RecordSet object is useful because it implements the dataProvider API, which means that you can use methods like addItem() , removeItem() , getLength() , and more. These methods work just like the component methods we have worked with before.

However, using a RecordSet object tends to have a higher overhead (both in terms of bandwidth consumed and client-side/server-side processing) than using an array of objects or other data structures. Thus, it is recommended to use native ActionScript data structures whenever possible.

Table 14.1 lists Flash Remoting data translation from ActionScript to Cold Fusion:

Table 14.1. ActionScript-to-Cold-Fusion Data Translation

A CTION S CRIPT D ATATYPE	C OLD F USION D ATATYPE
Number	Number
Boolean	Boolean
String	String
Ordered array	Array
Named array	Structure
Array of Objects	Array of structures
Date	Date
Ordinary object	CFC arguments structures
XML object	XML document

Table 14.2 lists Flash Remoting data translation from ActionScript to Java.

Table 14.2. ActionScript-to-Java Data Translation

A CTION S CRIPT D ATATYPE	J AVA D ATATYPE
Number	Number
Boolean	Boolean
String	String
Ordered array	Array
Named array	Object
Array of objects	Array of objects
Date	Date
Ordinary object	Object
XML object	XML document object

Table 14.3 lists Flash Remoting data translation from ActionScript to .NET.

Table 14.3. ActionScript-to-.NET Data Translation

A CTION S CRIPT D ATATYPE	C OLD F USION D ATATYPE
Number	Number
Boolean	Boolean
String	String
Ordered array	Array
Named array	Object
Array of objects	Array of objects
Date	Date
Ordinary object	Object
XML object	XML document object

Handling Flash Remoting Errors

The onStatus event is called whenever a server-side error is thrown. It is a good idea to always build an onStatus event, attached to the responder object, to catch any errors that may be thrown by the server, as shown in the following code:

 myResponder.onStatus = function (statusObject){ //code to handle errors } 

The statusObject returned by Flash Remoting in the event of a server-side error contains these properties that describe the exact error:

• level

• description

• code

• details

The following code will loop through the returned status object and populate a text field with the string "Connecting to Server Error" so that the user knows something went wrong:

 myResponder.onStatus = function (statusObject) { for (var i:String in statusObject){ trace (i + "-" + statusObject[i]); }