/*
* Hamsam - Instant Messaging API
* Copyright (C) 2003 Raghu K
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
package hamsam.api;
import java.io.Serializable;
import java.util.Vector;
import hamsam.protocol.Protocol;
import hamsam.exception.IllegalArgumentException;
import hamsam.exception.UnsupportedOperationException;
import hamsam.exception.IllegalStateException;
/**
* A conference is a communication mechanism by which more than
* two buddies can exchange messages with each other.
*
* <p>
* Not all protocols support conferences. To check whether a protocol supports
* conferencing, use {@link hamsam.protocol.Protocol#isConferenceSupported()
* Protocol.isConferenceSupported()} method.
*/
public class Conference implements Serializable
{
/**
* The underlying protocol for this conference.
*/
private Protocol protocol;
/**
* The host buddy.
*/
private Buddy host;
/**
* A list of all participants, including the host.
*/
private Vector buddies;
/**
* Construct a conference. This constructor is meant for internal use
* by the library and not for the users of Hamsam. You may use
* {@link #Conference(Protocol,Buddy,Buddy[],String) Conference(protocol,host,
* buddies,message)} to start a new conference.
*
* @param protocol the underlying protocol for this conference.
* @param host the buddy who is hosting this conference.
* @param buddies a list of all buddies participating in this conference,
* including the host.
* @throws UnsupportedOperationException if the protocol does not support conferences.
* @throws IllegalArgumentException if the protocol for any of the participants is
* different from the one specified.
*/
public Conference(Protocol protocol, Buddy host, Buddy[] buddies) throws UnsupportedOperationException, IllegalArgumentException
{
if(protocol.isConferenceSupported())
{
this.buddies = new Vector();
this.protocol = protocol;
if(host.getProtocol() != protocol)
throw new IllegalArgumentException("Protocol is not same for all participants");
this.host = host;
for(int i = 0; i < buddies.length; i++)
if(buddies[i].getProtocol() != protocol)
throw new IllegalArgumentException("Protocol is not same for all participants");
else
addParticipant(buddies[i]);
}
else
throw new UnsupportedOperationException("This protocol does not support conference");
}
/**
* Start a new conference and invite buddies to join. This constructor is
* used to create new conferences.
*
* @param protocol the underlying protocol for this conference.
* @param host the buddy who is hosting this conference.
* @param buddies a list of all buddies participating in this conference,
* including the host.
* @param message the invitation message that is to be sent to the participants.
*
* @throws UnsupportedOperationException if the protocol does not support conferences.
* @throws IllegalArgumentException if the protocol for any of the participants is
* different from the one specified.
* @throws IllegalStateException if the protocol is not connected yet
*/
public Conference(Protocol protocol, Buddy host, Buddy[] buddies, String message) throws UnsupportedOperationException, IllegalArgumentException, IllegalStateException
{
this(protocol, host, buddies);
protocol.startConference(this, message);
}
/**
* Quit from this conference.
*
* @throws UnsupportedOperationException if the underlying protocol does not
* support conferences.
* @throws IllegalStateException if the protocol is not connected yet
*/
public void quit() throws UnsupportedOperationException, IllegalStateException
{
protocol.quitConference(this);
}
/**
* Send a message to this conference.
*
* @param message the message to be sent.
*
* @throws UnsupportedOperationException if the underlying protocol does not
* support conferences.
* @throws IllegalStateException if the protocol is not connected yet
*/
public void sendMessage(Message message) throws UnsupportedOperationException, IllegalStateException
{
protocol.sendConferenceMessage(this, message);
}
/**
* Add a new participant to this conference object. This method is meant for
* internal use by the library and not for the users of Hamsam.
*
* @param buddy the buddy to be added to this conference.
*/
public void addParticipant(Buddy buddy)
{
if(!buddies.contains(buddy))
buddies.add(buddy);
}
/**
* Returns all participants for this conference.
*
* @return all participants for this conference.
*/
public Buddy[] getParticipants()
{
return (Buddy[]) buddies.toArray(new Buddy[0]);
}
/**
* Returns the host buddy for this conference.
*
* @return the host buddy for this conference.
*/
public Buddy getHost()
{
return host;
}
/**
* Returns the protocol for this conference.
*
* @return the protocol for this conference.
*/
public Protocol getProtocol()
{
return protocol;
}
/**
* Removes a buddy from this conference object. This method is for
* internal use by Hamsam. As a user of the API, you should never
* invoke this method. Hamsam does not allow you to block another user
* from a conference.
*
* @param buddy the buddy to be removed.
*/
public void removeParticipant(Buddy buddy)
{
buddies.remove(buddy);
}
}