com.wilko.jaim
Class JaimConnection

java.lang.Object
  |
  +--com.wilko.jaim.JaimConnection
All Implemented Interfaces:
java.lang.Runnable

public class JaimConnection
extends java.lang.Object
implements java.lang.Runnable

The JaimConnection object is the primary interface into the Jaim library. Programs should instantiate a JaimConnection (in most cases the simple constructor should be used). Once JaimConnection has been instantiated, call connect() followed by logIn(java.lang.String, java.lang.String, int).


Constructor Summary
JaimConnection()
          Creates new JaimConnection that connects to the default host and port.
JaimConnection(java.lang.String host, int port)
          Creates a new Jaim Connection to the specified host/port.
 
Method Summary
 void acceptChat(java.lang.String chatRoomID)
          Accept a chatroom invitation.
 void addBlock(java.lang.String buddy)
          Adds the specified buddy to your block list.
 void addBuddy(java.lang.String buddy)
          Deprecated. the watchBuddy(java.lang.String) method should be used instead
 com.wilko.jaim.Buddy addBuddy(java.lang.String buddyName, java.lang.String groupName)
          Add a buddy to a group.
 com.wilko.jaim.Buddy addBuddy(java.lang.String buddyName, java.lang.String groupName, int pos)
          Add a buddy to a group.
 void addEventListener(com.wilko.jaim.JaimEventListener l)
          Add an EventListener object.
 void addPermit(java.lang.String buddy)
          Adds the specified buddy to your permit list.
 void chatSend(java.lang.String chatRoomID, java.lang.String message)
          Send a message to a chatroom.
 void connect()
          Initiate a connection to the TOC server
 void deleteBuddy(java.lang.String buddy)
          Deprecated. use unwatchBuddy(java.lang.String) instead
 void disconnect()
          Disconnect from the TOC server
protected  void Dispatch(com.wilko.jaim.FLAPFrame fr)
           
 com.wilko.jaim.Group getGroupBy(java.lang.String name)
          Return a group, given its name
 java.util.Collection getGroups()
          Return the set of groups that have been stored in the TOC server The information returned from this method is only valid if isConfigValid() returns true
 void getInfo(java.lang.String username)
          Get the information for the specified user
 long getInterMessageDelay()
          Deprecated. This function is no longer used
 java.lang.String getNickName()
          Get the formatted Nick Name for this connection.
 java.io.InputStream getURL(java.lang.String file)
          Get an Input stream associated with a URL returned by the "GOTO_URL" toc response
protected  void HandleTocResponse(com.wilko.jaim.TocResponse tr)
           
 void inviteToChat(java.lang.String chatRoomID, java.lang.String user, java.lang.String msg)
          Invite a user to join a chat room.
 boolean isConfigValid()
          Indicate whether configuration information has been received from the TOC server.
 boolean isLoginComplete()
          Check if the TOC login process has completed
 void joinChat(java.lang.String chatRoom)
          Join a chatroom.
 void leaveChat(java.lang.String chatRoomID)
          Leave a chatroom, using the ID specified in the ChatJoinTocResponse
 void logIn(java.lang.String username, java.lang.String password, int waitTime)
          login to the TOC server.
 void logOut()
          Log out from the TOC server
 void removeEventListener(com.wilko.jaim.JaimEventListener l)
          Remove an EventListener object.
 void run()
          The run method for the dispatcher thread
 void saveConfig()
          Save group/buddy list configuration to the TOC server
 void sendEvil(java.lang.String buddy, boolean anonymous)
          Send a warning or "Evil" to another user.
 void sendIM(java.lang.String recipient, java.lang.String msg)
          Send an instant message
 void sendIM(java.lang.String recipient, java.lang.String msg, boolean auto)
          Send an instant message
 void setAway(java.lang.String awayMsg)
          Set the information for the logged in user
 void setDebug(boolean debug)
          Enable/Disable debugging messages to stdout
 void setEventListener(com.wilko.jaim.JaimEventListener l)
          Deprecated. replaced by addEventListener(com.wilko.jaim.JaimEventListener)
 void setIdle(int idleSecs)
          Set the idle time for this user
 void setInfo(java.lang.String information)
          Set the information for the logged in user
 void setInterMessageDelay(long msec)
          Deprecated. This function is no longer used - send throttling is automatic
 void unwatchBuddy(java.lang.String buddy)
          Delete a buddy from the buddy watch list.
 void watchBuddy(java.lang.String buddy)
          Add a buddy to the watch list for this connection.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JaimConnection

public JaimConnection()
Creates new JaimConnection that connects to the default host and port. In most cases this constructor should be used.


JaimConnection

public JaimConnection(java.lang.String host,
                      int port)
Creates a new Jaim Connection to the specified host/port. There are currently no reasons to call this constructor, however AOL may change the TOC host and port in the future

Parameters:
host - The hostname or IP address of the TOC server
port - The port number to connect to on the host
Method Detail

setDebug

public void setDebug(boolean debug)
Enable/Disable debugging messages to stdout

