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).

Version:

$Revision: 1.20 $

Author:

paulw

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	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
Buddy	addBuddy(java.lang.String buddyName, java.lang.String groupName) Add a buddy to a group.
Buddy	addBuddy(java.lang.String buddyName, java.lang.String groupName, int pos) Add a buddy to a group.
void	addEventListener(JaimEventListener l) Add an EventListener object.
void	addPermit(java.lang.String buddy) Adds the specified buddy to your permit list.
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(FLAPFrame fr)
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(TocResponse tr)
boolean	isConfigValid() Indicate whether configuration information has been received from the TOC server.
boolean	isLoginComplete() Check if the TOC login process has completed
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(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(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(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(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(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(FLAPFrame fr)

HandleTocResponse

protected void HandleTocResponse(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 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 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 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

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