Giant Flying Saucer

Several years ago there was a socket server for Flash called Unity. Well, recently Unity has been reborn (re-written actually) as the Union Platform. The same developers (Colin Moock and Derek Clayton) are still hard at work making connecting Flash/Flex applications via sockets as easy as possible. Keep in mind the spec for Union’s message format is open so I’d assume you could connect clients like Silverlight, thick clients, etc. to Union as well. This is going to be an excellent platform for building online games, chat applications, and much more.

This post was updated on May 10, 2009 based upon feedback from the master of ActionScript himself Colin Moock.

In this article we will build a multiuser chat application in Flex. You can build this chat application in one of two ways. First, you can download the goodies and install them and use the Union server that has been setup for developers to use at TryUnion.com. If you go that way then you only need to have Flex Builder 3.02 (a trial version is available) and Reactor. If you prefer to install everything then you will need:
1. Java 1.6 (JDK)
2. Flex Builder 3.02 (a trial version is available)
3. Union Platform – grab Reactor (this is the ActionScript 3 client SDK) and the Server.

I’m using Windows Vista to build this chat application and I’ll assume you have everything installed and ready to go. I am still learning the Union Platform API so there are probably more efficient ways to go about things, feel free to leave comments on how best to optimize this code.

Before you begin please note there is an issue when it comes to joining rooms in the Alpha 1 release – in particular an error is thrown and that has to do with the ordering of UPC messages and will be resolved in the Alpha 2 release.

Lets begin. First open Flex Builder and create a new project. Call it “UnionRoomChat”.

Click the “next” button and on the last page of the wizard link to the Reactor.swc file you downloaded as part of the Union client SDK.

I’m going to layout the initial panel the user will be greeted with when they first come to our chat application. It will consist of a button, a textinput control as well as a simple graphic I pulled from Wikimedia Commons. My screen looks like this:

The MXML so far looks like this:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" fontFamily="Verdana" fontSize="12" color="#000000" currentState="Start">
	<mx:states>
		<mx:State name="Login">
			<mx:AddChild position="lastChild">
				<mx:Panel width="362" height="226" layout="absolute" horizontalCenter="0" verticalCenter="0" borderColor="#A2A2A2" backgroundColor="#EEEEEE" id="login_pnl" title="Union Room Chat">
					<mx:TextInput x="98.5" y="15" maxChars="20" id="username_txt" borderStyle="solid"/>
					<mx:Label x="13.5" y="17" text="Username:" fontWeight="bold"/>
					<mx:Button click="onLoginClicked();" x="266.5" y="13" label="Login" id="login_btn"/>
					<mx:Image x="107" y="45" source="images/Crystal_Clear_talk.png"/>
				</mx:Panel>
			</mx:AddChild>
		</mx:State>
	</mx:states>
</mx:Application>

That’s pretty straight forward, I’m going to add the following ActionScript now to the MXML file:

<mx:Script>
	<![CDATA[

		import net.user1.reactor.Room;
		import net.user1.reactor.IClient;
		import net.user1.reactor.UConnection;
		import net.user1.reactor.UConnectionEvent;

		private var connection:UConnection;

		private function onLoginClicked():void
		{
			// Create the connection object
			connection = new UConnection();
			// Add the event listeners
			connection.addEventListener(UConnectionEvent.READY, connectionReadyListener);
			connection.addEventListener(UConnectionEvent.CLOSE, connectionCloseListener);
			// Open the connection, I've set my port to 80
			connection.open("localhost", 80);
		}

		private function connectionReadyListener(e:UConnectionEvent):void
		{
			trace("Connected!");
		}

		private function connectionCloseListener(e:UConnectionEvent):void
		{
			trace("Closed!");
		}
	]]>
</mx:Script>

If we run this project right now (ignoring the username textbox) we ought to see something like this in Flex Builder’s console:

Ok, we need to add the code now to set the username. We will do this using attributes of the Client class. The code now looks like this:

