Package com.vaadin.collaborationengine

Interface CollaborationList

  • All Superinterfaces:
    HasExpirationTimeout
    public interface CollaborationList
extends HasExpirationTimeout
    A list that is shared between multiple users. List instances can be retrieved through a TopicConnection. Changes performed by one user will be delivered as events to subscribers defined by other users.
    Since:
    3.1
    Author:
    Vaadin Ltd

    • Method Detail

      • getItems

        <T> List<T> getItems​(Class<T> type)
        Gets the list items as instances of the given class.
        Type Parameters:
        T - the type of the class given as the argument
        Parameters:
        type - the expected type of the items
        Returns:
        a list of the items
        Throws:
        JsonConversionException - if one or more values in the list cannot be converted to an instance of the given class

      • getItems

        <T> List<T> getItems​(com.fasterxml.jackson.core.type.TypeReference<T> type)
        Gets the list items as instances of the given type reference.
        Type Parameters:
        T - the type of the reference given as the argument
        Parameters:
        type - the reference of the expected type of the items
        Returns:
        a list of the items
        Throws:
        JsonConversionException - if one or more values in the list cannot be converted to an instance of the given type reference

      • getItem

        <T> T getItem​(ListKey key,
              Class<T> type)
        Gets the list item identifier by the given key as instance of the given class.
        Type Parameters:
        T - the type of the value from type parameter, e.g. String
        Parameters:
        key - the key of the requested item, not null
        type - the expected type of the item, not null
        Returns:
        the requested item
        Throws:
        JsonConversionException - if the value in the list cannot be converted to an instance of the given class
        Since:
        4.1

      • getItem

        <T> T getItem​(ListKey key,
              com.fasterxml.jackson.core.type.TypeReference<T> type)
        Gets the list item identifier by the given key as instance of the given type reference.
        Type Parameters:
        T - the type reference of the value from type parameter, e.g. List
        Parameters:
        key - the key of the requested item, not null
        type - the expected type reference of the item, not null
        Returns:
        the requested item
        Throws:
        JsonConversionException - if the value in the list cannot be converted to an instance of the given class
        Since:
        4.1

      • getKeys

        Stream<ListKey> getKeys()
        Gets the keys for all the items on the list.
        Returns:
        the keys
        Since:
        4.1

      • apply

        ListOperationResult<Boolean> apply​(ListOperation operation)
        Performs the given list operation. The operation contains the value, its position and other requirements. If any of the conditions are not met, the operation may fail (see ListOperationResult).
        Parameters:
        operation - the list operation, not null
        Returns:
        the result of the operation, not null

      • insertFirst

        default ListOperationResult<Void> insertFirst​(Object item)
        Inserts the given item as the first item of the list.
        Parameters:
        item - the item, not null
        Returns:
        the result of the operation, not null

      • insertFirst

        @Deprecated(since="5.1",
            forRemoval=true)
default ListOperationResult<Void> insertFirst​(Object item,
                                              EntryScope scope)
        Deprecated, for removal: This API element is subject to removal in a future version.
        Use apply(ListOperation) with ListOperation.insertFirst(Object).withScope(EntryScope).
        Inserts the given item as the first item of the list, with the given scope.
        Parameters:
        item - the item, not null
        scope - the scope of the entry, not null
        Returns:
        the result of the operation, not null

      • insertLast

        default ListOperationResult<Void> insertLast​(Object item)
        Inserts the given item as the last item of the list.
        Parameters:
        item - the item, not null
        Returns:
        the result of the operation, not null
        Since:
        4.1

      • insertLast

        @Deprecated(since="5.1",
            forRemoval=true)
default ListOperationResult<Void> insertLast​(Object item,
                                             EntryScope scope)
        Deprecated, for removal: This API element is subject to removal in a future version.
        Use apply(ListOperation) with ListOperation.insertLast(Object).withScope(EntryScope).
        Inserts the given item as the last item of the list, with the given scope.
        Parameters:
        item - the item, not null
        scope - the scope of the entry, not null
        Returns:
        the result of the operation, not null
        Since:
        4.1

      • insertBefore

        default ListOperationResult<Boolean> insertBefore​(ListKey key,
                                                  Object item)
        Inserts the given item just before the given key location.
        Parameters:
        key - the position key, not null
        item - the item, not null
        Returns:
        the result of the operation, not null

      • insertBefore

        @Deprecated(since="5.1",
            forRemoval=true)
default ListOperationResult<Boolean> insertBefore​(ListKey key,
                                                  Object item,
                                                  EntryScope scope)
        Deprecated, for removal: This API element is subject to removal in a future version.
        Use apply(ListOperation) with ListOperation.insertBefore(ListKey, Object).withScope (EntryScope) .
        Inserts the given item just before the given key location, with the given scope.
        Parameters:
        key - the position key, not null
        item - the item, not null
        scope - the scope of the entry, not null
        Returns:
        the result of the operation, not null

      • insertAfter

        default ListOperationResult<Boolean> insertAfter​(ListKey key,
                                                 Object item)
        Inserts the given item just after the given key location.
        Parameters:
        key - the position key, not null
        item - the item, not null
        Returns:
        the result of the operation, not null

      • insertAfter

        @Deprecated(since="5.1",
            forRemoval=true)
