hamsam.protocol
Interface Protocol

public interface Protocol

A protocol is a specific implementation of instant messaging services. Popular examples of instant messaging services are MSN, Yahoo!, NIM etc.

Hamsam provides an implementation independent way of dealing with protocols through this interface. Each of the protocols implements the methods in this interface, so that a user of Hamsam library can use these methods to talk to any protocol available.

This also makes Hamsam a plug-and-play library. The Protocol interface along with the ProtocolManager class, helps to easily add new protocols, without any change to the source code. This means that, if you have an application coded properly, you don't need to change that code, as and when new versions of Hamsam library (with new protocol additions) are released.

See Also:

ProtocolManager

Method Summary

void	addToBuddyList(Buddy buddy) Add a buddy to your buddy list.
void	changeBuddyAlias(Buddy buddy, java.lang.String alias) Changes the alias of a buddy.
void	changeStatus(java.lang.String status) Change the status message for the user logged in for this protocol.
void	connect(java.lang.String username, java.lang.String password, ProxyInfo info) Connect to the instant messaging server.
void	deleteFromBuddyList(Buddy buddy) Delete a buddy from your buddy list.
void	disconnect() Disconnect from the instant messaging service.
java.lang.String	getProtocolName() Returns the name of this protocol.
SmileyComponent[]	getSupportedSmileys() Returns an array of all SmileyComponents supported by this protocol.
java.lang.String[]	getSupportedStatusMessages() Returns an array of status messages supported by this protocol.
void	ignoreBuddy(Buddy buddy) Prevent a buddy from sending you messages.
boolean	isBuddyAddRequestSupported() Determines whether this protocol will notify you if a user attempts to add you to his / her buddy list.
boolean	isBuddyGroupSupported() Determines whether this protocol supports arranging buddies in different groups.
boolean	isBuddyNameAliasSupported() Determines whether this protocol supports buddy name aliases.
boolean	isConferenceSupported() Determines whether this protocol supports conferences.
boolean	isIgnoreSupported() Determines whether this protocol supports ignoring buddies.
boolean	isInvisibleSupported() Determines whether this protocol supports setting the status of the user to invisible.
boolean	isMailNotifySupported() Determines whether this protocol supports e-mail alerts.
boolean	isOfflineMessageSupported() Determines whether this protocol supports sending and receiving offline messages.
boolean	isTypingNotifySupported() Determines whether this protocol supports typing notifications.
void	quitConference(Conference conf) Disconnect the current user from a conference.
void	sendConferenceMessage(Conference conf, Message message) Send a conference message.
void	sendInstantMessage(Buddy buddy, Message message) Send an instant message to a buddy.
void	setListener(IMListener listener) Sets the listener for this protocol.
void	startConference(Conference conf, java.lang.String message) Start a new conference by inviting some buddies.
void	typingStarted(Buddy buddy) Notify this buddy that you have started typing.
void	typingStopped(Buddy buddy) Notify this buddy that you have stopped typing.
void	unignoreBuddy(Buddy buddy) Undo a previous ignore operation for a buddy.

Method Detail

changeStatus

public void changeStatus(java.lang.String status)
                  throws IllegalArgumentException,
                         IllegalStateException

Change the status message for the user logged in for this protocol. If status is null, the status is changed to invisible. If this protocol does not support invisible status, it throws an IllegalArgumentException.

A protocol may support only a limited range of status messages. If you pass a status message which is not supported by the underlying protocol, it will throw an IllegalArgumentException. In order to get a complete list of supported status messages, use the getSupportedStatusMessages() method.

Parameters:

status - the new status message.

Throws:

IllegalArgumentException - if status is null and this protocol does not support invisible status, or the status message is invalid.

IllegalStateException - if the protocol is not connected.

See Also:

isInvisibleSupported(), getSupportedStatusMessages()

connect

public void connect(java.lang.String username,
                    java.lang.String password,
                    ProxyInfo info)
             throws IllegalStateException

Connect to the instant messaging server. This is equivalent to the logging in to the service.

Parameters:

username - the user id to log in.

password - the password for authentication.

