com.zion.jbuddy.conference
Interface IConference

public interface IConference

Represents a multi-user conference session.

This class preserves the state of a conference, such as its name (see getName) or the list of users currently connected to it (see getBuddies). It also allows the client to send messages to the conference and invite other users to join.

Creating a Conference

The following steps should be taken to create a conference:

1. Retrieve a new conference instance from the conference service by calling conferenceFactory.
2. Add listeners to the conference using addListener.
3. Call create on the conference.

Example:

IConference conference = myClient.getConferenceService().conferenceFactory();
conference.addListener(myConferenceListener);
conference.create("MyNewRoom");

Joining an Existing Conference

The following steps should be taken to join an existing conference:

1. Retrieve a new conference instance from the conference service by calling conferenceFactory.
2. Add listeners to the conference using addListener.
3. Call join on the conference (being sure to provide a name).

Example:

IConference conference = myClient.getConferenceService().conferenceFactory();
conference.addListener(myConferenceListener);
conference.join("SomeonesRoom");

Accepting Incoming Conference Invitations

Register a listener with the conference service to receive incoming invitations.
To accept and join an incoming conference, call accept on that conference.

Example:

IConferenceServiceListener myConferenceServiceListener = new ConferenceServiceAdapter() {
    public void invitationReceived(ConferenceServiceEvent event) {
        IConference conference = event.getConference();
         
        System.out.println(event.getBuddy() + " has invited us to join " + conference);
        try {
            conference.accept();
        }
        catch (IOException e) {
            e.printStackTrace();
        }
    }
};
myClient.getConferenceService().addListener(myConferenceServiceListener);

Valid for AIM, ICQ, JABBER, LCS, MSN, SAMETIME, YIM.

Since:

5.0, 6.3 LCS (only OCS)

See Also:

IConferenceService, IConferenceListener

Method Summary

void	accept() Accepts a pending invitation and connects to this conference.
void	addListener(IConferenceListener listener) Enables a listener to receive events from this conference.
void	create(String name) Attempts to create a new conference.
void	decline(String message) Declines a pending invitation to join this conference.
void	disconnect() Disconnects the client from this conference.
IBuddy[]	getBuddies() Returns the buddies (users) currently connected to this conference.
IBuddy	getBuddy(String name) Returns the specified buddy (user) that is connected to this conference.
IClient	getClient() Returns the client this conference is associated with.
String	getClientName() Returns the client's user name in this conference.
String	getDisplayName() Returns this conference's display name.
String	getName() Returns this conference's name.
String	getPassword() Returns this conference's password.
void	invite(String[] recipients, String message) Invites users to this conference.
void	invite(String recipient, String message) Invites a user to this conference.
boolean	isOnline() Returns true if the client is successfully connected to this conference.
boolean	isPublished() Returns whether this conference is published (viewable/searchable from a public directory).
void	join(String name) Attempts to join an existing conference.
void	removeListener(IConferenceListener listener) Stops a listener from receiving events from this conference.
void	sendIM(String message) Sends a message of type IM to this conference.
void	sendMessage(IMessage message) Sends a message to this conference.
void	setDisplayName(String displayName) Sets this conference's display name.
void	setPassword(String password) Sets this conference's password.
void	setPublished(boolean isPublished) Sets whether this conference is published (viewable/searchable from a public directory).

Method Detail

getName

String getName()

Returns this conference's name.

To provide a name to this conference, pass one to either create or join.

Valid for AIM, ICQ, JABBER, SAMETIME, YIM.

Returns:

this conference's name, or null. Returns null if this conference is not currently online, or the protocol doesn't support conference names.

getDisplayName

String getDisplayName()

Returns this conference's display name.

Valid for ICQ, JABBER, SAMETIME.

Returns:

this conference's display name, or null. Returns null if the protocol doesn't support display names.

setDisplayName

void setDisplayName(String displayName)
                    throws IOException

Sets this conference's display name.

This method should be called to set the display name before creating this conference. However, some protocols (currently only ICQ and JABBER) allow you to set the conference's display name while the conference is online, if you have sufficient privileges.

The default display name varies between protocols.

Valid for ICQ, JABBER, SAMETIME.

Parameters:

displayName - the display name to set. A null or empty string may be specified, which will cause a default display name to be chosen. The default name varies between protocols; to see the default, pass null here, then call getDisplayName().

Throws:

IOException - if the protocol doesn't support setting the display name, you do not have sufficient privileges, or some other problem occurred

getPassword

String getPassword()

Returns this conference's password.

setPassword

void setPassword(String password)
                 throws IOException

Sets this conference's password.