default ListOperationResult<Boolean> insertAfter​(ListKey key,
                                                 Object item,
                                                 EntryScope scope)
        Deprecated, for removal: This API element is subject to removal in a future version.
        Use apply(ListOperation) with ListOperation.insertAfter(ListKey, Object).withScope (EntryScope) .
        Inserts the given item just after the given key location, with the given scope.
        Parameters:
        key - the position key, not null
        item - the item, not null
        scope - the scope of the entry, not null
        Returns:
        the result of the operation, not null

      • moveBefore

        default CompletableFuture<Boolean> moveBefore​(ListKey key,
                                              ListKey keyToMove)
        Moves the second given key just before the first given key location.
        Parameters:
        key - the position key, not null
        keyToMove - the key to move, not null
        Returns:
        a completable future that is resolved when the operation has completed, not null

      • moveAfter

        default CompletableFuture<Boolean> moveAfter​(ListKey key,
                                             ListKey keyToMove)
        Moves the second given key just after the first given key location.
        Parameters:
        key - the position key, not null
        keyToMove - the key to move, not null
        Returns:
        a completable future that is resolved when the operation has completed, not null

      • set

        default CompletableFuture<Boolean> set​(ListKey key,
                                       Object value)
        Sets a new value for the item identified by the given key.
        Parameters:
        key - the item key, not null
        value - the new value of the item
        Returns:
        the result of the operation, not null
        Since:
        4.1

      • set

        @Deprecated(since="5.2",
            forRemoval=true)
default CompletableFuture<Boolean> set​(ListKey key,
                                       Object value,
                                       EntryScope scope)
        Deprecated, for removal: This API element is subject to removal in a future version.
        Use apply(ListOperation) with ListOperation.set(ListKey, Object).withScope(EntryScope).
        Sets a new value for the item identified by the given key, with the given scope.
        Parameters:
        key - the item key, not null
        value - the new value of the item
        scope - the scope of the entry, not null
        Returns:
        the result of the operation, not null
        Since:
        4.1

      • remove

        default CompletableFuture<Boolean> remove​(ListKey key)
        Removes the value for the item identified by the given key.
        Parameters:
        key - the item key, not null
        Returns:
        the result of the operation, not null

      • append

        @Deprecated(since="4.0",
            forRemoval=true)
default CompletableFuture<Void> append​(Object item)
        Deprecated, for removal: This API element is subject to removal in a future version.
        Use apply(ListOperation) with ListOperation.insertLast(Object)
        Appends the given item to the list.

        The given item must be JSON-serializable so it can be sent over the network when Collaboration Engine is hosted in a standalone server.

        Parameters:
        item - the item to append, not null
        Returns:
        a completable future that is resolved when the item has been appended to the list
        Throws:
        JsonConversionException - if the given item isn't serializable as JSON string

      • append

        @Deprecated(since="4.0",
            forRemoval=true)
default CompletableFuture<Void> append​(Object item,
                                       EntryScope scope)
        Deprecated, for removal: This API element is subject to removal in a future version.
        Use apply(ListOperation) with ListOperation.insertLast(Object).withScope(EntryScope)
        Appends the given item to the list with the given scope.

        The given item must be JSON-serializable so it can be sent over the network when Collaboration Engine is hosted in a standalone server.

        The scope parameter specifies the scope of the entry, which is either one of EntryScope.TOPIC to keep the entry in the list until explicitly removed, or EntryScope.CONNECTION to automatically remove the entry when the connection which put the entry is deactivated.

        Parameters:
        item - the item to append, not null
        scope - the scope of the entry, not null
        Returns:
        a completable future that is resolved when the item has been appended to the list
        Throws:
        JsonConversionException - if the given item isn't serializable as JSON string

      • subscribe

        Registration subscribe​(ListSubscriber subscriber)
        Subscribes to changes to this list. When subscribing, the subscriber will receive an event for each item already in the list.
        Parameters:
        subscriber - the subscriber to use, not null
        Returns:
        a handle that can be used for removing the subscription, not null

      • getConnection

        TopicConnection getConnection()
        Gets the topic connection which is used to propagate changes to this list.
        Returns:
        the topic connection used by this list, not null

      • getExpirationTimeout

        Optional<Duration> getExpirationTimeout()
        Gets the optional expiration timeout of this list. An empty Optional is returned if no timeout is set, which means the list is not cleared when there are no connected users to the related topic (this is the default).
        Specified by:
        getExpirationTimeout in interface HasExpirationTimeout
        Returns:
        the expiration timeout

      • setExpirationTimeout

        void setExpirationTimeout​(Duration expirationTimeout)
        Sets the expiration timeout of this list. If set, the list content is cleared when expirationTimeout has passed after the last connection to the topic this list belongs to is closed. If set to null, the timeout is cancelled.
        Specified by:
        setExpirationTimeout in interface HasExpirationTimeout
        Parameters:
        expirationTimeout - the expiration timeout