Package com.flowable.engage.conversation.api

Interface ConversationService

All Known Implementing Classes:
ConversationServiceImpl
public interface ConversationService
The conversation service is the main API for the conversation and messaging functionality.
Author:
Micha Kiener, Filip Hrisafov, Anatolii Balakiriev

  • Method Summary

    Modifier and Type Method Description
    void addParticipants​(java.lang.String conversationId, java.util.Collection<java.lang.String> participants)
    Adds the given participants to the conversation with the given id
    void addTag​(java.lang.String conversationId, java.lang.String tag)
    Adds the provided tag to the specified conversation.
    void addTags​(java.lang.String conversationId, java.util.Collection<java.lang.String> tags)
    Tag the conversation with provided tags
    void archive​(java.lang.String conversationId)
    Archives the conversation with the given id.
    void assignToGroup​(java.lang.String conversationId, java.lang.String assignedGroupId)
    Assigns the conversation to a group of users (set the assignedGroupId property).
    void assignToUser​(java.lang.String conversationId, java.lang.String assignedUserId)
    Assigns the conversation to a user (set the assigneeId property).
    void changeOwner​(java.lang.String conversationId, java.lang.String ownerUserId)
    Changes an owner of the conversation.
    long countConversationsWithLastMessageBetween​(java.util.Date from, java.util.Date until, boolean includePrivateMessages, boolean includeStickMessages)
    TODO: this might be not the right service Number of conversations which received new messages within a given time frame.
    ConversationBuilder createConversationBuilder()
    Returns a conversation builder used to start new Conversation objects.
    ConversationParticipantBuilder createConversationParticipantBuilder​(java.lang.String conversationId)
    Creates a new participant builder to add or remove participants to / from a conversation with various extended options mainly on message visibility.
    ConversationQuery createConversationQuery()
    Creates a new conversation query as a builder where you can add predicates in order to query for conversations.
    ConversationStatusQuery createConversationStatusQuery()
    Creates a new conversation status query, that can be used to get the different unread statuses for a conversation.
    ConversationUserQuery createConversationUserQuery()
    Creates a new user query to request user ids involved in a specific conversation (e.g.
    void deleteConversation​(java.lang.String conversationId)
    Deletes a conversation and all related data (messages, unread counts, etc.).
    boolean exists​(java.lang.String conversationId)  
    Conversation findById​(java.lang.String conversationId)
    Finds the conversation with the given id.
    Conversation findByIdWithIdentityLinks​(java.lang.String conversationId)
    Finds the conversation with the given id, with the identity links already prefetched.
    Conversation findByIdWithIdentityLinksAndVariables​(java.lang.String conversationId)
    Finds the conversation with the given id, with the identity links and variables already prefetched.
    java.util.List<Conversation> findConversationsWithLastMessageBetween​(java.util.Date from, java.util.Date until, boolean includePrivateMessages, boolean includeStickMessages)
    TODO: this might be not the right service Finds conversations which received new messages within a given time frame.
    java.lang.Object getVariable​(java.lang.String conversationId, java.lang.String variableName)
    The variable value.
    java.util.Map<java.lang.String,​java.lang.Object> getVariables​(java.lang.String conversationId)
    All variables visible from the given conversation.
    void linkConversationWithUserAccount​(java.lang.String conversationId, java.lang.String userAccountId)
    Set the id of the user account that is linked with this conversation.
    void removeAssignedGroup​(java.lang.String conversationId)
    Removes an assigned group from a conversation (sets the assignedGroupId proeprty to null).
    void removeAssignedUser​(java.lang.String conversationId)
    Removes an assigned user from a conversation.
    void removeParticipants​(java.lang.String conversationId, java.util.Collection<java.lang.String> participants)
    Removes the given participants to the conversation with the given id
    void removeTag​(java.lang.String conversationId, java.lang.String tag)
    Removes the provided tag from the specified conversation, if it exists.
    void removeTags​(java.lang.String conversationId, java.util.Collection<java.lang.String> tags)
    Remove the provided tags from the conversation
    void removeUserAccountFromConversation​(java.lang.String conversationId)
    Remove the id of the user account from this conversation.
    void removeVariable​(java.lang.String conversationId, java.lang.String variableName)
    Removes a variable for a conversation.
    void removeVariables​(java.lang.String conversationId, java.util.Collection<java.lang.String> variableNames)
    Removes variables for a conversation.
    void reopen​(java.lang.String conversationId)
    Reopens the archived conversation with the given id.
    Conversation setReference​(java.lang.String conversationId, java.lang.String referenceId, java.lang.String referenceType, java.lang.String referenceDefinitionId)
    Set the optional reference for a conversation like a case or process where the conversation is liked to.
    void setVariable​(java.lang.String conversationId, java.lang.String variableName, java.lang.Object value)
    Update or create a variable for a conversation.
    void setVariables​(java.lang.String conversationId, java.util.Map<java.lang.String,​java.lang.Object> variables)
    Update or create given variables for a conversation.
    long unreadMessagesCount​(java.lang.String userId, java.lang.String conversationId)
    The unread data count for the user with id userId in the conversation with id conversationId
    Conversation updateAvatarId​(java.lang.String conversationId, java.lang.String avatarId)
    Updates the conversation avatar id for the given conversation.
    Conversation updateDescription​(java.lang.String conversationId, java.lang.String description)
    Updates the conversation description for the given conversation.
    Conversation updateName​(java.lang.String conversationId, java.lang.String name)
    Updates the conversation name (title) for the given conversation.
    void userTyping​(java.lang.String conversationId, java.lang.String userId)
    Information that a user with id userId is typing in the conversation with id conversationId

  • Method Details

    • createConversationQuery

      ConversationQuery createConversationQuery()
      Creates a new conversation query as a builder where you can add predicates in order to query for conversations. If you search by the conversation id only you should better use findById(String) because it takes the cache into account.
      Returns:
      the conversation query builder

    • createConversationBuilder

      ConversationBuilder createConversationBuilder()
      Returns a conversation builder used to start new Conversation objects. Make sure to always explicitly set the sub type of the conversation as it is a mandatory information.
      Returns:
      the conversation builder

    • createConversationParticipantBuilder

      ConversationParticipantBuilder createConversationParticipantBuilder​(java.lang.String conversationId)
      Creates a new participant builder to add or remove participants to / from a conversation with various extended options mainly on message visibility.
      Parameters:
      conversationId - the id of the conversation to manage participants through the builder
      Returns:
      a conversation participant builder

    • createConversationUserQuery

      ConversationUserQuery createConversationUserQuery()
      Creates a new user query to request user ids involved in a specific conversation (e.g. participants or all involved users, etc).
      Returns:
      the conversation query builder

    • createConversationStatusQuery

      ConversationStatusQuery createConversationStatusQuery()
      Creates a new conversation status query, that can be used to get the different unread statuses for a conversation.
      Returns:
      the conversation status query builder

    • exists

      boolean exists​(java.lang.String conversationId)
      Returns:
      Checks if the given conversation exists.

    • unreadMessagesCount

      long unreadMessagesCount​(java.lang.String userId, java.lang.String conversationId)
      The unread data count for the user with id userId in the conversation with id conversationId
      Parameters:
      userId - the id of the user for which the unread data count is needed
      conversationId - the id of the conversation for which the count is needed
      Returns:
      the number of unread messages for the given user in the given conversation

    • setReference

      Conversation setReference​(java.lang.String conversationId, java.lang.String referenceId, java.lang.String referenceType, java.lang.String referenceDefinitionId)
      Set the optional reference for a conversation like a case or process where the conversation is liked to.
      Parameters:
      conversationId - the id of the conversation to set its reference
      referenceId - the id of the referenced work item
      referenceType - the type of the referenced work item
      referenceDefinitionId - the optional definition id of the referenced work item
      Returns:
      the modified conversation retrieved from the database

    • updateName

      Conversation updateName​(java.lang.String conversationId, java.lang.String name)
      Updates the conversation name (title) for the given conversation.
      Parameters:
      conversationId - the id of the conversation to change its name
      name - title of the conversation, it can be also be null or empty
      Returns:
      modified conversation retrieved from database

    • updateDescription

      Conversation updateDescription​(java.lang.String conversationId, java.lang.String description)
      Updates the conversation description for the given conversation.
      Parameters:
      conversationId - the id of the conversation to change its description
      description - the description of the conversation, it can be also be null or empty
      Returns:
      modified conversation retrieved from database

    • updateAvatarId

      Conversation updateAvatarId​(java.lang.String conversationId, java.lang.String avatarId)
      Updates the conversation avatar id for the given conversation.
      Parameters:
      conversationId - the id of the conversation to change its description
      avatarId - the avatar id of the conversation, it can be also be null or empty
      Returns:
      modified conversation retrieved from database

    • archive

      void archive​(java.lang.String conversationId)
      Archives the conversation with the given id. You can't post anything to an archived conversation, the only thing left to do is re-opening it.
      Parameters:
      conversationId - the id of the conversation to be archived

    • reopen

      void reopen​(java.lang.String conversationId)
      Reopens the archived conversation with the given id.
      Parameters:
      conversationId - the id of the conversation to be reopened

    • addParticipants

      void addParticipants​(java.lang.String conversationId, java.util.Collection<java.lang.String> participants)
      Adds the given participants to the conversation with the given id
      Parameters:
      conversationId - the id of the conversation to which the participants needs to be added
      participants - the ids of the participants that need to be added

    • removeParticipants

      void removeParticipants​(java.lang.String conversationId, java.util.Collection<java.lang.String> participants)
      Removes the given participants to the conversation with the given id
      Parameters:
      conversationId - the id of the conversation from which the participants need to be removed
      participants - the ids of the participants that need to be removed

    • assignToGroup

      void assignToGroup​(java.lang.String conversationId, java.lang.String assignedGroupId)
      Assigns the conversation to a group of users (set the assignedGroupId property).
      Parameters:
      conversationId - the id of the conversation to be assigned to a group
      assignedGroupId - the id of the group to assign the conversation to

    • removeAssignedGroup

      void removeAssignedGroup​(java.lang.String conversationId)
      Removes an assigned group from a conversation (sets the assignedGroupId proeprty to null).
      Parameters:
      conversationId - the id of the conversation to remove the assgined group from

    • assignToUser

      void assignToUser​(java.lang.String conversationId, java.lang.String assignedUserId)
      Assigns the conversation to a user (set the assigneeId property).
      Parameters:
      conversationId - the id of the conversation to be assigned to a user
      assignedUserId - the id of the user to assign the conversation to

    • removeAssignedUser

      void removeAssignedUser​(java.lang.String conversationId)
      Removes an assigned user from a conversation.
      Parameters:
      conversationId - the id of the conversatoin to remove the assigned user (set the assigneeId ot null).

    • changeOwner

      void changeOwner​(java.lang.String conversationId, java.lang.String ownerUserId)
      Changes an owner of the conversation.
      Parameters:
      conversationId - the id of the conversation to change an owner in
      ownerUserId - the id of the user to become a new owner of this conversation

    • userTyping

      void userTyping​(java.lang.String conversationId, java.lang.String userId)
      Information that a user with id userId is typing in the conversation with id conversationId
      Parameters:
      conversationId - the id of the conversation in which the user is typing
      userId - the id of the user that is doing the typing

    • deleteConversation

      void deleteConversation​(java.lang.String conversationId)
      Deletes a conversation and all related data (messages, unread counts, etc.).
      Parameters:
      conversationId - the id of the conversation which needs to be deleted.

    • addTags

      void addTags​(java.lang.String conversationId, java.util.Collection<java.lang.String> tags)
      Tag the conversation with provided tags
      Parameters:
      conversationId - the id of the conversation to which the tags need to be added
      tags - the tags that should be added to the conversation

    • addTag

      void addTag​(java.lang.String conversationId, java.lang.String tag)
      Adds the provided tag to the specified conversation.
      Parameters:
      conversationId - the id of the conversation where the tag should be added
      tag - the tag to be added, must not be null or empty

    • removeTags

      void removeTags​(java.lang.String conversationId, java.util.Collection<java.lang.String> tags)
      Remove the provided tags from the conversation
      Parameters:
      conversationId - the id of the conversation from which tags need to be removed
      tags - the tags that need to be removed from the conversation

    • removeTag

      void removeTag​(java.lang.String conversationId, java.lang.String tag)
      Removes the provided tag from the specified conversation, if it exists.
      Parameters:
      conversationId - the id of the conversatoin to remove the provided tag from
      tag - the tag to be removed

    • countConversationsWithLastMessageBetween

      long countConversationsWithLastMessageBetween​(java.util.Date from, java.util.Date until, boolean includePrivateMessages, boolean includeStickMessages)
      TODO: this might be not the right service Number of conversations which received new messages within a given time frame. If you are only interested in general messages (neither private nor sticky messages) it's better to use ConversationQuery and build a query with ConversationQuery.lastMessageAfter(Date) or ConversationQuery.lastMessageBefore(Date) This method is needed if private or sticky messages are also to be taken account, because Conversation.getLastMessageTime() will not be updated for private or sticky messages.
      Parameters:
      from - start of the time frame (optional)
      until - end of the time frame (optional)
      includePrivateMessages - true if private messages should also be considered
      includeStickMessages - true if sticky messages should also be considered
      Returns:
      count of conversations with new messages within given time frame

    • findConversationsWithLastMessageBetween

      java.util.List<Conversation> findConversationsWithLastMessageBetween​(java.util.Date from, java.util.Date until, boolean includePrivateMessages, boolean includeStickMessages)
      TODO: this might be not the right service Finds conversations which received new messages within a given time frame. If you are only interested in general messages (neither private nor sticky messages) it's better to use ConversationQuery and build a query with ConversationQuery.lastMessageAfter(Date) or ConversationQuery.lastMessageBefore(Date) This method is needed if private or sticky messages are also to be taken account, because Conversation.getLastMessageTime() will not be updated for private or sticky messages.
      Parameters:
      from - start of the time frame (optional)
      until - end of the time frame (optional)
      includePrivateMessages - true if private messages should also be considered
      includeStickMessages - true if sticky messages should also be considered
      Returns:
      list of conversations with new messages withing given time frame

    • findByIdWithIdentityLinks

      Conversation findByIdWithIdentityLinks​(java.lang.String conversationId)
      Finds the conversation with the given id, with the identity links already prefetched.

    • findByIdWithIdentityLinksAndVariables

      Conversation findByIdWithIdentityLinksAndVariables​(java.lang.String conversationId)
      Finds the conversation with the given id, with the identity links and variables already prefetched.

    • findById

      Conversation findById​(java.lang.String conversationId)
      Finds the conversation with the given id. If you are interested in the conversation owner, participants etc. you must call findByIdWithIdentityLinks(String).
      Parameters:
      conversationId - the conversation id
      Returns:
      the conversation without any identity links

    • linkConversationWithUserAccount

      void linkConversationWithUserAccount​(java.lang.String conversationId, java.lang.String userAccountId)
      Set the id of the user account that is linked with this conversation. If a conversation is already linked with a user account then this operation will fail. If a conversation needs to have it's user account changed then call removeUserAccountFromConversation(String) first.
      Parameters:
      conversationId - the id of the conversation that should be updated
      userAccountId - the id of the user account that should be linked with the conversation

    • removeUserAccountFromConversation

      void removeUserAccountFromConversation​(java.lang.String conversationId)
      Remove the id of the user account from this conversation. If the conversation is not linked with a user already then this method does nothing.
      Parameters:
      conversationId - the id of the conversation that should be updated

    • getVariables

      java.util.Map<java.lang.String,​java.lang.Object> getVariables​(java.lang.String conversationId)
      All variables visible from the given conversation.
      Parameters:
      conversationId - id of the conversation, cannot be null.
      Returns:
      the variables or an empty map if no such variables are found.
      Throws:
      org.flowable.common.engine.api.FlowableObjectNotFoundException - when no conversation is found for the given conversationId.

    • getVariable

      java.lang.Object getVariable​(java.lang.String conversationId, java.lang.String variableName)
      The variable value. Returns null when no variable value is found with the given name or when the value is set to null.
      Parameters:
      conversationId - id of conversation, cannot be null.
      variableName - name of variable, cannot be null.
      Returns:
      the variable value or null if the variable is undefined or the value of the variable is null.
      Throws:
      org.flowable.common.engine.api.FlowableObjectNotFoundException - when no conversation is found for the given conversationId.

    • setVariable

      void setVariable​(java.lang.String conversationId, java.lang.String variableName, java.lang.Object value)
      Update or create a variable for a conversation.
      Parameters:
      conversationId - id of conversation to set variable in, cannot be null.
      variableName - name of variable to set, cannot be null.
      value - value to set. When null is passed, the variable is not removed, only it's value will be set to null.
      Throws:
      org.flowable.common.engine.api.FlowableObjectNotFoundException - when no conversation is found for the given conversationId.

    • setVariables

      void setVariables​(java.lang.String conversationId, java.util.Map<java.lang.String,​java.lang.Object> variables)
      Update or create given variables for a conversation.
      Parameters:
      conversationId - id of the conversation, cannot be null.
      variables - map containing name (key) and value of variables, can be null.
      Throws:
      org.flowable.common.engine.api.FlowableObjectNotFoundException - when no conversation is found for the given conversationId.

    • removeVariable

      void removeVariable​(java.lang.String conversationId, java.lang.String variableName)
      Removes a variable for a conversation.
      Parameters:
      conversationId - id of conversation to remove variable in.
      variableName - name of variable to remove.

    • removeVariables

      void removeVariables​(java.lang.String conversationId, java.util.Collection<java.lang.String> variableNames)
      Removes variables for a conversation.
      Parameters:
      conversationId - id of conversation to remove variable in.
      variableNames - collection containing name of variables to remove.