changes

A Java package (library/API) to connect and use the Yahoo Instant Messager and Chat protocols (YMSG)

************************************************************************
*                                                                      *
* Version 0.6                                                          *
*                                                                      *
************************************************************************

New stuff:

1) New overloaded methods added to support identities
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identities are now supported, with the introduction of several overloaded
methods to allow a choosen Yahoo identity to be specified.

  Session.sendMessage(String to,String msg,YahooIdentity yid)
  Session.sendBuzz(String to,YahooIdentity yid)
  Session.createConference(String[] users,String msg,Identity yid)

The original (non-identity) versions of these methods simply use the primary
identity.  (Note: the *primary* identity - not necessarily the one the user
logged in with!)


2) Identity methods removed/added
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The former setIdentity() method has been removed, it was never supported 100% 
anyway, and has been replaced by the overloaded methods detailed above.  Three 
new methods have been added to support the new identity code:

  Session.getPrimaryIdentity()
  Session.getLoginIdentity()
  Session.activateIdentity(YahooIdentity yid,boolean activate)

The first will return the primary identity - the original account identity to
which all other identities are aliases.  The second returns the login identity,
the account which was used to log into this session (not the most useful of
things to know... but it's there just-in-case!)  And finally the third 
changes the visibility of identities, except the primary identity.

The YahooConference class has also had a method added to allow access to the
identity associated with the conference.

  YahooConference.getIdentity()


3) New exception: IllegalIdentityException
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A subclass of RuntimeException, so try/catch blocks are optional (but highly
recommended).  Thrown when an operation is attempted with an identity which
is not valid for the current session - in other words, the identity is not
owned by the current user.  Also thrown when activate/deactivate is called 
on the primary identity (which Yahoo apparently does not support!)
  

4) FADE and ALT added to MessageDecoder and MessageElement
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Decoders for Swing Document objects now support fading and alterating
colour text.

Thanks to John Morris, who provided examples of some useful pointers and 
optimisations to the Swing Document code, as well as some sample fade/alt
code.


5) Methods added to MessageDecoderSettings for FADE and ALT control
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Two new accessor pairs have been added to MessageDecoderSettings in
the support package, which enable respect for fade and alt tags within
messages to be enabled or disabled.  Default is false - decoders will
not respect these tags, instead rendering text within them in the 
current font colour.


6) chatLogin() now throws LoginRefusedException
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Typically happens when the room is 'full', this method now correctly reports
the inability to login to a chatroom with a LoginRefusedException.  (This one
is hard to test - so let me know if you encounter problems!)


7) SwingTestClient upgraded
   ~~~~~~~~~~~~~~~~~~~~~~~~
Numerous changes to the SwingTestClient, to introduce identities and make
it easier to use.


8) Properties
   ~~~~~~~~~~
ymsg.network.loginTimeout is now read each time a login() or chatLogin() is
called, meaning that changes in the timeout value during the run of a program
are reflected in the next login.  

All main host and port values are now accessible (should you need to alter
them) via properties.  See README for all the properties now supported.


9) MutableMessageElement added to support rich format encoding
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Trying to marry up Swing and Yahoo's strange message encoding scheme is a 
challenge too far at this point.  The MutableMessageElement is a half-way
solution which allows messages to be built up in a tree-like format, and
then encoded to Yahoo's IM or chat formats.

MutableMessageElement is a Collection, specifically a List (see the
java.util.List interface) which allows its children to be manipulated.
Static methods are used to create new elements, which can then be nested 
inside one another to form the message tree.

This class is still experimental, and could be prone to widespread change.


10) MessageElement constants now public
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As a result of the new MutableMessageElement class, the constants inside its 
parent class, 'MessageElement', have been made public.  To avoid confusion,
use them as statics of the MutableMessageElement class...

"MutableMessageElement.TEXT" rather than "MessageElement.TEXT"


11) 40 new Emoticons added
    ~~~~~~~~~~~~~~~~~~~~~~
The extra emoticons from http://help.yahoo.com/help/us/mesg/use/use-44.html
have been added to the Emoticons class, plus the new Messenger v6.0 emoticons, 
bringing the total up to 75.


