Server Push

The server-client communication is done by default with a WebSocket connection if the browser and the server support it. If not, Vaadin will fall back to a method supported by the browser. Vaadin Push uses a custom build of the Atmosphere framework for client-server communication.

The server push support in Vaadin requires the separate Vaadin Push library. It is included in the installation package as vaadin-push.jar.

With Ivy, you can get it with the following declaration in the ivy.xml:

XML

In some servers, you may need to exlude a sl4j dependency as follows:

XML

            rev="&vaadin.version;" conf="default->default">
    <exclude org="org.slf4j" name="slf4j-api"/>
</dependency>

Pay note that the Atmosphere library is a bundle, so if you retrieve the libraries with Ant, for example, you need to retrieve type=”jar,bundle”.

Retrieving with Maven

In Maven, you can get the push library with the following dependency in the POM:

XML

<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-push</artifactId>
    <version>${vaadin.version}</version>
</dependency>

To enable server push, you need to define the push mode either in the deployment descriptor or with the @Push annotation for the UI.

You can use server push in two modes: automatic and manual. The automatic mode pushes changes to the browser automatically after access() finishes. With the manual mode, you can do the push explicitly with push(), which allows more flexibility.

Sever push can use several transports: WebSockets, long polling, or combined WebSockets+XHR. WebSockets is the default transport.

The @Push annotation

You can enable server push for a UI with the @Push annotation as follows. It defaults to automatic mode ( PushMode.AUTOMATIC).

@Push
public class PushyUI extends UI {

To enable manual mode, you need to give the PushMode.MANUAL parameter as follows:

Java

@Push(PushMode.MANUAL)
public class PushyUI extends UI {

To use the long polling transport, you need to set the transport parameter as Transport.LONG_POLLING as follows:

Java

You can enable the server push and define the push mode also in the servlet configuration with the pushmode parameter for the servlet in the web.xml deployment descriptor. If you use a Servlet 3.0 compatible server, you also want to enable asynchronous processing with the async-supported parameter. Note the use of Servlet 3.0 schema in the deployment descriptor.

<?xml version="1.0" encoding="UTF-8"?>
<web-app
  id="WebApp_ID" version="3.0"
  xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <servlet>
    <servlet-name>Pushy UI</servlet-name>
    <servlet-class>
        com.vaadin.server.VaadinServlet</servlet-class>
    <init-param>
        <param-name>UI</param-name>
        <param-value>com.example.my.PushyUI</param-value>
    </init-param>
    <!-- Enable server push -->
    <init-param>
      <param-name>pushmode</param-name>
      <param-value>automatic</param-value>
    </init-param>
    <async-supported>true</async-supported>
</web-app>

Making changes to a UI object from another thread and pushing them to the browser requires locking the user session when accessing the UI. Otherwise, the UI update done from another thread could conflict with a regular event-driven update and cause either data corruption or deadlocks. Because of this, you may only access an UI using the access() method, which locks the session to prevent conflicts. It takes a Runnable which it executes as its parameter.

For example:

Java

ui.access(new Runnable() {
    @Override
    public void run() {
        series.add(new DataSeriesItem(x, y));
    }
});

In Java 8, where a parameterless lambda expression creates a runnable, you could simply write:

Java

ui.access(() ->

If the push mode is manual, you need to push the pending UI changes to the browser explicitly with the push() method.

Java

ui.access(new Runnable() {
    @Override
    public void run() {
        series.add(new DataSeriesItem(x, y));
        ui.push();
    }
});

Below is a complete example of a case where we make UI changes from another thread.

See the .

When sharing data between UIs or user sessions, you need to consider the message-passing mechanism more carefully, as explained next.

Broadcasting messages to be pushed to UIs in other user sessions requires having some sort of message-passing mechanism that sends the messages to all UIs that register as recipients. As processing server requests for different UIs is done concurrently in different threads of the application server, locking the threads properly is very important to avoid deadlock situations.

The Broadcaster

The standard pattern for sending messages to other users is to use a broadcaster singleton that registers the UIs and broadcasts messages to them safely. To avoid deadlocks, it is recommended that the messages should be sent through a message queue in a separate thread. Using a Java ExecutorService running in a single thread is usually the easiest and safest way.

Java

public class Broadcaster implements Serializable {
    static ExecutorService executorService =
        Executors.newSingleThreadExecutor();
    public interface BroadcastListener {
        void receiveBroadcast(String message);
    }
    private static LinkedList<BroadcastListener> listeners =
        new LinkedList<BroadcastListener>();
    public static synchronized void register(
            BroadcastListener listener) {
        listeners.add(listener);
    }
    public static synchronized void unregister(
            BroadcastListener listener) {
        listeners.remove(listener);
    }
    public static synchronized void broadcast(
            final String message) {
        for (final BroadcastListener listener: listeners)
            executorService.execute(new Runnable() {
                @Override
                public void run() {
                    listener.receiveBroadcast(message);
                }
            });
    }

See the .

In Java 8, you could use lambda expressions for the listeners instead of the interface, and a parameterless expression to create the runnable:

Java

for (final Consumer<String> listener: listeners)
    executorService.execute(() ->
            listener.accept(message));

See the on-line example.

The receivers need to implement the receiver interface and register to the broadcaster to receive the broadcasts. A listener should be unregistered when the UI expires. When updating the UI in a receiver, it should be done safely as described earlier, by executing the update through the access() method of the UI.

Java

@Push
       implements Broadcaster.BroadcastListener {
    VerticalLayout messages = new VerticalLayout();
    @Override
    protected void init(VaadinRequest request) {
        ... build the UI ...
        // Register to receive broadcasts
        Broadcaster.register(this);
    }
    // Must also unregister when the UI expires
    @Override
    public void detach() {
        Broadcaster.unregister(this);
        super.detach();
    }
    @Override
    public void receiveBroadcast(final String message) {
        // Must lock the session to execute logic safely
        access(new Runnable() {
            @Override
            public void run() {
                // Show it somehow
                messages.addComponent(new Label(message));
            }
        });
    }
}

See the .

Sending Broadcasts

To send broadcasts with a broadcaster singleton, such as the one described above, you would only need to call the broadcast() method as follows.

final TextField input = new TextField();
sendBar.addComponent(input);
Button send = new Button("Send");
send.addClickListener(new ClickListener() {
    @Override
    public void buttonClick(ClickEvent event) {
        // Broadcast the message
        Broadcaster.broadcast(input.getValue());
        input.setValue("");

See the .