This specification is for a feature added to the BlazeDS flex-messaging-core.jar file in in July 2008.
This feature appears in BlazeDS builds greater than 3.1.0.2602.

Java AMF Client

Feature Summary

This feature will provide a Java based AMF client. Using this feature, customers will be able to write and read AMF messages using Java on the client (i.e. no Flash player). This in turn will enable Java applications talk to AMF compliant servers such as BlazeDS, LCDS, or AMFPHP.

The initial implementation will be similar to the Flash Player's flash.net.NetConnection and Peter Farland's flex.net.AMFConnection but the APIs will be more Java-like and less Actionscript-like. It will be called AMFConnection since no RTMP will be supported.

Future Work

After the initial AMFConnection implementation, further work can be done to convert all BlazeDS client side code such as Channels, Producer, Consumer, RemoteObject, to Java but all of these are out of scope for this feature.

Functional Description

Motivation for the feature

Joe Doe is a Java developer who recently started investigating Flex for his rich internet application (RIA). He builds amazing prototypes in no time using Flex's rich UI capabilities. After having convinced his boss to use Flex for his project, he wants to feed a ton of data to his Flex application to make it a true RIA. Soon, he discovers yet another goodness from Adobe: BlazeDS and he uses BlazeDS's RemoteObject to get data to his Flex application from his J2EE server using highly efficient binary AMF format.

With his UI and data rich internet application and efficient AMF format over the wire, life could not get any better for Joe…Until his boss knocks on his door one day about a requirement that he had forgotten to mention before and it goes like this: The legacy (not so UI rich) Java clients also need to be able to get to the same data the Flex application can get and they have to do so in the efficient AMF format.

At this point, Joe is devastated. He doesn't have time or interest to write an AMF serializer/deserializer in Java. Only if he had something like flash.net.NetConnection in Java where he can make simple Flash remoting calls to the BlazeDS server and process the AMF responses. So, this feature is for people like Joe where they need a Java client to be able to serialize AMF messages, send them to an AMF compliant server and deserialize AMF responses from those servers.

Basic usage

From user's perspective, this feature will be a number of Java classes with public APIs for connecting to a remote AMF compliant server and making Flash remoting calls similar to Flash's NetConnection (See the API Description section). Here's an example of how it will work:

// Create the AMF connection.
AMFConnection amfConnection = new AMFConnection();

// Connect to the remote url.
String url = "http://localhost:8400/team/messagebroker/amf";
try
{
    amfConnection.connect(url);
}
catch (ClientStatusException cse)
{
    System.out.println(cse);
    return;
}

// Make a remoting call and retrieve the result.
try
{
    Object result = amfConnection.call("remoting_AMF.echo", "echo me1");
}
catch (ClientStatusException cse)
{
    System.out.println(cse);
}
catch (ServerStatusException sse)
{
    System.out.println(sse);
}

// Close the connection.
amfConnection.close();

What this feature is not

• It is not full implementation of BlazeDS Actionscript client libraries. It will strictly be a mirror of Flash player's NetConnection but no Channels will be built on top of it. Similarly, no Consumer, Producer, etc. of BlazeDS will be implemented on top.
• Flash player's NetConnection supports RTMP. AMFConnection will not support RTMP, and hence the name AMFConnection instead of NetConnection.

Detailed Design

AMFConnection and AMFHeaderProcessor

As mentioned before, AMFConnection is the main class for this feature. Users will connect to remote urls using AMFConnection and get ClientStatusException and ServerStatusException when things go wrong. Under the covers, AMFConnection will use BlazeDS's AMF serialization/deserialization code along with an HTTP library to make HTTP requests (details further down).

Similar to NetConnection, AMFConnection will support a way to process AMF headers. In NetConnection there is client property which indicates the object on which callback methods should be invoked during AMF header processing. In AMFConnection, there will be an AMFHeaderProcessor interface for it.

Cookies will be automatically handled by AMFConnection. Note that AMFConnection and all other classes will be written in Java5.

AMF serialization and deserialization

AMFConnection will need BlazeDS's flex.messaging.io.* code (which lives in flex-messaging-core.jar) to do AMF serialization/deserialization. We will put AMFConnection and its supporting classes in flex.messaging.io.* package and ask people to compile against flex-messaging-core.jar.

Http request and response mechanism

We have two choices for making Http requests from the Java AMF client. Java's URLConnection/HttpURLConnection and Apache Common's HTTPClient .

We want to use Java's URLConnection to avoid a 3rd party library. The biggest advantage of HTTPClient over URLConnection is that HTTPClient supports cookies. However, cookie support will be added to URLConnection as well.

Package and jar names

AMFConnection and its supporting classes will live in flex.messaging.io.amf.client* package, and it will be jar'ed into flex-messaging-amf.jar along with BlazeDS's AMF serialization code.

API Description

These are the supported public APIs.

public AMFConnection();

public static void registerAlias(String alias, String className);

public void addAmfHeader(String name, boolean mustUnderstand, Object data);
public void addAmfHeader(String name, Object data);
public boolean removeAmfHeader(String name);
public void removeAllAmfHeaders();

public void addHttpRequestHeader(String name, String value);
public boolean removeHttpRequestHeader(String name);
public void removeAllHttpRequestHeaders();

public Object call(String command, Object ... arguments) throws ClientStatusException,
                                                                ServerStatusException;
public void connect(String url) throws ClientStatusException;
public void close();

public AMFHeaderProcessor getAMFHeaderProcessor();
public void setAMFHeaderProcessor(AMFHeaderProcessor amfHeaderProcessor);

public static int getDefaultObjectEncoding();
public static void setDefaultObjectEncoding(int value);

public int getObjectEncoding();
public void setObjectEncoding(int value);

public String getUrl();

.

public interface AMFHeaderProcessor
{
    public void processHeader(MessageHeader header) throws ClientStatusException;
}

Error Handling

There are two types of errors/status. First, AMF messages that have onStatus in their target uri. These are basically errors/status sent by the server and will be thrown as ServerStatusException. Second, errors/status that happen on the client in AMFConnection such as connect failures, or connect close status notification. These will be thown as ClientStatusException. ClientStausException will try to mirror NetConnection's NetStatusEvent in terms of status codes and currently it has the following codes which might expand as the feature is implemented:

• AMFConnection.Call.Failed
• AMFConnection.Connect.Failed

Dependencies and Risks

None.

Compatibility

This feature provides AMF support to Java clients which is completely new. However, AMFConnection should work against BlazeDS remoting destinations with no problems, along with other AMF compliant server such as LCDS.

Security Considerations

None.

Performance Issues

None.

Standards Consideration

• AMF0 spec
• AMF1 spec