Getting started with BlazeDS

Getting started with BlazeDS

Table of Contents

1. Introduction
2. Setting up your BlazeDS environment
3. Building a messaging application
4. Building a remoting application

<!-- InstanceBeginEditable name="ArticleContent" -->

Building a messaging application

The BlazeDS Message Service provides a publish/subscribe infrastructure that allows your Flex application to publish messages and subscribe to a set of messaging destinations, enabling the development of real-time data push and collaborative applications.

Follow these steps to build a simple chat application that demonstrates the BlazeDS Message Service.

Step 1: Create the messaging destination

A messaging destination represents a topic of real time conversation that interested parties can subscribe (listen) to or contribute to by posting their own messages.

To define the simple chat destination for this application:

1. In the blazeds-server project, open messaging-config.xml located in the Flex folder.

2. Add a destination called tutorial-chat defined as follows:

   <destination id="tutorial-chat"/>

3. Restart Tomcat.

A key element of a destination is the channel used to exchange data between the client and the server. Using BlazeDS, a messaging destination typically uses either a streaming or a polling channel.

• Using a streaming channel, the server response is left open until the channel connection is closed, allowing the server to send incremental chunks of data to the client. Because HTTP connections are not duplex, a single streaming Action Message Format (AMF) or HTTP channel actually requires two browser HTTP connections in order to send data in both directions. One is needed for the streamed response from the server to the client that the channel hangs on to. A second transient connection, drawn from the browser pool, is needed only when data is sent to the server. This second transient connection is immediately released back to the browser’s connection pool after the data is sent.
• A polling channel can be configured with a polling interval, or it can be set up to wait for data at the server-side if data is not immediately available (this approach is generally referred to as long polling). In either case, each poll response completes the request. Browser HTTP 1.1 connections are persistent by default, so the browser will likely recycle existing HTTP connections to send subsequent poll requests, which lowers the overhead for polling.

Notice that there is no need to explicitly define a channel for the tutorial-chat destination. When you do not specify channels at the destination level, the destination uses the default channels defined at the top of the messaging-config.xml file. In this case, the client will first try to connect to the message service using the “my-streaming-amf” channel. If a connection to the server cannot be established using that channel, the client will fall back to the “my-polling-amf” channel. Channels themselves are configured in services-config.xml.

Step 2: Create a Flex project

1. In Eclipse, select File > New > Project…
2. Expand the Flex Builder node, select Flex Project, and click Next.
3. Enter “tutorial-chat” as the project name.
4. Ensure Use default location is selected.
5. Select Web Application as the application type.
6. Select J2EE as the application server type.
7. Select Use remote object access service.
8. Deselect Create combined Java/Flex project using WTP.
9. Click Next.

10. Ensure the root folder for LiveCycle Data Services matches the root folder of your BlazeDS web application. The settings should look similar to these (you may need to adjust the exact folder name based on your own settings):

    Root Folder: C:/blazeds/tomcat/webapps/samples
    Root URL: http://localhost:8400/samples/
    Context Root: /samples

11. Click Validate Configuration, and then Finish.

Step 3: Create the client application

In the newly created tutorial-chat project, open the main.mxml file located in the src folder, and implement the application as follows:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
creationComplete="consumer.subscribe()">

<mx:Script>
<![CDATA[import mx.messaging.events.MessageEvent;
import mx.messaging.messages.AsyncMessage;

private function send():void
{
var message:AsyncMessage = new AsyncMessage();
message.body.chatMessage = msg.text;
producer.send(message);
msg.text = "";
}

private function messageHandler(event:MessageEvent):void
{
log.text += event.message.body.chatMessage + "/n";
}

]]>
</mx:Script>

<mx:Producer id="producer" destination="tutorial-chat"/>
<mx:Consumer id="consumer" destination="tutorial-chat" message="messageHandler(event)"/>

<mx:Panel title="Chat" width="100%" height="100%">
<mx:TextArea id="log" width="100%" height="100%"/>
<mx:ControlBar>
<mx:TextInput id="msg" width="100%" enter="send()"/>
<mx:Button label="Send" click="send()"/>
</mx:ControlBar>
</mx:Panel>
</mx:Application>

Code highlights:

• On the client side, the BlazeDS Message Service API provides two classes, Producer and Consumer, which you use to publish and subscribe to a destination, respectively.
• To subscribe to a destination, you use the subscribe() method of the Consumer class.
• When a message is published to a destination you subscribed to, the message event is triggered on the Consumer.

In this example, messages are published by Flex clients. The BlazeDS Message Service also provides a Java API that allows a server-side component to publish messages to a BlazeDS destination. A third option for exchanging messages between Flex and Java applications is to map destinations to Java Message Service (JMS) topics, enabling Flex clients to publish and subscribe to JMS topics.

Step 4: Run the application

1. Click the Run icon in the Eclipse toolbar to start the application
2. Open the same URL in another browser window to start a second instance of the chat application
3. Type a message in one of the chat clients and click "Send": the message appears in the two chat clients