PresenceManager.java 4.59 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;

import org.jivesoftware.messenger.user.User;
15
import org.jivesoftware.messenger.auth.UnauthorizedException;
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
    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.
     *
62
     * @param username the name of the user.
Matt Tucker's avatar
Matt Tucker committed
63 64
     * @return the Presence packets for all the users's connected sessions.
     */
65
    public Collection<Presence> getPresences(String username);
Matt Tucker's avatar
Matt Tucker committed
66 67 68 69 70 71 72

    /**
     * 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
     */
73
    public void probePresence(JID prober, JID probee);
74

75 76 77 78 79 80 81 82
    /**
     * Handle a presence probe sent by a remote server. The logic to apply is the following: If
     * the remote user is not in the local user's roster with a subscription state of "From", or
     * "Both", then return a presence stanza of type "error" in response to the presence probe.
     * Otherwise, answer the presence of the local user sessions or the last unavailable presence.
     *
     * @param packet the received probe presence from a remote server.
     */
83 84 85 86 87 88 89 90 91 92 93 94
    public void handleProbe(Presence packet) throws UnauthorizedException;

    /**
     * Sends unavailable presence from all of the user's available resources to the remote user.
     * When a remote user unsubscribes from the presence of a local user then the server should
     * send to the remote user unavailable presence from all of the local user's available
     * resources.
     *
     * @param recipientJID JID of the remote user that will receive the unavailable presences.
     * @param userJID JID of the local user.
     */
    public void sendUnavailableFromSessions(JID recipientJID, JID userJID);
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

    /**
     * Notification message saying that the sender of the given presence just became available.
     *
     * @param presence the presence sent by the available user.
     */
    public void userAvailable(Presence presence);

    /**
     * Notification message saying that the sender of the given presence just became unavailable.
     *
     * @param presence the presence sent by the unavailable user.
     */
    public void userUnavailable(Presence presence);

    /**
     * Returns the status sent by the user in his last unavailable presence or <tt>null</tt> if the
     * user is online or never set such information.
     *
     * @param user the user to return his last status information
     * @return the status sent by the user in his last unavailable presence or <tt>null</tt> if the
     *         user is online or never set such information.
     */
    public String getLastPresenceStatus(User user);

    /**
     * Returns the number of milliseconds since the user went offline or -1 if such information
     * is not available or if the user is online.
     *
     * @param user the user to return his information.
     * @return the number of milliseconds since the user went offline or -1 if such information
     *         is not available or if the user is online.
     */
    public long getLastActivity(User user);
129
}