/**
 * 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.box.server.waveserver;

import com.google.common.base.Function;

import org.waveprotocol.box.server.frontend.CommittedWaveletSnapshot;
import org.waveprotocol.wave.federation.Proto.ProtocolAppliedWaveletDelta;
import org.waveprotocol.wave.model.id.WaveletName;
import org.waveprotocol.wave.model.operation.wave.TransformedWaveletDelta;
import org.waveprotocol.wave.model.version.HashedVersion;
import org.waveprotocol.wave.model.wave.ParticipantId;
import org.waveprotocol.wave.model.wave.data.ObservableWaveletData;
import org.waveprotocol.wave.model.wave.data.ReadableWaveletData;

import java.util.Collection;

/**
 * Interface for a container class for a Wavelet's current state as well as its
 * delta history. Local and remote wavelet interfaces inherit from this one.
 */
interface WaveletContainer {

  /**
   * Manufactures wavelet containers.
   *
   * @param <T> type manufactured by this factory.
   */
  interface Factory<T extends WaveletContainer> {
    /**
     * @return a new wavelet container with the given wavelet name
     */
    T create(WaveletNotificationSubscriber notifiee, WaveletName waveletName, String waveDomain);
  }

  /** Returns the name of the wavelet. */
  WaveletName getWaveletName();

  /** Returns a snapshot copy of the wavelet state. */
  ObservableWaveletData copyWaveletData() throws WaveletStateException;

  /** Returns a snapshot of the wavelet state, last committed version. */
  CommittedWaveletSnapshot getSnapshot() throws WaveletStateException;
  
  /**
   * Provides read access to the inner state of the {@link WaveletContainer}.
   * 
   * @param <T> the return type of the method.
   * @param function the function to apply on the {@link ReadableWaveletData}.
   * @return the output of the function.
   * @throws WaveletStateException if the wavelet is in an unsuitable state.
   */
  <T> T applyFunction(Function<ReadableWaveletData, T> function) throws WaveletStateException;

  /**
   * Retrieve the wavelet history of deltas applied to the wavelet.
   *
   * @param versionStart start version (inclusive), minimum 0.
   * @param versionEnd end version (exclusive).
   * @return serialised {@code ProtocolAppliedWaveletDelta}s in the range as
   *         requested, ordered by applied version.
   * @throws AccessControlException if {@code versionStart} or
   *         {@code versionEnd} are not in the wavelet history.
   * @throws WaveletStateException if the wavelet is in a state unsuitable for
   *         retrieving history.
   */
  Collection<ByteStringMessage<ProtocolAppliedWaveletDelta>> requestHistory(
      HashedVersion versionStart, HashedVersion versionEnd)
      throws AccessControlException, WaveletStateException;

  /**
   * Retrieve the wavelet history of deltas applied to the wavelet, with
   * additional safety check that
   *
   * @param versionStart start version (inclusive), minimum 0.
   * @param versionEnd end version (exclusive).
   * @return deltas in the range as requested, ordered by applied version.
   * @throws AccessControlException if {@code versionStart} or
   *         {@code versionEnd} are not in the wavelet history.
   * @throws WaveletStateException if the wavelet is in a state unsuitable for
   *         retrieving history.
   */
  Collection<TransformedWaveletDelta> requestTransformedHistory(HashedVersion versionStart,
      HashedVersion versionEnd) throws AccessControlException, WaveletStateException;

  /**
   * @param participantId id of participant attempting to gain access to
   *        wavelet, or null if the user isn't logged in.
   * @throws WaveletStateException if the wavelet is in a state unsuitable for
   *         checking permissions.
   * @return true if the participant is a participant on the wavelet or if the
   *         wavelet is empty or if a shared domain participant is participant
   *         on the wavelet.
   */
  boolean checkAccessPermission(ParticipantId participantId) throws WaveletStateException;

  /**
   * The Last Committed Version returns when the local or remote wave server
   * committed the wavelet.
   *
   * @throws WaveletStateException if the wavelet is in a state unsuitable for
   *         getting LCV.
   */
  HashedVersion getLastCommittedVersion() throws WaveletStateException;

  /**
   * @return true if the participant id is a current participant of the wavelet.
   *          Each invocation acquires and releases the lock.
   */
  boolean hasParticipant(ParticipantId participant) throws WaveletStateException;
  
  /**
   * @return the wavelet creator. This method doesn't acquire
   *         {@link WaveletContainer} lock since wavelet creator cannot change
   *         after wavelet creation and therefore it is save to concurrently
   *         read this property without lock.
   */
  ParticipantId getCreator();
  
  /**
   * This method doesn't acquire {@link WaveletContainer} lock since shared
   * domain participant cannot change and therefore it is safe to concurrently
   * read this property without lock.
   * 
   * @return the shared domain participant.
   */
  public ParticipantId getSharedDomainParticipant();

  /**
   * @return true if the wavelet is at version zero, i.e., has no delta history
   */
  boolean isEmpty() throws WaveletStateException;
  
}