Getting Started with JBuddy^TM

• Please refer to the JBuddyBots folder and the docs folder contained within for in depth JBuddy Bot Framework instructions.
• Please refer to the JBuddy .NET documentation for COM and .NET specific instructions.

JBuddy SDK is a powerful Java API for communicating with popular instant message and presence internet services with a simple, generic interface. Adding JBuddy technology to an application can take as few as a dozen lines of code! This document describes the process of integrating JBuddy technology into an existing application.

I. Adding a Call-Back Mechanism

At least one class must implement the IGateway interface. This provides a call-back mechanism for messages from the IM server to be received. Any class that implements the IGateway must define the following methods.

• incomingMessage(IClient client, IMessage msg)

This method will be called by JBuddy whenever the IM server sends a message. Provide code for processing incoming messages here.

• adminMessage(IClient client, IMessage msg)

This method will be called by JBuddy whenever any special notifications (including errors) are encountered in communication with the IM server. Provide code for processing administrative messages here.

• incomingBuddy(IClient client, IBuddy buddy)

This method will be called by JBuddy whenever a presence update occurs (online status changes of users in the buddy list). The current presence/status of users in the buddy list are automatically stored but this provides the ability to add extra handling.

• connectionLost(IClient client, String reason)

This method will be called by JBuddy whenever the connection to the IM service is lost.

II. Creating a IClient Instance

A valid screen name and password and network access is required to use an IM service. With JBuddy SDK, connections to the IM service are managed through IClient instances. JBuddy supports both public and enterprise IM solutions. In version 6, JBuddy connects to eight popular IM services: AOL Instant Messenger (AIM), ICQ, Microsoft Messenger (MSN), and Yahoo Instant Messenger (YIM), Google Talk (XMPP), Lotus Sametime, Microsoft LCS/OCS, Jabber (XMPP), and JBuddy Message Server. To create an IClient, call the IClientFactory's factory method with the appropriate arguments. For example, this is how an AIM client would be created with IClientFactory:

IClient myAimClient = IClientFactory.factory(myGateway, IClient.AIM, "myAIMUserName", "myAIMPassword");

(Where myGateway is an object reference to a user supplied class that implements IGateway.)

To create a instance of a ICQ, MSN, YIM client, Google Talk, Lotus Sametime, Microsoft LCS/OCS, Jabber, or JBuddy Message Server simply substitute IClient.ICQ, IClient.MSN, or IClient.YIM, IClient.JABBER, IClient.SAMETIME, IClient.LCS, IClient.JABBER, or IClient.JSC for IClient.AIM, respectively.

III. Connecting to the IM Server

To connect to the IM Server simply call connect() on the client. After a successful return from connect(), no further methods should be invoked on the JBuddy API except iclient's isOnline(). Once isOnline() returns true(), the iclient is ready for use. Note: during the sign on process and before isOnline() returns true, the IGateway's callbacks may be called such as when the iclient's buddy list is retrieved. The developer should NOT use the callback thread for invoking the JBuddy API methods and must not perform any 'expensive' operations that would delay the callback from returning since the callback thread is the socket listener's thread for some of the IM protocols.

myAimClient.connect();

IV. Sending an Instant Message

To send an Instant Message, simply call sendIM(recipientUserId, message) on the client or use sendMessage() to send rich formatted text. Note: do not send any IMs for at least a few seconds after signing on a client since some IM protocols such as AIM are sensitive to misuse.

myAimClient.sendIM(recipientUserId, message);

V. Disconnecting from the IM Server

To disconnect to the IM Server simply call disconnect() on the client. If you just sent a message you should avoid disconnecting for a few seconds so that the IM server will process your request and not disregard it as misuse.

myAimClient.disconnect();

VI. Summary

There are many other features in JBuddy SDK that are not listed here that can be added to an application. Refer to the demonstration examples and the JBuddy Java API documentation found in the javadocs folder. Also don't overlook the power and simplicity of the JBuddyBots Framework. With this Bot Framework you can quickly create an interactive IM application with simple XML.