vaadin-framework/client/src/main/java/com/vaadin/client/communication/PushConnection.java

/*
 * Copyright 2000-2021 Vaadin Ltd.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */

package com.vaadin.client.communication;

import com.google.gwt.user.client.Command;
import com.vaadin.client.ApplicationConnection;
import com.vaadin.shared.ui.ui.UIState.PushConfigurationState;

import elemental.json.JsonObject;

/**
 * Represents the client-side endpoint of a bidirectional ("push") communication
 * channel. Can be used to send UIDL request messages to the server and to
 * receive UIDL messages from the server (either asynchronously or as a response
 * to a UIDL request.) Delegates the UIDL handling to the
 * {@link ApplicationConnection}.
 *
 * @author Vaadin Ltd
 * @since 7.1
 */
public interface PushConnection {

    /**
     * Two-phase construction to allow using GWT.create().
     *
     * @param connection
     *            The ApplicationConnection
     */
    public void init(ApplicationConnection connection,
            PushConfigurationState pushConfigurationState);

    /**
     * Pushes a message to the server. Will throw an exception if the connection
     * is not active (see {@link #isActive()}).
     * <p>
     * Implementation detail: If the push connection is not connected and the
     * message can thus not be sent, the implementation must call
     * {@link ConnectionStateHandler#pushNotConnected(JsonObject)}, which will
     * retry the send later.
     * <p>
     * This method must not be called if the push connection is not
     * bidirectional (if {@link #isBidirectional()} returns false)
     *
     * @param payload
     *            the payload to push
     * @throws IllegalStateException
     *             if this connection is not active
     *
     * @see #isActive()
     */
    public void push(JsonObject payload);

    /**
     * Checks whether this push connection is in a state where it can push
     * messages to the server. A connection is active until
     * {@link #disconnect(Command)} has been called.
     *
     * @return <code>true</code> if this connection can accept new messages;
     *         <code>false</code> if this connection is disconnected or
     *         disconnecting.
     */
    public boolean isActive();

    /**
     * Closes the push connection. To ensure correct message delivery order, new
     * messages should not be sent using any other channel until it has been
     * confirmed that all messages pending for this connection have been
     * delivered. The provided command callback is invoked when messages can be
     * passed using some other communication channel.
     * <p>
     * After this method has been called, {@link #isActive()} returns
     * <code>false</code>. Calling this method for a connection that is no
     * longer active will throw an exception.
     *
     * @param command
     *            callback command invoked when the connection has been properly
     *            disconnected
     * @throws IllegalStateException
     *             if this connection is not active
     */
    public void disconnect(Command command);

    /**
     * Returns a human readable string representation of the transport type used
     * to communicate with the server.
     *
     * @since 7.1
     * @return A human readable string representation of the transport type
     */
    public String getTransportType();

    /**
     * Checks whether this push connection should be used for communication in
     * both directions or if an XHR should be used for client to server
     * communication.
     *
     * A bidirectional push connection must be able to reliably inform about its
     * connection state.
     *
     * @since 7.6
     * @return true if the push connection should be used for messages in both
     *         directions, false if it should only be used for server to client
     *         messages
     */
    public boolean isBidirectional();

}