/**
 * $RCSfile$
 * $Revision$
 * $Date$
 *
 * Copyright (C) 2004 Jive Software. All rights reserved.
 *
 * This software is published under the terms of the GNU Public License (GPL),
 * a copy of which is included in this distribution.
 */

package org.jivesoftware.messenger.muc;

import org.jivesoftware.messenger.MetaDataFragment;
import org.jivesoftware.messenger.Presence;
import org.jivesoftware.messenger.XMPPAddress;
import org.jivesoftware.messenger.auth.UnauthorizedException;

import org.jivesoftware.messenger.muc.ChatDeliverer;
import org.jivesoftware.messenger.muc.MUCRoom;
import org.jivesoftware.messenger.muc.MUCUser;
import org.jivesoftware.messenger.muc.NotAllowedException;

/**
 * Defines the permissions and actions that a MUCUser may use in
 * a particular room. Each MUCRole defines the relationship between
 * a MUCRoom and a MUCUser.
 * <p/>
 * MUCUsers can play different roles in different chatrooms.
 *
 * @author Gaston Dombiak
 */
public interface MUCRole extends ChatDeliverer {

    /**
     * Runs moderated discussions. Is allowed to kick users, grant and revoke voice, etc.
     */
    int MODERATOR = 0;
    /**
     * A normal occupant of the room. An occupant who does not have administrative privileges; in
     * a moderated room, a participant is further defined as having voice
     */
    int PARTICIPANT = 1;
    /**
     * An occupant who does not have voice  (can't speak in the room)
     */
    int VISITOR = 2;
    /**
     * An occupant who does not permission to stay in the room (was banned)
     */
    int NONE_ROLE = 3;


    /**
     * Owner of the room
     */
    int OWNER = 10;
    /**
     * Administrator of the room
     */
    int ADMINISTRATOR = 20;
    /**
     * A user who is on the "whitelist" for a members-only room or who is registered with an
     * open room.
     */
    int MEMBER = 30;
    /**
     * A user who has been banned from a room.
     */
    int OUTCAST = 40;
    /**
     * A user who doesn't have an affiliation. This kind of users can register with members-only
     * rooms and may enter an open room.
     */
    int NONE = 50;

    /**
     * Obtain the current presence status of a user in a chatroom.
     *
     * @return The presence of the user in the room.
     * @throws UnauthorizedException Thrown if the caller doesn't have permission to know this
     *                               user's presence.
     */
    Presence getPresence() throws UnauthorizedException;

    /**
     * Returns the extended presence information that includes information about roles,
     * affiliations, JIDs, etc.
     *
     * @return the extended presence information that includes information about roles,
     *         affiliations.
     * @throws UnauthorizedException Thrown if the caller doesn't have permission to know this
     *                               user's presence.
     */
    MetaDataFragment getExtendedPresenceInformation() throws UnauthorizedException;

    /**
     * Set the current presence status of a user in a chatroom.
     *
     * @param presence The presence of the user in the room.
     * @throws UnauthorizedException Thrown if the caller doesn't have permission to know this
     *                               user's presence.
     */
    void setPresence(Presence presence) throws UnauthorizedException;

    /**
     * Call this method to promote or demote a user's role in a chatroom.
     * It is common for the chatroom or other chat room members to change
     * the role of users (a moderator promoting another user to moderator
     * status for example).<p>
     * <p/>
     * Owning ChatUsers should have their membership roles updated.
     *
     * @param newRole The new role that the user will play.
     * @throws UnauthorizedException Thrown if the caller doesn't have permission to know this
     *                               user's presence.
     * @throws NotAllowedException   Thrown if trying to change the moderator role to an owner or
     *                               administrator.
     */
    void setRole(int newRole) throws UnauthorizedException, NotAllowedException;

    /**
     * Obtain the role state of the user.
     *
     * @return The role status of this user.
     */
    int getRole();

    /**
     * Obtain the role state of the user as a String. This string representation will be
     * incorporated into the extended packet information.
     *
     * @return The role status of this user.
     */
    public String getRoleAsString();

    /**
     * Call this method to promote or demote a user's affiliation in a chatroom.
     *
     * @param newAffiliation The new affiliation that the user will play.
     * @throws UnauthorizedException Thrown if the caller doesn't have permission to set the
     *                               user's affiliation.
     * @throws NotAllowedException   Thrown if trying to ban an owner or an administrator.
     */
    public void setAffiliation(int newAffiliation) throws UnauthorizedException,
            NotAllowedException;

    /**
     * Obtain the affiliation state of the user.
     *
     * @return The affiliation status of this user.
     */
    public int getAffiliation();

    /**
     * Obtain the affiliation state of the user as a String. This string representation will be
     * incorporated into the extended packet information.
     *
     * @return The affiliation status of this user.
     */
    public String getAffiliationAsString();

    /**
     * Obtain the nickname for the user in the chatroom.
     *
     * @return The user's nickname in the room or null if invisible.
     */
    String getNickname();

    /**
     * An event callback for kicks (being removed from a room). This provides the user an
     * opportunity to react to the kick (although the chat user has already been kicked when this
     * method is called). Remove users from a chatroom by calling ChatRoom.leaveRoom().
     *
     * @throws UnauthorizedException Thrown if the caller doesn't have permission to know this
     *                               user's presence.
     */
    void kick() throws UnauthorizedException;

    /**
     * Changes the nickname of the occupant within the room to the new nickname.
     *
     * @param nickname the new nickname of the occupant in the room.
     */
    void changeNickname(String nickname);

    /**
     * Obtain the chat user that plays this role.
     *
     * @return The chatuser playing this role.
     */
    MUCUser getChatUser();

    /**
     * Obtain the chat room that hosts this user's role.
     *
     * @return The chatroom hosting this role.
     */
    MUCRoom getChatRoom();

    /**
     * Obtain the XMPPAddress representing this role in a room: room@server/nickname
     *
     * @return The Jabber ID that represents this role in the room.
     */
    XMPPAddress getRoleAddress();
}
