FileDocCategorySizeDatePackage
ContactListManager.javaAPI DocAndroid 1.5 API20624Wed May 06 22:42:46 BST 2009com.android.im.engine

ContactListManager

public abstract class ContactListManager extends Object
ContactListManager manages the creating, removing and retrieving contact lists.

Fields Summary
public static final int
LISTS_NOT_LOADED
ContactListManager state that indicates the contact list(s) has not been loaded.
public static final int
LISTS_LOADING
ContactListManager state that indicates the contact list(s) is loading.
public static final int
BLOCKED_LIST_LOADED
ContactListManager state that indicates the blocked list has been loaded.
public static final int
LISTS_LOADED
ContactListManager state that indicates the contact list(s) has been loaded.
protected ContactList
mDefaultContactList
protected Vector
mContactLists
protected CopyOnWriteArrayList
mContactListListeners
protected SubscriptionRequestListener
mSubscriptionRequestListener
protected Vector
mBlockedList
private int
mState
private Vector
mBlockPending
A pending list of blocking contacts which is used for checking duplicated block operation.
private Vector
mDeletePending
A pending list of deleting contacts which is used for checking duplicated delete operation.
Constructors Summary
protected ContactListManager()
Creates a new ContactListManager.

param
conn The underlying protocol connection.


                   
      
        mContactLists = new Vector<ContactList>();
        mContactListListeners = new CopyOnWriteArrayList<ContactListListener>();
        mBlockedList = new Vector<Contact>();

        mBlockPending = new Vector<String>(4);
        mDeletePending = new Vector<Contact>(4);

        mState = LISTS_NOT_LOADED;
Methods Summary
public synchronized voidaddContactListListener(ContactListListener listener)
Adds a listener to the manager so that it will be notified for contact list changed.

param
listener the listener to add.

        if ((listener != null) && !mContactListListeners.contains(listener)) {
            mContactListListeners.add(listener);
        }
protected voidaddContactToListAsync(java.lang.String address, ContactList list)

        checkState();

        doAddContactToListAsync(address, list);
public abstract voidapproveSubscriptionRequest(java.lang.String contact)

public voidblockContactAsync(Contact contact)
        blockContactAsync(contact.getAddress().getFullName());
    
public voidblockContactAsync(java.lang.String address)
Blocks a certain Contact. The contact will be removed from any
ContactList after be blocked. If the contact has already been blocked,
the method does nothing.
param
address the address of the contact to block.
throws
ImException if an error occurs
        checkState();

        if(isBlocked(address)){
            return;
        }

        if (mBlockPending.contains(address)) {
            return;
        }
        doBlockContactAsync(address, true);
    
protected voidcheckState()
Check the state of the ContactListManager. Only the LIST_LOADED state
is permitted.
throws
ImException if the current state is not LIST_LOADED
        if (getConnection().getState() != ImConnection.LOGGED_IN) {
            throw new ImException(ImErrorInfo.CANT_CONNECT_TO_SERVER,
                    "Can't connect to server");
        }

        if (getState() != LISTS_LOADED) {
            throw new ImException(ImErrorInfo.ILLEGAL_CONTACT_LIST_MANAGER_STATE,
                    "Illegal contact list manager state");
        }
    
public booleancontainsContact(Contact contact)
Tell whether the manager contains the specified contact
param
contact the specified contact
return
true if the contact is contained in the lists of the manager,
otherwise, return false
        for (ContactList list : mContactLists) {
            if (list.containsContact(contact)) {
                return true;
            }
        }

        return false;
    
public voidcreateContactListAsync(java.lang.String name)
Create a contact list with the specified name asynchronously.
param
name the specific name of the contact list
throws
ImException
        createContactListAsync(name, null, false);
    
public voidcreateContactListAsync(java.lang.String name, boolean isDefault)
Create a contact list with specified name and whether it is to be
created as the default list.
param
name the specific name of the contact list
param
isDefault whether the contact list is to be created as the
default list
throws
ImException
        createContactListAsync(name, null, isDefault);
    
public voidcreateContactListAsync(java.lang.String name, java.util.Collection contacts)
Create a contact list with specified name and contacts asynchronously.
param
name the specific name of the contact list
param
contacts the initial contacts of the contact list
throws
ImException
        createContactListAsync(name, contacts, false);
    
public synchronized voidcreateContactListAsync(java.lang.String name, java.util.Collection contacts, boolean isDefault)
Create a contact list with specified name and contacts asynchronously,
and whether it is to be created as the default contact list.
param
name the name of the contact list
param
contacts the initial contacts of the list
param
isDefault whether the contact list is the default list
throws
ImException
        checkState();

        if (getContactList(name) != null) {
            throw new ImException(ImErrorInfo.CONTACT_LIST_EXISTS,
                    "Contact list already exists");
        }

        if (mContactLists.isEmpty()) {
            isDefault = true;
        }

        doCreateContactListAsync(name, contacts, isDefault);
    
