ymsg.network
Class YahooChatCategory

Object
  YahooChatCategory

public class YahooChatCategory

extends Object

Represents a chatroom category. Categories are like directories - each category may contain more categories (sub-directories), a list of public chatrooms and a list of private chatrooms. Each room is further sub-divided into lobbies which hold a limited number of users at one time. The YahooChatCategory class is used to form the thickest branches of this tree, and as such is the starting-point for accessing the Yahoo chat system.

The category data is loaded from Yahoo's servers via a special type of HTTP (web) call, returning an XML document listing catrgories and their sub-categories as a tree like structure. Each category contains at least one non-zero entry of the following type:

• Zero or more sub-categories.
• Zero or more public (Yahoo) chatrooms.
• Zero or more private (user) chatrooms.

(It is not possible to have a category with no sub-categories, as well as no rooms!)

These structures are held as Vector objects and can be accessed via the appropriate methods of this class. A call to inspect the public or private rooms of a category will trigger a further download of data from Yahoo's servers, for each individual category inspected. It is therefore recommended that any GUI breaks the hierarchy up into two sections - a tree of categories, then a list of rooms in that category, displayed (and therefore downloaded) only when the category is selected.

The jYMSG API caches data loaded from Yahoo, so revisiting a category does not necessarily force it to reload. The category tree hardly ever changes - even so, a timeout feature should ideally be introduced to invalidate the data when past a certain age, to cater for extreme users who leave either IM software running for weeks at a time without a restart. API users should not rely on an instant response upon subsequent revisits to a category, in case such a feature is added at a later date.)

Rooms information changes on an occassional basis, particularly adding and removing lobbies. This data is also cached when loaded, but can be manually reloaded using the refresh method of this class.

Note: there is no requirement to actually log into Yahoo before reading category, room or lobby information. However, the Session object must be connected before a user can actually enter a desired chatroom lobby.

Future proof warning : It has been pointed out that the static loadCategories methods used to load the category hierarchy are not locale friendly. In a future version of jYMSG these methods may be replaced with a non-static mechanism, which allows multiple hierarchies to be used. This will mean chat room data from different Yahoo locales (not just the US) could be usable side-by-side within a single session.

Since:

1.0

Constructor Summary

YahooChatCategory()

Method Summary

Vector	getCategories() Returns a list sub-categories for this category.
long	getId() Returns the unique ID number for this category.
String	getName() Returns the title of this category.
Vector	getPrivateRooms() Returns a list of private (user) rooms for this category.
Vector	getPublicRooms() Returns a list of public (Yahoo) rooms for this category.
static YahooChatCategory	loadCategories() Top-level method which loads the entire chat category tree.
static YahooChatCategory	loadCategories(Session session) User-specific version of parameter-less loadCategories method, used to fetch the root of the chat category tree.
void	refresh() Forces a re-read of the public and private rooms data for this category.
static void	setLocalePrefix(String l) Enables chatroom data from non-US locales to be accessed.
String	toString() Returns a string representation of this object.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

YahooChatCategory

public YahooChatCategory()

Method Detail

getPublicRooms

public Vector getPublicRooms()

Returns a list of public (Yahoo) rooms for this category. The list is in the form of a Vector of YahooChatRoom objects. This data is loaded if not already present for this category. The list may be zero length.

Returns:

list of public room objects

Throws:

IOException - If i/o problems from underlying streams

Since:

1.0

getPrivateRooms

public Vector getPrivateRooms()

Returns a list of private (user) rooms for this category. The list is in the form of a Vector of YahooChatRoom objects. This data is loaded if not already present for this category. The list may be zero length.

Returns:

list of private room objects

Throws:

IOException - If i/o problems from underlying streams

Since:

1.0

refresh

public void refresh()

Forces a re-read of the public and private rooms data for this category.

Throws:

IOException - If i/o problems from underlying streams

Since:

1.0

getCategories

public Vector getCategories()

Returns a list sub-categories for this category. The list is in the form of a Vector of YahooChatConference objects. The list may be zero length.

Returns:

list of category objects

Since:

1.0

getName

public String getName()

Returns the title of this category.

Returns:

the category name (title)

Since:

1.0

getId

public long getId()

Returns the unique ID number for this category. Under normal circumstances, jYMSG API users should not need to bother with this - it is merely internal detail.

Returns:

category id

Since:

1.0

loadCategories

public static YahooChatCategory loadCategories()

Top-level method which loads the entire chat category tree. This static method is the starting point for using Yahoo chatrooms. The data loaded by this method is cached to speed up future calls.

The YahooChatCategory object returned by this method is a dummy 'root' object - the Yahoo category hierarchy does not have a single root node of its own, so an artificial root is created. This root object is guarantedd therefore to have no public or private rooms, and always have at least one category (unless something has gone horribly wrong!)

Note 1: this method does not depend upon a Session object to work. It can be used without logging into Yahoo.

Note 2: the name and ID fields of the root object have no purpose. getName returns the default string <root>, while getId returns the generation timestamp included in the XML category data loaded from Yahoo. Neither values should be relied upon in future releases. A formalised way of accessing the timestamp may be introduced in later versions.

Note 3: also: the data returned by this method will not contain any adult group listings. To get those, cookies from an appropriate user account must be sent when the data is requested. See the overloaded method loadCategories(Session session) for more.

See future proof warning at the top of the page.

Returns:

root category object

Throws:

IOException - if i/o problems from underlying streams

Since:

1.0

loadCategories

public static YahooChatCategory loadCategories(Session session)

User-specific version of parameter-less loadCategories method, used to fetch the root of the chat category tree. Functions identically to its counterpart, except the cookies from the supplied Session object are remembered, and transmitted as part of each request.

If the supplied Session is null, or its getCookies method returns null (because the session is not logged in) this method functions in the same way as its overloaded companion.

See future proof warning at the top of the page.

Parameters:

session - a connected session object

Returns:

root category object

Throws:

IOException - if i/o problems from underlying streams

Since:

1.0

setLocalePrefix

public static void setLocalePrefix(String l)

Enables chatroom data from non-US locales to be accessed. Pass in the country prefix (for example "fr") without the trailing dot, and it will be prepended to the hostname used to fetch chat category data. This must be done before the call to a loadCategories method. Pass in null to reset the URL back to the default US locale. This method is a stop-gap, to compensate for the fact that the loadCategories methods were designed erroneously without regard for non-US locales. This method may be removed when a more suitable soltution is developed.

See future proof warning at the top of the page.

Parameters:

l - a country prefix, ie. "fr"

Since:

1.0

toString

public String toString()

Returns a string representation of this object.

Returns:

object as a string