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

import java.util.Iterator;

/**
 * <p>Defines the provider methods required for creating, reading, updating and deleting roster items.</p>
 * <p/>
 * <p>Rosters are another user resource accessed via the user or chatbot's long ID. A user/chatbot may have
 * zero or more roster items and each roster item may have zero or more groups. Each roster item is
 * additionaly keyed on a XMPP jid. In most cases, the entire roster will be read in from memory and manipulated
 * or sent to the user. However some operations will need to retrive specific roster items rather than the
 * entire roster.</p>
 *
 * @author Iain Shigeoka
 */
public interface RosterItemProvider {
    /**
     * <p>Creates a new roster item for the given user (optional operation).</p>
     * <p/>
     * <p><b>Important!</b> The item passed as a parameter to this method is strictly a convenience for passing all
     * of the data needed for a new roster item. The roster item returned from the method will be cached by Messenger.
     * In some cases, the roster item passed in will be passed back out. However, if an implementation may
     * return RosterItems as a separate class (for example, a RosterItem that directly accesses the backend
     * storage, or one that is an object in an object database).
     * <p/>
     * <p>If you don't want roster items edited through messenger, throw UnsupportedOperationException.</p>
     *
39 40
     * @param username the username of the user/chatbot that owns the roster item
     * @param item the settings for the roster item to create
Matt Tucker's avatar
Matt Tucker committed
41 42 43
     * @return The created roster item
     * @throws UnsupportedOperationException If the provider does not support the operation (this is an optional operation)
     */
44
    CachedRosterItem createItem(String username, RosterItem item) throws UserAlreadyExistsException, UnsupportedOperationException;
Matt Tucker's avatar
Matt Tucker committed
45 46 47 48 49 50

    /**
     * <p>Update the roster item in storage with the information contained in the given item (optional operation).</p>
     * <p/>
     * <p>If you don't want roster items edited through messenger, throw UnsupportedOperationException.</p>
     *
51
     * @param username the username of the user/chatbot that owns the roster item
Matt Tucker's avatar
Matt Tucker committed
52 53 54 55
     * @param item   The roster item to update
     * @throws UserNotFoundException         If no entry could be found to update
     * @throws UnsupportedOperationException If the provider does not support the operation (this is an optional operation)
     */
56
    void updateItem(String username, CachedRosterItem item) throws UserNotFoundException, UnsupportedOperationException;
Matt Tucker's avatar
Matt Tucker committed
57 58 59 60 61 62

    /**
     * <p>Delete the roster item with the given itemJID for the user (optional operation).</p>
     * <p/>
     * <p>If you don't want roster items deleted through messenger, throw UnsupportedOperationException.</p>
     *
63
     * @param username the long ID of the user/chatbot that owns the roster item
Matt Tucker's avatar
Matt Tucker committed
64 65 66
     * @param rosterItemID The roster item to delete
     * @throws UnsupportedOperationException If the provider does not support the operation (this is an optional operation)
     */
67
    void deleteItem(String username, long rosterItemID) throws UnsupportedOperationException;
Matt Tucker's avatar
Matt Tucker committed
68 69

    /**
70
     * Returns an iterator on the usernames whose roster includes the specified JID.
Matt Tucker's avatar
Matt Tucker committed
71
     *
72 73
     * @param jid the jid that the rosters should include.
     * @return an iterator on the usernames whose roster includes the specified JID.
Matt Tucker's avatar
Matt Tucker committed
74
     */
75
    Iterator<String> getUsernames(String jid);
Matt Tucker's avatar
Matt Tucker committed
76 77 78 79

    /**
     * <p>Obtain a count of the number of roster items available for the given user.</p>
     *
80
     * @param username the username of the user/chatbot that owns the roster items
Matt Tucker's avatar
Matt Tucker committed
81 82
     * @return The number of roster items available for the user
     */
83
    int getItemCount(String username);
Matt Tucker's avatar
Matt Tucker committed
84 85 86 87 88 89 90 91

    /**
     * <p>Retrieve an iterator of RosterItems for the given user.</p>
     * <p/>
     * <p>This method will commonly be called when a user logs in. The data will be cached
     * in memory when possible. However, some rosters may be very large so items may need
     * to be retrieved from the provider more frequently than usual for provider data.
     *
92
     * @param username the username of the user/chatbot that owns the roster items
Matt Tucker's avatar
Matt Tucker committed
93 94
     * @return An iterator of all RosterItems owned by the user
     */
95
    Iterator getItems(String username);
Matt Tucker's avatar
Matt Tucker committed
96
}