Package com.vaadin.collaborationengine

Class CollaborationEngine

java.lang.Object
com.vaadin.collaborationengine.CollaborationEngine
public class CollaborationEngine extends Object
CollaborationEngine is an API for creating collaborative experiences in Vaadin applications. It's used by sending and subscribing to changes between collaborators via collaboration topics.

Use getInstance() to get a reference to the singleton object in cases where Vaadin's thread locals are defined (such as in UI code invoked by the framework). In other circumstances, an instance can be found as an attribute in the runtime context (typically ServletContext) using the fully qualified class name of this class as the attribute name. That instance will only be available after explicitly calling configure(VaadinService, CollaborationEngineConfiguration) during startup or calling getInstance() at least once.

Since:
1.0
Author:
Vaadin Ltd

  • Method Details

    • getInstance

      public static CollaborationEngine getInstance()
      Gets the CollaborationEngine instance from the current VaadinService.

      Situations without a current VaadinService can also find the corresponding instance by looking it up from the runtime context (such as ServletContext) using CollaborationEngine.class.getName() as the attribute name. That instance will only be available after explicitly calling configure(VaadinService, CollaborationEngineConfiguration) during startup or calling getInstance() at least once.

      Returns:
      the CollaborationEngine instance
      Since:
      1.0

    • getInstance

      public static CollaborationEngine getInstance(VaadinService vaadinService)
      Gets the CollaborationEngine instance from the provided VaadinService.
      Returns:
      the CollaborationEngine instance
      Since:
      3.0

    • configure

      public static CollaborationEngine configure(VaadinService vaadinService, CollaborationEngineConfiguration configuration)
      Sets the configuration for the Collaboration Engine associated with the given Vaadin service. This configuration is required when running in production mode. It can be set only once.

      You should register a VaadinServiceInitListener where you call this method with the service returned by ServiceInitEvent.getSource().

      Parameters:
      vaadinService - the Vaadin service for which to configure the Collaboration Engine
      configuration - the configuration to provide for the Collaboration Engine
      Returns:
      the configured Collaboration Engine instance
      Since:
      3.0

    • openTopicConnection

      public TopicConnectionRegistration openTopicConnection(Component component, String topicId, UserInfo localUser, SerializableFunction<TopicConnection,Registration> connectionActivationCallback)
      Opens a connection to the collaboration topic with the provided id based on a component instance. If the topic with the provided id does not exist yet, it's created on demand.
      Parameters:
      component - the component which hold UI access, not null
      topicId - the id of the topic to connect to, not null
      localUser - the user who is related to the topic connection, a SystemUserInfo can be used for non-interaction threads. Not null.
      connectionActivationCallback - the callback to be executed when a connection is activated, not null
      Returns:
      the handle that can be used for configuring or closing the connection
      Since:
      1.0

    • openTopicConnection

      public TopicConnectionRegistration openTopicConnection(ConnectionContext context, String topicId, UserInfo localUser, SerializableFunction<TopicConnection,Registration> connectionActivationCallback)
      Opens a connection to the collaboration topic with the provided id based on a generic context definition. If the topic with the provided id does not exist yet, it's created on demand.
      Parameters:
      context - context for the connection
      topicId - the id of the topic to connect to, not null
      localUser - the user who is related to the topic connection, a SystemUserInfo can be used for non-interaction threads. Not null.
      connectionActivationCallback - the callback to be executed when a connection is activated, not null
      Returns:
      the handle that can be used for configuring or closing the connection
      Since:
      1.0

    • requestAccess

      public void requestAccess(UserInfo user, Consumer<AccessResponse> requestCallback)
      Requests access for a user to Collaboration Engine. The provided callback will be invoked with a response that tells whether the access is granted.

      This method can be used to check if the user has access to the Collaboration Engine, e.g. if the license is not expired and there is quota for that user; depending on the response, it's then possible to adapt the UI enabling or disabling collaboration features.

      To avoid calling this method multiple times per user, it is suggested to cache the result during the login process (e.g. in the session).

      In the callback, you can check from the response whether the user has access or not with the AccessResponse.hasAccess() method. It returns true if access has been granted for the user.

      The current UI is accessed to run the callback, which means that UI updates in the callback are pushed to the client in real-time. Because of depending on the current UI, the method can be called only in the request processing thread, or it will throw.

      Parameters:
      user - the user requesting access
      requestCallback - the callback to accept the response
      Since:
      3.0

    • requestAccess

      public void requestAccess(ConnectionContext context, UserInfo user, Consumer<AccessResponse> requestCallback)
      Requests access for a user to Collaboration Engine. The provided callback will be invoked with a response that tells whether the access is granted.

      This method can be used to check if the user has access to the Collaboration Engine, e.g. if the license is not expired and there is quota for that user; depending on the response, it's then possible to adapt the UI enabling or disabling collaboration features.

      To avoid calling this method multiple times per user, it is suggested to cache the result during the login process (e.g. in the session).

      In the callback, you can check from the response whether the user has access or not with the AccessResponse.hasAccess() method. It returns true if access has been granted for the user.

      Parameters:
      context - context for the connection
      user - the user requesting access
      requestCallback - the callback to accept the response
      Since:
      3.0

    • getUserColorIndex

      public int getUserColorIndex(UserInfo userInfo)
      Gets the color index of a user if different to -1, or let Collaboration Engine provide one. If the color index for a user id does not exist yet, it's created on demand based on the user id.
      Parameters:
      userInfo - user info
      Returns:
      the color index
      Since:
      3.1

    • getSystemContext

      public SystemConnectionContext getSystemContext()
      Gets a system connection context for this collaboration engine instance. The system connection context can be used when Collaboration Engine is used in situations that aren't directly associated with a UI, such as from a background thread or when integrating with external services.
      Returns:
      a system connection context instance, not null