SFS2X Docs / AdvancedTopics / buddy-list-api

» The Buddy List API

SmartFoxServer 2X provides a new set of client and server API specifically designed for managing Buddies and Buddy Lists including persistence, custom states, ability to go online/offline, runtime and persistent Buddy Variables, server side events and more... The new Buddy API (version 3.0) are loosely based on the previous SFS 1.x Buddy List framework, although we attempted to provide a more simplified approach, better flexibility and more advanced features.

If you are familiar with the previous system you will notice the following differences:

• File based persistence: we have abandoned the old database persistence model in favor of a simpler and faster file-based system. The persistence model is in general much simpler to manage and developers will be able to provide their own custom Storage classes and use their favorite data sources.
• Mutual add/remove: this feature was removed from the system. We noticed that it created confusion for Users and in general it could not satisfy the many different requirements we have encountered. We opted for a more streamlined approach that provides the developer with all the necessary tools to implement their own mutual add/remove features without forcing them into rigid, pre-built solutions. Thanks to a much richer set of server-side Buddy events, developers will be able to extend the Buddy List system in any directions.
  
  In particular we highly recommend to check the new Invitation API provided by the game API.

» New features

The following is a rapid overview of the new features and improvements added in the framework:

• Online status: with SFS 1.x the Buddy would go online every time he logged in the Zone and would go offline any time he would log out. With SFS2X the online state is completely under the control of the developer. Any user can go online and offline in the Buddy system without having to logout etc... Additionally the online state is persistent, so the next time a User will log in again he will be in same online/offline state as when he left in the previous session.


• Custom states: States are custom Strings that are defined in the Zone configuration and can be used to notify the current Buddy "mode". Examples could be: “Available”, “Chat with me”, “Play with me”, “Occupied”, “Be right back” etc… These states should be configured from server side. They will be sent to each client together with the initial BuddyList, after requesting an InitBuddyList from client or server.


• Nickname: an additional nickname is supported by the Buddy List for every Buddy. This is handled via Buddy Variables and stored persistently.


• Enhanced Buddy Variables: Buddy variables are now more flexible supporting all common data types (Bool, Integer, Double, String...) as well as complex objects (SFSObject/Array) just like the other User/Room Variable counterparts.


• Buddy Messages: instead of using private messages (SFS 1.x) Buddies will be able to use a new specific type of message called the BuddyMessage. This is better integrated in the Buddy List system, it embeds the logic for handling blocked Buddies etc... without "polluting" the generic public/private message which are Buddy agnostic. It is strongly recommended to use BuddyMessages for any communication between Buddies.


• Temp Buddies: Temp Buddies where introduced to handle the following common scenario.
  
  • User Gonzo adds User Piggy to his buddy list
  • Gonzo sends a message to Piggy
  • Piggy receives the message but she knows nothing about Gonzo.
  • Gonzo is then added as temp Buddy in Piggy’s list. This means that the Buddy will be transient and it will not be saved, unless Piggy goes ahead and calls addBuddy(‘Gonzo’)


• Server Side Events: the Buddy API provide many useful new events on the server side that can be used in your Extension to handle specific situations: BUDDY_ADD, BUDDY_REMOVE, BUDDY_BLOCK, BUDDY_VARIABLES_UPDATE, BUDDY_ONLINE_STATE_UPDATE, BUDDY_MESSAGE, BUDDY_LIST_INIT.

» Buddy List Persistence

The Buddy List persistence is delegated to an implementation of the BuddyStorage interface found under the com.smartfoxserver.v2.buddylist.storage package. This is the skeleton of the interface:

 
void init();
void destroy();
 
BuddyList loadList(String ownerName) throws SFSBuddyListNotFoundException, IOException;
void saveList(BuddyList buddyList) throws IOException;
List<BuddyVariable> getOfflineVariables(String buddyName) throws IOException;
 
BuddyListManager getBuddyListManager();
void setBuddyListManager(BuddyListManager buddyListManager);

The init() and destroy() method are called upon creation and destruction of the class, while the BuddyListManager getter/setter is used to maintain a reference to the BuddyListManager object that governs the Buddy Lists in the current Zone. The remaining methods represent the core of the persistence mechanism, which is very simple.

• loadList(String ownerName): load the Buddy list for the specified Buddy name.
• saveList(BuddyList buddyList): save the passed Buddy list in the storage system.
• getOfflineVariables(String buddyName): retrieve offline Buddy Variables for a specific Buddy. This method is needed in the following scenario:
  • User Fozzie logs in the system and loads his Buddy List
  • For every Buddy in Fozzie's list that is not online we will need to load their persistent variables directly from the storage system
  • For every offline Buddy the Buddy List Manager will call this method
  It's probably reccomendable to use a small cache of offline variables in order to avoid hitting the data source every time. This is what we do with our default file-based implementation.

You will be able to provide your custom implementation by simply dropping your .jar file in the SFS2X lib/ folder and providing the fully qualified name of the storage class in the AdminTool (Zone Configurator -> BuddyList tab).

>> DOWNLOAD the the default BuddyStorage source code <<

 

(c) 2004-2013 gotoAndPlay() — All rights reserved — www.smartfoxserver.com