net.java.sip.communicator.service.contactlist
Interface MetaContactListService

All Known Implementing Classes:

MetaContactListServiceImpl

public interface MetaContactListService

The MetaContactListService handles the global project contact list including contacts from all implemented protocols.

An implementation of the MetaContactListService would take care of synchronizing the local copy ot the contact list with the versions stored on the various server protocols.

All modules that would for some reason like to query or modify the contact list should use this service rather than accessing protocol providers directly.

The point of MetaContacts is being able to merge different protocol specific contacts so that they represent a single person or identity. Every protocol specific Contact would therefore automatically be assigned to a corresponding MetaContact. A single MetaContact may containg multiple contacts (e.g. a single person often has accounts in different protocols) while a single protocol specific Contact may only be assigned to a exactly one MetaContact.

Once created a MetaContact may be updated to contain multiple protocol specific contacts. These protocol specific contacts may also be removed away from a MetaContact. Whenever a MetaContact remains empty (i.e. all of its protocol specific contacts are removed) it is automatically deleted.

Note that for most of the methods defined by this interface, it is likely that implementations require one or more network operations to complete before returning. It is therefore strongly advised not to call these methods in event dispatching threads (watch out UI implementors ;) ) as this may lead to unpleasant user experience.

The MetaContactListService also defines a property named:
net.java.sip.communicator.service.contactlist.PROVIDER_MASK
When this property is set, implementations of the MetaContactListService would only interact with protocol providers that same property set to the same value. This feature is mostly used during unit testing so that testing bundles could make sure that a tested meta contact list implementation would only load their mocking protocol provider implementations during the test run.

Author:

Emil Ivov

Field Summary

static String

PROVIDER_MASK_PROPERTY This property is used to tell implementations of the MetaContactListService that they are to only interact with providers that have the same property set to the same value as the system one.

Method Summary

void	addMetaContactListListener(MetaContactListListener l) Adds a listener for MetaContactListChangeEvents posted after the tree changes.
void	addNewContactToMetaContact(ProtocolProviderService provider, MetaContact metaContact, String contactID) First makes the specified protocol provider create the contact as indicated by contactID, and then associates it to the _existing_ metaContact given as an argument.
void	clearUserDefinedDisplayName(MetaContact metaContact) Resets display name of the MetaContact to show the value from the underlying contacts.
MetaContact	createMetaContact(ProtocolProviderService provider, MetaContactGroup contactGroup, String contactID) First makes the specified protocol provider create a contact corresponding to the specified contactID, then creates a new MetaContact which will encapsulate the newly crated protocol specific contact.
MetaContactGroup	createMetaContactGroup(MetaContactGroup parentGroup, String groupName) Creates a MetaContactGroup with the specified group name.
Iterator<MetaContact>	findAllMetaContactsForProvider(ProtocolProviderService protocolProvider) Returns a list of all MetaContacts containing a protocol contact from the given ProtocolProviderService.
Iterator<MetaContact>	findAllMetaContactsForProvider(ProtocolProviderService protocolProvider, MetaContactGroup metaContactGroup) Returns a list of all MetaContacts contained in the given group and containing a protocol contact from the given ProtocolProviderService.
MetaContact	findMetaContactByContact(Contact contact) Returns the MetaContact containing the specified contact or null if no such MetaContact was found.
MetaContact	findMetaContactByMetaUID(String metaContactID) Returns the MetaContact that corresponds to the specified metaContactID.
MetaContactGroup	findMetaContactGroupByContactGroup(ContactGroup group) Returns the MetaContactGroup encapsulating the specified protocol contact group or null if no such MetaContactGroup was found.
MetaContactGroup	findMetaContactGroupByMetaUID(String metaGroupID) Returns the MetaContactGroup that corresponds to the specified metaGroupID.
MetaContactGroup	findParentMetaContactGroup(MetaContact child) Returns the meta contact group that is a direct parent of the specified child.
MetaContactGroup	findParentMetaContactGroup(MetaContactGroup child) Returns the meta contact group that is a direct parent of the specified child.
MetaContactGroup	getRoot() Returns the root MetaContactGroup in this contact list.
void	moveContact(Contact contact, MetaContact newParent) Makes the specified contact a child of the newParent MetaContact.
void	moveContact(Contact contact, MetaContactGroup newParent) Makes the specified contact a child of the newParent MetaContactGroup.
void	moveMetaContact(MetaContact metaContact, MetaContactGroup newGroup) Moves the specified MetaContact to newGroup.
void	purgeLocallyStoredContactListCopy() Removes local resources storing copies of the meta contact list.
void	removeContact(Contact contact) Deletes the specified contact from both the local contact list and (if applicable) the server stored contact list if supported by the corresponding protocol.
void	removeMetaContact(MetaContact metaContact) Removes the specified metaContact as well as all of its underlying contacts.
void	removeMetaContactGroup(MetaContactGroup groupToRemove) Removes the specified meta contact group, all its corresponding protocol specific groups and all their children.
void	removeMetaContactListListener(MetaContactListListener l) Removes a listener previously added with addContactListListener.
void	renameMetaContact(MetaContact metaContact, String newName) Sets the display name for metaContact to be newName.
void	renameMetaContactGroup(MetaContactGroup group, String newGroupName) Renames the specified MetaContactGroup as indicated by the newName param.

