public interface OperationSetPersistentPresence extends OperationSetPresence
Note: Also register the persistent presence implementation for OperationSetPresence support, since OperationSetPersistentPresence extends OperationSetPresence.
A server stored contact list is stored somewhere across the network and this interface allows GUI and other plugins to use it in a way similar to the way they'd use a javax.swing.tree.TreeModel, i.e. it would contain an initial number of members/children that is likely to change, dispatching a series of events delivered through the SubscriptionListener and ServerStoredGroupChangeListener interfaces.
The interfaces defines extended subscription methods that include an extra parentGroup parameter. Simple subscribe and usubscribe operations defined by the parent OperationSetPresence operation set, will still work, adding contacts to a default, root group. to be used by GUI and other plugins the same way that they would use a
Modifier and Type | Method and Description |
---|---|
void |
addServerStoredGroupChangeListener(ServerStoredGroupListener listener)
Registers a listener that would receive events upon changes in server
stored groups.
|
void |
createServerStoredContactGroup(ContactGroup parent,
java.lang.String groupName)
Creates a group with the specified name and parent in the server stored
contact list.
|
Contact |
createUnresolvedContact(java.lang.String address,
java.lang.String persistentData,
ContactGroup parentGroup)
Creates and returns a unresolved contact from the specified
address and persistentData.
|
ContactGroup |
createUnresolvedContactGroup(java.lang.String groupUID,
java.lang.String persistentData,
ContactGroup parentGroup)
Creates and returns a unresolved contact group from the specified
address and persistentData.
|
ContactGroup |
getServerStoredContactListRoot()
Returns the root group of the server stored contact list.
|
void |
moveContactToGroup(Contact contactToMove,
ContactGroup newParent)
Removes the specified contact from its current parent and places it under
newParent.
|
void |
removeServerStoredContactGroup(ContactGroup group)
Removes the specified group from the server stored contact list.
|
void |
removeServerStoredGroupChangeListener(ServerStoredGroupListener listener)
Removes the specified group change listener so that it won't receive any
further events.
|
void |
renameServerStoredContactGroup(ContactGroup group,
java.lang.String newName)
Renames the specified group from the server stored contact list.
|
void |
setDisplayName(Contact contact,
java.lang.String newName)
Sets the display name for contact to be newName.
|
void |
subscribe(ContactGroup parent,
java.lang.String contactIdentifier)
Persistently adds a subscription for the presence status of the contact
corresponding to the specified contactIdentifier and indicates that it
should be added to the specified group of the server stored contact list.
|
void |
subscribe(java.lang.String contactIdentifier)
Persistently adds a subscription for the presence status of the contact
corresponding to the specified contactIdentifier to the top level group.
|
void |
unsubscribe(Contact contact)
Persistently removes a subscription for the presence status of the
specified contact.
|
addContactPresenceStatusListener, addProviderPresenceStatusListener, addSubscriptionListener, createUnresolvedContact, findContactByID, getCurrentStatusMessage, getPresenceStatus, getSupportedStatusSet, publishPresenceStatus, queryContactStatus, removeContactPresenceStatusListener, removeProviderPresenceStatusListener, removeSubscriptionListener, setAuthorizationHandler
void subscribe(java.lang.String contactIdentifier) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException, OperationFailedException
Apart from an exception in the case of an immediate failure, the method won't return any indication of success or failure. That would happen later on through a SubscriptionEvent generated by one of the methods of the SubscriptionListener.
subscribe
in interface OperationSetPresence
contactIdentifier
- the contact whose status updates we are
subscribing for.
OperationFailedException
- with code NETWORK_FAILURE if subscribing
fails due to errors experienced during network communicationjava.lang.IllegalArgumentException
- if contact is not a contact
known to the underlying protocol providerjava.lang.IllegalStateException
- if the underlying protocol provider is not
registered/signed on a public service.void subscribe(ContactGroup parent, java.lang.String contactIdentifier) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException, OperationFailedException
contactIdentifier
- the contact whose status updates we are
subscribing for.parent
- the parent group of the server stored contact list where
the contact should be added.
OperationFailedException
- with code NETWORK_FAILURE if subscribing
fails due to errors experienced during network communicationjava.lang.IllegalArgumentException
- if contact or parent
are not a contact known to the underlying protocol provider.java.lang.IllegalStateException
- if the underlying protocol provider is not
registered/signed on a public service.void unsubscribe(Contact contact) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException, OperationFailedException
unsubscribe
in interface OperationSetPresence
contact
- the contact whose status updates we are unsubscribing
from.OperationFailedException
- with code NETWORK_FAILURE if
unsubscribing fails due to errors experienced during network
communicationjava.lang.IllegalArgumentException
- if contact is not a contact
known to the underlying protocol providerjava.lang.IllegalStateException
- if the underlying protocol provider is not
registered/signed on a public service.void createServerStoredContactGroup(ContactGroup parent, java.lang.String groupName) throws OperationFailedException
groupName
- the name of the new group to create.parent
- the group where the new group should be createdOperationFailedException
- with code NETWORK_FAILURE if creating
the group fails because of a network error.java.lang.IllegalArgumentException
- if parent is not a contact
known to the underlying protocol providerjava.lang.IllegalStateException
- if the underlying protocol provider is not
registered/signed on a public service.void removeServerStoredContactGroup(ContactGroup group) throws OperationFailedException
group
- the group to remove.OperationFailedException
- with code NETWORK_FAILURE if deleting
the group fails because of a network error.java.lang.IllegalArgumentException
- if parent is not a contact
known to the underlying protocol provider.java.lang.IllegalStateException
- if the underlying protocol provider is not
registered/signed on a public service.void renameServerStoredContactGroup(ContactGroup group, java.lang.String newName)
group
- the group to rename.newName
- the new name of the group.OperationFailedException
- with code NETWORK_FAILURE if deleting
the group fails because of a network error.java.lang.IllegalArgumentException
- if parent is not a contact
known to the underlying protocol provider.java.lang.IllegalStateException
- if the underlying protocol provider is not
registered/signed on a public service.void moveContactToGroup(Contact contactToMove, ContactGroup newParent) throws OperationFailedException
contactToMove
- the Contact to movenewParent
- the ContactGroup where Contact would
be placed.OperationFailedException
- when the operation didn't finished
successfully.ContactGroup getServerStoredContactListRoot()
void addServerStoredGroupChangeListener(ServerStoredGroupListener listener)
listener
- a ServerStoredGroupChangeListener that would receive
events upon group changes.void removeServerStoredGroupChangeListener(ServerStoredGroupListener listener)
listener
- the ServerStoredGroupChangeListener to removeContact createUnresolvedContact(java.lang.String address, java.lang.String persistentData, ContactGroup parentGroup)
address
- an identifier of the contact that we'll be creating.persistentData
- a String returned Contact's getPersistentData()
method during a previous run and that has been persistently
stored locally.parentGroup
- the group where the unresolved contact is supposed to
belong to.ContactGroup createUnresolvedContactGroup(java.lang.String groupUID, java.lang.String persistentData, ContactGroup parentGroup)
groupUID
- an identifier, returned by ContactGroup's getGroupUID,
that the protocol provider may use in order to create the
group.persistentData
- a String returned ContactGroups's
getPersistentData() method during a previous run and that has
been persistently stored locally.parentGroup
- the group under which the new group is to be created
or null if this is group directly underneath the root.void setDisplayName(Contact contact, java.lang.String newName) throws java.lang.IllegalArgumentException
contact
- the Contact that we are renamingnewName
- a String containing the new display name for
metaContact.java.lang.IllegalArgumentException
- if contact is not an
instance that belongs to the underlying implementation.
Jitsi, the OpenSource Java VoIP and Instant Messaging client.
Distributable under Apache license.