Introduction to Haxe Remoting

Haxe Remoting is a way to talk between different platforms. With Haxe remoting you can communicate transparently, send data and call methods, between Server Side, JavaScript and Flash.

In order to use remoting, you need to establish a Connection first. There are two kinds of Haxe Remoting connections : haxe.remoting.Connection and haxe.remoting.AsyncConnection. As the names imply, the first one is used for synchronous connections where for example the method result can be directly obtained when calling a method, and the other one is an asynchronous connection where call results are events that will happen later in the execution process.

The following constructors are available to build a connection :

  • on all platforms :
    • HttpAsyncConnection.urlConnect(url : String)
      will return an asynchronous connection to the given URL that can be a Haxe/Server application. See below on how to implement the server side part.
  • in Flash :
    • ExternalConnection.jsConnect(name:String, ctx:Context)
      will return a connection to the local JavaScript Haxe code. The JS Haxe code must be compiled with the class ExternalConnection included. This is only working with Flash Player 8 and higher.
    • AMFConnection.urlConnect(url : String) and
      AMFConnection.connect( cnx : NetConnection )
      allows you to connect to an AMF Remoting server such as Flash Media Server or AMFPHP.
    • SocketConnection.create( sock : flash.XMLSocket )
      allows remoting communications over an XMLSocket
    • LocalConnection.connect( name : String )
      allows remoting communications over a Flash LocalConnection
  • in Javascript :
    • ExternalConnection.flashConnect(name:String,obj:String,ctx:Context)
      will return a connection to the given Flash Object. Some HTML properties must be set. This will only work with Flash 8 and higher. Please note that the Haxe Flash content must be loaded and it must include the haxe.remoting.Connection class.
  • in Neko :
    • HttpConnection.urlConnect(url : String)
      will work as the asynchronous version but in synchronous mode.
    • SocketConnection.create(...)
      can be used for real time communications with a Flash client which is using an XMLSocket to connect to the server.

Flash/JavaScript communications are only supported for Flash Player >= 8.

Data Serialization

Haxe Remoting can send a lot of different kinds of data:

  • int and float numbers
  • strings
  • booleans
  • null
  • arrays
  • anonymous objects
  • classes instances (see below)
  • enums instances (see below)

Haxe Serialization can be used apart from Haxe Remoting by using the classes haxe.Serializer and haxe.Unserializer. It enables you to store all kinds of data for medium or long term storage as a String.

Classes and Enum instances can be serialized as well using Haxe Serialization. You only have to be sure that the class exists when unserializing the data or an exception will be raised. The fields and the class/enum names are stored in the serialized data, so for example when you add methods after serialization, they will be present when unserializing the data.

Please be careful, there is no versioning, so if you modify a class field type by changing "Int" to "String" or rename a field, the previously serialized data will not be synchronized with your new class type.

Using the Connection

Using a synchronous connection is pretty easy. Once you obtained your connection, you can simply use classic dot-access to evaluate a path and then use call() to call the method and get the result:

var cnx = haxe.remoting.ExternalConnection.jsConnect("default",null);
// call the JS method api.myMethod(0,1)
trace(cnx.api.myMethod.call([0,1]));

When an error occurs in a synchronous call, an exception is raised on the caller-side, as if you were calling a local method.

Using the AsyncConnection

The asynchronous connection is a bit more tricky since instead of directly returning the result, it's taking an additional function parameter that will be called when the result is available :

var cnx = haxe.remoting.HttpAsyncConnection.urlConnect("http://localhost");
// setup error handler
cnx.setErrorHandler( function(err) trace("Error : "+Std.string(err)) );
// result handler
var onResult = function(r) trace("Result : "+Std.string(r));
cnx.api.myMethod.call([0,1],onResult);

When an error occurs in an asynchronous call, the exception value is passed to the error handler.

Remoting Context

Now that you have seen how you can call some methods, let's see how you can share an API so it can be called.

For this we will be using the Context class :

// create an empty context
var ctx = new haxe.remoting.Context();
// share the object "api" containing one single method
ctx.addObject("api",{ myMethod : function(a,b) return a + b });
// connect from Flash to JS and allow the content of ctx to be called
var cnx = haxe.remoting.ExternalConnection.jsConnect("default",ctx);

As you can see, once a Context is created, you can share several objects whose methods are allowed to be called. The Context is then used when initializing the connection.

From Here

Now that you know how to use a Remoting Connection, you can proceed to the other tutorials that will show examples of different kind of connections.

version #6006, modified 2009-05-20 23:29:00 by adnez