SmartFoxServer AJAX API(Beta) Readme

About

SmartFoxServer AJAX API is Google Web Toolkit (GWT) module that allows you to create cross-browser AJAX multi user applications using Java. SmartFoxServer AJAX API requires the BlueBox installed and active.

NOTE: Please note the following:

• Due to the Same Origin Policy (SOP) the SmartFoxServer AJAX API related JavaScript files and the BlueBox should be on the same domain name, protocol and port (some browsers permit different port)
• HTTP 1.1 requires browsers to limit the number of outgoing HTTP connections to two per domain/port. So if you test the application loading multiple instances of the page in the same browser you may experience significant lag. During test with Mozilla Firefox 2 and Internet Explorer 7 with three instances (the same browser instance and different tabs) of sfsChat the lag was so big that making any test was almost impossible. The reason is the same as what makes BlueBox so fast – when HTTP request is made it doesn’t send response until there is some update to send or given time has expired. So for example when two instances wait for response and third tries to login it cannot because the connections limit is reached and it needs to wait until one of the other instances receive response and this may take in some cases about 20 seconds – as you can see this is really huge lag and with more instances it gets even worse. Starting different instances of Mozilla Firefox does not fix the problem while starting multiple instances of Internet Explorer 7 solves the problem. Maybe the best approach is to test the application on different browsers for example Mozilla Firefox, Internet Explorer, Safari and Opera. This approach has one big advantage – you can test how your application looks and performs on the major browsers. Of course other solutions are also possible – for example to make the tests on different computers

Quick Start

You can found quick start guide here .

Usage

You can use the SmartFoxServer AJAX API in the same way as any other GWT module:

1. Add sfs_ajax_api_dir/api/sfs_ajax_api.jar to your classpath where sfs_ajax_api_dir is the folder where you have unpacked the SmartFoxServer AJAX API
2. Your module must inherits it.gotoandplay.smartfoxserver.SFS_API module:

   <inherits name="it.gotoandplay.smartfoxserver.SFS_API" />

3. To test application in hosted mode you need BlueBox running on localhost:8080. If BlueBox is running on different host and/or port you need to make a change in the SmartFoxServer AJAX API source code. In it.gotoandplay.smartfoxserver.server.BlueBoxProxy class change:

   private static final String BLUE_BOX_URL = "http://127.0.0.1:8080/BlueBox/HttpBox.do"; 

   with the correct address.

SmartFoxServer AJAX API and SmartFoxServer AS3 API

SmartFoxServer AJAX API is based on SmartFoxServer AS3 API so you can use the SmartFoxServer AS3 API documentation as reference. There are some differences you should know about:

• Less features. There are some features that are in SmartFoxServer AS3 API but not in SmartFoxServer AJAX API:
  • Because of the Same Origin Policy there are not properties or method related to the server address and port. The connection method is without arguments. There is no loadConfig method. Also because the only possible connection is HTTP there is no connection type (socket or HTTP) related properties or methods
  • No buddy list related properties or methods
  • No file uploading
  • No sendObject or sendObjectToGroup
  • Only raw string protocol is supported for extensions messages
• Some properties are now accessible only through methods:
  • The isConnected property of SmartFoxClient class can be accessed with public boolean getIsConnected() and public void setIsConnected(boolean b)
  • The httpPollSpeed property of SmartFoxClient class can be accessed with public int getHttpPollSpeed() and public void setHttpPollSpeed(int sp)
• Dynamic object are represented by HashMap – the property name of the object is now key in the HashMap. For example param property of SFSEvent object now it’s HashMap. To get the success parameter of onLogin event you can use this code:

  Boolean success = event.params.get("success");

• The associative arrays are now instances of HashMap. Both user list and room list are now HashMap and key are the room id and the user id
• There are some changes to the event system:
  • SFSEvent have only one method - public String getType() and only one public field – public HashMap params
  • The params field is now public HashMap params – please see 3. For more details
  • The addEventListener method of SmartFoxClient is now public void addEventListener(String type, SFSEventHandler handler) where type is the type of the event (the same as in SmartFoxServer AS3 API) and SFSEventHandler is interface that contains only void handleEvent(SFSEvent event) which is called when the event occur and the SFSEvent instance is passed as parameter. You can have more than one handler for one event type and all of them are called in the same order as they are added. removeEventListener method of SmartFoxClient is now public void removeEventListener (String type, SFSEventHandler handler). It removes only the first handler of the given type. Please note that it compares the event type with equals() but the handler with == so when you invoke removeEventListener you should pass the same object as parameter for handler as when you have invoked addEventListener.
  • Because some of the features are removed so some of the events are removed too. The events that are fired by SmartFoxClient are: onAdminMessage, onConnection, onConnectionLost, onCreateRoomError, onDebugMessage, onExtensionResponse, onJoinRoom, onJoinRoomError, onLogin, onLogout, onModeratorMessage, onPrivateMessage, onPublicMessage, onRoomAdded, onRoomDeleted, onRoomLeft, onRoomListUpdate, onRoomVariablesUpdate, onSpectatorSwitched, onUserCountChange, onUserEnterRoom, onUserLeaveRoom, onUserVariablesUpdate
  • public function createRoom (roomObj:Object, roomId:int = -1) : void now is public void createRoom(String name, String pass, int maxUsers, int maxSpectators, boolean isGame, boolean exitCurrent, boolean uCount, HashMap[] vars, HashMap extension, int roomId). If the room does not have variables or extensions then pass null for these arguments
  • In almost all cases the optional function arguments are now mandatory. The most significant change is that now the optional roomId argument is mandatory. For example for sendPublicMessage you can use this code:

    sfs.sendPublicMessage("Some Message", sfs.activeRoomId);

Examples

There are two examples – chat application and white board. The chat application shows some basic SmartFoxServer functionalities as public and private messaging, room creation. The white board application is a more complicated and shows how SFS can be used with the new <canvas> tag so more complicated graphics features can be added. Also it demonstrates the usage of server side extensions.

How to install the examples

To install the sfsChat example just copy the content of the sfs_ajax_api_dir/examples/sfsChat/www to sfs_install_dir/Server/webserver/webapps/root where:

• sfs_ajax_api_dir is the folder where you have unpacked the SmartFoxServer AJAX API
• sfs_install_dir is the folder where you have installed the SmartFoxServer

To install the whiteBoard example follow these steps (whiteBoard example uses server side extension so some additional steps are required):

1. Copy the content of the sfs_ajax_api_dir/examples/whiteBoard/www to sfs_install_dir/Server/webserver/webapps/root where:
   • sfs_ajax_api_dir is the folder where you have unpacked the SmartFoxServer AJAX API
   • sfs_install_dir is the folder where you have installed the SmartFoxServer
2. Copy the content of the sfs_ajax_api_dir/examples/whiteBoard/sfsExtension to sfs_install_dir/Server/sfsExtensions
3. Add the following xml snippet to the zones configuration in the SmartFoxServer configuration xml file:

   <Zone name="whiteBoard" uCountUpdate="false" maxUsers="50" customLogin="false">
   	<Rooms>
   		<Room name="Lobby" maxUsers="50" isPrivate="false" isTemp="false" autoJoin="true" uCountUpdate="false">
   			<Extensions>
   				<extension name="xt" className="whiteBoardExtension.as" type="script" />
   			</Extensions>
   		</Room>
   	</Rooms>
   </Zone>