hamsam.api
Class Buddy

java.lang.Object
  |
  +--hamsam.api.Buddy

All Implemented Interfaces:

java.io.Serializable

public class Buddy

extends java.lang.Object

implements java.io.Serializable

A buddy is a person who is participating in instant messaging. A buddy is usually identified by a unique name in the underlying protocol's namespace.

See Also:

Serialized Form

Constructor Summary

Buddy(Protocol protocol, java.lang.String username)
Construct a buddy object for a buddy with a specified protocol and username.

Buddy(Protocol protocol, java.lang.String username, java.lang.String group)
Construct a buddy object for a buddy with a specified protocol, username, and group.

Method Summary

void	addToBuddyList() Add this buddy to your buddy list.
void	changeAlias(java.lang.String alias) Changes the alias name of this buddy.
void	deleteFromBuddyList() Delete this buddy from your buddy list.
boolean	equals(java.lang.Object obj) Compares the specified object with this Buddy for equality.
java.lang.String	getAlias() Returns the alias name of this buddy.
java.lang.String	getGroup() Returns the group of this buddy.
Protocol	getProtocol() Get the protocol used by this buddy.
java.lang.String	getStatus() Get the status message for this buddy.
java.lang.String	getUsername() Returns the username of this buddy.
void	ignore() Prevent this buddy from sending you messages.
void	sendInstantMessage(Message message) Send an instant message to this buddy.
void	setAlias(java.lang.String alias) Set the alias name of this buddy.
void	setStatus(java.lang.String status) Set the status message for this buddy.
void	typingStarted() Notify this buddy that you have started typing.
void	typingStopped() Notify this buddy that you have stopped typing.
void	unignore() Undo a previous ignore operation for this buddy.

Methods inherited from class java.lang.Object

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

Constructor Detail

Buddy

public Buddy(Protocol protocol,
             java.lang.String username)

Construct a buddy object for a buddy with a specified protocol and username. This constructor is used when the group of the buddy is not relevant.

Parameters:

protocol - the underlying protocol for this buddy.

username - the username of this buddy.

Buddy

public Buddy(Protocol protocol,
             java.lang.String username,
             java.lang.String group)

Construct a buddy object for a buddy with a specified protocol, username, and group. If the protocol does not support buddy groups, the group parameter is ignored.

Parameters:

protocol - the underlying protocol for this buddy.

username - the username of this buddy.

group - the group to which this buddy belongs to. If the protocol does not support groups, this parameter is ignored.

Method Detail

getStatus

public java.lang.String getStatus()

Get the status message for this buddy. Hamsam does not always keep track of buddy statuses. The only place where a client is notified about status change is the IMListener.buddyStatusChanged(Buddy) method.

Returns:

the status message, or null if this buddy is offline.

See Also:

Protocol.changeStatus(String status)

setStatus

public void setStatus(java.lang.String status)

Set the status message for this buddy.

Parameters:

status - the status message.

getAlias

public java.lang.String getAlias()

Returns the alias name of this buddy. Alias is also known as nick name. Alias is not unique in the namespace of a protocol. Not all protocols support aliases. If this buddy's protocol does not support aliases, this method returns null.

Returns:

the alias name of this buddy.

See Also:

Protocol.isBuddyNameAliasSupported

setAlias

public void setAlias(java.lang.String alias)

Set the alias name of this buddy. This method is internally used by Hamsam API and not meant for users of the API. If you want to change the alias name of a buddy, use changeAlias(newAlias) instead.

Alias is also known as nick name. Alias is not unique in the namespace of a protocol. Not all protocols support aliases.

Parameters:

alias - the alias name of this buddy.

See Also:

Protocol.isBuddyNameAliasSupported

changeAlias

public void changeAlias(java.lang.String alias)
                 throws UnsupportedOperationException

Changes the alias name of this buddy. Alias is also known as nick name. Alias is not unique in the namespace of a protocol. Not all protocols support aliases. If this buddy's protocol does not support aliases, this method throws an UnSupportedOperationException.

Parameters:

alias - the new alias for this buddy

UnsupportedOperationException

getProtocol

public Protocol getProtocol()

Get the protocol used by this buddy.

Returns:

the protocol of this buddy.

getUsername

public java.lang.String getUsername()

Returns the username of this buddy.

Returns:

the username of this buddy.

getGroup

public java.lang.String getGroup()

Returns the group of this buddy. If the underlying protocol does not support groups, this will return null.

Returns:

the group of this buddy.

addToBuddyList

public void addToBuddyList()
                    throws IllegalArgumentException,
                           IllegalStateException

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

Throws:

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

IllegalStateException - if the protocol is not connected yet

See Also:

IMListener.buddyAddRequest, IMListener.buddyAdded, IMListener.buddyAddFailed

deleteFromBuddyList

public void deleteFromBuddyList()
                         throws IllegalArgumentException,
                                IllegalStateException

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

Throws:

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

IllegalStateException - if the protocol is not connected yet

See Also:

IMListener.buddyDeleted, IMListener.buddyDeleteFailed

ignore

public void ignore()
            throws UnsupportedOperationException,
                   IllegalStateException

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

Throws:

UnsupportedOperationException - if this protocol does not support ignoring buddies.

IllegalStateException - if the protocol is not connected yet

See Also:

IMListener.buddyIgnored, IMListener.buddyIgnoreFailed

unignore

public void unignore()
              throws UnsupportedOperationException,
                     IllegalStateException

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

Throws:

UnsupportedOperationException - if this protocol does not support ignoring buddies.

IllegalStateException - if the protocol is not connected yet

See Also:

IMListener.buddyUnignored, IMListener.buddyUnignoreFailed

sendInstantMessage

public void sendInstantMessage(Message message)
                        throws IllegalStateException

Send an instant message to this buddy.

Parameters:

message - the message to be sent.

Throws:

IllegalStateException - if the protocol is not yet connected.

typingStarted

public void typingStarted()
                   throws UnsupportedOperationException,
                          IllegalStateException

Notify this buddy that you have started typing.

Throws:

UnsupportedOperationException - if this protocol does not support typing notifications.

IllegalStateException - if the protocol is not connected yet

typingStopped

public void typingStopped()
                   throws UnsupportedOperationException,
                          IllegalStateException

Notify this buddy that you have stopped typing.

Throws:

UnsupportedOperationException - if this protocol does not support typing notifications.

IllegalStateException - if the protocol is not connected yet

equals

public boolean equals(java.lang.Object obj)

Compares the specified object with this Buddy for equality. Returns true if and only if the specified object is also a Buddy, both Buddies have the same protocol and username.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to be compared for equality with this Buddy.

Returns:

true if the specified object is equal to this Buddy.