6.x Java Extensions CookBook

This document provides quick snippets of code organized by theme that will get you started with most of the server side coding tasks. Feel free to suggest more "recipes" by sending us an email or posting in our support forums

» Using String/Raw protocol

The String/Raw protocol allows you to send data in very small packets, with a configurable character separator (default: %). The difference with XML and JSON formats is that you can no longer pass nested objects with key-value pairs, but only a sequence of strings that can be retrieved on the other side in the same order in which the have been created.

To give you an idea this is a very obvious example:

%Hello%World%this%is%a%test%

You will be able to get the first element ("Hello") at index 0, the next one ("World") at index 1 etc... just like you would do in a zero-based indexed array.

Recipe #1:

The client sends an object containing a string and a number. The sfs object is a instance of the SmartFoxClient class and the three parmeters passed to the sendXtMessage() method are: the name of the extension, the "command" name and the parameters object.

var arr:Array = []
arr.push("Hello World!")
arr.push(54321)

sfs.sendXtMessage("test", "cmd", arr, "str")

Note that the in the sendXtMessage() 4th argument we have specifed the protocol type. On the server side you will receive a String array:

public void handleRequest(String cmd, String[] params, User u, int fromRoom)
{
	String helloWorld = params[0];
	int num = Integer.parseInt(params[1]);
}

Recipe #2:

By following the ActionscriptObject/JSONObject examples we should be able to create a more complex test with nested objects. However, as we said in the introduction, the string/raw protocol doesn't allow nested objects in the same fashion that the other protocols do. We are only allowed to pass primitive data, that is converted into Strings separated by a specific token.

To solve this issue we can still use multiple separators to send nested data. Take a look at the following example:

var arr:Array = []
obj.push("Hello World!")
obj.push(54321)
obj.push("1,2,3,4,5") // numbers are comma separated

sfs.sendXtMessage("test", "cmd", arr, "str")

Here's the server side code:

public void handleRequest(String cmd, String[] params, User u, int fromRoom)
{
	String str = params[0];
	int num = Integer.parseInt(params[1]);
	String[] arr = params[2].split("\\,");

	// Cycle through all items
	for (int i = 0; i < arr.length; i++)
	{
		System.out.println("Item " + i + " = " + arr[i]);
	}
}

Please note that we have call the split() method on the third parameter sent by the client ("1,2,3,4,5") to obtain each number individually.

Recipe #3:

This recipe shows how to build a string-based response on the server side and how to handle it on the client. Suppose we are updating the position of an enemy starship in a multiplayer action game

public void handleRequest(String cmd, String[] data, User u, int fromRoom)
{
	/*
	* enemyShip is an object whose id property is a string and posX, posY are integers.
	*/	
	String[] params = new String[]
			{
				"shipUpdate",
				enemyShip.getId(),
				String.valueOf(enemyShip.getPosX()),
				String.valueOf(enemyShip.getPosY())
			}
			
	LinkedList recipients = new LinkedList();
	recipients.add(u);
	
	sendResponse(params, -1, null, recipients);
}

Note that the first element in the array is the command name which is used to identify each request and response. This is a convention that should always be followed when using this separator based protocol.

This is how we can handle the server message on the client side, in Actionscript 3:

public function onExtensionResponse(event:SFSEvent):void
{
	var params:Array = evt.params.dataObj
	
	/*
	* The first two indexes (0, 1) are reserved
	* 
	* param[0] = the "command" name sent from the server side
	* param[1] = the roomId
	*/
	var cmdName:String = params[0]
	var roomId:int = params [1]
	
	// This is the actual data 
	var shipId:String = params[2] 
	var shipPosX:int = params[3] 
	var shipPosY:int = params[4] 
}

Just pay attention that the first two parameter are always reserved to the command name and room Id