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

import org.waveprotocol.wave.model.document.indexed.LocationMapper;
import org.waveprotocol.wave.model.document.operation.DocInitialization;

/**
 * Document containing everything you need for a readable persistent view
 *
 * TODO(danilatos) Rename:
 *   ReadableDocument -> ReadableDomDocument
 *   RawDocument -> DomDocument
 *   ReadableWDocument -> ReadableDocument
 *
 * @author danilatos@google.com (Daniel Danilatos)
 */
public interface ReadableWDocument<N, E extends N, T extends N> extends
    ReadableDocument<N, E, T>,
    ReadableAnnotationSet<String>,
    LocationMapper<N> {

  /**
   * Returns the string representation of the document. Useful for equality
   * comparisons and some forms of serialization.
   *
   * Equivalent to {@code DocOpUtil.toXmlString(toInitialization())}
   *
   * NOTE(danilatos): Should we deprecate this method? Or does is it useful to
   * allow more efficient implementations than the definition above?
   *
   * @return Minimal normalized xml string.
   *
   *         WARNING(danilatos): Do not use this for debugging or logging
   *         purposes. Instead, use {@link #toDebugString()}
   */
  String toXmlString();

  /**
   * Returns a debug representation of the document. The format is not stable.
   * It is not useful for equality comparisons. It is useful for debugging and
   * logging. It is safe to call even if the document is potentially corrupted.
   *
   * If a document is based on an inner ReadableWDocument, it should delegate
   * to the inner instance for this method.
   *
   * Otherwise, a typical implementation might look something like
   * <code>
   * try {
   *   return DocOpUtil.toXmlString(DocOpScrub.maybeScrub(toInitialization()));
   * } catch (RuntimeException e) {
   *   return "#broken document#";
   * }
   * </code>
   *
   * @return A (scrubbed if necessary) representation of the document. Should
   *         not contain decorations e.g. reporting the implementation type.
   *         That way, adapter or wrapper classes can delegate without a large
   *         amount of cruft building up. {@link #toString()} should contain the
   *         extra decorations.
   */
  String toDebugString();

  /**
   * Returns a useful, scrubbed if necessary, representation of the document.
   * Should not be usable for equality comparisons. A typical implementation
   * might look like
   *
   * <code>
   * return "ImplName@" + Integer.toHexString(System.identityHashCode(this))
   *     + "[" + toDebugString() + "]";
   * </code>
   */
  @Override String toString();

  /**
   * @return this document represented as an initialization, suitable for
   *         {@link org.waveprotocol.wave.model.document.MutableDocument#hackConsume(org.waveprotocol.wave.model.document.operation.Nindo)
   *         copying} this document's content into another document.
   */
  DocInitialization toInitialization();
}