<mx:Script>
	<![CDATA[

		import net.user1.reactor.Room;
		import net.user1.reactor.IClient;
		import net.user1.reactor.UConnection;
		import net.user1.reactor.UConnectionEvent;

		private var connection:UConnection;
		private var client:IClient;

		private function onLoginClicked():void
		{
			// Create the connection object
			connection = new UConnection();
			// Add the event listeners
			connection.addEventListener(UConnectionEvent.READY, connectionReadyListener);
			connection.addEventListener(UConnectionEvent.CLOSE, connectionCloseListener); 

			// Open the connection, I've set my port to 80
			connection.open("localhost", 80);
		}

		private function connectionReadyListener(e:UConnectionEvent):void
		{
			trace("Connected!");

			// Get a reference to the client
			client = connection.getClientManager().self();
			// Set the username attribute, you would want to ensure
			// the user actually entered something in username_txt
			client.setAttribute("username", username_txt.text, null, false);
		}

		private function connectionCloseListener(e:UConnectionEvent):void
		{
			trace("Closed!");
		}    		

	]]>
</mx:Script>

You can see we added more code to the “connectionReadyListener” function to handle setting the username attribute. Now we need to join the default chat room, or if it doesn’t exist we need to create it. We also need to move to the main lobby chat panel now that we are connected. Lets add the new panel first by adding a new state to the project called “MainPanel”.

The new panel will look like this:

We need to add some code to the end of the “connectionReadyListener” function in order for the new main lobby panel to show up.

setCurrentState("MainLobby");

Now we need to add the code to make this all work! First, recall we need to join the default chat room and if it doesn’t exist we need to create it. The RoomManager will do this work for us, in particular the call to createRoom. If the room already exists you might see this show up in the console “[SERVER] Room creation results for room ‘mainLobbyRoom’: ROOM_EXISTS”. That is ok, we can ignore that for this simple application.

// Create a room that doesn't go away when no one is in it
var roomSettings:RoomSettings = new RoomSettings();
roomSettings.dieOnEmpty = false;
// Create the room (it might already exist)
currentRoom = connection.getRoomManager().createRoom("mainLobbyRoom", roomSettings);
// Listen for chat messages in this room
currentRoom.addMessageListener(CHAT_MESSAGE, mainLobbyChatMessageListener);
// Join the room
currentRoom.join();

I’m going to add a string const to the top of the script since we will reuse this string fairly often:

private const CHAT_MESSAGE:String = "CHAT_MESSAGE";

Lets add code now to send a chat message. First we will add an event handler for the send button:

<mx:Button x="252" y="263" label="Send" id="send_btn" click="onSendClicked();"/>

Now we add a function for the send button:

private function onSendClicked():void
{
    if(currentRoom != null)
    {
        currentRoom.sendMessage(CHAT_MESSAGE, true, null, input_txt.text);
        input_txt.text = "";
    }
}

We can hook up the chatMessageListener function which will display the messages to the user:

private function chatMessageListener(fromClient:IClient, chatText:String ):void
{
    output_txt.htmlText += "<b>" + fromClient.getAttribute(null, "username") + ":</b> " + chatText;
}

Time to hook up the disconnect button:

<mx:Button x="470" y="263" label="Disconnect" id="disconnect_btn" width="140" click="onDisconnectClicked();" />

…and the function for it:

private function onDisconnectClicked():void
{
	// You don't need to call the leave() function since
	// the disconnect will remove the client when the
	// connection is closed but it is a good practice in
	// case something goes wrong in the disconnect and
	// the user appears as a ghost (ghosts are eventually
	// removed by the server when they cannot be reached).
    if(currentRoom != null)
        currentRoom.leave();

    connection.close();
    setCurrentState("Login");

    output_txt.htmlText = "";
    input_txt.text = "";
}

