Collaboration Engine 1.0 is a Java library that enables real-time collaboration in Vaadin applications. The main use case for this release is editing a form together. You can find more information about the product and the detailed documentation in https://vaadin.com/collaboration.

Share Data in Topics

Collaboration Engine 1.0 introduces the concept of topics. A topic is like a chat room, where data is shared among the people in the same room. To send and receive updates between users, they must connect to the same topic. All Collaboration Engine APIs require providing the unique string identifier of the used topic.

See Who is Present in a View – CollaborationAvatarGroup

The CollaborationAvatarGroup component enables the users to see the avatars of other active users.

UserInfo localUser = new UserInfo(userId, name, imageUrl);
CollaborationAvatarGroup avatarGroup = new CollaborationAvatarGroup(
        localUser, "topic-id");
layout.add(avatarGroup);

When the avatar group becomes attached, the user's avatar is added for all users who are connected to the same topic. The user name and image URL provided in the UserInfo object are used for rendering the avatar.

Edit a Form Together – CollaborationBinder

CollaborationBinder enhances Vaadin's regular Binder API. It enables collaboration with the field components by propagating field values in real time between the users who are connected to the same topic. Also, it provides the field-highlight feature, which indicates when another user is editing a field.

TextField nameField = new TextField("Name");
DatePicker dateOfBirthField = new DatePicker("Date of birth");

UserInfo localUser = new UserInfo(userId, name);
CollaborationBinder<Person> binder = new CollaborationBinder<>(
        Person.class, localUser);

binder.forField(nameField).bind("name");
binder.forField(dateOfBirthField).bind("dateOfBirth");

binder.setTopic("person/" + person.getId(), () -> person);

Note: Collaboration Engine stores all data in JSON format, which causes some limitations. In some cases you need to provide additional type information or implement custom serialization logic. There's more information about that in the documentation.

Build Custom Collaboration Features With the Low-Level API

At the lower abstraction level, you can connect to the topics in Collaboration Engine and propagate changes through CollaborationMap data structures. You can use put and replace to update the key-value pairs in the maps, and use subscribe to react to changes coming from other users.

Paragraph paragraph = new Paragraph();
CollaborationEngine.getInstance().openTopicConnection(paragraph,
        "topic-id", localUser, topicConnection -> {
            CollaborationMap map = topicConnection
                    .getNamedMap("map-id");
            map.subscribe(
                    e -> paragraph.setText(e.getValue(String.class)));
            map.put("key", "value");
            return null;
        });

The high-level features CollaborationAvatarGroup and CollaborationBinder are built on top of these low-level CollaborationEngine and CollaborationMap APIs.

Limitations

These are some of the limitations in version 1.0 that will be addressed in future releases:

• Server clusters are not supported. Collaboration Engine 1.0 is a library that runs inside your application server. Because of this, users that are connected to different servers in a cluster can't collaborate together.
• TypeScript view are not supported. Collaboration Engine 1.0 has only Java API.
• CollaborationBinder can't set automatic validators based on JSR-303 Bean Validation annotations, like BeanValidationBinder does.
• The low-level API has only the map data structure. CollaborationList is planned for later, in order to support add and remove operations without a complex compare-and-set process. Also, nested CollaborationMaps and CollaborationLists are yet to be supported.