net.java.sip.communicator.service.protocol
Interface AdHocChatRoom

All Known Implementing Classes:

AdHocChatRoomIcqImpl, AdHocChatRoomMsnImpl, AdHocChatRoomYahooImpl

public interface AdHocChatRoom

Represents an ad-hoc rendez-vous point where multiple chat users could communicate together. This interface describes the main methods used by some protocols for multi user chat, without useless methods (such as kicking a participant) which aren't supported by these protocols (MSN, ICQ, Yahoo!, etc.). AdHocChatRoom acts like a simplified ChatRoom.

Author:

Valentin Martinet

Method Summary

void	addMessageListener(AdHocChatRoomMessageListener listener) Registers listener so that it would receive events every time a new message is received on this ad-hoc chat room.
void	addParticipantPresenceListener(AdHocChatRoomParticipantPresenceListener listener) Adds a listener that will be notified of changes in our participation in the ad-hoc room such as us being join, left...
Message	createMessage(String messageText) Create a Message instance for sending a simple text messages with default (text/plain) content type and encoding.
String	getIdentifier() Returns the identifier of this AdHocChatRoom.
String	getName() Returns the name of this AdHocChatRoom.
ProtocolProviderService	getParentProvider() Returns a reference to the provider that created this room.
List<Contact>	getParticipants() Returns a List of Contacts corresponding to all participants currently participating in this room.
int	getParticipantsCount() Returns the number of participants that are currently in this ad-hoc chat room.
void	invite(String userAddress, String reason) Invites another Contact to this ad-hoc chat room.
void	join() Joins this ad-hoc chat room with the nickname of the local user so that the user would start receiving events and messages for it.
void	leave() Leaves this chat room.
void	removeMessageListener(AdHocChatRoomMessageListener listener) Removes listener so that it won't receive any further message events from this ad-hoc room.
void	removeParticipantPresenceListener(AdHocChatRoomParticipantPresenceListener listener) Removes a participant presence listener.
void	sendMessage(Message message) Sends the Message to this ad-hoc chat room.

Method Detail

getName

String getName()

Returns the name of this AdHocChatRoom. The name can't be changed until the AdHocChatRoom is ended.

Returns:

a String containing the name

getIdentifier

String getIdentifier()

Returns the identifier of this AdHocChatRoom. The identifier of the ad-hoc chat room would have the following syntax: [adHocChatRoomName]@[adHocChatRoomServer]@[accountID]

Returns:

a String containing the identifier of this AdHocChatRoom.

addParticipantPresenceListener

void addParticipantPresenceListener(AdHocChatRoomParticipantPresenceListener listener)

Adds a listener that will be notified of changes in our participation in the ad-hoc room such as us being join, left...

Parameters:

listener - a member participation listener.

removeParticipantPresenceListener

void removeParticipantPresenceListener(AdHocChatRoomParticipantPresenceListener listener)

Removes a participant presence listener.

Parameters:

listener - a member participation listener.

addMessageListener

void addMessageListener(AdHocChatRoomMessageListener listener)

Registers listener so that it would receive events every time a new message is received on this ad-hoc chat room.

Parameters:

listener - a MessageListener that would be notified every time a new message is received on this ad-hoc chat room.

removeMessageListener

void removeMessageListener(AdHocChatRoomMessageListener listener)

Removes listener so that it won't receive any further message events from this ad-hoc room.

Parameters:

listener - the MessageListener to remove from this ad-hoc room

invite

void invite(String userAddress,
            String reason)

Invites another Contact to this ad-hoc chat room.

Parameters:

userAddress - the address of the Contact of the user to invite to the ad-hoc room.

reason - a reason, subject, or welcome message that would tell users why they are being invited.

getParticipants

List<Contact> getParticipants()

Returns a List of Contacts corresponding to all participants currently participating in this room.

Returns:

a List of Contacts instances corresponding to all room members.

Throws:

OperationFailedException - if we fail retrieving the list of room participants.

getParticipantsCount

int getParticipantsCount()

Returns the number of participants that are currently in this ad-hoc chat room.

Returns:

int the number of Contacts, currently participating in this ad-hoc room.

createMessage

Message createMessage(String messageText)

Create a Message instance for sending a simple text messages with default (text/plain) content type and encoding.

Parameters:

messageText - the string content of the message.

Returns:

Message the newly created message

sendMessage

void sendMessage(Message message)
                 throws OperationFailedException

Sends the Message to this ad-hoc chat room.

Parameters:

message - the Message to send.

Throws:

OperationFailedException - if sending the message fails for some reason.

getParentProvider

ProtocolProviderService getParentProvider()

Returns a reference to the provider that created this room.

Returns:

a reference to the ProtocolProviderService instance that created this ad-hoc room.

join

void join()
          throws OperationFailedException

Joins this ad-hoc chat room with the nickname of the local user so that the user would start receiving events and messages for it.

Throws:

OperationFailedException - with the corresponding code if an error occurs while joining the ad-hoc room.

leave

void leave()

Leaves this chat room. Once this method is called, the user won't be listed as a member of the chat room any more and no further chat events will be delivered.