Roster.java 4.74 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4 5
/**
 * $RCSfile$
 * $Revision$
 * $Date$
 *
Matt Tucker's avatar
Matt Tucker committed
6
 * Copyright (C) 2004 Jive Software. All rights reserved.
Matt Tucker's avatar
Matt Tucker committed
7
 *
Matt Tucker's avatar
Matt Tucker committed
8 9
 * This software is published under the terms of the GNU Public License (GPL),
 * a copy of which is included in this distribution.
Matt Tucker's avatar
Matt Tucker committed
10
 */
Matt Tucker's avatar
Matt Tucker committed
11

Matt Tucker's avatar
Matt Tucker committed
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
package org.jivesoftware.messenger.user;

import org.jivesoftware.messenger.XMPPAddress;
import org.jivesoftware.messenger.auth.UnauthorizedException;
import java.util.Iterator;
import java.util.List;

/**
 * <p>A roster is a list of users that the user wishes to know if they are online.</p>
 * <p>Rosters are similar to buddy groups in popular IM clients. The Roster interface is
 * a generic representation of the roster data. There are two primary implementations
 * of the Roster in Messenger, the CachedRoster representing a cached, persistently stored
 * Roster attached to a user/chatbot account, and an IQRoster containing a roster as XML
 * data (usually as it enters and exists Messenger over an XMPP c2s or s2s connection).
 * It is an important distinction as changes to CachedRosters will be saved to disk while
 * IQRosters are transient data objects.</p>
 *
 * @author Iain Shigeoka
 *
 * @see IQRoster
 * @see CachedRoster
 */
public interface Roster {

    /**
     * Returns true if the specified user is a member of the roster, false otherwise.
     *
     * @param user the user object to check.
     * @return true if the specified user is a member of the roster, false otherwise.
     */
    public boolean isRosterItem(XMPPAddress user);

    /**
     * Returns an iterator of users in this roster.
     *
     * @return an iterator of users in this roster.
     */
Gaston Dombiak's avatar
Gaston Dombiak committed
49
    public Iterator<RosterItem> getRosterItems() throws UnauthorizedException;
Matt Tucker's avatar
Matt Tucker committed
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118

    /**
     * Returns the total number of users in the roster.
     *
     * @return the number of online users in the roster.
     */
    public int getTotalRosterItemCount() throws UnauthorizedException;

    /**
     * Gets a user from the roster. If the roster item does not exist, an empty one is created.
     * The new roster item is not stored in the roster until it is added using
     * addRosterItem().
     *
     * @param user the XMPPAddress for the roster item to retrieve
     * @return The roster item associated with the user XMPPAddress
     * @throws UnauthorizedException If not the user or an administrator
     */
    public RosterItem getRosterItem(XMPPAddress user) throws UnauthorizedException, UserNotFoundException;

    /**
     * Create a new item to the roster. Roster items may not be created that contain the same user address
     * as an existing item.
     *
     * @param user the item to add to the roster.
     * @throws UnauthorizedException if not the item or an administrator.
     */
    public RosterItem createRosterItem(XMPPAddress user) throws UnauthorizedException, UserAlreadyExistsException;

    /**
     * Create a new item to the roster. Roster items may not be created that contain the same user address
     * as an existing item.
     *
     * @param user     the item to add to the roster.
     * @param nickname The nickname for the roster entry (can be null)
     * @param groups   The list of groups to assign this roster item to (can be null)
     * @throws UnauthorizedException      if not the item or an administrator.
     * @throws UserAlreadyExistsException If a roster item already exists for the given user
     */
    public RosterItem createRosterItem(XMPPAddress user, String nickname, List groups) throws UnauthorizedException, UserAlreadyExistsException;

    /**
     * Create a new item to the roster based as a copy of the given item.
     * Roster items may not be created that contain the same user address
     * as an existing item in the roster.
     *
     * @param item the item to copy and add to the roster.
     * @throws UnauthorizedException      if not the item or an administrator.
     * @throws UserAlreadyExistsException If a roster item already exists for the given user
     */
    public RosterItem createRosterItem(RosterItem item) throws UnauthorizedException, UserAlreadyExistsException;

    /**
     * Update an item that is already in the roster.
     *
     * @param item the item to update in the roster.
     * @throws UnauthorizedException if not the user or an administrator.
     * @throws UserNotFoundException If the roster item for the given user doesn't already exist
     */
    public void updateRosterItem(RosterItem item) throws UnauthorizedException, UserNotFoundException;

    /**
     * Remove a user from the roster.
     *
     * @param user the user to remove from the roster.
     * @return The roster item being removed or null if none existed
     * @throws UnauthorizedException if not the user or an administrator.
     */
    public RosterItem deleteRosterItem(XMPPAddress user) throws UnauthorizedException;
}