4.1. Essentials of Remoting

Remoting, simply put, is remote procedure calls (RPC) over the wire. Flex client applications can use RPC to communicate with remote Java objects that expose their methods as services. Such client applications can pass parameters to these remote Java objects and receive the result of these remote procedures. Java programs obviously take Java data types as inputs and return Java data types from its methods. A Flex client, on the other hand, is written in ActionScript 3 (AS3) (and its associated XML-based declarative language, MXML), so it sends and receives only AS3 objects. The remoting infrastructure needs to make the two languages talk to each other and map the data types in one language to the data types in the other. BlazeDS provides this essential infrastructure, which, apart from providing the translators, includes the communication protocol and the convenience classes that make RPC happen in an effective and efficient manner. Figure 4-1 attempts to put this definition of remoting in a diagram.

Figure 4.1. Figure 4-1

For successful remoting, components exist both on the client and the server. These client-side components act as stubs or handles for their server-side service counterparts. Client-side programs call the remote methods on these handles as if they were local. On receiving a remote procedure call, these client-side components pass the request down to their server counterparts. The server-side service classes are the real workhorses, which provide the desired service functionality.

The request-response process over RPC hops through multiple steps between the Flex client component and the remoting service. Walking through this transmission will elucidate the roles of the pieces involved.

4.1.1. Remoting Communication Flow

A picture is considered worth a 1000 words, so I have put together a sequence diagram for the flow for you. Look at Figure 4-2.

In addition, I wanted to add some words of explanation, so here it is. A RemoteObject is a client component that interacts with a remoting destination. A Flex application invokes the remote method on a remoting destination via a local RemoteObject instance. Each remoting destination can expose one or more methods. When multiple methods are exposed, each of these needs to be identified uniquely at the RemoteObject stub. On the client side, a RemoteObject stub maps an object of type mx.rpc.remoting.mxml.Operation for each of the remote methods at the remote destination. The Operation object type is associated as an attribute of the remote object instance. The name of the attribute is the same as the name of the remote method.

Figure 4.2. Figure 4-2

Therefore, if a RemoteObject were bound to a remoting service destination called someRemotingService, which exposed two remote methods, called methodA and methodB, the RemoteObject would have two attributes of types Operation, called methodA and methodB, respectively. A RemoteObject declaration and instantiation using MXML for this case could be like so:

<mx:RemoteObject
    id="aRemoteObjectInstance"
    destination="someRemotingService"
    result="aResultHandler(event);"
    fault="afaultHandler(event);"/>

The remote methods, methodA and methodB, could be accessible using aRemoteObjectInstance, as follows:

var operation1:Operation = aRemoteObjectInstance.methodA;
var operation2:Operation = aRemoteObjectInstance.methodB;

A remote method, such as methodA or methodB, can be called by invoking it, using either the remote object instance or the operation's send method. For example, each of the following results in the same method call:

• aRemoteObjectInstance.methodA()

• aRemoteObjectInstance.methodA.send()

• operation1.send()

By default, all method calls are relayed over the binary AMFChannel, that transmits AMF 3 (AMF expands to Action Message Format as mentioned in the earlier chapters) binary messages over HTTP. You know from the last chapter that communication between a Flex client and a BlazeDS instance is established using a channel-endpoint pair. Channel represents the client-side pipe and endpoint is the entry point to the pipe on the server side. If preferred, messages can also be relayed as AMF in XML (AMFX) over HTTP. This textual channel is called HTTPChannel.

Remote objects at the client side connect to BlazeDS using a channel, which is part of a channel set. The purpose of a channel set is to provide a bundle of channel options so that connection managers can fail over to an alternative lesser preferred channel in the event of unavailability of or failure at the preferred channel.

Channels are appropriately paired with endpoints so that they can connect to each other and exchange data without a problem. So an AMFChannel is paired with an AMFEndpoint, and an HTTPChannel is paired with an HTTPEndpoint.

Once a message reaches the endpoint, it is received and directed to the specified destination by the message broker. Destinations can map to local resources that reside in the web server or remote and external programs. Toward the end of the request flow and just before the actual call on the remote service sits an adapter or an assembler. The adapter is the important translator that bridges the communication gap between BlazeDS and the server side objects. POJOs use the built-in Java adapter.

A remote call to a server-side object results in a method invocation. A call to a method on a Java object always returns a value, although it can possibly be void. In some languages, null return types like void are also called none. Being a Java method, it returns a Java data type. This returned result is transferred up the wire back to the invoking client, using a route that is the reverse of the one used by the invoking call. On its way up, the result goes through a series of transformations, the most prominent of which is serialization. Serialization with translation converts Java data types to their appropriate AS3 counterparts, which become consumable objects in a Flex application. You will learn more about serialization in a later section titled "Diving into Serialization — AS3 to Java and back."

Next, details on the classes, components, and modules that make remoting happen will be covered. Many of these were already introduced in this section, so it only builds on what you have already learned.

4.1.2. Remoting-Related Classes, Components, and Modules

Starting from the client side, the first important class is RemoteObject. A RemoteObject can be instantiated in AS3 or in MXML. Therefore, a pair of classes exists, namely mx.rpc.remoting.RemoteObject and mx.rpc.remoting.mxml.RemoteObject. So, you can create an instance of the class in AS3 as follows:

