Flash Remoting and ActionScript 2.0

"Learn the true power of ActionScript and you can become more powerful than any…"sorry, wrong book. But in reality, if you do learn ActionScript, your skills and abilities with Flash will increase. In my opinion, ActionScript is the heart of Flash. Pretty much everything you can do within the Flash GUI, you can accomplish using ActionScript, but more! This unit will cover the basic ActionScript commands that are used in Flash Remoting.

NOTE

Make sure you have the Macromedia Flash Remoting for ActionScript 2.0 components installed on your machine. This download includes:

• The Flash Remoting ActionScript API

• The RemotingConnector component

To download Macromedia Flash Remoting for ActionScript 2.0 components, visit http://www.macromedia.com/software/flashremoting.

Macromedia created the Flash Remoting ActionScript classes to assist in the configuration of Flash Remoting, to communicate with remote services (CFCs), and to control client data. To use these classes within your project, you must place the Remoting library on your stage. The Remoting.fla library contains two items: RemotingClasses and RemotingDebugClasses. They enable you to utilize some of the following classes: Connection, DataGlue, FaultEvent, Log, Netdebug, PendingCall, RecordSet, RelayResponder, ResultEvent, and Service.

The following is an overview of the steps to follow to create Flash Remoting using ActionScript 2.0:

1.	Drag the RemotingClasses to the stage. You can leave the RemotingDebugClasses alone.
2.	Import your required Flash Remoting ActionScript classes.
3.	Establish a gateway connection and service object (CFC).
4.	Communicate with the CFC (functions and methods).
5.	Handle the results in Flash.

So, let's get started:

1.	Open Flash 8. You now should have a new document.
2.	Change the size of the stage to 550x500 pixels.
3.	Save this document as unleashedCafeMain in C:\unleasedCafe\unleashedCafeMain.fla.
4.	Rename Layer1 to RemotingClasses.
5.	Create a new layer and name it remotingActions.
6.	Drag the RemotingClasses to the stage. To open the Remoting library, select Window, Common Libraries, Remoting, and then select the remotingClasses layer.
7.	Drag the clip RemotingClasses to the stage on the remotingClasses layer. Place the object off the stage on the upper-left side.
8.	Lock the remotingClasses layer.

When RemotingClasses is placed on your stage, it also places a copy of it in your library (F11). The RemotingClasses are exported in your SWF when you publish your movie. For this reason, the clip can actually be deleted from the stage, but for the purposes of this chapter we will keep it on the stage.

Import Flash Remoting ActionScript Classes

Use the import keyword to access the Flash Remoting classes without needing to use the fully qualified name.

1.	Select the remotingActions layer.
2.	Open the Actions panel by selecting Window, Actions, or press F9.

The following directives need to be implemented: type the following into the Actions panel:

 // Import the Flash Remoting Classes import mx.remoting.Service; import mx.services.Log; import mx.rpc.RelayResponder; import mx.rpc.FaultEvent; import mx.rpc.ResultEvent; import mx.remoting.PendingCall; import mx.remoting.RecordSet; import mx.remoting.DataGlue; 

The preceding lines of code allow us to access all the methods and properties for each of the preceding classes. Each will be explained as we move along. For more information on the import keyword and a full list of directives, visit www.macromedia.com.

Establish a Gateway Connection and Service

Now that we have access to the Service class, we can create a new Service object. The Service class allows us to establish a gateway connection while creating a link to the CFC and its functions.

The constructor for the Service class is as follows:

• Service (gatewayURI, logger, serviceName, conn, resp).

• gatewayURI A reference to the gateway on the application server.

• logger Creates a log object using the Log class; it is used to send debugging messages.

• serviceName The name of the CFC, which is now considered "the service."

• conn The Connection object used to connect to the service. This replaces the NetConnection class in ActionScript 1.0. If used, it will take precedence over the gatewayURI. If this object is not used, you must enter a null value.

• Resp The Responder object used to handle the results from the server. If this object is not used, you must enter a null value.

Create a new Service object:

Return to the Actions panel and type the following under the last import directive.

[View full width]
 // Connect to the Gateway // Establish the Service var unleashedService : Service = new Service( "http://localhost/flashservices/gateway",  new Log (Log.DEBUG), "unleashedCafeSite.unleashedCom", null, null); 

This will allow us to link to the Flash Remoting gateway, create a log for debugging in the Output window, and establish a link to the remote service (CFC).

