3.1.0.alpha3

Expiration Timeout for CollaborationBinder

You can now configure CollaborationBinder to discard any changes to the fields after a set duration of inactivity.

For example:

binder.setExpirationTimeout(Duration.ofMinutes(15));

The example will cause Collaboration Engine to discard the edited field values in the topic it's connected to, if no users have connected to the topic for the last 15 minutes. Collaboration Engine discards the data when a new user joins the topic. It loads the data from the bean supplier instead, providing the user with a fresh copy from, e.g. the database.

This is a convenience API to the low-level functionality, "Remove Unsaved Edits After a Configurable Duration of Inactivity," introduced in 3.1.0.alpha1.

Other Changes

• Calling UserInfo.setColorIndex(-1) now means that the Collaboration Engine should manage the user's color index and keep it consistent across topics and components. -1 is now the default value for colorIndex.
• CollaborationEngine has now a public method, getUserColorIndex(UserInfo userInfo). It simply returns the user's color index it is explicitly defined. Otherwise, when the color index is -1, it will assign a color index automatically. It is useful when you build custom collaborative experiences and want to user colors which are consistent with other features, like CollaborationBinder and CollaborationAvatarGroup.
• Changes in 3.0.1 have been added to 3.1.0.alpha3.

Install Instructions

We release pre-releases in a separate maven repository, to not pollute maven central. If you want to test out the prerelease, you will have to add the repository and dependency to your pom.xml. The version is compatible with Vaadin 14, 18 and 19 projects.

pom.xml:

<project ..>
    ..
    <repositories>
        ..
        <repository>
            <id>vaadin-prereleases</id>
            <url>https://maven.vaadin.com/vaadin-prereleases</url>
        </repository>
    </repositories>
    ..
    <dependencies>
        <dependency>
            <groupId>com.vaadin</groupId>
            <artifactId>collaboration-engine</artifactId>
            <version>3.1.0.alpha3</version>
        </dependency>
    </dependencies>
    ..
</project>

3.1.0.alpha2

Prototype of a Real-Time Conversation Component

Collaboration Engine 3.1 aims to introduce the Discuss module. It enables end-users to hold real-time discussions with each other, leave comments and keep track of recent edits to any component or view.

3.1.0.alpha1 introduced a new component in the the package, named ExampleComponent. This is a prototype for the upcoming Discuss module, and the name of the component will change when we build the actual component. That work has already started.

Now, 3.1.0.alpha2 has added CollaborationExampleComponent that combines ExampleComponent and Collaboration Engine. Like with CollaborationAvatarGroup and CollaborationBinder, you don't have to take care of the logic yourself. Give it the info of the user and a topic ID, and you are good to go.

UserInfo user = new UserInfo(userId, name, avatar);
CollaborationExampleComponent chat = new CollaborationExampleComponent(user, "generalChat");
add(chat);

Here is a full copy-pastable view that you can add to a Vaadin 14 project to test out the feature:

package com.example.application.views.helloalpha;

import com.vaadin.collaborationengine.CollaborationExampleComponent;
import com.vaadin.collaborationengine.UserInfo;
import com.vaadin.flow.component.button.Button;
import com.vaadin.flow.component.orderedlayout.HorizontalLayout;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.component.page.Push;
import com.vaadin.flow.component.textfield.IntegerField;
import com.vaadin.flow.component.textfield.TextField;
import com.vaadin.flow.router.PageTitle;
import com.vaadin.flow.router.Route;

@Push
@Route("hello")
@PageTitle("Hello Alpha")
public class HelloAlphaView extends VerticalLayout {

    public HelloAlphaView() {
        TextField nameField = new TextField("Your name");
        IntegerField avatarField = new IntegerField("Avatar number");
        Button submit = new Button("Engage!", e -> {
            String name = nameField.getValue();
            String avatar = "https://i.pravatar.cc/150?img="
                    + avatarField.getValue();
            UserInfo user = new UserInfo(name, name, avatar);
            CollaborationExampleComponent chat = new CollaborationExampleComponent(
                    user, "generalChat");
            removeAll();
            add(chat);
        });

        HorizontalLayout controls = new HorizontalLayout(nameField, avatarField,
                submit);
        controls.setAlignItems(Alignment.END);
        add(controls);
    }

}

Note that ExampleComponent and CollaborationExampleComponent are early prototypes which will be removed before a stable release!

Install Instructions

We release pre-releases in a separate maven repository, to not pollute maven central. If you want to test out the prerelease, you will have to add the repository and dependency to your pom.xml. The version is compatible with Vaadin 14, 18 and 19 projects.

pom.xml:

