/**
 * Copyright 2008 Google Inc.
 *
 * 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 org.waveprotocol.wave.concurrencycontrol.channel;

import org.waveprotocol.wave.concurrencycontrol.common.ChannelException;
import org.waveprotocol.wave.model.id.IdFilter;
import org.waveprotocol.wave.model.id.WaveletId;
import org.waveprotocol.wave.model.operation.wave.TransformedWaveletDelta;
import org.waveprotocol.wave.model.operation.wave.WaveletDelta;
import org.waveprotocol.wave.model.version.HashedVersion;
import org.waveprotocol.wave.model.wave.data.ObservableWaveletData;

import java.util.List;
import java.util.Map;

/**
 * Encapsulates the WaveView rpcs as a channel.
 * Lifecycle:
 * ({@link #open(Listener, IdFilter, Map)} then {@link #close()}.
 *
 */
public interface ViewChannel {
  /**
   * Callback interface for asynchronous notification of connection events,
   * which corresponds to the following regular expression:
   * <pre>
   *   Connection = onConnected onUpdate* [onOpenFinished] onUpdate* [onFailure] onClosed
   * </pre>
   * Note that each event can only occur at most once.
   */
  interface Listener {
    /**
     * Notifies this listener that the channel is now connected, and deltas
     * can be submitted.
     */
    void onConnected();

    /**
     * Notifies this listener that the initial set of updates have been
     * received.
     */
    void onOpenFinished() throws ChannelException;

    /**
     * Notifies this listener that an exception has occurred. The ViewChannel is not
     * closed yet when this method is called, but it will be closed after this call.
     *
     * @param ex The exception that occured whilst handling responses from the server.
     */
    void onException(ChannelException ex);

    /**
     * Notifies this listener that the connection has terminated.
     *
     * Note: "terminated" is interpreted as client-side termination, either
     *   through a {@link #close() requested close} or through a failure.
     *   It does not necessarily mean that the server has acknowledge the
     *   channel closure.  Indeed, there may be update messages in transit
     *   both to and from the server.  It is up to a higher layer of the
     *   communication stack to deal with such outstanding messages.
     */
    void onClosed();

    /**
     * Notifies this listener of a snapshot on the stream.
     *
     * @param waveletId             id of the wavelet being updated
     * @param wavelet               optional update message (may be null)
     * @param lastCommittedVersion  optional committed version (may be null)
     * @param currentSignedVersion  optional current/latest version on the server
     */
    void onSnapshot(WaveletId waveletId, ObservableWaveletData wavelet,
        HashedVersion lastCommittedVersion,
        HashedVersion currentSignedVersion)
        throws ChannelException;

    /**
     * Notifies this listener of an update on the stream.
     *
     * @param waveletId             id of the wavelet being updated
     * @param waveletDeltas                optional deltas (may be empty)
     * @param lastCommittedVersion  optional committed version (may be null)
     * @param currentSignedVersion  optional current/latest version on the server
     */
    void onUpdate(WaveletId waveletId, List<TransformedWaveletDelta> waveletDeltas,
        HashedVersion lastCommittedVersion, HashedVersion currentSignedVersion)
        throws ChannelException;
  }

  /**
   * Opens this WaveView channel, requesting that, for some wavelets, only
   * deltas should be received.
   *
   * Can be called only once.
   *
   * @param viewListener     listener for connection lifecycle events and incoming updates
   * @param waveletFilter    filter specifying wavelets to open
   * @param knownWavelets    map of wavelet ids to lists of known
   *                         versions, from one of which deltas should be
   *                         streamed
   */
  void open(Listener viewListener, IdFilter waveletFilter,
      Map<WaveletId, List<HashedVersion>> knownWavelets);

  /**
   * Closes this WaveView channel.
   */
  void close();

  /**
   * Submits a delta on this channel.
   *
   * @param waveletId       id of the target wavelet
   * @param delta           delta to apply
   * @param callback        callback to notify of the submit response
   */
  void submitDelta(WaveletId waveletId, WaveletDelta delta, SubmitCallback callback);

  /**
   * @param waveletId The wavelet that we want to get debug info.
   * @return Debug string that details profile information regarding data being sent.
   */
  String debugGetProfilingInfo(WaveletId waveletId);
}