12) Proxy-Authorization headers supported in HTTP connections
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[926918] Setting the property "ymsg.network.httpProxyAuth" to the required 
contents of "Proxy-Authorization" will cause this header to be included in 
HTTP messages.  This enables jYMSG to work from networks using HTTP through a 
proxy which needs authentication.

The static method HTTPConnectionHandler.setProxyAuthorizationProperty() 
can be used to set this property in a high level way.  It will build the 
required string, but only supports Basic encoding scheme at present.


13) AccountLockedException and LoginRefusedException extended
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[984099] LoginRefusedException has been enhanced to better describe the nature 
of the login failure.  The new method getStatus() returns a value from 
StatusConstants revealing Yahoo's reason for refusing our login.  -1 is 
returned if the reason is unknown.

AccountLockedException has been made a subclass of LoginRefusedException, so 
all login refusals can now be handled in one generic exception block if 
distinction between different types of failure is not important.  Its status 
value will always return as STATUS_LOCKED.

STATUS_LOCKED is returned when an account is locked; STATUS_BADUSERNAME (an
alias for STATUS_NOTATHOME) when Yahoo claims not to recognise the account;
and STATUS_BAD otherwise (bad password).


14) YahooChatCategory.setLocalePrefix(String) added
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
I got an email from someone trying to use jYMSG to access French chatrooms.
It occured to me that my code doesn't offer any support for non-English
rooms, and as such I've added a new method to allow other Yahoo chat servers
to be queried for chat data.

YahooChatCategory.setLocalePrefix("fr");

This results in "fr.insider.msg.yahoo.com" being queried instead of 
"insider.msg.yahoo.com" .  To clear the setting back to the default call
the method with null.

Note: as the loadCategories() methods cache their data, the call to this
method must be done *before* any call to loadCategories.  This is a rather
clunky solution: one hopes future versions of jYMSG will have better locale 
support, with the ability to access rooms from multiple locales from one 
session.  (Perhaps in retrospect making parts of this class static was a
mistake?)


15) Session.refreshStats() added
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Causes a USERSTAT packet to be sent, to which the Yahoo service will reply
with packets confirming the session status and new mail count (usually zero).  
Doesn't appear to have any function other than to confirm what we already 
know about our session - but as Yahoo supports this functionality (the 
official Yahoo clients have it wired to their "View->Refresh" menu option)
jYMSG now gives you access to it too.


16) Usernames are now lower cased
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[1053155] Any username passed into the login() method will be silently set
to all lower case characters, in keeping with Yahoo's username scheme.


17) SessionListener.conferenceInviteDeclinedReceived added
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As well as an associated method in the adapter.  This is called when someone
declines to join a conference we have invited them to.


Bugs:

1) Fixed bug in YahooChatCategory, re. voice and webcams
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[881368] [1001334] A NullPointerException was thrown when a room element did 
not contain the expected attributes.  Now those attributes are silently set to 
zero.


2) InterruptedIOException thrown by login() and chatLogin()
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Both of these methods in Session used to throw plain IOExceptions on time 
out - these have been upgraded to the more specific subclass of
java.io.InterruptedIOException, meaning that it is now possible to 
distinguish between timeouts and general IO problems.


3) chatLogin() sets status correctly
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
chatLogin() in Session now sets its chat status to FAILED when exiting
via a timeout exception.


4) chatLogin() now moves directly from room to room
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There is now no need to call chatLogout() before moving from room to room.
This was an artificial restriction that Yahoo didn't itself impose.  Calling 
chatLogin() a second time while still logged into a room will cause Yahoo to
automatically log you out of the current room before moving you to the new 
room.  Call chatLogout() when leaving chat rooms altogether.


5) Typing nofifiers and identities, Yahoo bug *implemented*!!!!
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Strange as it may seem, jYMSG actually implements bad functionality 
deliberately!  Yahoo does not allow identities to work with typing notifiers.
All notify packets are sent in the primary identity, regardless of whether
this is appropriate or not.  Further, if a client sends a notify packet with 
an identity other than the primary identity, the Yahoo server re-writes the
packet before it is passed onto the receiving client.

This raises two issues: (1) Typing notify packets sent by 'identities' will
be ignored by the receiver or mis-directed to the wrong window.  (2) Yahoo
IM gives away the primary identity of anyone who uses this type of alias.

I've posted a bug report on the mailing list of the coder who works on the