The URI (http://localhost/flashservices/gateway) is only a reference to a virtual directory. There is no physical directory on your server named flashservices/gateway. The gateway is considered a servlet mapping, and flashservices is a Java application context.

The new Log (Log.DEBUG) sends events and error information to the Output window within the Flash environment. This object is an optional parameter to the Service class.

The unleashedCafeSite.unleashedCom refers to the directory where your CFC is located. The name of our CFC is unleashedCom and it is located in C:\unleashedCafeSite, hence unleashedCafeSite.unleashedCom. In some cases it may not be necessary to include the directory name. If you are having some problems with your Flash Remoting application connecting to the CFC, this may be the first area that you attempt to debug.

Communicate with the CFC and Handle the Results

Imagine walking into your boss's office and asking for a day off. Your boss answers your request and regardless of the outcome, yes or no, you process the answer. Also, in some cases, your boss may act as if he never heard your request. This most definitely is an error! You then process this error and either ask again or fix the error.

The preceding example is a demonstration of how Flash communicates with the CFC. Flash asks the CFC for a request, the CFC processes the request and either returns the success or failure.

NOTE

For the sake of understanding, the terminology used in this chapter is as follows:

• Method Refers to an ActionScript function

• Function Refers to a CFC function

First, we need to create a ActionScript function (method). A method is simply a group of statements that perform actions. Methods allow you to consolidate many similar actions and use a single identifier to execute them.

Next, we will establish the service named unleashedService with a call to our CFC function named getTestConn(). To call this function from Flash, we need to create a PendingCall object.

To do so, open your Actions panel and type the following under the Service declaration:

 // Test the Connection function getTestConn(){ //Create a PendingCall objects var testConn_pc:PendingCall = unleashedService.getTestConn(); //Use the responder property to handle the success for failure testConn_pc.responder = new RelayResponder(this, "getTestConn_Result", "getTestConn_Fault"); } 

There are a few ways of communicating or calling functions within the CFC from Flash. The recommended method is to utilize the PendingCall class. The PendingCall object has a responder property that provides access to an associated RelayResponder object. The RelayResponder class provides a means of relaying messages to predefined methods that execute various actions based on the success or failure of the call to the service function. In our example, we create a new RelayResponder object and assign a result method (getTestConn_Result) and a fault method (getTestConn_Fault) and assign access to these methods to our PendingCall object (testConn_pc.responder).

Next, we will create the Result function and the Fault function. To do so, type the following code after the closing brace (}) of our getTestConn()method:

 //Handle the Success function getTestConn_Result(re:ResultEvent){ trace(re.result); } //Handle the Failure function getTestConn_Fault(fault:FaultEvent):Void{ trace("error"); } 

The preceding code creates two methods that handle the results. Let's look at the getTestConn_Result() method. The service function unleashedCom.getTestConn() returns a simple string "….connection successful". Take another look at our CFC:

 <cfcomponent displayName="unleashedCom"> <! Establish a Flash Remoting Connection > <cffunction name="getTestConn" access="remote" returnType="string"> <cfreturn ". . . connection successful"> </cffunction> </cfcomponent> 

This string is passed as an argument to the getTestConn_Result method as a ResultEvent object. The ResultEvent object has a property called result. The result property provides access to the returned result. So, to access this string in Flash we simply would reference the result property of the ResultEvent objectthat is, re.result. Since we do not have any components or text field objects on our stage to apply the results, the quickest way for us to view the results would be to send the results to the Output window using the trace command, trace (re.result).

The next method, getTestConn_Fault, handles errors. In our example, if Flash Remoting returns fault, the method would send "error" to the Output window. The FaultEvent class is a very helpful means of debugging your application along with the Log class.

For more information on the ResultEvent, FaultEvent, and Log objects, refer to the Flash Remoting ActionScript Dictionary Help.

Type the following line of code to execute the getTestConn() method:

 //Start the Application getTestConn();  

The Preceding line of code executes everything that is within the getTestConn() method.

Now test your movie. From the main menu, select Control, Test Movie.

Your Output window should appear and look as shown in Figure 23.6:

Figure 23.6. The Output window.

That's it; you now have completed your first Flash Remoting application. You can use this script along with the CFC in each of your Flash Remoting applications to test your connection. As you build more Flash Remoting applications, you will find that connecting to your remote service can be your biggest headache. Your code should look as follows:

 // Import the Flash Remoting Classes import mx.remoting.Service; import mx.services.Log; import mx.rpc.RelayResponder; import mx.rpc.FaultEvent; import mx.rpc.ResultEvent; import mx.remoting.PendingCall; import mx.remoting.RecordSet; import mx.remoting.DataGlue; // Connect to the Gateway // Establish the Service var unleashedService : Service = new Service(  "http://localhost/flashservices/gateway",   new Log (Log.DEBUG),  "unleashedCafeSite.unleashedCom",  null,  null); // Test the Connection function getTestConn(){ //Create a PendingCall objects var testConn_pc:PendingCall = unleashedService.getTestConn(); //Use the responder property to handle the success for failure testConn_pc.responder = new RelayResponder(this, "getTestConn_Result", "getTestConn_Fault"); } //Handle the Success function getTestConn_Result(re:ResultEvent){ trace(re.result); } //Handle the Failure function getTestConn_Fault(fault:FaultEvent):Void{ trace("error"); } //Start the Application getTestConn();