There are several more things we need to do now. First I want to hook up the event listeners for the rooms being added or existing rooms being removed as well as initially listening to the lobby room at the start.

   private function addRoomListeners():void
   {
        currentRoom.addEventListener(RoomEvent.ADD_CLIENT, clientAddedListener);
        currentRoom.addEventListener(RoomEvent.REMOVE_CLIENT, clientRemovedListener);
        currentRoom.addEventListener(RoomEvent.SYNCHRONIZE, synchronizeRoomListener);
   }

   private function removeRoomListeners():void
   {
        currentRoom.removeEventListener(RoomEvent.ADD_CLIENT, clientAddedListener);
        currentRoom.removeEventListener(RoomEvent.REMOVE_CLIENT, clientRemovedListener);
        currentRoom.removeEventListener(RoomEvent.SYNCHRONIZE, synchronizeRoomListener);
   }

That code will go into connectionReadyListener() and later on will be called in the join room and create room functions.

I’m going to run the project and open an additional window so I have two chat applications running.

Lets hook up the code now to fill the rooms and users listboxes. I’m going to create a bindable variable for the rooms and users listboxes to make this easy.

[Bindable]
private var arrRooms:Array = new Array();
[Bindable]
private var arrUsers:Array = new Array();

Now I bind them like this:

<mx:List x="319" y="22" width="142" height="234" verticalScrollPolicy="on" id="users_lst" dataProvider="{arrUsers}"></mx:List>
<mx:List x="469" y="22" width="142" height="170" verticalScrollPolicy="on" id="rooms_lst" dataProvider="{arrRooms}"></mx:List>

We will hook up the synchronizeRoomListener function as well so we get the initial list of the users in the room they join.

   private function synchronizeRoomListener(e:RoomEvent):void
   {
        // Get the list of all users in the current room
        var arrClientTemp:Array = currentRoom.getClients();
        arrUsers.length = 0;           

        for(var i:int = 0; i < arrClientTemp.length; i++)
        {
            var c:Client = arrClientTemp[i];
            arrUsers.push(c.getAttribute(null, "username"));
        }
        arrUsers.sort(Array.CASEINSENSITIVE);
        users_lst.data = arrUsers;
   }

So the functions now to handle the populating of the user and room listboxes will look like this:

   private function clientAddedListener(e:RoomEvent):void
   {
   		arrUsers.push(e.getClient().getAttribute(null, "username"));
   		arrUsers.sort(Array.CASEINSENSITIVE);
   		users_lst.data = arrUsers;
   }         

   private function clientRemovedListener(e:RoomEvent):void
   {
   	   // To be safe you probably would want to remove the clients by
   	   // their clientID, not their username attribute like I'm using
   	   // since you could have two users with the same username and end up
   	   // removing the wrong one.  Or if your using some form of authentication
   	   // you would want to ensure no two usernames could be the same when
   	   // users register for your application
	   arrUsers.splice(arrUsers.indexOf(e.getClient().getAttribute(null, "username")), 1);
       users_lst.data = arrUsers;
   }

   private function roomRemovedListener(e:RoomManagerEvent):void
   {
       for(var obj:Object in arrRooms)
       {
       		if(arrRooms[obj] == e.getRoomID())
       			arrRooms.splice(arrRooms.indexOf(e.getRoomID()), 1);
       }
       rooms_lst.data = arrRooms;
   }

   private function roomAddedListener(e:RoomManagerEvent):void
   {
   		arrRooms.push(e.getRoomID());
   		rooms_lst.data = arrRooms;
   		rooms_lst.dataProvider.refresh();
   }

We can add the code now to hook up the create room and join room buttons:

private function onCreateRoomClicked():void
{
	// Ensure the room hasn't already been created
	if (currentRoom.getRoomID() == connection.getClientManager().self().getAttribute(null, "username"))
	{
		output_txt.htmlText = "<b>Room '" + currentRoom.getRoomID() + "' already exists.</b>";
		return;
	}            	

    currentRoom.removeMessageListener(CHAT_MESSAGE, chatMessageListener);
    removeRoomListeners();
    currentRoom.leave();
    currentRoom = connection.getRoomManager().createRoom(connection.getClientManager().self().getAttribute(null, "username"));
    currentRoom.addMessageListener(CHAT_MESSAGE, chatMessageListener);
    addRoomListeners();
    currentRoom.join();
    output_txt.htmlText = "<b>Creating room: " + currentRoom.getRoomID() + "...</b>";
}

