Building Collaborative Applications with Flex Data Services and Flash Media Server

I presented a session called “Building Collaborative Applications with Flex Data Services and Flash Media Server” at MAX (the Adobe developer conference) last week. Beyond the basics of the Flex pub/sub messaging infrastructure, the session provided techniques to build real life collaborative applications. I started with a simple chatroom, and then incrementally added features to end up with an IM client supporting presence and videoconferencing.

Many people have asked me to make my code available. So here it is. If you didn’t attend MAX, I added a brief description for each version of the application.

To run these samples, you need to install the Flex Data Services. If you haven’t already done so, you can download the Flex Data Services here, and follow the installation instructions.

Install the samples

1. Download flex-collaboration.zip here and expand it on your local file system
2. Copy the flexchat directory in the context root of your web application
3. Copy the WEB-INF\src and WEB-INF\classes directories in the corresponding directory structure of your web application

Install the flexchat database

Starting with chat3.mxml, you will need a MySQL database.

1. Create a new MySQL database or use an existing one
2. Import the flexchat database using the flexchat.sql script
3. Make sure a MySQL JDBC driver is available to your web application
4. Edit flexchat.properties in WEB-INF\classes, and make sure the connection properties match your configuration

Install Flash Media Server

chat6.mxml requires Flash Media Server to enable videoconferencing.

1. Install the Flash Media Server: you can download a free developer edition here (click free developer edition)
2. In C:\Program Files\Macromedia\Flash Media Server 2\applications, create a directory called flex_videoconference and copy the main.asc file in that directory

Samples Walkthrough

chat1.mxml

chat1.mxml is a minimal chat application showing how to use the pub/sub messaging capabilities of Flex with just a couple of lines of code.

In this version, messages posted to the “chat” destination go to all the clients who subscribed to it. This is appropriate for a multi-user chatroom use case, but not for instant messaging applications where you want private conversations with individual users.

To run this sample, define a “chat” destination in messaging-config.xml as follows:

    <destination id="chat">

        <properties>
            <network>
                <session-timeout>0</session-timeout>
            </network>
            <server>
                <max-cache-size>1000</max-cache-size>
                <message-time-to-live>0</message-time-to-live>
                <durable>false</durable>
            </server>
        </properties>

        <channels>
            <channel ref="my-rtmp"/>
        </channels>

    </destination>

You may need to restart your server after modifying messaging-config.xml.

chat2.mxml

In this version, we use subtopics to enable private conversations between users. If you want to send a message to a user named Joe, you publish your message to the “Joe” subtopic of the chat destination (chat.Joe). Similarly, if Joe only needs to receive the messages that are sent to him, his client application can subscribe to the “Joe” subtopic.

Subtopics don’t need to be declared. All you need to do is configure your destination to support subtopics as shown below (allow-subtopics and subtopic-separator tags):

    <destination id="chat">

        <properties>
            <network>
                <session-timeout>0</session-timeout>
            </network>
            <server>
                <max-cache-size>1000</max-cache-size>
                <message-time-to-live>0</message-time-to-live>
                <durable>false</durable>
                <allow-subtopics>true</allow-subtopics>
                <subtopic-separator>.</subtopic-separator>
            </server>
        </properties>

        <channels>
            <channel ref="my-rtmp"/>
        </channels>

    </destination>

chat3.mxml

In this version, we add a buddy list using a DataService. The buddy list is displayed after the user logs on. You need to install the MySQL database to run this application.

To run this sample, add a “chat-buddies” destination in data-management-config.xml as follows:

    <destination id="chat-buddies">

        <adapter ref="java-dao" />

        <properties>
            <source>flex.samples.chat.BuddyAssembler</source>
	    <scope>application</scope>

            <metadata>
                <identity property="userId"/>
                <identity property="buddyId"/>
            </metadata>

            <network>
                <session-timeout>20</session-timeout>
                <paging enabled="false" pageSize="10" />
                <throttle-inbound policy="ERROR" max-frequency="500"/>
                <throttle-outbound policy="REPLACE" max-frequency="500"/>
            </network>
        </properties>

    </destination>

chat4.mxml

In chat4.mxml, we add a custom adapter (ChatAdapter.java) to the chat destination to support basic presence information. ChatAdapter implements the FlexSessionListener interface and uses the sessionCreated and sessionDestroyed callback methods to keep track of when users connect and disconnect, and notify interested parties.

The client application uses separate consumers to subscribe to a “status” subtopic for each buddy in the buddy list (chat.status.jane, chat.status.eric, chat.status.susan, etc.). See the dsBuddiesResult() method for the implementation details.

To run this sample, add our simple ChatAdapter in the list of configured adapters in messaging-config.xml. Th list of configured adapters should look like this:

    <adapters>
        <adapter-definition id="actionscript" class="flex.messaging.services.messaging.adapters.ActionScriptAdapter" default="true" />
        <adapter-definition id="jms" class="flex.messaging.services.messaging.adapters.JMSAdapter"/>
        <adapter-definition id="chat" class="flex.samples.chat.ChatAdapter"/>
    </adapters>

Next, specify that you want to use the chat adapter in the chat destination by adding the adapter reference as follows:

    <destination id="chat">

        <properties>
            <network>
                <session-timeout>0</session-timeout>
            </network>
            <server>
                <max-cache-size>1000</max-cache-size>
                <message-time-to-live>0</message-time-to-live>
                <durable>false</durable>
                <allow-subtopics>true</allow-subtopics>
                <subtopic-separator>.</subtopic-separator>
            </server>
        </properties>

        <channels>
            <channel ref="my-rtmp"/>
        </channels>

        <adapter ref="chat"/>

    </destination>

The unresolved issue in this version is that when you log on, you still don’t know which of your buddies are *already* online, and what their status is.

chat5.mxml

In this version, we use a DataService (“chat-sessions”) to keep track of the active user sessions along with presence information. Just like we did in ChatAdaper, the UserSessionAssembler class implements the FlexSessionListener interface and uses the sessionCreated and sessionDestroyed callback methods to create and remove user sessions. Using a DataService to keep track of presence information is convenient because changes (i.e. status information) are automatically pushed to all interested clients.

To run this sample, add a “chat-sessions” destination in data-management-config.xml as follows:

    <destination id="chat-sessions">

        <adapter ref="java-dao" />

        <properties>
            <source>flex.samples.chat.UserSessionAssembler</source>
	        <scope>application</scope>

            <metadata>
                <identity property="userId"/>
            </metadata>

            <network>
                <session-timeout>20</session-timeout>
                <paging enabled="false" pageSize="10" />
                <throttle-inbound policy="ERROR" max-frequency="500"/>
                <throttle-outbound policy="REPLACE" max-frequency="500"/>
            </network>

        </properties>

    </destination>

chat6.mxml

This version is the same as chat5.mxml with the addition of videoconferencing features enabled by Flash Media Server. Start your webcam in one session. in the buddy list of another session, click the name of the user who is broadcasting to see the video feed.