SFS2X Platform Stack

» Migration guide: SFS 1 to SFS2X

In this document we are going to discuss how a SmartFoxServer Basic/PRO application can be converted to SmartFoxServer 2X.

The new SFS2X platforms maintains many of the previous concepts making the general workflow simpler and more streamlined. Also the Zones and Rooms objects have been extended with lots of new features that we are going to discuss in a moment.

Server Configuration

The old config.xml file is no longer used in SFS2X to store the server setup. Now you can avoid touching any XML at all and work with a convenient GUI that allows to configure every detail of the server and Zone(s) in a snap.

Client Side migration

Migrating the client side part of an application is probably the easiest part of the conversion work. The SFS2X API provide a very similar approach to the previous framework, using asynchronous requests and responses based on events.

The connection and login phase is now simplified, it requires only a few steps:

Connect to SFS2X via the connect() method
Handle the CONNECTION event and send a LoginRequest to join one of the available Zones
Handle the LOGIN event sent in response by the server

As a difference with the previous system the Room List details are now completely hidden from the developer's view. Once the LOGIN event is handled the Room List is already populated on the client and ready to be used.

Another major difference with the Basic/PRO versions is that SFS2X no longer supports auto-join Rooms, instead it allows the user to avoid joining any rooms, if it is necessary. Otherwise you will simply need to use a regular JoinRoom request. In other words the auto-join was removed to avoid confusion and everything is unified under one single join request which is very flexible.

To get started you can check the sources of the included demo application called SFS2X-Connector: it is a simple demo app that applies the concepts we have just mentioned in these paragraphs. If we take a look at the main class constructor you will find it very familiar:

public function SFS2XConnector()
{
	// Create an instance of the SmartFox class
 	sfs = new SmartFox()

	// Turn on the debug feature
	sfs.debug = true
	
	// Add SFS2X event listeners
	sfs.addEventListener(SFSEvent.CONNECTION, onConnection)
	sfs.addEventListener(SFSEvent.CONNECTION_LOST, onConnectionLost)
	sfs.addEventListener(SFSEvent.CONFIG_LOAD_SUCCESS, onConfigLoadSuccess)
	sfs.addEventListener(SFSEvent.CONFIG_LOAD_FAILURE, onConfigLoadFailure)
	
	// Connect button listener
	bt_connect.addEventListener(MouseEvent.CLICK, onBtConnectClick)
}

The API client is now called simply SmartFox and works very similarly to the previous edition. You start by adding listeners for all events you want to capture. As in SFS1 we can use an external configuration file containing the zone name, IP address and port of the server, this way we avoid to hard code these parameters into our application code.

The next step is to invoke sfs.loadConfig() which in turn will load the configuration and start the connection to the provided IP:port values.

ATTENTION: SmartFoxServer 2X uses TCP port 9933 by default, which differs from 9339 (the SFS1 default port)

If the connection succeeds whe can then proceed on with the log-in and we are ready to interact with the server.

One thing you will should notice that instead of calling the methods directly on the API class, you will create a request object that is passed to the send() method. Each possible request provided in the client API is found under the com.smartfoxserver.v2.requests package (this is valid for all API languages)

Example:

// Login with name and password
sfs.send(new LoginRequest("Gonzo", "TheGreat"))

// Join a Room
sfs.send(new JoinRoomRequest("The Lobby")) 

// Send a public message
sfs.send(new PublicMessageRequest("Hello SFS2X World!"))

// etc...

Client: the Room List

As mentioned earlier the client-side Room List is now handled transparently for the developer without the need to write any code or call any specific methods.

When the User is initally logged in he receives a Room List populated with the Rooms in all groups defined as default groups in the Zone configuration. This setting can represent one group or a list of them and it specifies all the groups that each User is subscribed to, when he's logged in.

Client: talking to extensions

Talking to an extension in SFS2X is simplified under many aspects. As in SFS PRO extensions are attached either to a Zone or to a Room, however in SFS2X there is only one extension per Zone or Room so you don't need to specify an extension id or name.

Instead of using several types of protocols (XML, JSON etc...) SFS2X completely hides the protocol details via the SFSObject and SFSArray, two collection classes specifically designed for network transport which allow to fine tune the data types used for each element.

For example numbers can be expressed in different ways: byte (8 bit), short (16 bit), int (32 bit) or long (64 bit) depending on their values and thus determining a different packet size. The following example shows a simple extension request:

// Prepare request parameters
var params:ISFSObject = new SFSObject()
params.putShort("px", 350)
params.putShort("py", 600)
params.putByte("speed", 20)

// Send request
sfs.send(new ExtensionRequest("move", params))

In the same way extension responses are handled via the usual EXTENSION_RESPONSE event using again the SFSObject class. We recommend to check both the server javadoc and the client documentation for more details on this class, it is quite powerful and supports nested SFSObject/Array(s) and over 20 basic data types.