info - the proxy information explaining how to connect.

Throws:

IllegalStateException - if no listener is set using the setListener method.

disconnect

public void disconnect()
                throws IllegalStateException

Disconnect from the instant messaging service. This is equivalent to logging out from the service.

Throws:

IllegalStateException - if the protocol is not connected.

getProtocolName

public java.lang.String getProtocolName()

Returns the name of this protocol. This method is used to distinguish each of the protocols supported by the API. No two protocols will have the same name. The name is a symbolic one like Yahoo or MSN that may be displayed to the end-user to identify this protocol.

Returns:

the identifying name of this protocol.

isBuddyAddRequestSupported

public boolean isBuddyAddRequestSupported()

Determines whether this protocol will notify you if a user attempts to add you to his / her buddy list.

Returns:

true if this protocol supports buddy add notifications, false otherwise.

isBuddyNameAliasSupported

public boolean isBuddyNameAliasSupported()

Determines whether this protocol supports buddy name aliases. Some protocols supports a nickname (friendly name) for buddies.

Returns:

true if this protocol supports buddy aliases, false otherwise.

isBuddyGroupSupported

public boolean isBuddyGroupSupported()

Determines whether this protocol supports arranging buddies in different groups.

Returns:

true if this protocol supports buddy groups, false otherwise.

isIgnoreSupported

public boolean isIgnoreSupported()

Determines whether this protocol supports ignoring buddies. Ignored buddies can not send messages to the person who ignored them.

Returns:

true if this protocol supports buddy ignore, false otherwise.

isOfflineMessageSupported

public boolean isOfflineMessageSupported()

Determines whether this protocol supports sending and receiving offline messages. Offline messages are messages which are sent when the receipient is not connected to the instant messaging system. These messages are stored by the instant messaging server and later delivered to the receipient when he / she connects to the system.

Returns:

true if this protocol supports offline messages, false otherwise.

isTypingNotifySupported

public boolean isTypingNotifySupported()

Determines whether this protocol supports typing notifications. In an instant messaging session, some protocols inform one user that the other person starts or stops typing.

Returns:

true if this protocol supports typing notifications, false otherwise.

isConferenceSupported

public boolean isConferenceSupported()

Determines whether this protocol supports conferences.

Returns:

true if this protocol supports conferences, false otherwise.

See Also:

Conference

isMailNotifySupported

public boolean isMailNotifySupported()

Determines whether this protocol supports e-mail alerts. Many protcols have associated e-mail accounts. When an e-mail arrives in that account, a notification is sent.

Returns:

true if this protocol supports e-mail notifications, false otherwise.

isInvisibleSupported

public boolean isInvisibleSupported()

Determines whether this protocol supports setting the status of the user to invisible. Invisible users appear as offline to other users although they can send and receive messages and participate in any other operations.

Returns:

true if this protocol supports invisible status, false otherwise.

setListener

public void setListener(IMListener listener)

Sets the listener for this protocol. This listener will be notified for any instant message events that originates from this protocol.

Parameters:

listener - the listener for this protocol, pass null to unregister the current listener.

startConference

public void startConference(Conference conf,
                            java.lang.String message)
                     throws UnsupportedOperationException,
                            IllegalStateException

Start a new conference by inviting some buddies.

Parameters:

conf - the conference which is to be started.

message - the invitation message to be sent.

Throws:

UnsupportedOperationException - if this protocol does not support conferences.

IllegalStateException - if the protocol is not yet connected.

quitConference

public void quitConference(Conference conf)
                    throws UnsupportedOperationException,
                           IllegalStateException

Disconnect the current user from a conference.

Parameters:

conf - the conference from which the user has to disconnect.

Throws:

UnsupportedOperationException - if this protocol does not support conferences.

IllegalStateException - if the protocol is not yet connected.

sendConferenceMessage

public void sendConferenceMessage(Conference conf,
                                  Message message)
                           throws UnsupportedOperationException,
                                  IllegalStateException

Send a conference message.

Parameters:

conf - the conference to which the message is to be sent.

message - the instant message to be sent.

Throws:

