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 =
To your Session
object, you need to associate an implementation of ymsg.network.event.SessionListener
MySessionListener mySessionListener = new MySessionListener(this);
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:
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:
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.
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 getMessage methods of the ymsg.network.event.SessionEvent object respectively.