Using Flash Remoting MX
Using Flash Remoting Components in ActionScript

Configuring Flash Remoting MX

Before you can call a remote service, you must configure Flash Remoting MX:

Note:   The client does not access the remote server when you configure Flash Remoting MX. The client first communicates with the remote server when it makes a first service function call.

To configure Flash Remoting MX:

1. Create the Flash Remoting connection object.
2. Create the service object.
3. If your application server or service requires user authentication, provide the authentication information.

The following sections describe these steps.

Creating the Flash Remoting connection object

When you configure a Flash Remoting connection, you identify a remote gateway for Flash to use in remote service requests and create a NetConnection object that enables Flash Remoting MX to connect to the remote gateway.

To create a Flash Remoting connection object:

1. Specify the gateway URL.
2. Create a NetConnection object that uses the specified URL.

You have several options for doing these steps, including the following:

• You can use the NetServices.createGatewayConnection method to specify the URL and create the NetConnection object.
• You can use a NetServices.setDefaultGatewayURL method to specify a default gateway, and use the NetServices.createGatewayConnection method without a URL to create the NetConnection object. Flash Remoting MX uses the default gateway for all connections that you create without otherwise specifying a gateway.
• You can specify the gateway in the web page you use to deploy the SWF file, and use the NetServices.createGatewayConnection method without a URL to create the NetConnection object.

You can combine these techniques. If you do so, the gateway URL is determined as follows:

1. A URL specified in a createGatewayConnection method takes precedence over any other URL.
2. A URL specified in the deployed web page takes precedence over a default gateway URL.
3. If you do not otherwise specify a gateway URL, Flash Remoting MX uses the gateway specified in a NetServices.setDefaultGatewayURL method.

Macromedia recommends using the setDefaultGatewayURL method to specify the URL of the gateway that you use in the Flash MX authoring environment. Doing so lets you test your Flash Remoting application directly in the development environment, without having to change your code when you deploy your application. When you deploy the SWF file, supply the production gateway URL in the web page that you use to run the Flash application. This way, you also do not have to make any changes in your Flash application to deploy the SWF file on different application servers.

Specifying the gateway in the NetServices createGatewayConnection method

To configure a connection to a specific gateway, use the createGatewayConnection method; for example:

var gatewayConnection = NetServices.createGatewayConnection("http://apps.mycompany.com/flashservices/gateway");

The gatewayConnection object returned by this method is the NetConnection object for the connection. You use this object to set security credentials, if required, and to get the Flash Remoting service or services that you will use.

This technique has the disadvantage of a hard-coded URL. To change the gateway URL, you must change the ActionScript and publish and deploy your movie.

Using the NetServices setDefaultGatewayURL method

The setDefaultGatewayURL method sets a default value for the gateway URL, which the createGatewayConnection method uses if you do not otherwise supply the Flash Remoting service URL. For example:

NetServices.setDefaultGatewayURL("http://apps.mycompany.com/flashservices/gateway")

var gatewayConnection = NetServices.createGatewayConnection();

Because you set a default gateway URL, you do not always need to specify the gateway URL elsewhere. However, you can override the default value by specifying a gateway URL in the createGatewayConnection method or in the web page that calls your SWF file.

Setting a default gateway URL provides you with the greatest flexibility in both development and deployment. It lets you provide a URL that works when you test your movie directly in the Flash development environment. It also lets you override the default value with a server-specific gateway when you deploy your movie.

Note:   If you specify localhost as the host in the setDefaultGatewayURL method, and you run your Flash application from outside the Flash development environment or stand-alone Flash player, Flash Remoting MX does not use localhost as the default gateway host. Instead, it replaces localhost and any port specified in the setDefaultGatewayURL method with the host and port specified to run the Flash application. For example, if you specify http://localhost/flashservices/gateway in the setDefaultGatewayURL method and start your Flash application by using the URL http://apps.mycompany.com:8500/flashapps/myapp.swf in a web page or browser, Flash Remoting MX uses http://apps.mycompany.com:8500/flashservices/gateway as the default gateway URL.

Specifying the gateway in a web page

You specify the gateway in the web page that loads your SWF file by adding entries in the OBJECT tag that calls the SWF file. You must use different techniques for Internet Explorer and Netscape browsers:

• To specify the gateway for Internet Explorer, specify the gateway URL as a flashvars parameter in an HTML PARAM tag inside the OBJECT tag body.
• To specify the gateway for Netscape, specify the gateway URL as a flashvars attribute to the HTML EMBED tag that specifies the Flash application.

The following HTML example runs the myMovie.swf Flash application and specifies
http://apps.myCompany.com/flashservices/gateway as the URL for the Flash Remoting services gateway. The first highlighted line contains the code for Internet Explorer. The second highlighted line contains the code for Netscape.

<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://apps.myCompany.com/
    flashservices/gateway">
<PARAM NAME=movie VALUE="MyMovie.swf"> 
<PARAM NAME=quality VALUE="high"> 
<PARAM NAME=bgcolor VALUE="#000099">
  <EMBED src="MyMovie.swf"
    FLASHVARS="gatewayURL=http://apps.mycompany.com/flashservices/gateway"
    quality=high bgcolor="#000099" 
    WIDTH="100%" 
    HEIGHT="100%" 
    NAME="movieName"
    TYPE="application/x-shockwave-flash"   
    PLUGINSPAGE="http://www.macromedia.com/go/getflashplayer">
  </EMBED>
</OBJECT>

