Flash Remoting TechNote

Common questions about Flash Remoting

Flash Remoting Overview

• What is Macromedia Flash Remoting?
• What are the benefits of using Macromedia Flash Remoting?
• What software must be installed to use Macromedia Flash Remoting?
• What operating systems does Macromedia Flash Remoting support?
• Where can I find more information about Macromedia Flash Remoting, such as release notes?

Flash Remoting for JRun 4

• What data types does Macromedia Flash Remoting support?
• What kinds of Java objects does Macromedia Flash Remoting support?
• Where should I place my Java application files to make them available to Macromedia Flash Remoting?
• Do my Java methods need to declare that they throw Exception?
• Do my Java classes have to implement Serializable to be a Flash Remoting service?
• How do I customize the restrictions of which Java classes Flash Remoting can call in JRun 4?

Flash Remoting ActionScript

• What ActionScript classes must I import into my Flash movie to use Macromedia Flash Remoting?
• How do I make service calls to an application server from a Macromedia Flash movie?
• Does the flashservices/gateway URL map to a directory on my server?
• How do I handle the results returned from a service call?
• How do I display service call results in Macromedia Flash MX UI components?

What is Macromedia Flash Remoting?

Macromedia Flash Remoting provides the infrastructure that lets you connect to remote services exposed by application server developers and web services. Flash Remoting simplifies the Flash application development process by providing a programming mode and runtime support for connecting ActionScript directly to remote server objects.

By storing information in a database and retrieving it, you can create dynamic and personalized content for your Flash movies. For example, you could create a message board, personal profiles for users, or a shopping cart that keeps track of a user's purchases so that it can determine the user's preferences.

Macromedia Flash Remoting supports object-based access, such as Java objects, and XML document processing to exchange data with any remote service, including an Enterprise JavaBean (EJB), a Java class, JavaBeans, or an MBean.

What are the benefits of Macromedia Flash Remoting?

The following table describes the features of Flash Remoting and the benefits:

What software must be installed to use Macromedia Flash Remoting?

• Macromedia Flash MX (www.macromedia.com/software/flash/)
• Flash Remoting Components (www.macromedia.com/software/flash/flashremoting/)
• JRun 4 (www.macromedia.com/software/jrun/)
• Macromedia Flash Player 6 (www.macromedia.com/software/flashplayer/)

The Flash Remoting service is embedded in the JRun 4, so no server-side installation is required.

What operating systems does Macromedia Flash Remoting support?

Macromedia Flash MX and the Flash Remoting Components support Windows and Macintosh. For more information about what version of Windows and Macintosh that Macromedia Flash MX and Flash Remoting Components, see www.macromedia.com/software/flashplayer/. For more information about the operating systems supported by JRun 4, see www.macromedia.com/software/jrun/.

Where can I find more information about Macromedia Flash Remoting, such as release notes?

Visit the Macromedia Flash Remoting Support Center at www.macromedia.com/support/flash/flashremoting/.

What data types does Macromedia Flash Remoting support?

The following table contains the ActionScript data types and their Java equivalents:

The following table contains the Java data types and their ActionScript equivalents:

What kinds of Java objects does Macromedia Flash Remoting support?

On JRun, Flash Remoting supports the following kinds of Java objects:

• Java classes (stateless)
• JavaBeans objects (stateful)
• Enterprise JavaBeans (EJBs; stateless session, stateful session, and entity beans)
• Java Management Extensions (JMX) MBeans

Where should I place my Java application files to make them available to Macromedia Flash Remoting?

Users can either add directories to the server's JVM Classpath using the JMC, or use the SERVER-INF directory associated with the server. To use the SERVER-INF directory, for standard Java classes, including JavaBeans, you put the classes under jrun_root/servers/jrun_server/SERVER-INF. Loose classes go in a classes subdirectory and jarred classes go in a lib subdirectory; the classes are available server-wide. By default, Remoting doesn't have access to classes in a web application, but you can put the Flash Remoting JAR file in a web application and add a servlet mapping to the web application's web.xml file. You can also place Java classes in the jrun_root/lib directory if you want them to be available to the entire JRun installation. Note also that when you do put classes under a WEB-INF directory, loose classes go in WEB-INF/classes and jarred classes go in WEB-INF/lib.

Do my Java methods need to declare that they throw Exception?

Not at all. Typically you would throw Exceptions when you care about propagating application exceptions to your Flash client, but the gateway itself doesn't handle checked exceptions. Java methods don't need to declare that system exceptions (Runtime Exceptions) are possible, they only need to indicate un-checked application exceptions. So if a system exception occurs, it will still be propagated to your Flash client without your having to declare it in the code.

Do my Java classes have to implement Serializable to be a Flash Remoting service?

If you're creating a JavaBean, then you must implement Serializable; you do not need to use the Serializable interface for plain old Java objects. If the JavaBean service adapter in the gateway finds that your targeted service is a Java class that is Serializable -- that it implements Serializable and all its fields are in fact Serializable and therefore capable of object streaming through Http sessions -- it makes a blanket assumption that you wish the service to be stateful to your client. So it will stash the instance in your HTTP session. If the targeted service is not serializable, no state is maintained and the service is treated as a stateless Java class. To avoid circumventing the resource optimizations in modern garbage collectors, no object pooling is performed in the Java adapter, either.

How do I customize the restrictions of which Java classes Flash Remoting can call in JRun 4?