public abstract ContactcreateTemporaryContact(java.lang.String address)
Creates a temporary contact. It's usually used when we want to create
a chat with someone not in the list.
param
address the address of the temporary contact.
return
the created temporary contact
public abstract voiddeclineSubscriptionRequest(java.lang.String contact)
public voiddeleteContactListAsync(java.lang.String name)
Delete a contact list of the specified name asynchronously
param
name the specific name of the contact list
throws
ImException
        deleteContactListAsync(getContactList(name));
    
public synchronized voiddeleteContactListAsync(ContactList list)
Delete a specified contact list asynchronously
param
list the contact list to be deleted
throws
ImException if any error raised
        checkState();

        if (null == list) {
            throw new ImException(ImErrorInfo.CONTACT_LIST_NOT_FOUND,
                    "Contact list doesn't exist");
        }

        doDeleteContactListAsync(list);
    
protected abstract voiddoAddContactToListAsync(java.lang.String address, ContactList list)
protected abstract voiddoBlockContactAsync(java.lang.String address, boolean block)
Block or unblock a contact.
param
address
the address of the contact to block or unblock.
param
block
true to block the contact; false
to unblock the contact.
protected abstract voiddoCreateContactListAsync(java.lang.String name, java.util.Collection contacts, boolean isDefault)
protected abstract voiddoDeleteContactListAsync(ContactList list)
protected abstract voiddoRemoveContactFromListAsync(Contact contact, ContactList list)
public java.util.ListgetBlockedList()
Gets a unmodifiable list of blocked contacts.
return
a unmodifiable list of blocked contacts.
throws
ImException
        checkState();

        return Collections.unmodifiableList(mBlockedList);
    
protected abstract ImConnectiongetConnection()
public ContactgetContact(java.lang.String address)
        for (ContactList list : mContactLists) {
            Contact c = list.getContact(address);
            if( c != null) {
                return c;
            }
        }
        return null;
    
public ContactgetContact(Address address)
Gets a contact by address.
param
address the address of the Contact.
return
the Contact or null if the Contact doesn't exist in any list.
        return getContact(address.getFullName());
    
public ContactListgetContactList(java.lang.String name)
Gets a contact list by name.
param
name the name of the contact list.
return
the ContactList or null if the contact list doesn't exist.
        for (ContactList list : mContactLists) {
            if (list.getName() != null && list.getName().equals(name)) {
                return list;
            }
        }
        return null;
    
public ContactListgetContactList(Address address)
Get the contact list by the address
param
address the address of the contact list
return
the ContactList or null if the list doesn't exist
        for (ContactList list : mContactLists) {
            if (list.getAddress().equals(address)) {
                return list;
            }
        }

        return null;
    
public java.util.CollectiongetContactLists()
Gets a collection of the contact lists.
return
a collection of the contact lists.
        return Collections.unmodifiableCollection(mContactLists);
    
public ContactListgetDefaultContactList()
Gets the default contact list.
return
the default contact list.
throws
ImException
        checkState();
        return mDefaultContactList;
    
public synchronized intgetState()
Get the state of the ContactListManager
return
the current state of the manager
        return mState;
    
public synchronized SubscriptionRequestListenergetSubscriptionRequestListener()
        return mSubscriptionRequestListener;
    
public booleanisBlocked(Contact contact)
Checks if a contact is blocked.
param
contact the contact.
return
true if it's blocked, false otherwise.
throws
ImException if contacts has not been loaded.
        return isBlocked(contact.getAddress().getFullName());
    
public synchronized booleanisBlocked(java.lang.String address)
Checks if a contact is blocked.
param
address the address of the contact.
return
true if it's blocked, false otherwise.
throws
ImException if contacts has not been loaded.
        if(mState < BLOCKED_LIST_LOADED) {
            throw new ImException(ImErrorInfo.ILLEGAL_CONTACT_LIST_MANAGER_STATE,
                "Blocked list hasn't been loaded");
        }
        for(Contact c : mBlockedList) {
            if(c.getAddress().getFullName().equals(address)){
                return true;
            }
        }
        return false;
    
public abstract voidloadContactListsAsync()
Load the contact lists from the server. This method will normally called
after the user logged in to get the initial/saved contact lists from
server. After called once, this method should not be called again.
public abstract java.lang.StringnormalizeAddress(java.lang.String address)
protected voidnotifyBlockContact(Contact contact, boolean blocked)
Notify that a contact has been blocked/unblocked.
param
contact the blocked/unblocked contact
        synchronized (this) {
            if (blocked) {
                mBlockedList.add(contact);
                String addr = contact.getAddress().getFullName();
                mBlockPending.remove(addr);
            } else {
                mBlockedList.remove(contact);
            }
        }
        for (ContactListListener listener : mContactListListeners) {
            listener.onContactChange(blocked ? ContactListListener.CONTACT_BLOCKED
                    : ContactListListener.CONTACT_UNBLOCKED, null, contact);
        }
    