UnsupportedOperationException - if this protocol does not support conferences.

IllegalStateException - if the protocol is not yet connected.

addToBuddyList

public void addToBuddyList(Buddy buddy)
                    throws IllegalArgumentException,
                           IllegalStateException

Add a buddy to your buddy list. The result of this operation will be notified to the registered IMListener.

Parameters:

buddy - the buddy to be added.

Throws:

IllegalArgumentException - if the protocol supports buddy groups and the group of the buddy is not specified.

IllegalStateException - if the protocol is not yet connected.

See Also:

IMListener.buddyAddRequest, IMListener.buddyAdded, IMListener.buddyAddFailed

deleteFromBuddyList

public void deleteFromBuddyList(Buddy buddy)
                         throws IllegalArgumentException,
                                IllegalStateException

Delete a buddy from your buddy list. The result of this operation will be notified to the registered IMListener.

Parameters:

buddy - the buddy to be deleted.

Throws:

IllegalArgumentException - if the protocol supports buddy groups and the group of the buddy is not specified.

IllegalStateException - if the protocol is not yet connected.

See Also:

IMListener.buddyDeleted, IMListener.buddyDeleteFailed

ignoreBuddy

public void ignoreBuddy(Buddy buddy)
                 throws UnsupportedOperationException,
                        IllegalStateException

Prevent a buddy from sending you messages. The result of this operation will be notified to the registered IMListener.

Parameters:

buddy - the buddy to be ignored.

Throws:

UnsupportedOperationException - if this protocol does not support ignoring buddies.

IllegalStateException - if the protocol is not yet connected.

See Also:

IMListener.buddyIgnored, IMListener.buddyIgnoreFailed

unignoreBuddy

public void unignoreBuddy(Buddy buddy)
                   throws UnsupportedOperationException,
                          IllegalStateException

Undo a previous ignore operation for a buddy. The result of this operation will be notified to the registered IMListener.

Parameters:

buddy - the buddy to be ignored.

Throws:

UnsupportedOperationException - if this protocol does not support ignoring buddies.

IllegalStateException - if the protocol is not yet connected.

See Also:

IMListener.buddyUnignored, IMListener.buddyUnignoreFailed

sendInstantMessage

public void sendInstantMessage(Buddy buddy,
                               Message message)
                        throws IllegalStateException

Send an instant message to a buddy.

Parameters:

buddy - the buddy to whom the message should be sent.

message - the message to be sent.

Throws:

IllegalStateException - if the protocol is not yet connected.

typingStarted

public void typingStarted(Buddy buddy)
                   throws UnsupportedOperationException,
                          IllegalStateException

Notify this buddy that you have started typing.

Parameters:

buddy - the buddy to whom the typing notification is to be sent.

Throws:

UnsupportedOperationException - if this protocol does not support typing notifications.

IllegalStateException - if the protocol is not yet connected.

typingStopped

public void typingStopped(Buddy buddy)
                   throws UnsupportedOperationException,
                          IllegalStateException

Notify this buddy that you have stopped typing.

Parameters:

buddy - the buddy to whom the typing notification is to be sent.

Throws:

UnsupportedOperationException - if this protocol does not support typing notifications.

IllegalStateException - if the protocol is not yet connected.

getSupportedSmileys

public SmileyComponent[] getSupportedSmileys()

Returns an array of all SmileyComponents supported by this protocol.

Returns:

an array of all SmileyComponents supported by this protocol.

getSupportedStatusMessages

public java.lang.String[] getSupportedStatusMessages()

Returns an array of status messages supported by this protocol. Some protocols may support any status message, in that case a null is returned.

Returns:

array of status messages supported by this protocol, or null if this protocol supports any status message.

changeBuddyAlias

public void changeBuddyAlias(Buddy buddy,
                             java.lang.String alias)
                      throws UnsupportedOperationException

Changes the alias of a buddy.

Parameters:

buddy - the buddy whose alias needs to be changed.

alias - the new alias of this buddy.

Throws:

UnsupportedOperationException - if this protocol does not support buddy aliases.

See Also:

isBuddyNameAliasSupported()