private function onJoinRoomClicked():void
{
    if(rooms_lst.selectedItem != null)
    {
        currentRoom.removeMessageListener(CHAT_MESSAGE, chatMessageListener);
        removeRoomListeners();
        currentRoom.leave();
        currentRoom = connection.getRoomManager().joinRoom(rooms_lst.selectedItem.toString());
        currentRoom.addMessageListener(CHAT_MESSAGE, chatMessageListener);
        addRoomListeners();
        output_txt.htmlText = "<b>Joining room: " + currentRoom.getRoomID() + "...</b>";
    }
}

My final code looks like this:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" fontFamily="Verdana" fontSize="12" color="#000000" currentState="Login">
    <mx:states>
        <mx:State name="Login">
            <mx:AddChild position="lastChild">
                <mx:Panel width="362" height="226" layout="absolute" horizontalCenter="0" verticalCenter="0" borderColor="#A2A2A2" backgroundColor="#EEEEEE" id="login_pnl" title="Union Room Chat">
                    <mx:TextInput x="98.5" y="15" maxChars="20" id="username_txt" borderStyle="solid"/>
                    <mx:Label x="13.5" y="17" text="Username:" fontWeight="bold"/>
                    <mx:Button click="onLoginClicked();" x="266.5" y="13" label="Login" id="login_btn"/>
                    <mx:Image x="107" y="45" source="images/Crystal_Clear_talk.png"/>
                </mx:Panel>
            </mx:AddChild>
        </mx:State>
        <mx:State name="MainLobby">
            <mx:AddChild position="lastChild">
                <mx:Panel width="640" height="338" layout="absolute" horizontalCenter="0" verticalCenter="0" fontFamily="Verdana" fontSize="12" id="mainPanel_pnl" title="Union Room Chat">
                    <mx:TextArea x="10" y="22" width="301" height="234" borderStyle="solid" verticalScrollPolicy="on" id="output_txt"/>
                    <mx:TextInput x="10" y="264" width="234" id="input_txt" maxChars="100"/>
                    <mx:Button x="252" y="263" label="Send" id="send_btn" click="onSendClicked();"/>
                    <mx:Button x="469" y="200" label="Create Room" id="createRoom_btn" width="141" click="onCreateRoomClicked();" />
                    <mx:Button x="470" y="232" label="Join Room" id="joinRoom_btn" width="140" click="onJoinRoomClicked();"/>
                    <mx:Button x="470" y="263" label="Disconnect" id="disconnect_btn" width="140" click="onDisconnectClicked();" />
                    <mx:List x="319" y="22" width="142" height="234" verticalScrollPolicy="on" id="users_lst" dataProvider="{arrUsers}"></mx:List>
                    <mx:List x="469" y="22" width="142" height="170" verticalScrollPolicy="on" id="rooms_lst" dataProvider="{arrRooms}"></mx:List>
                    <mx:Label x="129" y="2" text="Chat" fontWeight="bold"/>
                    <mx:Label x="515" y="2" text="Rooms" fontWeight="bold"/>
                    <mx:Label x="363" y="2" text="Users" fontWeight="bold"/>
                </mx:Panel>
            </mx:AddChild>
        </mx:State>
    </mx:states>
    <mx:Script>
        <![CDATA[
            import net.user1.reactor.Client;
            import net.user1.reactor.Room;
            import net.user1.reactor.IClient;
            import net.user1.reactor.UConnection;
            import net.user1.reactor.RoomEvent;
            import net.user1.reactor.RoomSettings;
            import net.user1.reactor.RoomManagerEvent;
            import net.user1.reactor.UConnectionEvent;

            import mx.controls.Alert;

            private var connection:UConnection;
            private var currentRoom:Room;
            private var client:IClient;
            private var firstTime:Boolean = true;
            private const CHAT_MESSAGE:String = "CHAT_MESSAGE";

            [Bindable]
            private var arrRooms:Array = new Array();
            [Bindable]
            private var arrUsers:Array = new Array();   

            private function onLoginClicked():void
            {
                // Create the connection object
                connection = new UConnection();
                // Add the event listeners
                connection.addEventListener(UConnectionEvent.READY, connectionReadyListener);
                connection.addEventListener(UConnectionEvent.CLOSE, connectionCloseListener);

                // Open the connection, I've set my port to 80
                connection.open("localhost", 80);
            }

            private function connectionReadyListener(e:UConnectionEvent):void
            {
                // Get a reference to the client
                client = connection.getClientManager().self();
                // Set the username attribute, you would want to ensure
                // the user actually entered something in username_txt
                client.setAttribute("username", username_txt.text);
                setCurrentState("MainLobby");

                // Reset the arrays in case they disconnect and reconnect
                arrRooms.length = 0;
                arrUsers.length = 0;

                // Add event listeners when rooms are added or removed
                connection.getRoomManager().addEventListener(RoomManagerEvent.ROOM_ADDED, roomAddedListener);
                connection.getRoomManager().addEventListener(RoomManagerEvent.ROOM_REMOVED, roomRemovedListener);

                connection.getRoomManager().watchForRooms();

                // Create a room that doesn't go away when no one is in it
                var roomSettings:RoomSettings = new RoomSettings();
                roomSettings.dieOnEmpty = false;
                // Create the room (it might already exist)
                currentRoom = connection.getRoomManager().createRoom("mainLobbyRoom", roomSettings);

                currentRoom.addMessageListener(CHAT_MESSAGE, chatMessageListener);           

                // Start listening to the room events, it's a good
                // practice to set the listeners before you join the room
                addRoomListeners(); 

                // Join the room
                currentRoom.join();
           }

           private function addRoomListeners():void
           {
                currentRoom.addEventListener(RoomEvent.ADD_CLIENT, clientAddedListener);
                currentRoom.addEventListener(RoomEvent.REMOVE_CLIENT, clientRemovedListener);
                currentRoom.addEventListener(RoomEvent.SYNCHRONIZE, synchronizeRoomListener);
           }

           private function removeRoomListeners():void
           {
                currentRoom.removeEventListener(RoomEvent.ADD_CLIENT, clientAddedListener);
                currentRoom.removeEventListener(RoomEvent.REMOVE_CLIENT, clientRemovedListener);
                currentRoom.removeEventListener(RoomEvent.SYNCHRONIZE, synchronizeRoomListener);
           }           

           private function clientAddedListener(e:RoomEvent):void
           {
           		arrUsers.push(e.getClient().getAttribute(null, "username"));
           		arrUsers.sort(Array.CASEINSENSITIVE);
           		users_lst.data = arrUsers;
           }           

           private function clientRemovedListener(e:RoomEvent):void
           {
           	   // To be safe you probably would want to remove the clients by
           	   // their clientID, not their username attribute like I'm using
           	   // since you could have two users with the same username and end up
           	   // removing the wrong one.  Or if your using some form of authentication
           	   // you would want to ensure no two usernames could be the same when
           	   // users register for your application
			   arrUsers.splice(arrUsers.indexOf(e.getClient().getAttribute(null, "username")), 1);
               users_lst.data = arrUsers;
           }

           private function synchronizeRoomListener(e:RoomEvent):void
           {
                // Get the list of all users in the current room
                var arrClientTemp:Array = currentRoom.getClients();
                arrUsers.length = 0;           

                for(var i:int = 0; i < arrClientTemp.length; i++)
                {
                    var c:Client = arrClientTemp[i];
                    arrUsers.push(c.getAttribute(null, "username"));
                }
                arrUsers.sort(Array.CASEINSENSITIVE);
                users_lst.data = arrUsers;
           }                             

           private function roomRemovedListener(e:RoomManagerEvent):void
           {
               for(var obj:Object in arrRooms)
               {
               		if(arrRooms[obj] == e.getRoomID())
               			arrRooms.splice(arrRooms.indexOf(e.getRoomID()), 1);
               }
               rooms_lst.data = arrRooms;
           }

           private function roomAddedListener(e:RoomManagerEvent):void
           {
           		arrRooms.push(e.getRoomID());
           		rooms_lst.data = arrRooms;
           		rooms_lst.dataProvider.refresh();
           }                 

            private function connectionCloseListener(e:UConnectionEvent):void
            {
                Alert.show("Connection Closed");
            } 

            private function chatMessageListener(fromClient:IClient, chatText:String ):void
            {
                output_txt.htmlText += "<b>" + fromClient.getAttribute(null, "username") + ":</b> " + chatText;
            }

            private function onSendClicked():void
            {
                if(currentRoom != null)
                {
                    currentRoom.sendMessage(CHAT_MESSAGE, true, null, input_txt.text);
                    input_txt.text = "";
                }
            }

            private function onDisconnectClicked():void
            {
            	// You don't need to call the leave() function since
            	// the disconnect will remove the client when the
            	// connection is closed but it is a good practice in
            	// case something goes wrong in the disconnect and
            	// the user appears as a ghost (ghosts are eventually
            	// removed by the server when they cannot be reached).
                if(currentRoom != null)
                    currentRoom.leave();

                connection.close();
                setCurrentState("Login");

                output_txt.htmlText = "";
                input_txt.text = "";
            }

            private function onCreateRoomClicked():void
            {
            	// Ensure the room hasn't already been created
				if (currentRoom.getRoomID() == connection.getClientManager().self().getAttribute(null, "username"))
				{
					output_txt.htmlText = "<b>Room '" + currentRoom.getRoomID() + "' already exists.</b>";
					return;
				}            	

                currentRoom.removeMessageListener(CHAT_MESSAGE, chatMessageListener);
                removeRoomListeners();
                currentRoom.leave();
                currentRoom = connection.getRoomManager().createRoom(connection.getClientManager().self().getAttribute(null, "username"));
                currentRoom.addMessageListener(CHAT_MESSAGE, chatMessageListener);
                addRoomListeners();
                currentRoom.join();
                output_txt.htmlText = "<b>Creating room: " + currentRoom.getRoomID() + "...</b>";
            }

            private function onJoinRoomClicked():void
            {
                if (rooms_lst.selectedItem != null)
                {
                    currentRoom.removeMessageListener(CHAT_MESSAGE, chatMessageListener);
                    removeRoomListeners();
                    currentRoom.leave();
                    currentRoom = connection.getRoomManager().joinRoom(rooms_lst.selectedItem.toString());
                    currentRoom.addMessageListener(CHAT_MESSAGE, chatMessageListener);
                    addRoomListeners();
                    output_txt.htmlText = "<b>Joining room: " + currentRoom.getRoomID() + "...</b>";
                }
            }
        ]]>
    </mx:Script>