Import mx.rpc.remoting.RemoteObject;

public var aRemoteObject:RemoteObject;

public function init():void {
    aRemoteObject = new RemoteObject();
    aRemoteObject.destination = "someRemotingService";
    aRemoteObject.addEventListener(ResultEvent.RESULT, aResultHandler);
    aRemoteObject.addEventListener(FaultEvent.FAULT, aFaultHandler);
}

Alternatively, you can create a RemoteObject instance using MXML as follows:

<mx:RemoteObject
    id="aRemoteObjectInstance"
    destination="someRemotingService"
    result="aResultHandler(event);"
    fault="afaultHandler(event);"/>

The MXML object is an instance of mx.rpc.remoting.mxml.RemoteObject, which extends from mx.rpc.remoting.RemoteObject. The MXML RemoteObject class implements two interfaces, namely IMXMLSupport and IMXMLObject, in addition to extending from the AS3 RemoteObject class.

Implementing the IMXMLSupport interface allows RemoteObject to be used within an MXML document via its tags. The remote object instance is a service component and does not have a visual representation. The IMXMLObject interface defines the API that nonvisual components need to implement for it to work properly with the MXML compiler. The MXML version of RemoteObject implements IMXMLObject. The initialized method implementation of the IMXMLObject type is called once the remote object is created and all the properties specified in its MXML tags are initialized.

A remote object talks to a remote service by using a channel. Flex defines a channel as a member of a channel set. A channel set is essentially a bundle of channels. One channel is usually the preferred member of such a bundle, and the others are alternatives in some order of preference. Flex supports an open source binary protocol called AMF. The current version of AMF is AMF 3. AMF 3 provides a format and a protocol to exchange data between the client and the server in a manner that is faster and more efficient that mere textual data interchange. AMF 3 builds on top of HTTP and, therefore, does not require the use of any specific ports or proprietary handshake mechanisms for participants. The class that implements an AMF-based channel is AMFChannel.

The AMFChannel extends the NetConnectionChannel class, which provides the basic support for messaging. An AMFChannel can be polling type or nonpolling type. For RPC, the polling feature can be turned off. With polling turned on an AMFChannel mimics a channel for pushing data.

An alternative to sending binary data is to send text-based data. A format called AMFX sends AMF data in XML. This sort of text-based data can be transferred over an HTTPChannel.

A channel has a physical connection with an endpoint, which is its counterpart on the server. Multiple destinations share this physical connection.

An AMFChannel binds or connects to an AMFEndpoint. The channel and endpoint pairs need to be compatible. BlazeDS's flex.messaging.endpoint package contains the definitions for the endpoints. The specific endpoint class that couples with an AMFChannel is flex.messaging.endpoint.AMFEndpoint. Artifacts in BlazeDS can be unmanaged or managed, with the help of the JMX technology. Therefore, AMFEndpoint provides two constructors, one each for unmanaged and managed scenarios. Read the note on JMX technology if you aren't familiar with it.

You know that a message broker resides at the heart of a BlazeDS instance. The message broker receives messages from endpoints and sends them down to its configured services, which are identified by its destination identifier. The message broker also sends back messages to the clients via the endpoints. The message broker is implemented by the flex.messaging.MessageBroker class. The MessageBrokerServlet bootstraps the MessageBroker and sets ups its endpoints and services. All HTTP-based calls to BlazeDS are intercepted by the MessageBrokerServlet and then passed down to the appropriate endpoint for handling. The endpoint itself is a Servlet-based URL and is part of the MessageBrokerServlet infrastructure. The message broker Servlet extends the Java HTTPServlet class. Therefore, it has the same lifecycle as a Servlet and can be configured like any other Servlet.

The services in BlazeDS are defined within the flex.messaging.services package. The RemotingService class enables the invocation of services that support remoting. It can process remoting messages, which are abstracted in a RemotingMessage class. Message type classes such as RemotingMessage can be found in the flex.messaging.messages package. Services usually have an adapter to invoke the method. The remoting message class tells the adapter which method to invoke. It also passes in the parameters for the adapter settings and the arguments for the method that is invoked.

The JavaAdapter class provides an implementation for a basic adapter that allows you to invoke methods on server-side POJOs.

To recap, let's list all the classes discussed so far in somewhat the same sequence as they appear during a typical POJO method call. The classes discussed so far are:

• mx.rpc.remoting.RemoteObject

• mx.rpc.remoting.mxml.RemoteObject

• mx.messaging.channels.AMFChannel

• mx.messaging.channels.NetConnectionChannel

• mx.messaging.channels.HTTPChannel

• flex.messaging.endpoint.AMFEndpoint

• flex.messaging.MessageBrokerServlet

• flex.messaging.MessageBroker

• flex.messaging.services.RemotingService

• flex.messaging.messages.RemotingMessage

• flex.messaging.services.remoting.adapters.JavaAdapter

All the classes in the packages whose names start with flex.messaging are from the BlazeDS Java code base. Many of these components need to be configured before they are ready to be used appropriately. The next section walks you through the details of the server configuration for supporting remoting services.