Recipe 20.1 Establishing a Connection via Flash Remoting

20.1.1 Problem

You want to establish a connection to the Flash Remoting gateway on your chosen server.

20.1.2 Solution

Pass the URL of the Flash Remoting gateway to NetServices.createGatewayConnection( ). Alternatively, set a default gateway URL using NetServices.setDefaultGatewayURL( ). As an optional, additional step, specify the gateway URL in the FlashVars attribute within the HTML page in which the Flash movie is embedded (when applicable).

20.1.3 Discussion

A Flash movie accesses Flash Remoting functionality on a sever via a connection object that communicates via a gateway. A connection object is obtained by invoking NetServices.createGatewayConnection( ). A gateway is simply specified as a URL to the appropriate server.

Within ActionScript, you have two options for setting the Flash Remoting gateway URL that a connection object uses. The exact URL varies depending on the location of your remote application and the server model in use, as described in Recipe 20.2, Recipe 20.3, Recipe 20.4, and Recipe 20.5. The most direct route is to specify the URL as a parameter when you invoke the NetServices.createGatewayConnection( ) method. For example:

#include "NetServices.as"

myConnection =
   NetServices.createGatewayConnection("http://localhost/flashservices/gateway/");

There is technically nothing wrong with this direct approach. However, a better, more flexible approach is to set a default gateway URL with NetServices.setDefaultGatewayURL( default.htm) and not specify any parameter when creating the connection object. For example:

#include "NetServices.as"

// First, set the default gateway URL.
NetServices.setDefaultGatewayURL("../localhost/flashservices/gateway/default.htm");

// Then, create the connection object without passing a parameter to the method.
myConnection = NetServices.createGatewayConnection(  );

This technique may not seem advantageous, because it requires two lines of code to do what can essentially be accomplished in one line. However, to understand the benefit of this technique, it is helpful to know how Flash decides which gateway URL to use. Flash determines the gateway as follows:

Using setDefaultGatewayURL( ) is particularly valuable when, as in most scenarios, the gateway URL changes between the development phase and the release of your application. If you hardcode the gateway URL into your Flash movie (by specifying the value in the createGatewayConnection( ) method), you must change that value and reexport the Flash movie before publishing it to the production environment.

The recommended scenario is to set the default gateway URL in your Flash movie to the server that you use for development and/or testing, and do not specify a URL parameter for the createGatewayConnection( ) method. This way, you can easily test your movie during development. For example:

#include "NetServices.as"

NetServices.setDefaultGatewayURL(
    "http://development.server.com/flashservices/gateway/");
myConnection = NetServices.createGatewayConnection(  );

Then, in the HTML page in which the Flash movie is embedded for production, set a gatewayUrl variable with the production server's URL. Use the FlashVars attribute to accomplish this (shown in bold in the following code listing). In this way, you do not have to make changes to the Flash movie between the development and production environments.

<OBJECT 
  classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
  codebase="http://download.macromedia.com/pub/shockwave/
cabs/flash/swflash.cab#version=6,0,0,0"
  WIDTH="100%"
  HEIGHT="100%"
  id="myMovie">
<PARAM 
  NAME=flashvars
  VALUE="gatewayUrl=http://localhost/flashservices/gateway">
<PARAM NAME=movie VALUE="myMovie.swf">
<PARAM NAME=quality VALUE=high>
<PARAM NAME=bgcolor VALUE=#FFFFFF>
<EMBED src="myMovie.swf"
  FLASHVARS="gatewayUrl=http://localhost/flashservices/gateway"
    quality=high
  bgcolor=#FFFFFF
  WIDTH="100%"
  HEIGHT="100%"
  NAME="myMovie"
  TYPE="application/x-shockwave-flash"
  PLUGINSPAGE="http://www.macromedia.com/go/getflashplayer">
</EMBED>
</OBJECT>

20.1.4 See Also

Recipe 20.2 discusses the proper gateway URL for ColdFusion applications. Recipe 20.3 discusses the proper gateway URL for .NET applications. Recipe 20.4 discusses the proper gateway URL for J2EE applications. Recipe 20.5 gives pointers to resources for using Flash Remoting with PHP and Perl.