This method should be called to set the password before creating this conference or joining an existing conference. However, some protocols (currently only ICQ and JABBER) allow you to set the password while the conference is online, if you have sufficient privileges.

Creating a conference with a password set will require other users to provide the password before being allowed to join.

By default, conferences are NOT password-protected.

Valid for ICQ, JABBER, SAMETIME.

Parameters:

password - the password you wish to set. Pass an empty value if you no longer want this conference to be password-protected.

Throws:

IOException - if a problem occurred

isPublished

boolean isPublished()

Returns whether this conference is published (viewable/searchable from a public directory).

setPublished

void setPublished(boolean isPublished)
                  throws IOException

Sets whether this conference is published (viewable/searchable from a public directory). Published conferences can be visible to outside users (perhaps users not intended to join this conference), and users could possibly attempt to join without being invited.

This method should be called before creating this conference. However, some protocols (currently only ICQ and JABBER) allow you to set the publish mode while the conference is online, if you have sufficient privileges.

By default, conferences are NOT published.

Valid for ICQ, JABBER, SAMETIME.

Throws:

IOException - if a problem occurred

addListener

void addListener(IConferenceListener listener)

Enables a listener to receive events from this conference.

removeListener

void removeListener(IConferenceListener listener)

Stops a listener from receiving events from this conference.

accept

void accept()
            throws IOException

Accepts a pending invitation and connects to this conference.

This may only be called if the client was invited to this conference via the conference service invitationReceived event.

Throws:

IOException - if there is no pending invitation, or some other problem occurred

decline

void decline(String message)
             throws IOException

Declines a pending invitation to join this conference.

This may only be called if the client was invited to this conference via the conference service invitationReceived event.

Parameters:

message - the reason you are declining

Throws:

IOException - if there is no pending invitation, or some other problem occurred

create

void create(String name)
            throws IOException

Attempts to create a new conference.

This call may fail if the requested conference already exists on the server, depending on the protocol being used.

Parameters:

name - the name of the conference to create, or null to generate a random conference name (thus creating a random, dynamic conference). The syntax of the random name depends on the protocol being used. Some protocols (currently MSN, LCS and YIM) only support "dynamic" conferences, and will ignore this value.

Throws:

IOException - if the client is not online, is already connecting/connected to this conference, or some other problem occurred

join

void join(String name)
          throws IOException

Attempts to join an existing conference.

This call will fail if the protocol does not support joining existing conferences. Some protocols (currenly MSN LCS, and YIM) only support "dynamic" conferences, which users must be invited to before they can enter.

Parameters:

name - the name of the conference to join

Throws:

IOException - if the client is not online, is already connecting/connected to this conference, or some other problem occurred

isOnline

boolean isOnline()

Returns true if the client is successfully connected to this conference.

disconnect

void disconnect()

Disconnects the client from this conference.

See Also:

IConferenceListener.lostConnection(ConferenceEvent)

getClient

IClient getClient()

Returns the client this conference is associated with.

getClientName

String getClientName()

Returns the client's user name in this conference.

Some protocols (currently only ICQ and JABBER) may use different usernames for conferences than the ones used to connect to the IM server. This method should be called to discover the client's conference username.

Most protocols use the client's IM username for conferences. For those protocols, this method will return the same value as IClient.getName().

getBuddy

IBuddy getBuddy(String name)

Returns the specified buddy (user) that is connected to this conference.

Returns:

the buddy. Returns null if this conference is not currently online, or the specified user is not connected to this conference.

getBuddies

IBuddy[] getBuddies()

Returns the buddies (users) currently connected to this conference.

invite

void invite(String recipient,
            String message)
            throws IOException

Invites a user to this conference.

Parameters:

recipient - the user to invite

message - the message to send along with the invitation

Throws:

IOException - if this conference is not online, or some other problem occurred

invite

void invite(String[] recipients,
            String message)
            throws IOException

Invites users to this conference.

Parameters:

recipients - the users to invite

message - the message to send along with the invitation

Throws:

IOException - if this conference is not online, or some other problem occurred

sendIM

void sendIM(String message)
            throws IOException

Sends a message of type IM to this conference.

Parameters:

message - the message contents

Throws:

IOException - if this conference is not online, or some other problem occurred

sendMessage

void sendMessage(IMessage message)
                 throws IOException

Sends a message to this conference.

Use IMessageFactory to create an IMessage that can be passed to this method. Currently only IM, AUTO_RESPONSE, TYPING (MSN and LCS only), and TYPING_OFF (MSN and LCS only) messages are supported by conferences.

Parameters:

message - the message to send

Throws:

IOException - if this conference is not online, or some other problem occurred