Parameters:
debug - true if debugging messages should be output

setInterMessageDelay

public void setInterMessageDelay(long msec)
Deprecated. This function is no longer used - send throttling is automatic

Specify the intermessage delay time.
The sendIM(java.lang.String, java.lang.String) method will ensure that at least this amount of time has elapsed between messages

Parameters:
msec - The delay period in milliseconds

getInterMessageDelay

public long getInterMessageDelay()
Deprecated. This function is no longer used

Get the intermessage delay time

Returns:
The intermessage delay time in milliseconds

setEventListener

public void setEventListener(com.wilko.jaim.JaimEventListener l)
                      throws java.util.TooManyListenersException
Deprecated. replaced by addEventListener(com.wilko.jaim.JaimEventListener)

Set the EventListener object. This object will be notified of incoming TOC events

Parameters:
l - The listener class to be notified
java.util.TooManyListenersException

addEventListener

public void addEventListener(com.wilko.jaim.JaimEventListener l)
Add an EventListener object. This object will be notified of incoming TOC events

Parameters:
l - The listener class to be notified

removeEventListener

public void removeEventListener(com.wilko.jaim.JaimEventListener l)
Remove an EventListener object. This object will no longer be notified of incoming TOC events

Parameters:
l - The listener class to be removed

connect

public void connect()
             throws java.io.IOException
Initiate a connection to the TOC server

Throws:
java.io.IOException - If an underlying network communication fails

disconnect

public void disconnect()
                throws java.io.IOException
Disconnect from the TOC server

Throws:
java.io.IOException - if a network transport error occurs

isLoginComplete

public boolean isLoginComplete()
Check if the TOC login process has completed

Returns:
true if the login process is complete

logOut

public void logOut()
Log out from the TOC server


getNickName

public java.lang.String getNickName()
Get the formatted Nick Name for this connection. If no formatted nick name has been registered with the TOC server, then the username provided to the logIn call is returned

Returns:
The Nick Name associated with this connection

logIn

public void logIn(java.lang.String username,
                  java.lang.String password,
                  int waitTime)
           throws JaimException,
                  java.io.IOException
login to the TOC server. connect() method should be called first

Parameters:
username - The username to log in with
password - the password for the specified username
waitTime - time in milliseconds for successful login before declaring an error
Throws:
java.io.IOException - If a network error occurs
JaimException - If a login failure occurs or login fails to complete before waittime expires

run

public void run()
The run method for the dispatcher thread

Specified by:
run in interface java.lang.Runnable

Dispatch

protected void Dispatch(com.wilko.jaim.FLAPFrame fr)

HandleTocResponse

protected void HandleTocResponse(com.wilko.jaim.TocResponse tr)

sendIM

public void sendIM(java.lang.String recipient,
                   java.lang.String msg)
            throws java.io.IOException
Send an instant message

Parameters:
recipient - The nickname of the message recipient
msg - The message to send
Throws:
java.io.IOException - if a network error occurs

sendIM

public void sendIM(java.lang.String recipient,
                   java.lang.String msg,
                   boolean auto)
            throws java.io.IOException
Send an instant message

Parameters:
recipient - The nickname of the message recipient
msg - The message to send
auto - true if this is an automatic response (eg. away message)
Throws:
java.io.IOException - if a network error occurs

addBuddy

public com.wilko.jaim.Buddy addBuddy(java.lang.String buddyName,
                                     java.lang.String groupName,
                                     int pos)
Add a buddy to a group. This information can be saved on the server by calling saveConfig()

Parameters:
buddyName - The normalised buddy name to add
groupName - The name of the group to add this buddy to
pos - the position in the group at which to add the buddy.
Returns:
The Buddy object that represents the specified buddy name.

addBuddy

public com.wilko.jaim.Buddy addBuddy(java.lang.String buddyName,
                                     java.lang.String groupName)
Add a buddy to a group. This information can be saved on the server by calling saveConfig() The buddy is added to the end of the group

Parameters:
buddyName - The normalised buddy name to add
groupName - The name of the group to add this buddy to
Returns:
The Buddy object that represents the specified buddy name.

addBuddy

public void addBuddy(java.lang.String buddy)
              throws JaimException
Deprecated. the watchBuddy(java.lang.String) method should be used instead

Add a buddy to the watch list for this connection. This method must be called after connect() It also appears that the login process will not complete unless at least one buddy is added to the watch list

Parameters:
buddy - The nickname to add to the watch list
Throws:
JaimException - if the method is called at the wrong time
See Also:
JaimEventListener

watchBuddy

public void watchBuddy(java.lang.String buddy)
                throws JaimException
Add a buddy to the watch list for this connection. This method must be called after connect() It also appears that the login process will not complete unless at least one buddy is added to the watch list

Parameters:
buddy - The nickname to add to the watch list
Throws:
JaimException - if the method is called at the wrong time
See Also:
JaimEventListener

saveConfig

public void saveConfig()
                throws java.io.IOException
Save group/buddy list configuration to the TOC server