<project ..>
    ..
    <repositories>
        ..
        <repository>
            <id>vaadin-prereleases</id>
            <url>https://maven.vaadin.com/vaadin-prereleases</url>
        </repository>
    </repositories>
    ..
    <dependencies>
        <dependency>
            <groupId>com.vaadin</groupId>
            <artifactId>collaboration-engine</artifactId>
            <version>3.1.0.alpha2</version>
        </dependency>
    </dependencies>
    ..
</project>

3.1.0.alpha1

Remove Unsaved Edits After a Configurable Duration of Inactivity

You can now define an expiration timeout for maps stored in Collaboration Engine. For example, when using CollaborationBinder, if you wish that collaborative edits should be deleted when nobody has been present in the form for the last 15 minutes, and want to instead present the state of the work item as it is in the database, then you can do the following:

CollaborationEngine.getInstance().openTopicConnection(this, "topic-id",
        user, topicConnection -> {
            topicConnection
                    .getNamedMap(CollaborationBinder.class.getName())
                    .setExpirationTimeout(Duration.ofMinutes(15));
            return null;
        });

When the next user enters the form, the supplied bean provided by CollaborationBinder.setTopic(String topicId, SerializableSupplier<BEAN> initialBeanSupplier) will be used instead of the stored version. We will add a convenience method for easier access to CollaborationBinder in an upcoming release. For more details, see #23.

Configure Collaboration Engine with a Bean

You can now configure Collaboration Engine by providing a Spring or CDI bean implementing CollaborationEngineConfiguration. Within the configuration object, you can now also provide the data directory within the configuration object.

@SpringBootApplication
public class Application {
    public static void main(String... args) {
        SpringApplication.run(Application.class, args);
    }

    @Bean
    public CollaborationEngineConfiguration ceConfigBean() {
        CollaborationEngineConfiguration configuration = new CollaborationEngineConfiguration(
                licenseEvent -> {
                    // See "Notifications for Updating the License" in "Setting Up for Production" documentation

                });
        configuration.setDataDir("/Users/steve/vaadin/collaboration-engine/");
        return configuration;
    }
}

Sneak Peek of Upcoming Discuss Module

We are building our next features to Collaboration Engine, namely the discuss module. It enables users to hold real-time discussions with each other, leave comments and keep track of recent edits to any component or view.

In this first alpha release, we included a temporary UI component, called ExampleComponent. This is an initial version of the UI component where users can chat with each other. Note that this component and the associated files will be removed in a future 3.1.0.alpha release and replaced with a proper implementation. The name of the component will also change. This release enables us to start building a Collaboration Engine integration for the upcoming component as well as receive early feedback on the direction that we are taking. Next up we will add a Collaboration Engine version of the component, where you can attach the component to a topic, and it will automatically populate and store the messages.

Please share your thoughts and wishes either as issues or discussions here at GitHub!

Vaadin Collaboration Engine 3.0.1

Changes Since 3.0.0

• Removed the Vaadin BOM, now the Flow dependencies are scoped as provided.
• UserInfo can now be created outside the UI thread.

For what is new in 3.0.0, see 3.0.0 Release Notes.

3.0.0

Configuration API and License Events

When running in production mode, Collaboration Engine now needs to be configured using a configuration object with a handler for license events: with these events, you'll know when it's time to renew the license.

This is a new feature introduced to be notified of events occurring during the license lifecycle, e.g. when the license is expired or when the end-user quota has entered the grace period. The handler can then be used for example to forward these events via e-mail or to a monitoring application to be alerted about the current status of the license.

The configuration object should be set in a VaadinServiceInitListener, e.g.

@SpringComponent
public class MyVaadinInitListener implements VaadinServiceInitListener {
    
    @Override
    public void serviceInit(ServiceInitEvent serviceEvent) {
        VaadinService service = serviceEvent.getSource();

        LicenseEventHandler licenseEventHandler = licenseEvent -> {
            // handle the event
        };

        CollaborationEngineConfiguration configuration = new CollaborationEngineConfiguration(licenseEventHandler);
        CollaborationEngine.configure(service, configuration);
    }
}

This is a breaking change because it's now mandatory to set the configuration in production mode.

Other Noteworthy Changes Since 2.0

