1d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen/** 2d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * $RCSfile$ 3d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * $Revision$ 4d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * $Date$ 5d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 6d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Copyright 2003-2007 Jive Software. 7d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 8d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); 9d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * you may not use this file except in compliance with the License. 10d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * You may obtain a copy of the License at 11d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 12d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * http://www.apache.org/licenses/LICENSE-2.0 13d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 14d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Unless required by applicable law or agreed to in writing, software 15d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * distributed under the License is distributed on an "AS IS" BASIS, 16d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * See the License for the specific language governing permissions and 18d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * limitations under the License. 19d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen */ 20d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 21d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chenpackage org.jivesoftware.smack; 22d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 23d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chenimport org.jivesoftware.smack.packet.Presence; 24d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 25d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chenimport java.util.Collection; 26d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 27d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen/** 28d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * A listener that is fired any time a roster is changed or the presence of 29d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * a user in the roster is changed. 30d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 31d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @see Roster#addRosterListener(RosterListener) 32d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @author Matt Tucker 33d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen */ 34d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chenpublic interface RosterListener { 35d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 36d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen /** 37d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Called when roster entries are added. 38d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 39d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @param addresses the XMPP addresses of the contacts that have been added to the roster. 40d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen */ 41d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen public void entriesAdded(Collection<String> addresses); 42d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 43d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen /** 44d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Called when a roster entries are updated. 45d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 46d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @param addresses the XMPP addresses of the contacts whose entries have been updated. 47d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen */ 48d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen public void entriesUpdated(Collection<String> addresses); 49d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 50d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen /** 51d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Called when a roster entries are removed. 52d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 53d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @param addresses the XMPP addresses of the contacts that have been removed from the roster. 54d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen */ 55d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen public void entriesDeleted(Collection<String> addresses); 56d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 57d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen /** 58d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Called when the presence of a roster entry is changed. Care should be taken 59d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * when using the presence data delivered as part of this event. Specifically, 60d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * when a user account is online with multiple resources, the UI should account 61d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * for that. For example, say a user is online with their desktop computer and 62d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * mobile phone. If the user logs out of the IM client on their mobile phone, the 63d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * user should not be shown in the roster (contact list) as offline since they're 64d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * still available as another resource.<p> 65d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 66d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * To get the current "best presence" for a user after the presence update, query the roster: 67d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * <pre> 68d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * String user = presence.getFrom(); 69d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Presence bestPresence = roster.getPresence(user); 70d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * </pre> 71d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 72d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * That will return the presence value for the user with the highest priority and 73d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * availability. 74d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 75d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Note that this listener is triggered for presence (mode) changes only 76d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * (e.g presence of types available and unavailable. Subscription-related 77d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * presence packets will not cause this method to be called. 78d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 79d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @param presence the presence that changed. 80d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @see Roster#getPresence(String) 81d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen */ 82d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen public void presenceChanged(Presence presence); 83d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen}