public interface MetaContactListService
An implementation of the MetaContactListService would take care of synchronizing the local copy of 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 containing 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.
Modifier and Type | Field and Description |
---|---|
static java.lang.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.
|
Modifier and Type | Method and Description |
---|---|
void |
addMetaContactListListener(MetaContactListListener l)
Adds a listener for MetaContactListChangeEvents posted after
the tree changes.
|
void |
addNewContactToMetaContact(ProtocolProviderService provider,
MetaContact metaContact,
java.lang.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,
java.lang.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-created protocol specific
contact.
|
MetaContactGroup |
createMetaContactGroup(MetaContactGroup parentGroup,
java.lang.String groupName)
Creates a MetaContactGroup with the specified group name.
|
java.util.Iterator<MetaContact> |
findAllMetaContactsForAddress(java.lang.String contactAddress)
Returns a list of all MetaContacts containing a protocol contact
corresponding to the given contactAddress string.
|
java.util.Iterator<MetaContact> |
findAllMetaContactsForProvider(ProtocolProviderService protocolProvider)
Returns a list of all MetaContacts containing a protocol contact
from the given ProtocolProviderService.
|
java.util.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(java.lang.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(java.lang.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,
java.lang.String newName)
Sets the display name for metaContact to be newName.
|
void |
renameMetaContactGroup(MetaContactGroup group,
java.lang.String newGroupName)
Renames the specified MetaContactGroup as indicated by the
newName param.
|
static final java.lang.String PROVIDER_MASK_PROPERTY
MetaContactGroup getRoot()
MetaContactGroup findParentMetaContactGroup(MetaContactGroup child)
child
- the MetaContactGroup whose parent group we're
looking for. If no parent is found null is returned.MetaContactGroup findParentMetaContactGroup(MetaContact child)
child
- the MetaContact whose parent group we're looking
for.MetaContact findMetaContactByContact(Contact contact)
contact
- the contact whose encapsulating meta contact we're looking
for.MetaContactGroup findMetaContactGroupByContactGroup(ContactGroup group)
group
- the group whose encapsulating meta group we're looking for.MetaContact findMetaContactByMetaUID(java.lang.String metaContactID)
metaContactID
- a String identifier of a meta contact.MetaContactGroup findMetaContactGroupByMetaUID(java.lang.String metaGroupID)
metaGroupID
- a String identifier of a meta contact group.java.util.Iterator<MetaContact> findAllMetaContactsForProvider(ProtocolProviderService protocolProvider)
protocolProvider
- the ProtocolProviderService whose
contacts we're looking for.java.util.Iterator<MetaContact> findAllMetaContactsForProvider(ProtocolProviderService protocolProvider, MetaContactGroup metaContactGroup)
protocolProvider
- the ProtocolProviderService whose
contacts we're looking for.metaContactGroup
- the parent group.java.util.Iterator<MetaContact> findAllMetaContactsForAddress(java.lang.String contactAddress)
contactAddress
- the contact address for which we're looking for
a parent MetaContact.void addMetaContactListListener(MetaContactListListener l)
l
- the listener to addvoid removeMetaContactListListener(MetaContactListListener l)
l
- the listener to removevoid moveContact(Contact contact, MetaContact newParent) throws MetaContactListException
contact
- the Contact to move to thenewParent
- the MetaContact where we'd like contact to be moved.MetaContactListException
- with an appropriate code if the
operation fails for some reason.void moveContact(Contact contact, MetaContactGroup newParent) throws MetaContactListException
contact
- the Contact to move to thenewParent
- the MetaContactGroup where we'd like contact to be moved.MetaContactListException
- with an appropriate code if the
operation fails for some reason.void removeContact(Contact contact) throws MetaContactListException
contact
- the contact to remove.MetaContactListException
- with an appropriate code if the
operation fails for some reason.void addNewContactToMetaContact(ProtocolProviderService provider, MetaContact metaContact, java.lang.String contactID) throws MetaContactListException
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 providerMetaContactListException
- with an appropriate code if the
operation fails for some reason.MetaContact createMetaContact(ProtocolProviderService provider, MetaContactGroup contactGroup, java.lang.String contactID) throws MetaContactListException
If the specified parent MetaContactGroup did not have a corresponding group on the protocol server, it will be created before the contact itself.
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.MetaContactListException
- with an appropriate code if the
operation fails for some reason.void moveMetaContact(MetaContact metaContact, MetaContactGroup newGroup) throws MetaContactListException
metaContact
- the MetaContact to move.newGroup
- the MetaContactGroup that should be the
new parent of contact.MetaContactListException
- with an appropriate code if the
operation fails for some reason.void renameMetaContact(MetaContact metaContact, java.lang.String newName) throws java.lang.IllegalArgumentException
metaContact
- the MetaContact that we are renamingnewName
- a String containing the new display name for
metaContact.java.lang.IllegalArgumentException
- if metaContact is not an
instance that belongs to the underlying implementation.void clearUserDefinedDisplayName(MetaContact metaContact) throws java.lang.IllegalArgumentException
metaContact
- the MetaContact that we are operating onjava.lang.IllegalArgumentException
- if metaContact is not an
instance that belongs to the underlying implementation.void removeMetaContact(MetaContact metaContact) throws MetaContactListException
metaContact
- the metaContact to remove.MetaContactListException
- with an appropriate code if the
operation fails for some reason.MetaContactGroup createMetaContactGroup(MetaContactGroup parentGroup, java.lang.String groupName) throws MetaContactListException
parentGroup
- the MetaContactGroup that should be the
parent of the newly created group.groupName
- the name of the MetaContactGroup to create.MetaContactListException
- with an appropriate code if the
operation fails for some reason.void renameMetaContactGroup(MetaContactGroup group, java.lang.String newGroupName) throws MetaContactListException
group
- the MetaContactGroup to rename.newGroupName
- the new name of the MetaContactGroup to
rename.MetaContactListException
- with an appropriate code if the
operation fails for some reason.void removeMetaContactGroup(MetaContactGroup groupToRemove) throws MetaContactListException
groupToRemove
- the MetaContactGroup to have removed.MetaContactListException
- with an appropriate code if the
operation fails for some reason.void purgeLocallyStoredContactListCopy()
Jitsi, the OpenSource Java VoIP and Instant Messaging client.
Distributable under Apache license.