• Collaboration Engine now has a requestAccess method that can be used to check if the user has access (i.e. there is quota for the user and the license isn't expired) and act accordingly, e.g. enabling/disabling collaboration features in the UI.
• CollaborationAvatarGroup now shows the current user avatar even when quota is exceeded or license has expired.
• CollaborationBinder now works as a normal Binder when quota is exceeded or license has expired.
• Fix OSGi compatibility
• Fix field highlight (indicator of focused user with CollaborationBinder) when user ids contain spaces or some special characters (e.g. '@' when using email address as the id)

3.0.0.beta2

Configuration API and License Events

When running in production mode, Collaboration Engine now needs to be configured using a configuration object with a handler for license events: with these events, you'll know when it's time to renew the license.

This is a new feature introduced to be notified of events occurring during the license lifecycle, e.g. when the license is expired or when the end-user quota has entered the grace period. The handler can then be used for example to forward these events via e-mail or to a monitoring application to be alerted about the current status of the license.

The configuration object should be set in a VaadinServiceInitListener, e.g.

@SpringComponent
public class MyVaadinInitListener implements VaadinServiceInitListener {
    
    @Override
    public void serviceInit(ServiceInitEvent serviceEvent) {
        VaadinService service = serviceEvent.getSource();

        LicenseEventHandler licenseEventHandler = licenseEvent -> {
            // handle the event
        };

        CollaborationEngineConfiguration configuration = new CollaborationEngineConfiguration(licenseEventHandler);
        CollaborationEngine.configure(service, configuration);
    }
}

This is a breaking change because it's now mandatory to set the configuration in production mode.

Other Noteworthy Changes

• Collaboration Engine now has a requestAccess method that can be used to check if the user has access (i.e. there is quota for the user and the license isn't expired) and act accordingly, e.g. enabling/disabling collaboration features in the UI.
• CollaborationAvatarGroup now shows the current user avatar even when quota is exceeded or license has expired.
• CollaborationBinder now works as a normal Binder when quota is exceeded or license has expired.

Changes Since 3.0.0.beta1

• Fix field highlight (indicator of focused user with CollaborationBinder) when user ids contain spaces or some special characters (e.g. '@' when using email address as the id)
• Log a warning when trying to use Collaboration Engine but access is denied due to exceeding usage limits

3.0.0.beta1

Configuration API and License Events

When running in production mode, Collaboration Engine now needs to be configured using a configuration object with a handler for license events: with these events, you'll know when it's time to renew the license.

This is a new feature introduced to be notified of events occurring during the license lifecycle, e.g. when the license is expired or when the end-user quota has entered the grace period. The handler can then be used for example to forward these events via e-mail or to a monitoring application to be alerted about the current status of the license.

The configuration object should be set in a VaadinServiceInitListener, e.g.

@SpringComponent
public class MyVaadinInitListener implements VaadinServiceInitListener {
    
    @Override
    public void serviceInit(ServiceInitEvent serviceEvent) {
        VaadinService service = serviceEvent.getSource();

        LicenseEventHandler licenseEventHandler = licenseEvent -> {
            // handle the event
        };

        CollaborationEngineConfiguration configuration = new CollaborationEngineConfiguration(licenseEventHandler);
        CollaborationEngine.configure(service, configuration);
    }
}

This is a breaking change because it's now mandatory to set the configuration in production mode.

Other Noteworthy Changes

• Collaboration Engine now has a requestAccess method that can be used to check if the user has access (i.e. there is quota for the user and the license isn't expired) and act accordingly, e.g. enabling/disabling collaboration features in the UI.
• CollaborationAvatarGroup now shows the current user avatar even when quota is exceeded or license has expired.
• CollaborationBinder now works as a normal Binder when quota is exceeded or license has expired.

2.0.0

License Checking and Self-Service Trialing

To help the users avoid violating the licensing terms of Collaboration Engine, the version 2.0 will not work in production without a valid license file provided by Vaadin. You can request a license by contacting Vaadin.

When you deploy your app into production, the server environment needs to have a dedicated directory used by Collaboration Engine, and the license file needs to be placed in that directory. The path to this directory needs to be configured by setting the vaadin.ce.dataDir system property. If the property is missing or a valid license file is not found in the configured directory, any usage of Collaboration Engine will throw an exception. This is a breaking change!

When you develop your app with Collaboration Engine in development mode, the license file is not needed. You will be able to download and trial the product on your own before buying a license for it.

Other Noteworthy Changes

• Fixed CollaborationAvatarGroup to not show duplicate avatars when the same user has opened the view in multiple browsers
• Fixed a potential race condition in Collaboration Engine internals

2.0.0.alpha1 – License Checking and Self-Service Trialing

To help the users avoid violating the licensing terms of Collaboration Engine, the version 2.0 will not work in production without a valid license file provided by Vaadin. You can request a license by contacting Vaadin.

When you deploy your app into production, the server environment needs to have a dedicated directory used by Collaboration Engine, and the license file needs to be placed in that directory. The path to this directory needs to be configured by setting the ce.dataDir system property.

When you develop your app with Collaboration Engine in development mode, the license file is not needed. You will be able to download and trial the product on your own before buying it (soon after 2.0 stable release).

1.0.0 – Edit a Form Together

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.