Instant messaging represents a medium via which messaging partners can interact in a synchronous fashion. Correspondence can occur in a near “instant” manner. Chances are the majority of workgroups in your company rely on one of the “big four” instant messaging programs: AOL Instant Messenger, MSN Messenger, Lotus Sametime, or Yahoo! Instant Messenger. Yahoo! Instant Messenger in particular has accumulated a significant following because of its easy to use, rich graphical user interface. Facilities such as the ability to leave “offline” instant messages make Yahoo! Instant Messenger particularly attractive. If Yahoo turns out to be the instant messaging application that makes the most sense for you to use, then you’ll certainly want to know about jYMSG.

YMSG (without the j) is the protocol used by Yahoo’s instant messaging and chat software. jYMSG is a Java API that allows you to interact programmatically with Yahoo’s messaging and chat services. For example, with jYMSG you can have an instant message sent to your system administrator from your J2EE application server when a critical error requiring attention occurs. Sending a Yahoo instant message via Java is made quite easy with jYMSG. This article shows you how to build a Swing-based application through which you can instant message your Yahoo messaging partners. Though it will not be as feature rich as the Yaoo! Instant Messenger client, you will get a good introduction to the power of jYMSG.

jYMSG is released under the GNU General Public License. It is a SourceForge.net project that has gained a significant following due to the ease of use of its API. However, it is not endorsed or supported by Yahoo! Inc. It abstracts the more complex underlying interaction with Yahoo’s publicly released API. Before you get started using it, read the “Compatibilities” sidebar to make sure you have dependencies covered.

jYMSG is written purely in Java and uses no native code. Consequently, you can use the API on basically any platform that supports Java.

Obtaining jYMSG
To begin, download the jYMSG API from SourceForge. Because of a change in the login protocol, you will need to download a patch packaged as a JAR file that will allow you to connect to Yahoo via the API. This patch JAR (ymsg_network_v0_51.jar) will need to replace the ymsg_network_v0_5.jar, which ships with the v 0.5 download. This file as well as ymsg_support_v0_5.jar will need to be included in your runtime and Java build path.

Supported Features
The jYMSG API supports a slew of the Yahoo Instant Messenger protocol’s offerings, some of which are outlined below:

• Login/Logout
• Fallback ports
• Login timeouts
• HTML/Socks proxy support
• Groups and Friends list
• Adding and removing friends
• Ignore
• Conferences
• Chatrooms
• Typing notification
• File Transfer
• New mail updates

This article showcases just some of the API offerings of jYMSG; a full list of capabilities is available on the project page. But this article should prepare you to venture out on your own, focusing, in particular, on jYMSG’s messaging support.

Programming with jYMSG
Perhaps the best way to introduce you to how to program with the jYMSG API for messaging with Yahoo is via a working example. The example in this article is a Swing-based application that mimics some of the functionality of Yahoo Instant Messenger. It is not meant to be used in production. Rather, it provides a sandbox for the understanding of jYMSG API. Using the sample code in this article, you can can consider how to use the jYMSG in your organization.

To interact with the Yahoo messaging service using jYMSG, first create a ymsg.network.Session object:

ymsg.network.Session  yahooMessengerSession = new ymsg.network.Session();

To your Session object, you need to associate an implementation of ymsg.network.event.SessionListener:

MySessionListener mySessionListener = new MySessionListener(this);yahooMessengerSession.addSessionListener(mySessionListener);

It is this implementation that listens for events from Yahoo’s messaging and chat service. I’ll show you how to implement the SessionListener in just a bit.

To login into to the Yahoo messaging service, you simply use the login method of the instantiated ymsg.network.Session object:

yahooMessengerSession.login(userName, password);

The login method can throw an IllegalStateException (if the user is already logged in), an IOException (if i/o problems such as timeouts are experienced when logging in), an AccountLockedException (if Yahoo has locked the account trying to login), and LoginRefusedException (if the username/password combination is refused by the Yahoo server).