Field Detail

PROVIDER_MASK_PROPERTY

static final String PROVIDER_MASK_PROPERTY

This property is used to tell implementations of the MetaContactListService that they are to only interact with providers that have the same property set to the same value as the system one. This feature is mostly used during unit testing so that testing bundles could make sure that a tested meta contact list implementation would only load their mocking protocol provider implementations during the test run.

See Also:

Constant Field Values

Method Detail

getRoot

MetaContactGroup getRoot()

Returns the root MetaContactGroup in this contact list. All meta contacts and subgroups are children of the root meta contact and references to them can only be obtained through it.

Returns:

the root MetaContactGroup for this contact list.

findParentMetaContactGroup

MetaContactGroup findParentMetaContactGroup(MetaContactGroup child)

Returns the meta contact group that is a direct parent of the specified child.

Parameters:

child - the MetaContactGroup whose paret group we're looking for. If no parent is found null is returned.

Returns:

the MetaContactGroup that contains child or null if no parent couldn't be found.

findParentMetaContactGroup

MetaContactGroup findParentMetaContactGroup(MetaContact child)

Returns the meta contact group that is a direct parent of the specified child. If no parent is found null is returned.

Parameters:

child - the MetaContact whose paret group we're looking for.

Returns:

the MetaContactGroup that contains child or null if no such group could be found.

findMetaContactByContact

MetaContact findMetaContactByContact(Contact contact)

Returns the MetaContact containing the specified contact or null if no such MetaContact was found. The method can be used when for example we need to find the MetaContact that is the author of an incoming message and the corresponding ProtocolProviderService has only provided a Contact as its author.

Parameters:

contact - the contact whose encapsulating meta contact we're looking for.

Returns:

the MetaContact containing the speicified contact or null if no such contact is present in this contact list.

findMetaContactGroupByContactGroup

MetaContactGroup findMetaContactGroupByContactGroup(ContactGroup group)

Returns the MetaContactGroup encapsulating the specified protocol contact group or null if no such MetaContactGroup was found.

Parameters:

group - the group whose encapsulating meta group we're looking for.

Returns:

the MetaContact containing the speicified contact or null if no such contact is present in this contact list.

findMetaContactByMetaUID

MetaContact findMetaContactByMetaUID(String metaContactID)

Returns the MetaContact that corresponds to the specified metaContactID.

Parameters:

metaContactID - a String identifier of a meta contact.

Returns:

the MetaContact with the speicified string identifier or null if no such meta contact was found.

