Package com.avaya.clientservices.messaging

## Interface Conversation

- All Known Subinterfaces:
    `SearchConversation`

      public interface Conversation

  Interface for all conversation related tasks and properties.

  A conversation is managing a list of messages which are sent between its participants.

  Beside messages, a conversation also contains a lot of its own parameters. Almost all of them can be set only before it is published. After that, one can only send a message, add a new participant, change subject, etc.

  It is important to understand that all conversation participants have the same privileges. Once the first user starts a conversation it cannot be closed by that user; every user can leave only by themselves, and add new participants as desired.

  After creating new conversation object call `addParticipantAddresses(List, AddParticipantAddressesCompletionHandler)` method for adding new participants. Before sending first message set all other required parameters, like Subject and call `start(MessagingCompletionHandler)` method.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addComposingParticipantsListener​(ComposingParticipantsListener listener)` | Adds a listener that will be notified when list of composing participants changes.
    `void` | `addListener​(ConversationListener listener)` | Adds a new listener to the conversation.
    `void` | `addParticipant​(Contact contact, AddParticipantAddressesCompletionHandler completionHandler)` | Invokes an add participant request for this conversation for provided contact object.
    `void` | `addParticipantAddresses​(java.util.List<java.lang.String> addresses, AddParticipantAddressesCompletionHandler completionHandler)` | Invokes an add participant request for this conversation for each of the provided addresses.
    `void` | `clearLocalAttachmentData​(MessagingCompletionHandler completionHandler)` | Clear conversation local attachment data.
    `Message` | `createMessage()` | Creates a new Message in this conversation.
    `java.util.List<MessagingParticipant>` | `getActiveParticipants()` | Returns a list of active participants contained in this conversation.
    `Capability` | `getAddParticipantsCapability()` | Returns a `Capability` object that indicates if new participants can be added to the conversation.
    `java.util.List<MessagingParticipant>` | `getComposingParticipants()` | Returns a list of composing participants contained in this conversation.
    `ConversationType` | `getConversationType()` | Returns the conversation type.
    `Capability` | `getCreateMessageCapability()` | Returns a `Capability` object that indicates if a new message can be created in the conversation.
    `java.lang.String` | `getId()` | Returns the unique conversation identifier.
    `Capability` | `getIsTypingCapability()` | Returns a Capability object that indicates if typing status reporting is available.
    `java.util.Date` | `getLastAccessedTime()` | Returns the time the conversation was last accessed.
    `java.util.Date` | `getLastEntryTime()` | Returns the last entry timestamp of the conversation.
    `MessagingParticipant` | `getLastUpdatedByParticipant()` | Returns the last `MessagingParticipant` that updated this conversation.
    `java.util.Date` | `getLastUpdatedTime()` | Returns the time the conversation was last updated.
    `Capability` | `getLeaveCapability()` | Returns a `Capability` object that indicates if the conversation can be left.
    `Capability` | `getMarkAllContentAsReadCapability()` | Returns a `Capability` object that indicates if all messages in the conversation can be marked as read.
    `Capability` | `getMessageDeliveryStateCapability()` | Returns a capability indicating whether this conversation is capable of reporting delivery state updates for sent messages.
    `Capability` | `getMessageReadStateCapability()` | Returns a capability indicating whether this conversation is capable of reporting read state updates for sent messages.
    `Capability` | `getOlderContentCapability()` | Returns a `Capability` object that indicates whether the user can "scroll to get more messages", i.e.
    `java.util.List<MessagingParticipant>` | `getParticipants()` | Returns a list of participants contained in this conversation.
    `java.lang.String` | `getPreviewText()` | Returns the preview text of the conversation.
    `java.lang.String` | `getProviderConversationId()` | Returns the conversation ID from the underlying provider (e.g., the AMM server) as-is.
    `MessagingProviderType` | `getProviderType()` | Returns a provider type for the conversation.
    `Capability` | `getRemoveCapability()` | Returns a `Capability` object that indicates if the conversation can be removed.
    `Capability` | `getRemoveParticipantCapability()` | Returns a `Capability` object that indicates if a participant can be removed from the conversation.
    `Capability` | `getRemoveParticipantsCapability()` | Returns a `Capability` object that indicates if participants can be removed from the conversation.
    `SensitivityLevel` | `getSensitivity()` | Returns the sensitivity of the conversation.
    `Capability` | `getStartCapability()` | Returns a `Capability` object that indicates if the conversation can be started.
    `ConversationStatus` | `getStatus()` | Returns the server reconciled status of the conversation.
    `java.lang.String` | `getSubject()` | Returns the subject of the conversation if one is provided by the server.
    `int` | `getTotalAttachmentCount()` | Returns the total number of attachments in all messages of the conversation.
    `int` | `getTotalMessageCount()` | Returns the total number of messages in the conversation.
    `int` | `getUnreadAttachmentCount()` | Returns the total number of unread attachments in all messages of the conversation.
    `int` | `getUnreadMessageCount()` | Returns the number of unread messages in the conversation.
    `Capability` | `getUpdateLastAccessTimeCapability()` | Returns a `Capability` object that indicates if the last accessed time of the conversation can be updated.
    `Capability` | `getUpdateSensitivityCapability()` | Returns a `Capability` object that indicates if the sensitivity of the conversation can be updated.
    `Capability` | `getUpdateSubjectCapability()` | Returns a `Capability` object that indicates if the subject property of the conversation can be updated.
    `Capability` | `getUpdateTypeCapability()` | Returns a `Capability` object that indicates if the type of the conversation can be updated.
    `boolean` | `hasAttachments()` | Returns true if the conversation has any attachments on any of its messages.
    `boolean` | `hasUnreadAttachments()` | Returns true if the conversation has any unread attachments.
    `boolean` | `hasUnreadMessages()` | Returns true if the conversation has any unread messages.
    `boolean` | `hasUnreadMessagesSinceLastAccess()` | Returns whether the conversation has unread messages since the time the conversation was last accessed.
    `boolean` | `isActive()` | Returns true if the conversation is active.
    `boolean` | `isClosed()` | Returns true if the conversation is closed.
    `boolean` | `isMultiParty()` | Returns the multi-party status of the conversation.
    `boolean` | `isParticipantActive​(MessagingParticipant participant)` | Returns true if a specified participant is active in this conversation.
    `boolean` | `isPrivate()` | The conversation is private when `SensitivityLevel` of the conversation is set to `SensitivityLevel.PRIVATE`.
    `void` | `leave​(MessagingCompletionHandler completionHandler)` | Invokes a leave request for this conversation.
    `void` | `markAllContentAsRead​(MessagingCompletionHandler completionHandler)` | Marks all content in this conversation as read.
    `void` | `removeComposingParticipantsListener​(ComposingParticipantsListener listener)` | Removes a listener that will be notified when list of composing participants changes.
    `void` | `removeListener​(ConversationListener listener)` | Removes a listener from the conversation.
    `void` | `removeMessage​(Message message, MessagingCompletionHandler completionHandler)` | Removes a `Message` (only draft messages can be removed).
    `void` | `removeParticipant​(MessagingParticipant participant, MessagingCompletionHandler completionHandler)` | Invokes a remove participant request for this conversation.
    `void` | `removeParticipantAddresses​(java.util.List<java.lang.String> addresses, MessagingCompletionHandler completionHandler)` | Invokes a remove participant request for this conversation for each of the provided addresses.
    `void` | `retrieveMessages​(DataRetrievalWatcher<Message> dataRetrievalWatcher)` | Starts the retrieval of messages associated with this conversation.
    `void` | `retrieveMessagesAfter​(DataRetrievalWatcher<Message> dataRetrievalWatcher, int numberOfMessagesToRetrieve, Message afterMessage)` | Retrieves a list of the conversation messages after the specified message.
    `void` | `retrieveMessagesBefore​(DataRetrievalWatcher<Message> dataRetrievalWatcher, int numberOfMessagesToRetrieve, Message beforeMessage)` | Retrieves a list of the conversation messages before the specified message.
    `void` | `setLastAccessTime​(MessagingCompletionHandler completionHandler)` | Invokes a set last access time request for this conversation.
    `void` | `setSensitivity​(SensitivityLevel sensitivityLevel, MessagingCompletionHandler completionHandler)` | Sets the conversation sensitivity.
    `void` | `setSubject​(java.lang.String subject, MessagingCompletionHandler completionHandler)` | Sets the subject for this conversation.
    `void` | `setType​(ConversationType type, MessagingCompletionHandler completionHandler)` | Sets the conversation type.
    `void` | `start​(MessagingCompletionHandler completionHandler)` | Invokes a start request for this conversation.

- - ### Method Detail

    - #### addListener

          void addListener​(ConversationListener listener)

      Adds a new listener to the conversation.
      Parameters:
        `listener` - `ConversationListener` to be added to the service.

    - #### removeListener

          void removeListener​(ConversationListener listener)

      Removes a listener from the conversation.
      Parameters:
        `listener` - `ConversationListener` instance that is removed from the service.

    - #### addComposingParticipantsListener

          void addComposingParticipantsListener​(ComposingParticipantsListener listener)

      Adds a listener that will be notified when list of composing participants changes. When there are no composing participant listeners registered, the `getComposingParticipants()` method will always return an empty list, since the lack of an installed listener indicates that the application is not interested in this information.
      Parameters:
        `listener` - object to receive notification.
      See Also:
        `getComposingParticipants()`

    - #### removeComposingParticipantsListener

          void removeComposingParticipantsListener​(ComposingParticipantsListener listener)

      Removes a listener that will be notified when list of composing participants changes. When there are no composing participant listeners registered, the `getComposingParticipants()` method will always return an empty list, since the lack of an installed listener indicates that the application is not interested in this information.
      Parameters:
        `listener` - object to receive notification.
      See Also:
        `getComposingParticipants()`

    - #### getConversationType

          ConversationType getConversationType()

      Returns the conversation type.
      Returns:
        the conversation type.

    - #### getSubject

          java.lang.String getSubject()

      Returns the subject of the conversation if one is provided by the server.
      Returns:
        the subject of the conversation if one is provided by the server.
      See Also:
        `ConversationListener.onConversationSubjectChanged(Conversation, String)`, `setSubject(String, MessagingCompletionHandler)`

    - #### getId

          java.lang.String getId()

      Returns the unique conversation identifier.
      Returns:
        the unique conversation identifier.

    - #### getProviderConversationId

          java.lang.String getProviderConversationId()

      Returns the conversation ID from the underlying provider (e.g., the AMM server) as-is. It will be consistent across clients and application launches, but is only guaranteed to be unique for conversations of that provider type.
      Returns:
        a protocol level identifier of the conversation. It will be empty for draft conversation.

    - #### getTotalMessageCount

          int getTotalMessageCount()

      Returns the total number of messages in the conversation.
      Returns:
        the total number of messages in the conversation.
      See Also:
        `ConversationListener.onConversationTotalMessageCountChanged(Conversation, int)`

    - #### getUnreadMessageCount

          int getUnreadMessageCount()

      Returns the number of unread messages in the conversation.
      Returns:
        the number of unread messages in the conversation.
      See Also:
        `ConversationListener.onConversationTotalUnreadMessageCountChanged(Conversation, int)`

    - #### getTotalAttachmentCount

          int getTotalAttachmentCount()

      Returns the total number of attachments in all messages of the conversation.
      Returns:
        the total number of attachments in all messages of the conversation.
      See Also:
        `ConversationListener.onConversationTotalAttachmentCountChanged(Conversation, int)`

    - #### getUnreadAttachmentCount

          int getUnreadAttachmentCount()

      Returns the total number of unread attachments in all messages of the conversation.
      Returns:
        the total number of unread attachments in all messages of the conversation.
      See Also:
        `ConversationListener.onConversationTotalUnreadAttachmentCountChanged(Conversation, int)`

    - #### getLastUpdatedTime

          java.util.Date getLastUpdatedTime()

      Returns the time the conversation was last updated.
      Returns:
        the time the conversation was last updated.
      See Also:
        `ConversationListener.onConversationLastUpdatedTimeChanged(Conversation, Date)`

    - #### getLastAccessedTime

          java.util.Date getLastAccessedTime()

      Returns the time the conversation was last accessed.
      Returns:
        the time the conversation was last accessed.
      See Also:
        `ConversationListener.onConversationLastAccessTimeChanged(Conversation, Date)`

    - #### getLastEntryTime

          java.util.Date getLastEntryTime()

      Returns the last entry timestamp of the conversation. This is the timestamp of the most recent message in the conversation.
      Returns:
        the last entry timestamp of the conversation. This is the timestamp of the most recent message in the conversation.
      See Also:
        `setLastAccessTime(MessagingCompletionHandler)`, `ConversationListener.onConversationLatestEntryTimeChanged(Conversation, Date)`

    - #### getStatus

          ConversationStatus getStatus()

      Returns the server reconciled status of the conversation.
      Returns:
        the server reconciled status of the conversation.
      See Also:
        `ConversationListener.onConversationStatusChanged(Conversation, ConversationStatus)`

    - #### getSensitivity

          SensitivityLevel getSensitivity()

      Returns the sensitivity of the conversation.
      Returns:
        the sensitivity of the conversation.
      See Also:
        `isPrivate()`, `setSensitivity(SensitivityLevel, MessagingCompletionHandler)`, `ConversationListener.onConversationSensitivityChanged(Conversation, SensitivityLevel)`

    - #### isActive

          boolean isActive()

      Returns true if the conversation is active.

      An active conversation is one that allows new contributions from any of the current participants and has the local user as an active participant (i.e. the local user has not left the conversation).

      Returns:
        true if the conversation is active.

    - #### isClosed

          boolean isClosed()

      Returns true if the conversation is closed.

      A closed conversation prohibits new contributions (or activity of any kind) from any participants. Such conversations are candidates for being deleted (after backup) as part of storage management activities.

      Returns:
        true if the conversation is closed.
      See Also:
        `ConversationListener.onConversationClosedStatusChanged(Conversation, boolean)`

    - #### isMultiParty

          boolean isMultiParty()

      Returns the multi-party status of the conversation. A conversation is considered to be a multi-party conversation if there are more than two active participants in the conversation.
      Returns:
        the multi-party status of the conversation.
      See Also:
        `ConversationListener.onConversationMultiPartyStatusChanged(Conversation, boolean)`

    - #### isPrivate

          boolean isPrivate()

      The conversation is private when `SensitivityLevel` of the conversation is set to `SensitivityLevel.PRIVATE`.
      Returns:
        true if the conversation is private.

    - #### hasUnreadMessagesSinceLastAccess

          boolean hasUnreadMessagesSinceLastAccess()

      Returns whether the conversation has unread messages since the time the conversation was last accessed.
      Returns:
        whether the conversation has unread messages since the time the conversation was last accessed.
      See Also:
        `getLastAccessedTime()`, `ConversationListener.onConversationLastAccessTimeChanged(Conversation, Date)`, `ConversationListener.onConversationTotalUnreadMessageCountChanged(Conversation, int)`, `retrieveMessages(DataRetrievalWatcher)`

    - #### hasUnreadMessages

          boolean hasUnreadMessages()

      Returns true if the conversation has any unread messages.
      Returns:
        true if the conversation has any unread messages.
      See Also:
        `getUnreadMessageCount()`, `retrieveMessages(DataRetrievalWatcher)`

    - #### hasUnreadAttachments

          boolean hasUnreadAttachments()

      Returns true if the conversation has any unread attachments.
      Returns:
        true if the conversation has any unread attachments.
      See Also:
        `getUnreadAttachmentCount()`

    - #### hasAttachments

          boolean hasAttachments()

      Returns true if the conversation has any attachments on any of its messages.
      Returns:
        true if the conversation has any attachments on any of its messages.
      See Also:
        `getTotalAttachmentCount()`

    - #### getPreviewText

          java.lang.String getPreviewText()

      Returns the preview text of the conversation.

      Preview text is a body of the latest message in the conversation.

      Returns:
        the preview text of the conversation.
      See Also:
        `ConversationListener.onConversationPreviewTextChanged(Conversation, String)`

    - #### getLastUpdatedByParticipant

          MessagingParticipant getLastUpdatedByParticipant()

      Returns the last `MessagingParticipant` that updated this conversation.
      Returns:
        the last `MessagingParticipant` that updated this conversation.

    - #### isParticipantActive

          boolean isParticipantActive​(MessagingParticipant participant)

      Returns true if a specified participant is active in this conversation.
      Parameters:
        `participant` - the participant to query for
      Returns:
        true if the specified participant is an active participant of the conversation.

    - #### getUpdateSubjectCapability

          Capability getUpdateSubjectCapability()

      Returns a `Capability` object that indicates if the subject property of the conversation can be updated.

      This capability is Allowed when all of the following conditions are true:

      - The messaging service is online (has an active connection to the server).
      - The messaging server supports changing the subject of a conversation.
      - The Conversation is active (see `isActive()`).
      Returns:
        a `Capability` object that indicates if the subject property of the conversation can be updated.
      See Also:
        `setSubject(String, MessagingCompletionHandler)`, `isActive()`

    - #### getUpdateLastAccessTimeCapability

          Capability getUpdateLastAccessTimeCapability()

      Returns a `Capability` object that indicates if the last accessed time of the conversation can be updated.

      This capability is Allowed when all of the following conditions are true:

      - The messaging service is online (has an active connection to the server).
      - The Conversation is in the published state.
      Returns:
        a `Capability` object that indicates if the last accessed time of the conversation can be updated.
      See Also:
        `setLastAccessTime(MessagingCompletionHandler)`

    - #### getUpdateSensitivityCapability

          Capability getUpdateSensitivityCapability()

      Returns a `Capability` object that indicates if the sensitivity of the conversation can be updated.

      This capability is Allowed when the Conversation is in the draft state.

      Returns:
        a `Capability` object that indicates if the sensitivity of the conversation can be updated.
      See Also:
        `setSensitivity(SensitivityLevel, MessagingCompletionHandler)`

    - #### getUpdateTypeCapability

          Capability getUpdateTypeCapability()

      Returns a `Capability` object that indicates if the type of the conversation can be updated.

      This capability is currently always disabled because the messaging server only supports conversations of type "thread".

      Returns:
        a `Capability` object that indicates if the type of the conversation can be updated.
      See Also:
        `setType(ConversationType, MessagingCompletionHandler)`

    - #### getOlderContentCapability

          Capability getOlderContentCapability()

      Returns a `Capability` object that indicates whether the user can "scroll to get more messages", i.e. there are additional messages not yet downloaded from the server.

      This capability is Allowed when all of the following conditions are true:

      - The messaging service is online (has an active connection to the server).
      - The Conversation is in the published state.
      Returns:
        a `Capability` object that indicates whether the user can "scroll to get more messages", i.e. there are additional messages not yet downloaded from the server.
      See Also:
        `retrieveMessagesBefore(DataRetrievalWatcher, int, Message)`, `retrieveMessagesAfter(DataRetrievalWatcher, int, Message)`

    - #### getAddParticipantsCapability

          Capability getAddParticipantsCapability()

      Returns a `Capability` object that indicates if new participants can be added to the conversation.

      This capability is Allowed when all of the following conditions are true:

      - The messaging service is online (has an active connection to the server).
      - The Conversation is active (see `isActive()`).
      Returns:
        a `Capability` object that indicates if new participants can be added to the conversation.

    - #### getRemoveParticipantsCapability

          Capability getRemoveParticipantsCapability()

      Returns a `Capability` object that indicates if participants can be removed from the conversation.

      This capability is Allowed when the Conversation is in the draft state.

      Returns:
        a `Capability` object that indicates if participants can be removed from the conversation.
      See Also:
        `removeParticipantAddresses(List, MessagingCompletionHandler)`, `ConversationListener.onConversationParticipantsRemoved(Conversation, List)`

    - #### getRemoveParticipantCapability

          Capability getRemoveParticipantCapability()

      Returns a `Capability` object that indicates if a participant can be removed from the conversation.

      This capability is Allowed when one of the following conditions are true:

      - This conversation is in the draft state.
      - This conversation is published and messaging server allows to remove participants from it.
      Returns:
        a `Capability` object that indicates if a participant can be removed from the conversation.
      See Also:
        `removeParticipant(MessagingParticipant, MessagingCompletionHandler)`

    - #### getCreateMessageCapability

          Capability getCreateMessageCapability()

      Returns a `Capability` object that indicates if a new message can be created in the conversation.

      This capability is Allowed when all of the following conditions are true:

      - The messaging service is online (has an active connection to the server).
      - The Conversation is in the draft state and has been started (see `start(MessagingCompletionHandler)` method has been called) or is in the published state.
      - The Conversation does not have unsent messages.
      - The Conversation is not currently being left.
      Returns:
        a `Capability` object that indicates if a new message can be created in the conversation.
      See Also:
        `createMessage()`

    - #### getMarkAllContentAsReadCapability

          Capability getMarkAllContentAsReadCapability()

      Returns a `Capability` object that indicates if all messages in the conversation can be marked as read.

      This capability is Allowed when all of the following conditions are true:

      - The messaging service is online (has an active connection to the server).
      - The messaging server supports marking all messages of a conversation as read.
      - The Conversation is in the published state.
      Returns:
        a `Capability` object that indicates if all messages in the conversation can be marked as read
      See Also:
        `markAllContentAsRead(MessagingCompletionHandler)`

    - #### getLeaveCapability

          Capability getLeaveCapability()

      Returns a `Capability` object that indicates if the conversation can be left.

      This capability is Allowed when all of the following conditions are true:

      - The messaging service is online (has an active connection to the server).
      - The Conversation is in the published state.
      Returns:
        a `Capability` object that indicates if the conversation can be left.
      See Also:
        `leave(MessagingCompletionHandler)`

    - #### getStartCapability

          Capability getStartCapability()

      Returns a `Capability` object that indicates if the conversation can be started.

      This capability is Allowed when the Conversation is in the draft state and has not been started yet.

      Returns:
        a `Capability` object that indicates if the conversation can be started.
      See Also:
        `start(MessagingCompletionHandler)`

    - #### getRemoveCapability

          Capability getRemoveCapability()

      Returns a `Capability` object that indicates if the conversation can be removed.

      This capability is Allowed when the Conversation is in the draft state.

      Returns:
        a `Capability` object that indicates if the conversation can be removed.

    - #### getIsTypingCapability

          Capability getIsTypingCapability()

      Returns a Capability object that indicates if typing status reporting is available.
      Returns:
        Capability object that indicates if typing status reporting is available.

    - #### getMessageReadStateCapability

          Capability getMessageReadStateCapability()

      Returns a capability indicating whether this conversation is capable of reporting read state updates for sent messages.
      Returns:
        A `Capability` indicating whether this conversation is capable of reporting read state updates for sent messages.

    - #### getMessageDeliveryStateCapability

          Capability getMessageDeliveryStateCapability()

      Returns a capability indicating whether this conversation is capable of reporting delivery state updates for sent messages.
      Returns:
        A `Capability` indicating whether this conversation is capable of reporting delivery state updates for sent messages.

    - #### getParticipants

          java.util.List<MessagingParticipant> getParticipants()

      Returns a list of participants contained in this conversation.
      Returns:
        a list of participants contained in this conversation.
      See Also:
        `ConversationListener.onConversationParticipantsAdded(Conversation, List)`, `ConversationListener.onConversationParticipantsRemoved(Conversation, List)`

    - #### getActiveParticipants

          java.util.List<MessagingParticipant> getActiveParticipants()

      Returns a list of active participants contained in this conversation.
      Returns:
        a list of active participants contained in this conversation.
      See Also:
        `ConversationListener.onConversationParticipantsAdded(Conversation, List)`, `ConversationListener.onConversationParticipantsRemoved(Conversation, List)`

    - #### getComposingParticipants

          java.util.List<MessagingParticipant> getComposingParticipants()

      Returns a list of composing participants contained in this conversation. Note that the list will always be empty unless the client application has registered `ComposingParticipantsListener` on the conversation object.
      Returns:
        a list of composing participants contained in this conversation.

    - #### retrieveMessages

          void retrieveMessages​(DataRetrievalWatcher<Message> dataRetrievalWatcher)

      Starts the retrieval of messages associated with this conversation. This initial retrieval represents the most recent messages in the conversation and is limited to a maximum number that is specified by the messaging server. This is not necessarily the entire historical message content of the conversation.

      This method begins the retrieval of the dynamically-updated collection of messages associated with this conversation. Normally the client application will only need to call this method once to install a watcher object to monitor the initial download of messages and then continue to watch for updates to the collection.

      If older messages are required to be downloaded, the `retrieveMessagesBefore(DataRetrievalWatcher, int, Message)` and/or `retrieveMessagesAfter(DataRetrievalWatcher, int, Message)` methods can be used to retrieve additional message history. Note, however, that RetrieveMessages must be called first to install the `DataRetrievalWatcher` object that will monitor the retrieval, since these other methods work on a shared collection managed internally by the Conversation object. The application should use the `DataRetrievalWatcherListener.onCollectionChanged(DataRetrievalWatcher, DataCollectionChangeType, List)` callback to build up and maintain a local collection of messages associated with this conversation.

      When using these message retrieval methods, it is important to note that there can only be a single retrieval operation in progress at any given time. If there is a retrieval operation in progress when once of these three message retrieval methods are called, the currently running retrieval will be cancelled before starting the next operation.

      If the client application calls this method additional times, no actual download of messages from the server occurs, but the watcher listener callbacks that report progress will fire (i.e. "progress" and "done" callbacks). However, no additions to the message collection will occur as a result of the subsequent calls. If a different watcher object is supplied in a subsequent call, the previous watcher object is "unlinked" from the underlying message object collection and will never receive any additional updates.

      Parameters:
        `dataRetrievalWatcher` - `DataRetrievalWatcher` object, created by the application, to track the progress of the requested operation.
      See Also:
        `retrieveMessagesBefore(DataRetrievalWatcher, int, Message)`, `retrieveMessagesAfter(DataRetrievalWatcher, int, Message)`

    - #### retrieveMessagesBefore

          void retrieveMessagesBefore​(DataRetrievalWatcher<Message> dataRetrievalWatcher,
                                      int numberOfMessagesToRetrieve,
                                      Message beforeMessage)

      Retrieves a list of the conversation messages before the specified message. This list represents a list of contiguous messages which have been, or are being, downloaded.

      This method is used in conjunction with the `retrieveMessages(DataRetrievalWatcher)` method to retrieve older message content associated with the conversation. Please refer to the description of that method for detailed usage information.

      To determine when it is appropriate to call the retrieveMessagesBefore method, the client application should query the `getOlderContentCapability()` method.

      Parameters:
        `dataRetrievalWatcher` - `DataRetrievalWatcher` object, created by the application, to track the progress of the requested operation.
        `numberOfMessagesToRetrieve` - The maximum number of messages to retrieve. The actual number retrieved may be less than this if the maximum number of messages allowed per retrieval request, as configured on the server is less than the specified value, or if the start of the message list is reached.
        `beforeMessage` - the starting point in the retrieval. Messages immediately before this one will be retrieved.
      See Also:
        `retrieveMessages(DataRetrievalWatcher)`, `retrieveMessagesAfter(DataRetrievalWatcher, int, Message)`

    - #### retrieveMessagesAfter

          void retrieveMessagesAfter​(DataRetrievalWatcher<Message> dataRetrievalWatcher,
                                     int numberOfMessagesToRetrieve,
                                     Message afterMessage)

      Retrieves a list of the conversation messages after the specified message. This list represents a list of contiguous messages which have been, or are being, downloaded.

      This method is used in conjunction with the `retrieveMessages(DataRetrievalWatcher)` method to retrieve older message content associated with the conversation. Please refer to the description of that method for detailed usage information.

      To determine when it is appropriate to call the retrieveMessagesAfter method, the client application should query the `getOlderContentCapability()` method.

      Parameters:
        `dataRetrievalWatcher` - `DataRetrievalWatcher` object, created by the application, to track the progress of the requested operation.
        `numberOfMessagesToRetrieve` - the maximum number of messages to retrieve. The actual number retrieved may be less than this if the maximum number of messages allowed per retrieval request, as configured on the server, is less than the specified value, or if the end of the message list is reached.
        `afterMessage` - the starting point in the retrieval. Messages immediately after this one will be retrieved.
      See Also:
        `retrieveMessages(DataRetrievalWatcher)`, `retrieveMessagesBefore(DataRetrievalWatcher, int, Message)`

    - #### start

          void start​(MessagingCompletionHandler completionHandler)

      Invokes a start request for this conversation.
      Parameters:
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      See Also:
        `getStartCapability()`

    - #### leave

          void leave​(MessagingCompletionHandler completionHandler)

      Invokes a leave request for this conversation.

      After leaving, participant can no longer contribute to the conversation unless he is added once again.

      When last participant is leaving the conversation it will become closed after a while.

      Parameters:
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      See Also:
        `getLeaveCapability()`

    - #### markAllContentAsRead

          void markAllContentAsRead​(MessagingCompletionHandler completionHandler)

      Marks all content in this conversation as read.
      Parameters:
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      See Also:
        `getMarkAllContentAsReadCapability()`

    - #### addParticipantAddresses

          void addParticipantAddresses​(java.util.List<java.lang.String> addresses,
                                       AddParticipantAddressesCompletionHandler completionHandler)

      Invokes an add participant request for this conversation for each of the provided addresses.
      Parameters:
        `addresses` - a list of participant addresses to add to this conversation.
        `completionHandler` - `AddParticipantAddressesCompletionHandler` for this operation.
      See Also:
        `getAddParticipantsCapability()`

    - #### addParticipant

          void addParticipant​(Contact contact,
                              AddParticipantAddressesCompletionHandler completionHandler)

      Invokes an add participant request for this conversation for provided contact object.
      Parameters:
        `contact` - Contact object from directory search.
        `completionHandler` - `AddParticipantAddressesCompletionHandler` for this operation.
      See Also:
        `getAddParticipantsCapability()`

    - #### removeParticipantAddresses

          void removeParticipantAddresses​(java.util.List<java.lang.String> addresses,
                                          MessagingCompletionHandler completionHandler)

      Invokes a remove participant request for this conversation for each of the provided addresses.
      Parameters:
        `addresses` - a list of participant addresses to remove to this conversation.
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      See Also:
        `getRemoveParticipantsCapability()`

    - #### removeParticipant

          void removeParticipant​(MessagingParticipant participant,
                                 MessagingCompletionHandler completionHandler)

      Invokes a remove participant request for this conversation.
      Parameters:
        `participant` - the participant to remove from this conversation.
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      See Also:
        `getRemoveParticipantCapability()`

    - #### setLastAccessTime

          void setLastAccessTime​(MessagingCompletionHandler completionHandler)

      Invokes a set last access time request for this conversation.
      Parameters:
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      See Also:
        `getUpdateLastAccessTimeCapability()`, `getLastAccessedTime()`

    - #### setSubject

          void setSubject​(java.lang.String subject,
                          MessagingCompletionHandler completionHandler)

      Sets the subject for this conversation.
      Parameters:
        `subject` - the new subject of this conversation.
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      See Also:
        `getUpdateSubjectCapability()`

    - #### setType

          void setType​(ConversationType type,
                       MessagingCompletionHandler completionHandler)

      Sets the conversation type.
      Parameters:
        `type` - `ConversationType` the new conversation type.
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      See Also:
        `getUpdateTypeCapability()`

    - #### setSensitivity

          void setSensitivity​(SensitivityLevel sensitivityLevel,
                              MessagingCompletionHandler completionHandler)

      Sets the conversation sensitivity.
      Parameters:
        `sensitivityLevel` - `SensitivityLevel` the new conversation sensitivity.
        `completionHandler` - `MessagingCompletionHandler` for this operation.
      See Also:
        `getUpdateSensitivityCapability()`

    - #### createMessage

          Message createMessage()

      Creates a new Message in this conversation.
      Returns:
        a new `Message` object, or null if a new message could not be created.
      See Also:
        `getCreateMessageCapability()`

    - #### removeMessage

          void removeMessage​(Message message,
                             MessagingCompletionHandler completionHandler)

      Removes a `Message` (only draft messages can be removed).
      Parameters:
        `message` - the `Message` to be removed.
        `completionHandler` - `MessagingCompletionHandler` for this operation.

    - #### clearLocalAttachmentData

          void clearLocalAttachmentData​(MessagingCompletionHandler completionHandler)

      Clear conversation local attachment data.

      This method clears only application data and it is not applicable to any content downloaded to a user's device.

      Parameters:
        `completionHandler` - `MessagingCompletionHandler` for this operation.

    - #### getProviderType

          MessagingProviderType getProviderType()

      Returns a provider type for the conversation.
      Returns:
        a provider type for the conversation.