Roster.java 4.83 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
package org.jivesoftware.messenger.roster;
Matt Tucker's avatar
Matt Tucker committed
13 14

import org.jivesoftware.messenger.auth.UnauthorizedException;
Matt Tucker's avatar
Matt Tucker committed
15 16
import org.jivesoftware.messenger.user.UserNotFoundException;
import org.jivesoftware.messenger.user.UserAlreadyExistsException;
Matt Tucker's avatar
Matt Tucker committed
17 18
import org.xmpp.packet.JID;

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

    /**
     * Returns an iterator of users in this roster.
     *
     * @return an iterator of users in this roster.
     */
Gaston Dombiak's avatar
Gaston Dombiak committed
51
    public Iterator<RosterItem> getRosterItems() throws UnauthorizedException;
Matt Tucker's avatar
Matt Tucker committed
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68

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

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

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

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

    /**
     * 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
121 122
    public RosterItem deleteRosterItem(JID user) throws UnauthorizedException;
}