/*******************************************************************************
 * Copyright (c) 2000, 2007 IBM Corporation and others.
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 * 
 * SPDX-License-Identifier: EPL-2.0
 *
 
 *******************************************************************************/
package org.eclipse.dltk.core;

import org.eclipse.core.runtime.IProgressMonitor;

/**
 * Common protocol for script elements that must be opened before they can be
 * navigated or modified. Opening a textual element (such as a compilation unit)
 * involves opening a buffer on its contents. While open, any changes to the
 * buffer can be reflected in the element's structure; see {@link #isConsistent}
 * and {@link #makeConsistent(IProgressMonitor)}.
 * <p>
 * To reduce complexity in clients, elements are automatically opened by the
 * script model as element properties are accessed. The script model maintains
 * an LRU cache of open elements, and automatically closes elements as they are
 * swapped out of the cache to make room for other elements. Elements with
 * unsaved changes are never removed from the cache, and thus, if the client
 * maintains many open elements with unsaved changes, the LRU cache can grow in
 * size (in this case the cache is not bounded). However, as elements are saved,
 * the cache will shrink back to its original bounded size.
 * </p>
 * <p>
 * To open an element, all openable parent elements must be open. The script
 * model automatically opens parent elements, as it automatically opens
 * elements. Opening an element may provide access to direct children and other
 * descendants, but does not automatically open any descendents which are
 * themselves {@link IOpenable}. For example, opening a compilation unit
 * provides access to all its constituent elements, but opening a package
 * fragment does not open all compilation units in the package fragment.
 * </p>
 * <p>
 * This interface is not intended to be implemented by clients.
 * </p>
 */
public interface IOpenable extends IModelElement {

	/**
	 * Closes this element and its buffer (if any). Closing an element which is
	 * not open has no effect.
	 * 
	 * <p>
	 * Note: although {@link #close} is exposed in the API, clients are not
	 * expected to open and close elements - the script model does this
	 * automatically as elements are accessed.
	 * 
	 * @exception ModelException
	 *                if an error occurs closing this element
	 */
	public void close() throws ModelException;

	/**
	 * Returns the buffer opened for this element, or <code>null</code> if
	 * this element does not have a buffer.
	 * 
	 * @exception ModelException
	 *                if this element does not exist or if an exception occurs
	 *                while accessing its corresponding resource.
	 * @return the buffer opened for this element, or <code>null</code> if
	 *         this element does not have a buffer
	 */
	public IBuffer getBuffer() throws ModelException;

	/**
	 * Returns <code>true</code> if this element is open and:
	 * <ul>
	 * <li>its buffer has unsaved changes, or
	 * <li>one of its descendants has unsaved changes, or
	 * <li>a working copy has been created on one of this element's children
	 * and has not yet destroyed
	 * </ul>
	 * 
	 * @exception ModelException
	 *                if this element does not exist or if an exception occurs
	 *                while accessing its corresponding resource.
	 * @return <code>true</code> if this element is open and:
	 *         <ul>
	 *         <li>its buffer has unsaved changes, or
	 *         <li>one of its descendants has unsaved changes, or
	 *         <li>a working copy has been created on one of this element's
	 *         children and has not yet destroyed
	 *         </ul>
	 */
	boolean hasUnsavedChanges() throws ModelException;

	/**
	 * Returns whether the element is consistent with its underlying resource or
	 * buffer. The element is consistent when opened, and is consistent if the
	 * underlying resource or buffer has not been modified since it was last
	 * consistent.
	 * 
	 * <p>
	 * NOTE: Child consistency is not considered. For example, a package
	 * fragment responds <code>true</code> when it knows about all of its
	 * compilation units present in its underlying folder. However, one or more
	 * of the compilation units could be inconsistent.
	 * 
	 * @exception ModelException
	 *                if this element does not exist or if an exception occurs
	 *                while accessing its corresponding resource.
	 * @return true if the element is consistent with its underlying resource or
	 *         buffer, false otherwise.
	 * @see IOpenable#makeConsistent(IProgressMonitor)
	 */
	boolean isConsistent() throws ModelException;

	/**
	 * Returns whether this openable is open. This is a handle-only method.
	 * 
	 * @return true if this openable is open, false otherwise
	 */
	boolean isOpen();

	/**
	 * Makes this element consistent with its underlying resource or buffer by
	 * updating the element's structure and properties as necessary.
	 * <p>
	 * Note: Using this functionality on a working copy will interfere with any
	 * subsequent reconciling operation. Indeed, the next
	 * {@link ISourceModule#reconcile} operation will not account for changes
	 * which occurred before an explicit use of
	 * {@link #makeConsistent(IProgressMonitor)}
	 * <p>
	 * 
	 * @param progress
	 *            the given progress monitor
	 * @exception ModelException
	 *                if the element is unable to access the contents of its
	 *                underlying resource. Reasons include:
	 *                <ul>
	 *                <li>This script element does not exist
	 *                (ELEMENT_DOES_NOT_EXIST)</li>
	 *                </ul>
	 * @see IOpenable#isConsistent()
	 * @see ISourceModule#reconcile(int, boolean, WorkingCopyOwner,
	 *      IProgressMonitor)
	 */
	void makeConsistent(IProgressMonitor progress) throws ModelException;

	/**
	 * Opens this element and all parent elements that are not already open. For
	 * compilation units, a buffer is opened on the contents of the underlying
	 * resource.
	 * 
	 * <p>
	 * Note: although {@link #open} is exposed in the API, clients are not
	 * expected to open and close elements - the script model does this
	 * automatically as elements are accessed.
	 * 
	 * @param progress
	 *            the given progress monitor
	 * @exception ModelException
	 *                if an error occurs accessing the contents of its
	 *                underlying resource. Reasons include:
	 *                <ul>
	 *                <li>This script element does not exist
	 *                (ELEMENT_DOES_NOT_EXIST)</li>
	 *                </ul>
	 */
	public void open(IProgressMonitor progress) throws ModelException;

	/**
	 * Saves any changes in this element's buffer to its underlying resource via
	 * a workspace resource operation. This has no effect if the element has no
	 * underlying buffer, or if there are no unsaved changed in the buffer.
	 * <p>
	 * The <code>force</code> parameter controls how this method deals with
	 * cases where the workbench is not completely in sync with the local file
	 * system. If <code>false</code> is specified, this method will only
	 * attempt to overwrite a corresponding file in the local file system
	 * provided it is in sync with the workbench. This option ensures there is
	 * no unintended data loss; it is the recommended setting. However, if
	 * <code>true</code> is specified, an attempt will be made to write a
	 * corresponding file in the local file system, overwriting any existing one
	 * if need be. In either case, if this method succeeds, the resource will be
	 * marked as being local (even if it wasn't before).
	 * <p>
	 * As a result of this operation, the element is consistent with its
	 * underlying resource or buffer.
	 * 
	 * @param progress
	 *            the given progress monitor
	 * @param force
	 *            it controls how this method deals with cases where the
	 *            workbench is not completely in sync with the local file system
	 * @exception ModelException
	 *                if an error occurs accessing the contents of its
	 *                underlying resource. Reasons include:
	 *                <ul>
	 *                <li>This script element does not exist
	 *                (ELEMENT_DOES_NOT_EXIST)</li>
	 *                <li>This script element is read-only (READ_ONLY)</li>
	 *                </ul>
	 */
	public void save(IProgressMonitor progress, boolean force)
			throws ModelException;
}