uk.org.retep.xmpp.muc.MucRoomSet Maven / Gradle / Ivy

Go to download
/*
 * Copyright (c) 1998-2010, Peter T Mount

 * All rights reserved.
 *
 * 
 *   This program is free software; you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License as published by
 *   the Free Software Foundation; either version 3 of the License, or
 *   (at your option) any later version.
 * 
 *
 * 
 *   This program 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 General Public License for more details.
 * 
 *
 * 
 *   You should have received a copy of the GNU General Public License along
 *   with this program.  If not, see .
 * 
 *
 * 
 *        GNU GENERAL PUBLIC LICENSE - CLASSPATH EXCEPTION
 * 
 *
 * 
 *   Linking this library statically or dynamically with other modules
 *   is making a combined work based on this library. Thus, the terms
 *   and conditions of the GNU General Public License cover the whole
 *   combination.
 * 
 *
 * 
 *   As a special exception, the copyright holders of this library give
 *   you permission to link this library with independent modules to
 *   produce an executable, regardless of the license terms of these
 *   independent modules, and to copy and distribute the resulting
 *   executable under terms of your choice, provided that you also meet,
 *   for each linked independent module, the terms and conditions of the
 *   license of that module.
 * 
 *
 * 
 *   An independent module is a module which is either not derived from or based
 *   on this library, or a module who's classes extend those within this library
 *   as part of the implementation of the library.
 * 
 *
 * 
 *   If you modify this library, you may extend this exception to your version
 *   of the library, but you are not obligated to do so. If you do not wish to
 *   do so, delete this exception statement from your version.
 * 
 */
package uk.org.retep.xmpp.muc;

import java.util.Collection;
import uk.org.retep.util.messaging.MessageException;
import uk.org.retep.xmpp.JID;

/**
 * A collection of MucRoom instances
 * @param  Type of MucRoom contained in the set
 * @author peter
 */
public interface MucRoomSet
{

    /**
     * The JID of this set, specifically the domain of the MucRoom's it contains
     * @return
     */
    JID getJid();

    /**
     * Return the named room
     * @param name Name of room
     * @return MucRoom or null if not present
     * @throws MessageException
     */
    T get( final String name )
            throws MessageException;

    /**
     * Create the named room
     * @param name Name of room
     * @return true if the room was created or already existed. false means
     * the room could not be created, probably due to capacity restraints
     * @throws MessageException
     */
    boolean create( final String name )
            throws MessageException;

    /**
     * Add the named room
     * @param room MucRoom to add
     * @return true if the room was added
     * @throws MessageException
     */
    boolean add( final T room )
            throws MessageException;

    /**
     * Remove the named room
     * @param name Name of room
     * @return true if the room was removed
     * @throws MessageException
     */
    boolean remove( final String name )
            throws MessageException;

    /**
     * Returns a Collection of the room names in this set
     * @return
     * @throws MessageException
     */
    Collection getRoomNames()
            throws MessageException;

    /**
     * The number of rooms present
     * @return the number of rooms present
     */
    int getSize();

    /**
     * The maximum number of rooms possible, 0=unlimited
     * @return the maximum number of rooms possible, 0=unlimited
     */
    int getCapacity();

    /**
     * The maximum number of rooms possible, 0=unlimited
     *
     * 
     * If capacity>0 and there are more rooms than the capacity,
     * those rooms will remain until they are closed normally. However until the
     * room count drops below the capacity no more rooms can be created.
     * 
     *
     * @param capacity the maximum number of rooms possible, 0=unlimited
     */
    void setCapacity( int capacity );

    /**
     * The maximum number of rooms returned by roomNames, 0=all
     * @return
     */
    int getMaxRoomsReturned();

    /**
     * The maximum number of rooms returned by roomNames, 0=all
     *
     * @param maxRoomsReturned the maximum number of rooms returned by roomNames, 0=all
     */
    void setMaxRoomsReturned( int maxRoomsReturned );
}