/**
 * 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.model.supplement;

import org.waveprotocol.wave.model.conversation.InboxState;
import org.waveprotocol.wave.model.id.WaveletId;
import org.waveprotocol.wave.model.util.ReadableStringMap;
import org.waveprotocol.wave.model.version.HashedVersion;

import java.util.Set;

/**
 * Exposes per-user state associated with a conversation.
 * Specifically,
 * <ul>
 *   <li>read/unread state;</li>
 *   <li>folder allocations; and</li>
 *   <li>inboxing setting.<li>
 * </ul>
 *
 * The inboxing state depends on the versions of each wavelet
 * (same as the read/unread state).
 * <ul>
 * <li>
 *   The state is {@link InboxState#INBOX} if {@link #isFollowed(boolean)}
 *   returns true and for at least one wavelet
 *   {@link #isArchived(WaveletId, int)} returns false for the current version
 *   of that wavelet.
 * </li>
 * <li>
 *   The state is {@link InboxState#ARCHIVE} if {@link #isFollowed(boolean)}
 *   returns true and and {@link #isArchived(WaveletId, int)} returns true
 *   for the current version of each wavelet on the wave.
 * </li>
 * <li>
 *   The state is {@link InboxState#MUTE} when {@link #isFollowed(boolean)}
 *   returns false.
 * </li>
 * </ul>
 *
 */
public interface ReadableSupplement {

  //
  // Thread State Concerns.
  //

  /**
   * Retrieves the state of a thread, such as collapsed or expanded.
   *
   * @param waveletId  id of the thread's wavelet
   * @param threadId   id of the thread to change
   * @return the state of the specified thread.
   */
  ThreadState getThreadState(WaveletId waveletId, String threadId);

  /**
   * Tests whether a blip is unread.
   *
   * @param waveletId
   * @param blipId
   * @param version
   * @return true if the blip is unread at the given version.
   */
  boolean isBlipUnread(WaveletId waveletId, String blipId, int version);

  /**
   * Tests whether the set of participants in a wavelet is unread.
   *
   * @param waveletId
   * @param version
   * @return true if the set of participants is unread at the given version.
   */
  boolean isParticipantsUnread(WaveletId waveletId, int version);

  /**
   * Tests whether a wavelet's tags document is unread.
   *
   * @param waveletId The ID of the wavelet to check whether it's tags are unread.
   * @param version The version of the wavelet's tags document.
   * @return True if the wavelet's tags document is unread.
   */
  boolean isTagsUnread(WaveletId waveletId, int version);

  /**
   * @param waveletId
   *
   * @return true if the set of participants has ever been read.
   */
  boolean haveParticipantsEverBeenRead(WaveletId waveletId);

  /**
   * @return the folders to which this wave has been assigned.
   */
  Set<Integer> getFolders();

  /**
   * @return whether the wavelet is archived at the given version.
   */
  boolean isArchived(WaveletId waveletId, int version);

  /**
   * @return seen version and signature proving the seen version of
   * the given conversational wavelet (or zero)
   */
  HashedVersion getSeenVersion(WaveletId waveletId);

  /**
   * @return notified version (or zero)
   */
  int getNotifiedVersion(WaveletId waveletId);

  /**
   * @return true if at least one wavelet has been recorded as being notified.
   */
  boolean hasNotifiedVersion();

  /**
   * @return true if at least one wavelet has been recorded as being seen.
   */
  boolean hasSeenVersion();

  /**
   * @return Unmodifiable set of WaveletIds that have been recorded as being
   * seen.
   */
  Set<WaveletId> getSeenWavelets();

  /**
   * @return whether the wave is being followed.
   */
  boolean isFollowed(boolean defaultFollowed);

  /**
   * Gets a wanted evaluation set for the given wavelet id.
   */
  WantedEvaluationSet getWantedEvaluationSet(WaveletId waveletId);

  /**
   * @return whether the wave has a pending notification.
   */
  boolean hasPendingNotification();

  /**
   * @param waveletId the wavelet to check for pending notification.
   * @return whether the wavelet has a pending notification.
   */
  boolean hasPendingNotification(WaveletId waveletId);

  /**
   * Returns the gadget state as a String-to-String map.
   *
   * @param gadgetId ID of the gadget that owns the state.
   * @return the gadget state as a String-to-String map.
   */
  public ReadableStringMap<String> getGadgetState(String gadgetId);
}