Christophe Coenraets


27 April 2009


Prerequisite knowledge

Working knowledge of LiveCycle Data Services ES or BlazeDS.

User level


Additional Requirements

LiveCycle Data Services ES

When developers start working with the RemoteObject class or other BlazeDS and LiveCycle Data Services ES classes, a common point of confusion is where the services are configured and most importantly when the configuration is read.

The question often arises after an application stops working when you move it to another server, and it is one of the most frequently asked questions related to BlazeDS and LiveCycle Data Services ES. The goal of this article is to answer it while showing you how to externalize your services configuration from your code.

Services configuration at compile time

When you create a new BlazeDS or LiveCycle Data Services ES project in Flex Builder, you will typically select J2EE as the Application Server Type and then check Use Remote Object Access Service in the New Flex Project Wizard. This adds a compiler argument that specifies the location of your services-config.xml file. If you check the Flex Compiler properties of your Flex Builder project, you'll see something like this:

-services "c:\blazeds\tomcat\webapps\samples\WEB-INF\flex\services-config.xml"

When you then compile your application, the required values from services-config.xml are baked into the SWF. In other words, services-config.xml is read at compile time and not at run time as you may have thought. To abstract things a little bit, you can use tokens such as {}, {server.port}, and {context.root} in services-config.xml. However, {context.root} is still resolved at compile time, while {} and {server.port} are replaced at runtime using the server name and port number of the server that the SWF was loaded from (which is why you can't use these tokens for AIR applications).

Externalizing services configuration

Fortunately, the Flex SDK provides an API that allows you to configure your channels at runtime and entirely externalize your services configuration from your code (you definitely do not want to recompile your application when you move it to another server).

At a high level, it works like this:

var channelSet:ChannelSet = new ChannelSet(); var channel:AMFChannel = new AMFChannel("my-amf", "http://localhost:8400/lcds-samples/messagebroker/amf"); channelSet.addChannel(channel); remoteObject.channelSet = channelSet;

Clearly, this is still not optimal because the endpoint URL is still hardcoded in the application. At least in this case it is obvious that this is happening. So, the last step in externalizing the services configuration is to pass that endpoint URL value at runtime. There are a number of ways you can pass values to a SWF at runtime, including flashVars and URL parameters.

The approach I usually use is to read a configuration file using HTTPService at application startup. That configuration file includes (among other things) the information I need to programmatically create my channel set at runtime. Here is a basic implementation:

<?xml version="1.0" encoding="utf-8"?> <mx:Application xmlns:mx="" applicationComplete="configSrv.send()"> <mx:Script> <![CDATA[ import mx.controls.Alert; import mx.messaging.channels.AMFChannel; import mx.messaging.ChannelSet; import; private var channelSet:ChannelSet; private function configResultHandler(event:ResultEvent):void { var xml:XML = event.result as XML; var amfEndpoint:String = "" +"amf").@endpoint; if (amfEndpoint == "") {"amf channel not configured", "Error"); } else { channelSet = new ChannelSet(); var channel:AMFChannel = new AMFChannel("my-amf", amfEndpoint); channelSet.addChannel(channel); ro.channelSet = channelSet; ro.getProducts(); } } ]]> </mx:Script> <mx:HTTPService id="configSrv" url="config.xml" resultFormat="e4x" result="configResultHandler(event)"/> <mx:RemoteObject id="ro" destination="product"/> <mx:DataGrid dataProvider="{ro.getProducts.lastResult}" width="100%" height="100%"/> </mx:Application>

The configuration file (config.xml) looks like this:

<?xml version="1.0" encoding="utf-8"?> <config> <channels> <channel id="amf" endpoint="http://localhost:8400/lcds-samples/messagebroker/amf"/> </channels> </config>

Note: With this type of runtime configuration in place, you can create plain Flex Builder projects (that is, you can select None as the Application Server Type).

Where to go from here

This particular example is not extremely flexible. It assumes I will always work with an AMF channel and therefore the only thing my application needs to know at runtime is the AMF channel endpoint URL. For RemoteObject that's a fairly safe bet, however for messaging-related classes (Producer and Consumer), you may also want to externalize the type of channel you use (so you can choose from among AMF polling, long polling, streaming, RTMP, and so on). Before you start creating that kind of dynamic configuration system, you may want to take a look at existing frameworks that provide built-in capabilities to externalize your services configuration..