Example Source Code

Example Java source code for using the Yahoo Messenger IM SDK can be downloaded from the following location. The example code was developed using NetBeans 6.9, although it should easily port to any Java IDE.


        http://github.com/yahoo/messenger-sdk
      

The compressed archive is divided into two projects: a low-level set of libraries that interact with the Yahoo Messenger servers, and a GUI application that uses the low-level libraries to emulate a Java ME Yahoo Messenger IM SDK client.

In order to run the source code examples, you will need to do the following:

  1. If you simply wish to test the lower-level libraries, open the project in NetBeans. Next, open the com.yahoo.messenger.main.YahooMessengerTestMain.java file and insert your authentication consumer key and authentication consumer secret into the constant fields, then compile and run the project. If you need to create your authentication consumer key and secret, see here for more details.
  2. If you wish to run the LWUIT examples, you will need to first download the LWUIT libraries from here. These must be linked into the project so that LWUIT will not be listed as a missing resource. Open the LWUIT archive that you downloaded, then select the YahooMessengerLWUIT project. Finally, right-click and choose the "Properties" menu item, as shown below.
  3. Next, in the Project Properties dialog, choose Libraries & Resources from the Category pane, then press the "Add Jar/Zip..." button on the right side. Locate the file "LWUIT.jar" file inside the /lib subdirectory of the LWUIT distribution, and add it to the project. If there is a previous listing for the LWUIT.jar library, remove it. See the following figure.
  4. Finally, open the com.yahoo.messenger.ui.MessengerLWUITMidlet.java file and insert your authentication consumer key and authentication consumer secret into the constant fields, then compile and run the project. If you need to create your authentication consumer key and secret, see here for more details.

Note that the source code provided is not a complete Yahoo Messenger client in itself—much of the functionality has been left unimplemented. Instead, it serves as a springboard project that not only allows you to see how such a client works, but also provides a design framework to continue building an IM client across a number of platforms.

Specifically, the code consists of functionality to perform the following:

  1. Login to the Yahoo Messegner IM SDK servers.
  2. Obtain your contact list and presence status.
  3. Update both your presence status as well as those in your contact list.
  4. Send a message to a contact.
  5. Receive a message back from a contact.

The Yahoo Messenger Low-Level Libraries

The low-level libraries serve two direct purposes: they communicate with the Yahoo Messenger servers, and they maintain (to a minimal degree) the last known state reported by the server. The libraries consist of nine packages, which are described in greater detail below.

com.yahoo.messenger.manager

The managers are the primary classes of the low-level libraries. They are each implemented as a singleton class, which means there will be only one instance of each class. Instead of instantiating each one directly, you should access each one using its getInstance() method. Each class covers a different family of API calls, and may contain state (such as the user’s contact list or notifications) that was last reported by the servers. If there is state, the class also provides listener methods such that other classes, such as those in a high-level GUI, can monitor for changes.

com.yahoo.messenger.manager.reqresp

The classes in this package are the request/response classes that actually perform the communication with the Yahoo Messenger servers. Using any of the classes always entails the same process: instantiate a class, load the input properties with data (including authentication data), execute the request, then retrieve the output data from the respective properties. If an error occurs during the call, an exception is thrown that will propagate to the manager classes above.

com.yahoo.messenger.manager.data

These are simple data structures used by the manager classes to store state, as reported by the Yahoo Messenger servers.

com.yahoo.messenger.data.json , com.yahoo.messenger.data.notification.json

These classes are data structures that map to the schema found in the APIs. In addition to “getter” and “setter” methods for each member, they contain functionality that allows them to serialize their data to and from JSON, which is required when making calls to the Yahoo Messenger servers. A secondary package is used for data structures employed by the larger Notification API.

These two packages contain other noteworthy classes.

com.yahoo.messenger.exception

This package contains two classes that serve as the exception framework for the low-level Yahoo Messenger libraries.

com.yahoo.messenger.main

This package consists of a single class, YahooMessengerTestMain, which can be used to test out the low-level libraries without having a GUI attached. Remember that in order to run this class, you must obtain an application API key from developer.yahoo.com that has read/write permissions with Yahoo Messenger, as well as a personal Yahoo ID.

The following packages are provided for your convenience, although other Java implementations may have more robust implementations that you can take advantage of.

com.yahoo.messenger.beans

These are utility classes that attempt to emulate the functionality found in the Java Beans PropertyChangeSupport and PropertyChangeListener classes typical of a standard Java SE environment. The manager classes make use of this package to allow other classes to be notified of changes in their internal state.

com.yahoo.messenger.util

These are utility classes that handle items such as making and receiving HTTP GET or POST calls, or tokenizing and parsing strings.

The Yahoo Messenger Java ME/LWUIT GUI

The high-level GUI contains a skeleton Java ME application. It was developer using NetBeans 6.9 and makes use of the Lightweight User-Interface Toolkit (LWUIT) libraries developed by Sun Microsystems, Inc, which must be linked into the project classpath. Note that in order to run the example in a Java ME emulator, you will need the Sun Java Wireless Toolkit CLDC either as a separate implementation, or bundled with an IDE that supports it such as NetBeans.

The following are screen shots of the sample client while running:

The high-level GUI consists of only three packages.

com.yahoo.messenger.ui

This package contains each of the “screens” that are used by the Java ME skeleton client: a splash screen, a login screen, a contacts screen, and a chat screen. Each of these are constructed with the graphical LWUIT classes. The “main” MIDlet class is provided by MessengerLWUITMidlet.java, which in turn calls upon the other classes to build the rest of the GUI screens on an as-needed basis using a technique known as lazy instantiation.

com.yahoo.messenger.ui.task

This package contains functionality that calls upon the low-level libraries to communicate with the Yahoo Messenger servers. Each one is designed as a task that can be cancelled by the user, although the functionality to do so is left unimplemented.

com.yahoo.messenger.ui.renderer

This package contains helper classes that help to render list items, such as items in a contact list or a chat session, as per the LWUIT design.

Example PHP Source Code

You can download example source code written in PHP from the following site:


          http://github.com/yahoo/messenger-sdk-php
        

The example consists of a lower-level PHP library and demo that will access the Yahoo Messenger SDK APIs. The file Client.php is a demonstration program with the following features.

  • The program will automatically add a new buddy
  • The program will return recent Yahoo news for the command: news
  • The program will return recent OMG news for the command: omg
  • The program will change robot status for the command: status new_status
  • The program will return a command list for the command: help
  • The program will return a help command for any other keyword

Table of Contents