Roster.java 4.71 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
package org.jivesoftware.messenger.user;

import org.jivesoftware.messenger.auth.UnauthorizedException;
Matt Tucker's avatar
Matt Tucker committed
15 16
import org.xmpp.packet.JID;

Matt Tucker's avatar
Matt Tucker committed
17 18 19 20 21 22 23 24
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
Gaston Dombiak's avatar
Gaston Dombiak committed
25
 * Roster attached to a user/chatbot account, and an Roster containing a roster as XML
Matt Tucker's avatar
Matt Tucker committed
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
 * 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 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.
     */
Matt Tucker's avatar
Matt Tucker committed
42
    public boolean isRosterItem(JID user);
Matt Tucker's avatar
Matt Tucker committed
43 44 45 46 47 48

    /**
     * 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

    /**
     * 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
     */
Matt Tucker's avatar
Matt Tucker committed
67
    public RosterItem getRosterItem(JID user) throws UnauthorizedException, UserNotFoundException;
Matt Tucker's avatar
Matt Tucker committed
68 69 70 71 72 73 74 75

    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
76
    public RosterItem createRosterItem(JID user) throws UnauthorizedException, UserAlreadyExistsException;
Matt Tucker's avatar
Matt Tucker committed
77 78 79 80 81 82 83 84 85 86 87

    /**
     * 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
     */
Gaston Dombiak's avatar
Gaston Dombiak committed
88 89
    public RosterItem createRosterItem(JID user, String nickname, List<String> groups)
            throws UnauthorizedException, UserAlreadyExistsException;
Matt Tucker's avatar
Matt Tucker committed
90 91 92 93 94 95 96 97 98 99

    /**
     * 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
     */
Gaston Dombiak's avatar
Gaston Dombiak committed
100 101
    public void createRosterItem(org.xmpp.packet.Roster.Item item)
            throws UnauthorizedException, UserAlreadyExistsException;
Matt Tucker's avatar
Matt Tucker committed
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118

    /**
     * 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.
     */
Matt Tucker's avatar
Matt Tucker committed
119 120
    public RosterItem deleteRosterItem(JID user) throws UnauthorizedException;
}