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

import org.jivesoftware.messenger.auth.UnauthorizedException;
import org.jivesoftware.messenger.user.User;
16 17 18
import org.xmpp.packet.Presence;
import org.xmpp.packet.JID;

19
import java.util.Collection;
Matt Tucker's avatar
Matt Tucker committed
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43

/**
 * 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>
     *
Matt Tucker's avatar
Matt Tucker committed
44 45
     * @param user the user who's availability is in question
     * @return true if the user as available for messaging (1 or more available sessions)
Matt Tucker's avatar
Matt Tucker committed
46
     */
Matt Tucker's avatar
Matt Tucker committed
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65
    public boolean isAvailable(User user);

    /**
     * Returns the user's current presence, or <tt>null</tt> if the user is unavailable.
     * If the user is connected with more than one session, the user's "most available"
     * presence status is returned.
     *
     * @param user the user.
     * @return the user's current presence.
     */
    public Presence getPresence(User user);

    /**
     * Returns all presences for the user, or <tt>null</tt> if the user is unavailable.
     *
     * @param user the user.
     * @return the Presence packets for all the users's connected sessions.
     */
    public Collection<Presence> getPresences(User user);
Matt Tucker's avatar
Matt Tucker committed
66 67 68 69 70 71 72 73 74 75

    /**
     * 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();

    /**
76
     * Returns a Collection of users who are currently online. Online users with a
Matt Tucker's avatar
Matt Tucker committed
77 78
     * presence status other that online or idle will not be included.
     *
79
     * @return a Collection of online users.
Matt Tucker's avatar
Matt Tucker committed
80
     */
81
    public Collection<User> getOnlineUsers();
Matt Tucker's avatar
Matt Tucker committed
82 83

    /**
84
     * Returns a Collection of users sorted in the manner requested who are currently online.
Matt Tucker's avatar
Matt Tucker committed
85 86 87 88
     * 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.
89
     * @return a Collection of online users.
Matt Tucker's avatar
Matt Tucker committed
90
     */
91
    public Collection<User> getOnlineUsers(boolean ascending, int sortField);
Matt Tucker's avatar
Matt Tucker committed
92 93

    /**
94
     * Returns a Collection of users who are currently online matching the criteria given.
Matt Tucker's avatar
Matt Tucker committed
95 96
     * Online users with a presence status other than online or idle will not be included.
     *
97
     * @param ascending sort ascending if true, descending if false.
Matt Tucker's avatar
Matt Tucker committed
98 99
     * @param sortField  a valid sort field from the PresenceManager interface.
     * @param numResults - the number of results to return.
100
     * @return an Collection of online users matching the given criteria.
Matt Tucker's avatar
Matt Tucker committed
101
     */
102
    public Collection<User> getOnlineUsers(boolean ascending, int sortField, int numResults);
Matt Tucker's avatar
Matt Tucker committed
103 104 105 106 107 108 109 110 111 112 113 114

    /**
     * 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.
     * @return the presence for the user.
     * @throws UnauthorizedException if not the user.
     */
115
    public Presence createPresence(User user) throws UnauthorizedException;
Matt Tucker's avatar
Matt Tucker committed
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130

    /**
     * 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.
     */
131
    public void setOffline(JID jid) throws UnauthorizedException;
Matt Tucker's avatar
Matt Tucker committed
132 133 134 135 136 137 138

    /**
     * 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
     */
139
    public void probePresence(String prober, JID probee) throws UnauthorizedException;
Matt Tucker's avatar
Matt Tucker committed
140 141 142 143 144 145 146

    /**
     * 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
     */
147
    public void probePresence(JID prober, JID probee) throws UnauthorizedException;
148
}