/**
 * Copyright 2009 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.CorruptionDetail;
import org.waveprotocol.wave.model.id.IdFilter;
import org.waveprotocol.wave.model.id.WaveletId;
import org.waveprotocol.wave.model.version.HashedVersion;
import org.waveprotocol.wave.model.wave.ParticipantId;
import org.waveprotocol.wave.model.wave.data.ObservableWaveletData;

import java.util.Collection;

/**
 * Multiplexes several {@link OperationChannel operation channels} together. The
 * lifecycle of this multiplexer is simply
 * {@link #open(Listener, IdFilter, Collection)} followed by {@link #close()}.
 *
 */
public interface OperationChannelMultiplexer {
  /**
   * Listener for handling multiplexer events.
   */
  interface Listener {
    /**
     * Notifies this listener that a new channel has been established. The new
     * channel, based on the snapshot given here, is ready to be used
     * immediately.
     *
     * @param channel new channel
     * @param snapshot initial state of the wavelet on the new channel
     * @param accessibility initial accessibility of the new wavelet
     */
    void onOperationChannelCreated(OperationChannel channel, ObservableWaveletData snapshot,
        Accessibility accessibility);

    /**
     * Notifies this listener that an existing channel has been destroyed. The dropped
     * channel is typically likely to be replaced by a new one.
     *
     * @param channel destroyed channel
     * @param waveletId the id of the wavelet serviced over this channel
     */
    void onOperationChannelRemoved(OperationChannel channel, WaveletId waveletId);

    /**
     * Notifies this listener that the initial open has finished.
     *
     * The "initial open" is defined as the point after which the channel
     * listener has been notified of all operation channels for some "initial
     * set" of wavelets as decided by the server. Note that the channel listener
     * may also be notified of other channels, interleaved amongst the channels
     * for the initial set, before {@link #onOpenFinished()} is called.
     */
    void onOpenFinished();

    /**
     * Notifies this listener that the multiplexer has failed. This may occur
     * before or after any channels are created, before or after
     * {@link #onOpenFinished()}.
     *
     * No further messages will be received by any callback or operation channel
     * after this message.
     */
    void onFailed(CorruptionDetail detail);
  }

  /**
   * Information required to open a wavelet at a known state.
   */
  public static final class KnownWavelet {
    /** Wavelet data. May not be null. */
    public final ObservableWaveletData snapshot;

    /** Last committed version of wavelet. May not be null. */
    public final HashedVersion committedVersion;

    /** The wavelet's accessibility to the user. May not be null. */
    public final Accessibility accessibility;

    public KnownWavelet(ObservableWaveletData snapshot, HashedVersion committedVersion,
        Accessibility accessibility) {
      this.snapshot = snapshot;
      this.committedVersion = committedVersion;
      this.accessibility = accessibility;
    }
  }

  /**
   * Opens this multiplexer. After it becomes open, operation channels will be
   * passed to the {@code muxListener} as they come into existence. The listener
   * may be notified as part of this call, or afterwards.
   *
   * @param muxListener listener for multiplexer events
   * @param waveletFilter filter specifying the wavelets to open
   * @param knownWaveletSnapshots wavelet channels already known about, a
   *        channel will be immediately opened for each known wavelet
   */
  public void open(Listener muxListener, IdFilter waveletFilter,
      Collection<KnownWavelet> knownWaveletSnapshots);

  /**
   * Opens this multiplexer with no known wavelets.
   *
   * @see #open(Listener, IdFilter, Collection)
   */
  public void open(Listener muxListener, IdFilter waveletFilter);

  /**
   * Closes this multiplexer. The channel listener will no longer be notified of
   * new channels, and no more operations will be received on existing channels.
   * The behavior of requests to create new channels, or the submission of
   * operations to existing channels, is undefined.
   */
  public void close();

  /**
   * Creates a new operation channel.  The listener will be notified of the new
   * channel during this method.
   *
   * @param waveletId wavelet id for the new operation channel
   * @param creator address of the wavelet creator
   */
  public void createOperationChannel(WaveletId waveletId, ParticipantId creator);
}