Note:   If you specify the Flash Remoting gateway in the web page, the ActionScript #include NetServices.as directive must be on the main movie timeline, not in a movie clip.

Identifying the gateway

The specific format of the URL that you use to specify the gateway depends on the application server to which you are connecting:

• If you are connecting to a Java server or Macromedia ColdFusion MX, use the following format:

  http://webServer[:port]/flashservices/gateway
  

  In this URL, flashservices is the name of the Java application context, and gateway is the servlet mapping. If you do not use the default Flash Remoting deployment configuration, replace flashservices with the application context, and replace gateway with the servlet mapping.

• If you are connecting to a .NET server, use the following format:

  http://webServer[:port]/flashremoting/gateway.aspx
  

  In this URL, flashremoting is the logical directory used for Flash Remoting MX, and gateway.aspx is an intentionally blank file installed with Flash Remoting MX; the aspx suffix identifies this as a .NET request. If you do not use the standard installation configuration for Flash Remoting MX, you might need to change these values to reflect your configuration.

Creating the service object

Before you access a service function, you must use the getService method of the gateway connection object to create a service object in the Flash client. The gatewayConnection.getService method takes the following two parameters:

• The service name.
• Optionally, the name of the Flash responder object that will receive the results. If you omit the Flash responder, you must specify a Flash responder in each service function call. For more information on considerations for specifying a Flash responder, see "Handling service results".

The following example shows the getService method for a weather service:

if (inited == null)

{
  inited = true;
  NetServices.setDefaultGatewayURL("http://localhost/flashservices/gateway")
  gatewayConnection = NetServices.createGatewayConnection();
  weatherService =
    gatewayConnection.getService("flashExamples.weatherStation", this); 
}

In this example, you create the weatherService service object.

By specifying this as the responder object, you specify that the current Flash object is also the responder. It is a common practice to create the service object and define the result-handler callback routines in a single Flash object.

Specifying a service

The service name format depends on the type of service you are using. The following table lists how you specify service names for the supported service types:

Service type	Service name	Example
Web services (accessed through ColdFusion or .NET servers)	URL of the WSDL file for the service.	http://www.xmethods.net/sd/2001/BabelFishService.wsdl
ASP.NET pages (.aspx)	Logical directory path from the web root. Replace all slash or backslash characters in the path with periods.	FlashGateway.Samples.Weather Service
DLL files (.dll)	Fully qualified class name.	Flashgateway.Samples.Weather Service
EJBs	JNDI name of the EJBHome binding.	com.mycompany.samples.WeatherService
Java classes, including JavaBeans	Fully qualified Java class name.	com.mycompany.samples.WeatherService
Java servlets	Web application context root.	WeatherService
JMX (JRun 4 only)	MBean object name.	DefaultDomain:service= DeployerService
ColdFusion pages (.cfm)	Path from the web root to the page's directory. Replace all forward slash or backward slash characters in the path with periods.	Flashgateway.samples.Weather Service
ColdFusion components (.cfc)	Qualified ColdFusion component name starting from the web root.	Flashgateway.samples.Weather Service

For example, to create a service object for the Babelfish web service, specify a line similar to the following:

babelfishService = gatewayConnection.getService("http://www.xmethods.net/sd/2001/BabelFishService.wsdl", this);

EJB considerations

If you are accessing EJBs directly from ActionScript, the gatewayConnection.getService method returns the Home interface of the EJB. You must then use the Home interface create method to access the EJB. For more information, see "Calling EJBs from Flash".

Authenticating to the application server

In some cases, your application server might require you to provide user authentication -a user name and password-before you can use a service.

Flash Remoting MX provides the setCredentials method of the NetConnection object to specify authentication credentials to send to the application server. Flash then sends the credentials in the header of every service function call. This method is currently supported on the following servers:

• ColdFusion MX
• JRun 4

To use the setCredentials method, call the method after you have created the gateway object and before you call a service method. For a Flash application that is run by a single user during a session, you can call the setCredentials method any time after creating the gateway connection object, as follows:

#include "NetServices.as"

NetServices.setDefaultGatewayURL("http://www.mySite.com/flashservices/gateway");
gatewayConnection = NetServices.createGatewayConnection();
gatewayConnection.setCredentials(username, password) 
serviceObject = gatewayConnection.getService("myService", this);

Note:   To ensure security, never include specific user names or passwords in ActionScript.

Flash supplies the login credentials with each service request; therefore, your ActionScript should log the user out of the application server and reset the credentials when the user logs out of your Flash application.

To log out the user and reset the credentials:

1. Call a logout service method on the server that logs out the user. (For example, for ColdFusion, call a method that uses the cflogout tag.)
2. Set the gateway connection credential information to empty strings.

The following example shows these steps:

myService.logout();

gatewayConnection.setCredentials("", "");

The technique you use on the application server to authenticate the user and authorize access depends on the application server.

Using authentication in ColdFusion MX

If you use ColdFusion MX, the setCredentials method causes Flash Remoting MX to put the login ID and password in the ColdFusion page's CFLogin scope whenever you request a service. The Application.cfm page for the ColdFusion page or ColdFusion component should process this information as necessary in a cflogin tag. For more information on implementing security in ColdFusion, see "Securing access to ColdFusion from Flash Remoting MX".

Using authentication in JRun 4

Authentication in JRun 4 is only meaningful for EJBs, where you can use the setCredentials method to enable access to secured EJB methods. You must configure your application server for single sign on. The Flash gateway provides the security credentials to the login module. For more information on authentication in JRun 4, see "Using Flash Remoting MX with JRun security".