Using the XML-RPC client

  1. Basic Use
  2. Advanced Use (Creating your own strongly-typed service class)
  3. Remote Method parameters
  4. Retrieving results
  5. Retrieving errors
  6. Cross-domain security

There are two alternative ways to use the XML-RPC classes to execute remote method calls. The first “basic” approach parallels exactly the approach used to execute service method calls with Flash Remoting. The second works in a similar way but allows for more disciplined design — the programmer defines a typed service class with defined methods which can wrap remote methods, allowing for compile-time type safety.

Basic Use

In the basic approach, the programmer needs to do three things to carry out a remote method call:

  1. Create a Service instance
  2. Call method
  3. Assign responder property of PendingCall to specify methods to be called on Result/Fault

First you create an instance of the com.probertson.xmlrpc.Service class. In the most common scenario, you will pass in a service url and (possibly) a service name as constructor parameters. A Service instance mapping to an XML-RPC service named “math”, available at the url “http://example.com/RPC2/”, would be created with this constructor:

var myService:Service = new Service("http://example.com/RPC2/", "math", null, null);

XML-RPC method names are commonly written as two words separated by a period (e.g. “math.sum”). The “service name” parameter is the portion of the name before the period. The method name (which is called in the next step) is the portion of the method name after the period. In the rare case that a particular url exposes XML-RPC methods that do not have a period in their name (e.g. just “sum”), a Service instance can be created by passing null for the service name parameter.

Next you call the remote methods as methods of the Service instance. For example, if the remote service exposes a method named “sum” which takes two integer parameters, we can call that method as a method of our Service instance like this:

var myPendingCall:PendingCall = myService.sum(2, 3);

The parameters expected by the remote method can be added to the method call as is done with any method call (in the appropriate order, number, and types expected by the remote method). For more on acceptable parameters, see the section “Method Parameters” below.

As with SOAP web services calls and Flash Remoting calls, calls to XML-RPC methods are asynchronous. The object returned by a remote method call is not the result of the call; rather, as shown in the previous example, it is a com.probertson.xmlrpc.PendingCall instance which can be used to access the result (or error notification) when it is returned by the remote method. To retrieve a result (or notification of an error), you assign an object to the responder property of that PendingCall instance. The object you assign to the responder property must implement the mx.rpc.Responder interface; you use that Responder object to designate which methods will be called when a result or error is returned by the remote method. In the following example, an mx.rpc.RelayResponder instance is assigned as the responder property of the PendingCall:

var myResponder:RelayResponder = new RelayResponder(this, "sumResult", "sumFault");
myPendingCall.responder = myResponder;

(Note: this example assumes that there are methods named “sumResult” and “sumFault” in the class where the Service methods are being called.)

Advanced Use (Creating your own strongly-typed service class)

For people like me who are big fans of compile-time type checking, a big limitation of the Service class used in Flash Remoting (and the parallel one in this XML-RPC library) is that its methods and properties are not type-checked by the compiler. This is because the class is defined as a dynamic class — a necessity in order to allow methods to be called using the name of the remote method.

However, for cases where a service will be used extensively, or in any other case when compile-time type checking is desirable, the XML-RPC library provides an alternative approach which allows the developer to create a custom, type-safe XML-RPC Service class. This also has additional advantages. For example, it allows you to provide your own names for methods rather than requiring method names to match the remote method names exactly. It also allows you to specify certain values (such as the remote method url, or perhaps certain method parameters) as private constants in your class rather than exposing them publicly.

To create your own custom XML-RPC service class, you need to create a subclass of com.probertson.xmlrpc.ServiceBase. Your subclass’s constructor must call the ServiceBase constructor passing in all the arguments (or null as appropriate). For example, you might define the service url as a constant in your class, which is passed to the ServiceBase constructor. You can then write your own methods which will serve as wrappers for the remote methods. Each of your wrapper methods should call ServiceBase’s “call” method, passing the remote method name as the first parameter and any parameters expected by the remote method as additional parameters.

See the Advanced Math Service sample for a working example of this approach.

Remote Method parameters

The XML-RPC specification defines a limited number of types which can be used in XML-RPC method calls. These include a number of basic types, as well as the XML-RPC Struct which can be used to send/receive complex objects. The objects you pass as parameters in calls you make to an XML-RPC method (either a Service instance or internally in your own custom service class) must be one of these ActionScript types:

Note: currently the XML-RPC Base64-encoded type is not supported.

If a remote method expects a struct as a method parameter, you must define a class that you will use as an equivalent to that struct (that you will pass as an argument to the Service method call). Your struct class must implement the com.probertson.xmlrpc.IXmlRpcStruct interface. This interface requires you to define a single method, “getStructProperties,” which returns an Array (of String values) containing the names of the properties which should be included in the struct. You can define additional properties and methods if you wish; they will be ignored by the Service class and will not be sent as part of the remote method call.

Retrieving results

Often the result returned by an XML-RPC remote method call will be a single value; for instance the result of a “sum” method would be a single Number. Result values are retrieved through a mx.rpc.ResultEvent instance passed as a parameter to the method you specify as the onResult handler. The return type of the result (the result property of the ResultEvent instance) is defined as Object (since the return type can be any of the allowed XML-RPC types); however, inside the Object “box” the returned object is in fact an instantiated instance of the expected type as defined by the remote method, and can be cast/converted to the appropriate type then used in its appropriate type.

The result may be a single Array, in which case the same explanation applies — the result Object must simply be cast as an Array and can then be used as normal.

Sometimes the return type of a remote method call is an XML-RPC struct. In that case, the result (the value of the ResultEvent’s result property) will be a generic object, essentially an Object instance with properties defined to correspond to the properties specified for the struct by the remote method. You can simply access these properties as you might use the properties of any generic object/Object instance.

Alternatively, you can create your own object representing the XML-RPC struct returned by the method call, which will allow for type safety. If in your implementation you don’t need the returned object to have additional properties or methods, you can just cast the returned object to your type and it should work. However, if you need the object to have methods, constructor initialization, etc. you will need to provide a mechanism to create an instance of your class and copy the properties from the anonymous object to your instance. For example, you could have a static method that takes the anonymous object as an argument and returns an instance of your class with the property values from the anonymous object copied to properties of your class.

Retrieving errors

Occasionally, of course, a remote method call will return an error instead of a result. In that case, your specified fault handler method will be called. That method will be passed an mx.rpc.FaultEvent argument, which in turn has a fault property containing an mx.rpc.Fault instance (in this implementation, the Fault instance will be a com.probertson.xmlrpc.XmlRpcFault instance). You can see the documentation for the Fault class to find out the properties which are available as part of that class; however, only the faultstring and faultcode properties will contain information (the other properties will be null when a Fault is returned by an XML-RPC remote method call).

Cross-domain security

Like all ActionScript code that accesses remote urls, remote method calls made using the XML-RPC classes are subject to the Flash Player requirements on cross-domain security. For a detailed explanation and solutions, see the Flash documentation on Flash Player cross-domain data access security.