KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jivesoftware > messenger > PresenceManager


1 /**
2  * $RCSfile: PresenceManager.java,v $
3  * $Revision: 1.13 $
4  * $Date: 2005/07/21 03:06:49 $
5  *
6  * Copyright (C) 2004 Jive Software. All rights reserved.
7  *
8  * This software is published under the terms of the GNU Public License (GPL),
9  * a copy of which is included in this distribution.
10  */
11
12 package org.jivesoftware.messenger;
13
14 import org.jivesoftware.messenger.user.User;
15 import org.jivesoftware.messenger.user.UserNotFoundException;
16 import org.jivesoftware.messenger.auth.UnauthorizedException;
17 import org.xmpp.packet.Presence;
18 import org.xmpp.packet.JID;
19
20 import java.util.Collection JavaDoc;
21
22 /**
23  * The presence manager tracks on a global basis who's online. The presence
24  * monitor watches and reports on what users are present on the server, and
25  * in other jabber domains that it knows about. The presence manager does
26  * not know about invisible users (they are invisible).
27  *
28  * @author Iain Shigeoka
29  */
30 public interface PresenceManager {
31
32     /**
33      * Sort by username.
34      */
35     public static final int SORT_USERNAME = 0;
36
37     /**
38      * Sort by online time.
39      */
40     public static final int SORT_ONLINE_TIME = 1;
41
42     /**
43      * <p>Returns the availability of the user.<p>
44      *
45      * @param user the user who's availability is in question
46      * @return true if the user as available for messaging (1 or more available sessions)
47      */
48     public boolean isAvailable(User user);
49
50     /**
51      * Returns the user's current presence, or <tt>null</tt> if the user is unavailable.
52      * If the user is connected with more than one session, the user's "most available"
53      * presence status is returned.
54      *
55      * @param user the user.
56      * @return the user's current presence.
57      */
58     public Presence getPresence(User user);
59
60     /**
61      * Returns all presences for the user, or <tt>null</tt> if the user is unavailable.
62      *
63      * @param username the name of the user.
64      * @return the Presence packets for all the users's connected sessions.
65      */
66     public Collection JavaDoc<Presence> getPresences(String JavaDoc username);
67
68     /**
69      * Probes the presence of the given XMPPAddress and attempts to send it to the given user.
70      *
71      * @param prober The user requesting the probe
72      * @param probee The XMPPAddress whos presence we would like sent have have probed
73      */
74     public void probePresence(JID prober, JID probee);
75
76     /**
77      * Handle a presence probe sent by a remote server. The logic to apply is the following: If
78      * the remote user is not in the local user's roster with a subscription state of "From", or
79      * "Both", then return a presence stanza of type "error" in response to the presence probe.
80      * Otherwise, answer the presence of the local user sessions or the last unavailable presence.
81      *
82      * @param packet the received probe presence from a remote server.
83      */
84     public void handleProbe(Presence packet) throws UnauthorizedException;
85
86     /**
87      * Returns true if the the prober is allowed to see the presence of the probee.
88      *
89      * @param prober the user that is trying to probe the presence of another user.
90      * @param probee the username of the uset that is being probed.
91      * @return true if the the prober is allowed to see the presence of the probee.
92      * @throws UserNotFoundException If the probee does not exist in the local server or the prober
93      * is not present in the roster of the probee.
94      */
95     public boolean canProbePresence(JID prober, String JavaDoc probee) throws UserNotFoundException;
96
97     /**
98      * Sends unavailable presence from all of the user's available resources to the remote user.
99      * When a remote user unsubscribes from the presence of a local user then the server should
100      * send to the remote user unavailable presence from all of the local user's available
101      * resources.
102      *
103      * @param recipientJID JID of the remote user that will receive the unavailable presences.
104      * @param userJID JID of the local user.
105      */
106     public void sendUnavailableFromSessions(JID recipientJID, JID userJID);
107
108     /**
109      * Notification message saying that the sender of the given presence just became available.
110      *
111      * @param presence the presence sent by the available user.
112      */
113     public void userAvailable(Presence presence);
114
115     /**
116      * Notification message saying that the sender of the given presence just became unavailable.
117      *
118      * @param presence the presence sent by the unavailable user.
119      */
120     public void userUnavailable(Presence presence);
121
122     /**
123      * Returns the status sent by the user in his last unavailable presence or <tt>null</tt> if the
124      * user is online or never set such information.
125      *
126      * @param user the user to return his last status information
127      * @return the status sent by the user in his last unavailable presence or <tt>null</tt> if the
128      * user is online or never set such information.
129      */
130     public String JavaDoc getLastPresenceStatus(User user);
131
132     /**
133      * Returns the number of milliseconds since the user went offline or -1 if such information
134      * is not available or if the user is online.
135      *
136      * @param user the user to return his information.
137      * @return the number of milliseconds since the user went offline or -1 if such information
138      * is not available or if the user is online.
139      */
140     public long getLastActivity(User user);
141 }
Popular Tags