2.4 Sequence of Events in Flash

To access a remote service from Flash, your movie must initiate a connection using the NetServices.createGatewayConnection( ) method, which returns a NetConnection object through whose properties, methods, and events you'll manage the connection. You need to know the gateway URL for your Flash Remoting server in order to make a connection. The connection is defined one time for ColdFusion and J2EE servers, even if your movie accesses multiple services via the gateway. However, each ASP.NET service requires its own call to createGatewayConnection( ). In either case, each NetConnection object persists for the entire session. Note that when you create this connection object no call has been made to the server yet.

You'll call methods of the NetConnection object to manage the connection and access the remote service. The two NetConnection methods used most frequently in Flash Remoting applications are setCredentials( ) and getService( ). The setCredentials( ) method is used to authenticate a user.

As of this writing, setCredentials( ) is available for ColdFusion MX and JRun 4 only. It is covered in Chapter 5.

The getService( ) method sets up the call to a remote service by creating a service object, which contains the required information for Flash Remoting to make subsequent calls to methods of that remote service. The getService( ) method's parameters are the same when using any of the service types shown previously in Table 2-8; the service is called by name and Flash makes no assumption about the type of service being called. The syntax for calling the getService( ) method of the NetConnection object looks like this:

myService = myConnection_conn.getService(serviceName[, responderObject]);

where myConnection_conn is a NetConnection object returned by an earlier call to createGatewayConnection( ). The first parameter, serviceName, is a service name such as com.oreilly.frdg.HelloWorld. The optional second parameter, responderObject, is an object that will handle responses from future calls to methods of the remote service. We'll defer a detailed discussion of the many different ways to set up responder objects and service callbacks until Chapter 4. For now, simply note that our responder object defines onResult( ) and onStatus( ) methods that handle the results or errors returned when we invoke methods of the remote service.

When you call a method of your service, an AMF packet is sent to the remote service. The response of that remote service is automatically sent to responderObject.

The responderObject argument does not receive the result of the getService( ) call itself, which we stored in myService. Instead, responderObject is used to obtain the results from subsequent calls to methods of the service. Therefore, responderObject isn't used until a remote method call is executed. The myService object is simply a proxy through which you can make calls to methods of the remote service.

After initializing the connection with createGatewayConnection( ) and specifying a service with getService( ), you can call methods of the service using the object returned by getService( ). We stored that object in myService, so we can access methods of the remote service this way:


Each call to a method of the remote service returns an AMF packet, as described in Chapter 1. That packet is automatically sent to the responder object specified in the earlier call to getService( ). Your ActionScript code should handle the response events using onStatus( ) and onResult( ) functions as methods of the responder object. Alternative ways to handle these events are covered in Chapter 4.

An onStatus event is returned from the remote service if there were any errors. The onStatus( ) function must handle the errors and act accordingly. An onResult event is returned from the remote service if there were no errors. The onResult( ) function must handle the results of the service call and act accordingly.

Don't confuse the onStatus and onResult events with the onStatus( ) and onResult( ) methods that handle them. The events are returned in a serialized form from the server and deserialized by the NetServices class on the client. When that happens, the associated event handler is triggered. That is, the onStatus( ) and onResult( ) methods act as callback functions for the onStatus and onResult events.

    Part III: Advanced Flash Remoting