As such, if you wish to allow clients to connect to your own Java classes, you can modify a policy file to expand the permissions granted. For example, to allow the gateway to access classes in the com.macromedia package, add the following line to the lib/jrun.policy file. This will open access to the package to all users, which is not necessarily a bad thing in the com.macromedia case (since it's not a common package in our servers).

// PERMISSIONS GRANTED TO EVERYONE
grant {
// users should narrow or expand on this as they see fit
// to grant wide-open security access to all code, uncomment this line
//permission java.security.AllPermission;
// to grant clients access to classes in the jrun packages, uncomment this line
//permission java.lang.RuntimePermission "accessClassInPackage.jrun";
// add this line
 permission java.lang.RuntimePermission "accessClassInPackage.com.macromedia";
 //snipped
}

Currently, Java only allows package-level declarations.

What ActionScript classes must be imported into the Flash movie for Macromedia Flash Remoting?

You must include the ActionScript classes for Flash Remoting in the frame-level actions for a movie. The core functionality is provided by the NetServices.as and must be included. The two other ActionScript files, NetDebug.as and DataGlue.as are optional. The NetDebug ActionScript class is intended for development only. All references should be removed before deploying the Flash movie to a production server. DataGlue helps format results that use the RecordSet object.

The following command includes the NetServices API:

#include "NetServices.as"

The following command includes the NetDebug API:

#include "NetDebug.as"

The following command includes the DataGlue API:

#include "DataGlue.as"

The NetDebug ActionScript class is intended for development only. All references should be removed before deploying the Flash movie to a production server.

How do I make service calls to an application server from a Macromedia Flash movie?

To make service calls to an application server using Flash Remoting, you must first create a service object in your Flash movie using the NetServices functions createGatewayConnection and getService to create a connection object. The following code example creates a service object named myService:

#include "NetServices.as"

if (inited == null)
{ 
  // do this code only once
  inited = true;
         
  // set the default gateway URL (this is used only in authoring)
  NetServices.setDefaultGatewayUrl("http://localhost:8100/flashservices/gateway");
         
  // connect to the gateway
  gateway_conn = NetServices.createGatewayConnection();
         
  // get a reference to a service
  myService = gateway_conn.getService("my.service", this);
}

As the example shows, you can use the setDefaultGatewayUrl function to specify a Flash Remoting service URL for all service calls in the Flash movie. However, the setDefaultGatewayUrl function should only be used in the Macromedia Flash authoring environment. The service name, my.service, translates to the fully-qualifed name of the Java object.

Once you have created the connection object, you can make service calls to the application server, as the following example shows:

myService.remoteServiceMethodName(param1, "param2");

Does the flashservices/gateway URL map to a directory on my server?

The Flash Remoting service URL does not translate to an actual directory structure on your web or application server. The URL, which ends in flashservices/gateway, specifies the web application context and gateway servlet mapping for the Flash Remoting service.

How do I handle the results returned from a service function?

Users can either provide specific result handlers or generic result handlers. Also, a responder can be provided at the service level for all method calls, or provided as the first parameter to each individual method call.

Using the timeline "this" as the default responder objects, with specific callback handlers:

//Use the timeline as the default responder, passed as the second parameter
//to get service
myService = gateway_conn.getService("my.service", this);
...
//service function
myService.remoteMethodName(param1, "param2");
// a function that handles the results
// from the remoteMethodName function
function remoteMethodName_Result ( result )
{ 
 myListBox.setDataProvider(result);
}
// a function that handles the errors 
// thrown by the remoteMethodName function
function remoteMethodName_Status ( result )
{ 
 myListBox.setDataProvider(result);
}

Using a custom responder object, with generic callback handlers as the default responder:

MyResponder = function()
{
 this.onResult = function(result)
   {
    //Response handling code goes here
    trace(result);
   }
   this.onStatus = function(error)
   {
    //Error handling code goes here
    trace(error);
   }
}
   
...

//Use our custom responder object, passed as the second parameter to get service
myService = gateway_conn.getService("my.service", new MyResponder());

... 

Providing a custom responder object to each method call:

...
//Each method call will its own responder object
//Note that the second parameter to getService is not used. 
myService = gateway_conn.getService("my.service");
... 
   
myService.remoteMethodName(new MyResponder(), param1, "param2");

How do I display the results returned from a service function using Macromedia Flash MX UI components?

When working with Macromedia Flash MX UI components, you can display recordsets using the setDataProvider method of the ListBox and ComboBox components. You can also use the DataGlue functions, including bindFormatStrings and bindFormatFunction. The DataGlue function binds a data provider, such as a RecordSet object created on the server, to a data consumer, such as a ComboBox component. The data appear as standard label/data pairs.

The DataGlue functions do not make a copy of the original data provider's data. However, the data is fetched from the original data provider as needed by the data consumer. The data consumer can use the data like any other parameter. The label of each record is the text that is displayed for the record. The data of each record is the value that is returned by the data consumer's getValue function. The bindFormatStrings function lets you format the data in the function call. For example:

DataGlue.bindFormatStrings(myComboBox, myRecordSet, "#parkname# ¬
(#parktype#)", "#city#, #state# #zipcode#");

Note: The lines of code above should be written as one continuous line, as indicated by the "¬" symbol.

In this example, myComboBox represents a ComboBox component in the Flash movie, and myRecordSet represents the RecordSet object. The parkname, parktype, city, state, and zipcode variable represent record field names. The ComboBox displays the parkname and parktype variables. The city, state, and zipcode variables are returned when the user selects the record. You can use the getValue function to return the value.

The bindFormatStrings function lets you call a function to format the data. You create the function as shown in the following example:

function myFormatFunction ( record )
{
  // the label is the parkname record field, translated to lower case
  var theLabel = record.parkname.toLowerCase();
        
  // the data is the length of the parkname record field
  var theData = record.parkname.length;
         
  // return the label and value to the caller
  return {label: theLabel, data: theData};
}
//call the bindFormatFunction
DataGlue.bindFormatFunction(dataView2, result, myFormatFunction);

In this example, record represents a RecordSet object, and dataView2 represents a UI component in a Flash movie.