/* * $RCSfile$ * $Revision$ * $Date$ * * Copyright (C) 1999-2003 CoolServlets, Inc. All rights reserved. * * This software is the proprietary information of CoolServlets, Inc. * Use is subject to license terms. */ package org.jivesoftware.messenger.chat; import org.jivesoftware.messenger.Presence; import org.jivesoftware.messenger.auth.UnauthorizedException; import org.jivesoftware.messenger.user.UserAlreadyExistsException; import org.jivesoftware.messenger.user.UserNotFoundException; import java.util.Iterator; /** * A chat room on the chat server manages its users, and * enforces it's own security rules. * * @author Iain Shigeoka */ public interface ChatRoom extends ChatDeliverer { /** * Get the name of this room. * * @return The name for this room */ String getName(); /** * Obtain a unique numerical id for this room. * Useful for storing rooms in databases * (TBD: persistent rooms do not exist yet) * * @return The unique id for this room or -1 if no id has been set. */ long getID(); /** * <p>Obtain the room specific message history settings.</p> * * @return The message history strategy defaults for the room */ HistoryStrategy getHistoryStrategy(); /** * <p>Obtain the role of the chat server (mainly for addressing * messages and presence).</p> * * @return The role for the chat room itself * @throws UnauthorizedException If you don't have permission */ ChatRole getRole() throws UnauthorizedException; /** * Obtain the role of a given user by nickname. * * @param nickname The nickname of the user you'd like to obtain * @return The user's role in the room * @throws UnauthorizedException If you don't have permission to * access the user * @throws UserNotFoundException If there is no user with the given nickname */ ChatRole getMember(String nickname) throws UnauthorizedException, UserNotFoundException; /** * Obtain the roles of all users in the chatroom. * * @return Iterator over all users in the chatroom * @throws UnauthorizedException If you don't have permission to access * the user */ Iterator getMembers() throws UnauthorizedException; /** * Determine if a given nickname is taken. * * @param nickname The nickname of the user you'd like to obtain * @return True if a nickname is taken * @throws UnauthorizedException If you don't have permission to access * the user */ boolean hasMember(String nickname) throws UnauthorizedException; /** * Joins the room using the given nickname. * * @param nickname The nickname the user wants to use in the chatroom * @param user The user joining * @return The role created for the user * @throws UnauthorizedException If the user doesn't have permision * to join the room * @throws UserAlreadyExistsException If the nickname is already taken */ ChatRole joinRoom(String nickname, ChatUser user) throws UnauthorizedException, UserAlreadyExistsException; /** * Remove a member from the chat room. * * @param nickname The user to remove * @throws UnauthorizedException If the user doesn't have permission * to leave the room * @throws UserNotFoundException If the nickname is not found */ void leaveRoom(String nickname) throws UnauthorizedException, UserNotFoundException; /** * Create a new presence in this room for the given role. * * @return The new presence * @throws UnauthorizedException If the user doesn't have permission to * leave the room */ Presence createPresence(int presenceStatus) throws UnauthorizedException; /** * Broadcast a given message to all members of this chat room. * The sender is always set to be the chatroom. * * @param msg The message to broadcast */ void serverBroadcast(String msg) throws UnauthorizedException; /** * Returns the total length of the chat session. * * @return length of chat session in milliseconds. */ public long getChatLength(); }