Once you are successfully logged in, you are allowed to send messages to other Yahoo contacts with the sendMessage method of the ymsg.network.Session object. It is important that the contact that you are sending a message to has accepted you as a Friend. Otherwise, if the person you are sending messages to has opted to “Ignore anyone who is not on my Friend list” (the default messaging filtering option), messages you send will be sent into the black holes of cyberspace. Messages are sent via the syntax:

yahooMessengerSession.sendMessage(messageTo, messageText);

messageTo is a string representing the Friend to whom you want to send a text message. The text message itelf is represented by the string messageText.

Sending messages represents an active interaction with the Yahoo messaging service. How do you go about passively receiving messages and then reacting? This is done via an implementation of the ymsg.network.event.SessionListener interface. Implement this interface using the example class MySessionListener. The SessionListenerInterface obligates you to implement an array of methods. This demonstration only handles a few of these methods in order to demonstrate how the jYMSG API communicates with a client to handle events received from Yahoo’s IM protocol:

• messageReceived(SessionEvent ev): Invoked when someone sends you an instant messenger (personal) message.
• errorMessageReceived(SessionErrorEvent ev): Invoked when a protocol level error occurs. Typically, Yahoo is flagging an error in a recent operation.
• buzzReceived(SessionEvent ev): Invoked when someone sends you a buzz message.
• connectionClosed(SessionEvent ev): Invoked when the Yahoo connection is broken.

The connectionClosed method deserves some extra scrutiny since it can be called for a number of reasons (grabbed from jYMSG’s API documentation):

• At some point after the session is ended (logout), as confirmation that the session is now dead.
• At some point before or after login returns, when there has been a problem logging in (for example, incorrect password).
• When network problems mean the connection to Yahoo servers is lost. When Yahoo wishes to throw us off of the system for any reason (for example another client attempts to log in with the same Yahoo ID – the original client is terminated.)

It is important to note the difference between the chatMessageReceived(SessionChatEvent) method and the messageReceived(SessionEvent) method. The latter method handles instant messenger (personal messages) while the chatMessageReceived method handles chatroom lobby messages.

Within the messageReceived method, one can extract the sender info and text message sent to you by using the getFrom and getMessage methods of the ymsg.network.event.SessionEvent object respectively.

The Example Application in Action
The sample Swing application for this article (download the code from the link in the left column) is shown in action in Figure 1.

MySessionListener (the implementation of the SessionListener interface) has its own instance of the YahooClient object, which points to the instance created in the YahooClient class. This linking is how the MySessionListener instance instructs the Swing app to update itself as necessary. To separate presentation and business logic, the YahooClient class contains methods such as updateMessagingPanel and handleConnectionClosed, which are designed to react to events received by the SessionListener implementation.

Closing the Swing application triggers a windowClosing event as defined by the WindowListener interface. You then make a call to the ymsg.network.Session object’s logout method, which terminates the Yahoo session. The logout method can throw an IllegalStateException or an IOException.

Learn More with the Bundled Examples
This article barely scratches the surface of what the jYMSG API has to offer. The API, though not covering all of YMSG’s offerings, does cover the lion’s share of it (see project homepage for unsupported features).

This help documentation page is particularly useful for jumpstarting work with the API. For example, you can see the following code, which allows you to print your group and underlying friend’s list from your ymsg.network.Session object (ss in the code below):

	YahooGroup[] yg = ss.getGroups();	for(int i=0;i<yg.length;i++)	{   System.out.println(yg[i].getName());	    for(int j=0;j<yg[i].size();j++)	    {   YahooUser yu = yg[i].getUserAt(j);	        System.out.println("  "+yu.toString());	    }	}

As I tried to learn how to use the jYMSG API, I also found the example source code bundled with the jYMSG source download to be quite helpful. There are a huge number of classes in the ymsg.support package that you can analyze to understand how to use jYMSG to build your own messaging applications that can programmatically interact with Yahoo’s messaging and chat services. For example, you might use jYMSG to build an applet on your Web site that visitors can use to interact with your customer service representatives. You might also consider building a jYMSG log4J appender to allow your Java applications to send critical log messages to the appropriate personnel in your organization via a Yahoo instant message.