protected voidnotifyContactError(int type, ImErrorInfo error, java.lang.String listName, Contact contact)
Notify that a contact list related error has been raised.
param
type the type of the error
param
error the raised error
param
listName the list name, if any, associated with the error
param
contact the contact, if any, associated with the error
        if (type == ContactListListener.ERROR_REMOVING_CONTACT) {
            mDeletePending.remove(contact);
        } else if (type == ContactListListener.ERROR_BLOCKING_CONTACT) {
            mBlockPending.remove(contact.getAddress().getFullName());
        }
        for (ContactListListener listener : mContactListListeners) {
            listener.onContactError(type, error, listName, contact);
        }
    
protected voidnotifyContactListCreated(ContactList list)
Notify that a contact list has been created.
param
list the created list
        synchronized (this) {
            if (list.isDefault()) {
                for (ContactList l : mContactLists) {
                    l.setDefault(false);
                }
                mDefaultContactList = list;
            }
            mContactLists.add(list);
        }

        for (ContactListListener listener : mContactListListeners) {
            listener.onContactChange(ContactListListener.LIST_CREATED,
                    list, null);
        }
    
protected voidnotifyContactListDeleted(ContactList list)
Notify that a contact list has been deleted
param
list the deleted list
        synchronized(this) {
            mContactLists.remove(list);
            if (list.isDefault() && mContactLists.size() > 0) {
                mContactLists.get(0).setDefault(true);
            }
        }

        for (ContactListListener listener : mContactListListeners) {
            listener.onContactChange(ContactListListener.LIST_DELETED,
                    list, null);
        }
    
protected voidnotifyContactListLoaded(ContactList list)
Notify that a contact list has been loaded
param
list the loaded list
        for (ContactListListener listener : mContactListListeners) {
            listener.onContactChange(ContactListListener.LIST_LOADED,
                    list, null);
        }
    
protected voidnotifyContactListNameUpdated(ContactList list, java.lang.String name)
Notify that the name of the specified contact list has been updated.
param
list
param
name the new name of the list
        list.mName = name;

        for (ContactListListener listener : mContactListListeners) {
            listener.onContactChange(ContactListListener.LIST_RENAMED,
                    list, null);
        }
    
protected voidnotifyContactListUpdated(ContactList list, int type, Contact contact)
Notify that a contact has been added to or removed from a list.
param
list the updated contact list
param
type the type of the update
param
contact the involved contact, null if no contact involved.
        synchronized (this) {
            if (type == ContactListListener.LIST_CONTACT_ADDED) {
                list.insertToCache(contact);
            } else if (type == ContactListListener.LIST_CONTACT_REMOVED) {
                list.removeFromCache(contact);
                mDeletePending.remove(contact);
            }
        }

        for (ContactListListener listener : mContactListListeners) {
            listener.onContactChange(type, list, contact);
        }
    
protected voidnotifyContactListsLoaded()
Notify that all contact lists has been loaded
        setState(LISTS_LOADED);
        for (ContactListListener listener : mContactListListeners) {
            listener.onAllContactListsLoaded();
        }
    
protected voidnotifyContactsPresenceUpdated(Contact[] contacts)
Notify that the presence of the contact has been updated
param
contacts the contacts who have updated presence information
        for (ContactListListener listener : mContactListListeners) {
            listener.onContactsPresenceUpdate(contacts);
        }
    
protected voidremoveContactFromListAsync(Contact contact, ContactList list)
        checkState();

        if (mDeletePending.contains(contact)) {
            return;
        }

        doRemoveContactFromListAsync(contact, list);
    
public synchronized voidremoveContactListListener(ContactListListener listener)
Removes a listener from this manager.
param
listener the listener to remove.
        mContactListListeners.remove(listener);
    
protected abstract voidsetListNameAsync(java.lang.String name, ContactList list)
protected synchronized voidsetState(int state)
Set the state of the ContactListManager
param
state the new state
        if (state < LISTS_NOT_LOADED || state > LISTS_LOADED) {
            throw new IllegalArgumentException();
        }

        mState = state;
    
public synchronized voidsetSubscriptionRequestListener(SubscriptionRequestListener listener)
Sets the SubscriptionRequestListener to the manager so that it will be notified
when a subscription request from another user is received.
param
listener the ContactInvitationListener.
        mSubscriptionRequestListener = listener;
    
public voidunblockContactAsync(Contact contact)
        unblockContactAsync(contact.getAddress().getFullName());
    
public voidunblockContactAsync(java.lang.String address)
Unblock a certain contact. It will removes the contact from the blocked
list and allows the contact to send message or invitation to the client
again. If the contact is not blocked on the client, this method does
nothing. Whether the unblocked contact will be added to the ContactList
it belongs before blocked or not depends on the underlying protocol
implementation.
param
address the address of the contact to unblock.
throws
ImException if the current state is illegal
        checkState();

        if(!isBlocked(address)) {
            return;
        }

        doBlockContactAsync(address, false);