findMetaContactGroupByMetaUID

MetaContactGroup findMetaContactGroupByMetaUID(String metaGroupID)

Returns the MetaContactGroup that corresponds to the specified metaGroupID.

Parameters:

metaGroupID - a String identifier of a meta contact group.

Returns:

the MetaContactGroup with the specified string identifier or null if no such meta contact was found.

findAllMetaContactsForProvider

Iterator<MetaContact> findAllMetaContactsForProvider(ProtocolProviderService protocolProvider)

Returns a list of all MetaContacts containing a protocol contact from the given ProtocolProviderService.

Parameters:

protocolProvider - the ProtocolProviderService whose contacts we're looking for.

Returns:

a list of all MetaContacts containing a protocol contact from the given ProtocolProviderService.

findAllMetaContactsForProvider

Iterator<MetaContact> findAllMetaContactsForProvider(ProtocolProviderService protocolProvider,
                                                     MetaContactGroup metaContactGroup)

Returns a list of all MetaContacts contained in the given group and containing a protocol contact from the given ProtocolProviderService.

Parameters:

protocolProvider - the ProtocolProviderService whose contacts we're looking for.

metaContactGroup - the parent group.

Returns:

a list of all MetaContacts containing a protocol contact from the given ProtocolProviderService.

addMetaContactListListener

void addMetaContactListListener(MetaContactListListener l)

Adds a listener for MetaContactListChangeEvents posted after the tree changes.

Parameters:

l - the listener to add

removeMetaContactListListener

void removeMetaContactListListener(MetaContactListListener l)

Removes a listener previously added with addContactListListener.

Parameters:

l - the listener to remove

moveContact

void moveContact(Contact contact,
                 MetaContact newParent)
                 throws MetaContactListException

Makes the specified contact a child of the newParent MetaContact. If contact was previously a child of another meta contact, it will be removed from its old parent before being added to the new one. If the specified contact was the only child of its previous parent, then it (the previous parent) will be removed.

Parameters:

contact - the Contact to move to the

newParent - the MetaContact where we'd like contact to be moved.

Throws:

MetaContactListException - with an appropriate code if the operation fails for some reason.

moveContact

void moveContact(Contact contact,
                 MetaContactGroup newParent)
                 throws MetaContactListException

Makes the specified contact a child of the newParent MetaContactGroup. If contact was previously a child of a meta contact, it will be removed from its old parent and to a newly created one even if they both are in the same group. If the specified contact was the only child of its previous parent, then the meta contact will also be moved.

Parameters:

contact - the Contact to move to the

newParent - the MetaContactGroup where we'd like contact to be moved.

Throws:

MetaContactListException - with an appropriate code if the operation fails for some reason.

removeContact

void removeContact(Contact contact)
                   throws MetaContactListException

Deletes the specified contact from both the local contact list and (if applicable) the server stored contact list if supported by the corresponding protocol. If the MetaContact that contained the given contact had no other children, it will be removed.

Parameters:

contact - the contact to remove.

Throws:

MetaContactListException - with an appropriate code if the operation fails for some reason.

addNewContactToMetaContact

void addNewContactToMetaContact(ProtocolProviderService provider,
                                MetaContact metaContact,
                                String contactID)
                                throws MetaContactListException

First makes the specified protocol provider create the contact as indicated by contactID, and then associates it to the _existing_ metaContact given as an argument.

Parameters:

provider - the ProtocolProviderService that should create the contact indicated by contactID.

metaContact - the meta contact where that the newly created contact should be associated to.

contactID - the identifier of the contact that the specified provider

Throws:

MetaContactListException - with an appropriate code if the operation fails for some reason.

createMetaContact

MetaContact createMetaContact(ProtocolProviderService provider,
                              MetaContactGroup contactGroup,
                              String contactID)
                              throws MetaContactListException

