PresenceManager.java 4.6 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
package org.jivesoftware.messenger;

import org.jivesoftware.messenger.auth.UnauthorizedException;
import org.jivesoftware.messenger.user.User;
import java.util.Iterator;
17
import java.util.Collection;
Matt Tucker's avatar
Matt Tucker committed
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 49 50 51 52 53 54 55

/**
 * The presence manager tracks on a global basis who's online. The presence
 * monitor watches and reports on what users are present on the server, and
 * in other jabber domains that it knows about. The presence manager does
 * not know about invisible users (they are invisible).
 *
 * @author Iain Shigeoka
 */
public interface PresenceManager {

    /**
     * Sort by username.
     */
    public static final int SORT_USERNAME = 0;

    /**
     * Sort by online time.
     */
    public static final int SORT_ONLINE_TIME = 1;

    /**
     * <p>Returns the availability of the user.<p>
     *
     * @param user The user who's availability is in question
     * @return True if the user as available for messaging (1 or more available sessions)
     */
    public boolean isAvailable(User user) throws UnauthorizedException;

    /**
     * Returns the number of guests who are currently online. Guests with a
     * presence status other that online or idle will not be included.
     *
     * @return the number of online users.
     */
    public int getOnlineGuestCount();

    /**
56
     * Returns a Collection of users who are currently online. Online users with a
Matt Tucker's avatar
Matt Tucker committed
57 58
     * presence status other that online or idle will not be included.
     *
59
     * @return a Collection of online users.
Matt Tucker's avatar
Matt Tucker committed
60
     */
61
    public Collection<User> getOnlineUsers();
Matt Tucker's avatar
Matt Tucker committed
62 63

    /**
64
     * Returns a Collection of users sorted in the manner requested who are currently online.
Matt Tucker's avatar
Matt Tucker committed
65 66 67 68
     * Online users with a presence status other that online or idle will not be included.
     *
     * @param ascending sort ascending if true, descending if false.
     * @param sortField a valid sort field from the PresenceManager interface.
69
     * @return a Collection of online users.
Matt Tucker's avatar
Matt Tucker committed
70
     */
71
    public Collection<User> getOnlineUsers(boolean ascending, int sortField);
Matt Tucker's avatar
Matt Tucker committed
72 73

    /**
74
     * Returns a Collection of users who are currently online matching the criteria given.
Matt Tucker's avatar
Matt Tucker committed
75 76
     * Online users with a presence status other than online or idle will not be included.
     *
77
     * @param ascending sort ascending if true, descending if false.
Matt Tucker's avatar
Matt Tucker committed
78 79
     * @param sortField  a valid sort field from the PresenceManager interface.
     * @param numResults - the number of results to return.
80
     * @return an Collection of online users matching the given criteria.
Matt Tucker's avatar
Matt Tucker committed
81
     */
82
    public Collection<User> getOnlineUsers(boolean ascending, int sortField, int numResults);
Matt Tucker's avatar
Matt Tucker committed
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 119 120 121 122 123 124 125 126 127 128

    /**
     * Create a presence for a user. Creating a presence will automatically set the user to be
     * online.<p>
     * <p/>
     * The uid should be unique within the application instance. A good source of a uid is the
     * servlet session id.
     *
     * @param user the user to create a presence for.
     * @param uid  a unique string.
     * @return the presence for the user.
     * @throws UnauthorizedException if not the user.
     */
    public Presence createPresence(User user, String uid) throws UnauthorizedException;

    /**
     * Sets a presence to be offline which causes the presence to be removed from the system.
     *
     * @param presence to presence to set to be offline.
     * @throws UnauthorizedException if not the user.
     */
    public void setOffline(Presence presence) throws UnauthorizedException;

    /**
     * Sets a user to be offline which causes the presence to be removed from the system.
     *
     * @param jid the user to set to be offline.
     * @throws UnauthorizedException if not the user.
     */
    public void setOffline(XMPPAddress jid) throws UnauthorizedException;

    /**
     * Probes the presence of the given XMPPAddress and attempts to send it to the given user.
     *
     * @param prober The user requesting the probe
     * @param probee The XMPPAddress whos presence we would like sent have have probed
     */
    public void probePresence(String prober, XMPPAddress probee) throws UnauthorizedException;

    /**
     * Probes the presence of the given XMPPAddress and attempts to send it to the given user.
     *
     * @param prober The user requesting the probe
     * @param probee The XMPPAddress whos presence we would like sent have have probed
     */
    public void probePresence(XMPPAddress prober, XMPPAddress probee) throws UnauthorizedException;
129
}