/*******************************************************************************
 * Copyright (c) 2014, 2017 1C-Soft LLC and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     Vladimir Piskarev (1C) - initial API and implementation
 *******************************************************************************/
package org.eclipse.handly.buffer;

import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.handly.context.IContext;
import org.eclipse.handly.snapshot.ISnapshot;
import org.eclipse.handly.snapshot.ISnapshotProvider;
import org.eclipse.handly.snapshot.StaleSnapshotException;
import org.eclipse.handly.util.IReferenceCountable;
import org.eclipse.jface.text.IDocument;

/**
 * Represents a potentially shared buffer. A buffer contains the text contents
 * of a resource. The contents may be in the process of being edited, differing
 * from the actual contents of the underlying resource.
 * <p>
 * Clients can take a snapshot of the buffer, construct an edit tree based on
 * the snapshot, and apply the change back to the buffer. Note that an update
 * conflict may occur if the buffer's contents have changed since the inception
 * of the base snapshot.
 * </p>
 * <p>
 * When finished, clients must explicitly release their ownership of the buffer.
 * Clients that don't own the buffer must not access it. Attempting that may
 * result in unspecified behavior.
 * </p>
 * <p>
 * Buffers are generally designed to be safe for use by multiple threads.
 * Each buffer implementation is expected to clearly document thread-safety
 * guarantees it provides.
 * </p>
 */
public interface IBuffer
    extends ISnapshotProvider, IReferenceCountable
{
    /**
     * Takes a snapshot of the buffer.
     * <p>
     * Note that the taken snapshot may immediately become stale or expire.
     * </p>
     *
     * @return the buffer's snapshot (never <code>null</code>)
     */
    ISnapshot getSnapshot();

    /**
     * Applies the given change to the buffer. Note that an update conflict
     * may occur if the buffer's contents have changed since the inception
     * of the snapshot on which the change is based. In that case, a
     * {@link StaleSnapshotException} is thrown.
     *
     * @param change a buffer change (not <code>null</code>)
     * @param monitor a progress monitor, or <code>null</code>
     *  if progress reporting is not desired. The caller must not rely on
     *  {@link IProgressMonitor#done()} having been called by the receiver
     * @return undo change, if requested. Otherwise, <code>null</code>
     * @throws StaleSnapshotException if the buffer's contents have changed
     *  since the inception of the snapshot on which the change is based
     * @throws CoreException if the change's edit tree isn't in a valid state,
     *  or if one of the edits in the tree can't be executed, or (if the save
     *  mode of the change requested buffer save) in case the buffer could not
     *  be saved successfully
     */
    IBufferChange applyChange(IBufferChange change, IProgressMonitor monitor)
        throws CoreException;

    /**
     * Saves the buffer. It is up to the implementors of this method to decide
     * what saving means. Typically, the contents of an underlying resource
     * is changed to the contents of the buffer.
     *
     * @param context the operation context (not <code>null</code>)
     * @param monitor a progress monitor, or <code>null</code>
     *  if progress reporting is not desired. The caller must not rely on
     *  {@link IProgressMonitor#done()} having been called by the receiver
     * @throws CoreException if the buffer could not be saved successfully
     */
    void save(IContext context, IProgressMonitor monitor) throws CoreException;

    /**
     * Returns whether the buffer has been modified since the last time
     * it was opened or saved.
     *
     * @return <code>true</code> if the buffer has unsaved changes,
     *  <code>false</code> otherwise
     */
    boolean isDirty();

    /**
     * Returns the underlying document of this buffer.
     * <p>
     * Note that the relationship between a buffer and its document does not
     * change over the lifetime of a buffer.
     * </p>
     *
     * @return the buffer's underlying document (never <code>null</code>)
     */
    IDocument getDocument();
}