First makes the specified protocol provider create a contact corresponding to the specified contactID, then creates a new MetaContact which will encapsulate the newly crated protocol specific contact. Depending on implementations the method may sometimes need time to complete as it may be necessary for an underlying protocol to wait for a server to acknowledge addition of the contact.

If the specified parent MetaContactGroup did not have a corresponding group on the protocol server, it will be created before the contact itself.

Parameters:

provider - a ref to ProtocolProviderService instance which will create the actual protocol specific contact.

contactGroup - the MetaContactGroup where the newly created meta contact should be stored.

contactID - a protocol specific string identifier indicating the contact the protocol provider should create.

Returns:

the newly created MetaContact

Throws:

MetaContactListException - with an appropriate code if the operation fails for some reason.

moveMetaContact

void moveMetaContact(MetaContact metaContact,
                     MetaContactGroup newGroup)
                     throws MetaContactListException

Moves the specified MetaContact to newGroup.

Parameters:

metaContact - the MetaContact to move.

newGroup - the MetaContactGroup that should be the new parent of contact.

Throws:

MetaContactListException - with an appropriate code if the operation fails for some reason.

renameMetaContact

void renameMetaContact(MetaContact metaContact,
                       String newName)
                       throws IllegalArgumentException

Sets the display name for metaContact to be newName.

Parameters:

metaContact - the MetaContact that we are renaming

newName - a String containing the new display name for metaContact.

Throws:

IllegalArgumentException - if metaContact is not an instance that belongs to the underlying implementation.

clearUserDefinedDisplayName

void clearUserDefinedDisplayName(MetaContact metaContact)
                                 throws IllegalArgumentException

Resets display name of the MetaContact to show the value from the underlying contacts.

Parameters:

metaContact - the MetaContact that we are operating on

Throws:

IllegalArgumentException - if metaContact is not an instance that belongs to the underlying implementation.

removeMetaContact

void removeMetaContact(MetaContact metaContact)
                       throws MetaContactListException

Removes the specified metaContact as well as all of its underlying contacts.

Parameters:

metaContact - the metaContact to remove.

Throws:

MetaContactListException - with an appropriate code if the operation fails for some reason.

createMetaContactGroup

MetaContactGroup createMetaContactGroup(MetaContactGroup parentGroup,
                                        String groupName)
                                        throws MetaContactListException

Creates a MetaContactGroup with the specified group name. Initially, the group would only be created locally. Corresponding server stored groups will be created on the fly, whenever real protocol specific contacts are added to the group if the protocol lying behind them supports that.

Parameters:

parentGroup - the MetaContactGroup that should be the parent of the newly created group.

groupName - the name of the MetaContactGroup to create.

Returns:

the newly created MetaContactGroup

Throws:

MetaContactListException - with an appropriate code if the operation fails for some reason.

renameMetaContactGroup

void renameMetaContactGroup(MetaContactGroup group,
                            String newGroupName)
                            throws MetaContactListException

Renames the specified MetaContactGroup as indicated by the newName param. The operation would only affect the local meta group and would not "touch" any encapsulated protocol specific group.

Parameters:

group - the MetaContactGroup to rename.

newGroupName - the new name of the MetaContactGroup to rename.

Throws:

MetaContactListException - with an appropriate code if the operation fails for some reason.

removeMetaContactGroup

void removeMetaContactGroup(MetaContactGroup groupToRemove)
                            throws MetaContactListException

Removes the specified meta contact group, all its corresponding protocol specific groups and all their children. If some of the children belong to server stored contact lists, they will be updated to not include the child contacts any more.

Parameters:

groupToRemove - the MetaContactGroup to have removed.

Throws:

MetaContactListException - with an appropriate code if the operation fails for some reason.

purgeLocallyStoredContactListCopy

void purgeLocallyStoredContactListCopy()

Removes local resources storing copies of the meta contact list. This method is meant primarily to aid automated testing which may depend on beginning the tests with an empty local contact list.