</mx:Application>

A few last things based upon feedback I received from Colin…

1. You probably want to use a room qualifier for your roomIds. I could use something like “com.giantflyingsaucer.mainLobbyRoom”, etc. This way if your using TryUnion.com you can specifically check for those qualified roomIds that match your unique naming scheme and only show those to the users. This way you ignore any rooms created by other developers that your not interested in. It is also just good practice to use a naming convention like this even if your not using TryUnion.com.

2. You can add nice little features like when the user joins a room. You could do that with the RoomEvent.SYNCHRONIZE listener.

3. If you want to get the maximum amount of logging information while debugging you can do this:

// Add this import
import net.user1.logger.Logger;

// Set the level
connection.getLog().setLevel(Logger.DEBUG);

4. This chat application should have a label or something that displays the current room the user is in. You can get that information from the currentRoom variable.

My thanks to Colin and Derek for making another excellent product and for some great feedback on this article!

• Bookmark on Delicious
• Digg this post
• Recommend on Facebook
• Buzz it up
• share via Reddit
• Share with Stumblers
• Tweet about it
• Subscribe to the comments on this post

This entry was posted on Tuesday, May 5th, 2009 at 2:27 pm and is filed under AJAX, ActionScript, Adobe, C#, Flex, Java, Online Games, Socket Server. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.