Throws:
java.io.IOException - if a network error occurs

getGroups

public java.util.Collection getGroups()
Return the set of groups that have been stored in the TOC server The information returned from this method is only valid if isConfigValid() returns true

Returns:
A Collection of Group Objects

getGroupBy

public com.wilko.jaim.Group getGroupBy(java.lang.String name)
Return a group, given its name

Returns:
A Group Object corresponding to the string name

isConfigValid

public boolean isConfigValid()
Indicate whether configuration information has been received from the TOC server. If this method returns true then the information returned by getGroups() is valid

Returns:
true if configuration information has been received from the TOC server.

sendEvil

public void sendEvil(java.lang.String buddy,
                     boolean anonymous)
              throws java.io.IOException
Send a warning or "Evil" to another user. You must be involved in a communication with a user before you can warn them

Parameters:
buddy - The nickname of the buddy to warn
anonymous - true if the warning should be sent anonymously
Throws:
java.io.IOException - if a network error occurs

joinChat

public void joinChat(java.lang.String chatRoom)
              throws java.io.IOException
Join a chatroom.

Parameters:
chatRoom - the name of the chat room to join
Throws:
java.io.IOException - if a network error occurs

leaveChat

public void leaveChat(java.lang.String chatRoomID)
               throws java.io.IOException
Leave a chatroom, using the ID specified in the ChatJoinTocResponse

Parameters:
chatRoomID - the name of the chat room to join
Throws:
java.io.IOException - if a network error occurs

inviteToChat

public void inviteToChat(java.lang.String chatRoomID,
                         java.lang.String user,
                         java.lang.String msg)
                  throws java.io.IOException
Invite a user to join a chat room.

Parameters:
chatRoomID - the ID of the chat room to join, specified in the ChatJoinTocResponse
user - the name of the user to invite
msg - a message to include with the invitation
Throws:
java.io.IOException - if a network error occurs

acceptChat

public void acceptChat(java.lang.String chatRoomID)
                throws java.io.IOException
Accept a chatroom invitation.

Parameters:
chatRoomID - the ID of the chat room to join
Throws:
java.io.IOException - if a network error occurs

chatSend

public void chatSend(java.lang.String chatRoomID,
                     java.lang.String message)
              throws java.io.IOException
Send a message to a chatroom.

Throws:
java.io.IOException - if a network error occurs

setInfo

public void setInfo(java.lang.String information)
             throws java.io.IOException
Set the information for the logged in user

Parameters:
information - The information for this user (May contain HTML)
Throws:
java.io.IOException - if a network error occurs

getInfo

public void getInfo(java.lang.String username)
             throws java.io.IOException
Get the information for the specified user

Parameters:
username - The screenname for whom info is requested (May contain HTML)
Throws:
java.io.IOException - if a network error occurs

getURL

public java.io.InputStream getURL(java.lang.String file)
                           throws java.io.IOException,
                                  java.net.MalformedURLException
Get an Input stream associated with a URL returned by the "GOTO_URL" toc response

Parameters:
file - The "file" returned by calling GotoTocResponse#getURL
Returns:
An InputStream connected to the specified URL
Throws:
java.io.IOException - if an IO error occurs
java.net.MalformedURLException - if there is an error building the URL

setAway

public void setAway(java.lang.String awayMsg)
             throws java.io.IOException
Set the information for the logged in user

Parameters:
awayMsg - The away message for this user. May contain HTML. To cancel "away" status set the awayMsg to ""
Throws:
java.io.IOException - if a network error occurs

addPermit

public void addPermit(java.lang.String buddy)
               throws JaimException
Adds the specified buddy to your permit list.

Parameters:
buddy - The buddy to add to your block list. If this is an empty string, mode is changed to "permit none"
Throws:
JaimException - if a network error occurs

addBlock

public void addBlock(java.lang.String buddy)
              throws JaimException
Adds the specified buddy to your block list.

Parameters:
buddy - The buddy to add to your block list. If this is an empty string, mode is changed to "deny none"
Throws:
JaimException - if a network error occurs

setIdle

public void setIdle(int idleSecs)
             throws java.io.IOException
Set the idle time for this user

Parameters:
idleSecs - The number of seconds the user has been idle for. Set to 0 to indicate current activity. The server will increment the idle time if non-zero
Throws:
java.io.IOException - if a network error occurs

deleteBuddy

public void deleteBuddy(java.lang.String buddy)
Deprecated. use unwatchBuddy(java.lang.String) instead

Delete a buddy from the buddy watch list. The buddy should have been added with addBuddy(java.lang.String, java.lang.String, int) first. The buddy list can only be modified after connect() is called.

Parameters:
buddy - The buddy name to be deleted\

unwatchBuddy

public void unwatchBuddy(java.lang.String buddy)
Delete a buddy from the buddy watch list. The buddy should have been added with addBuddy(java.lang.String, java.lang.String, int) first. The buddy list can only be modified after connect() is called.

Parameters:
buddy - The buddy name to be deleted