/*******************************************************************************
 * Copyright (c) 2000, 2008 IBM Corporation 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:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jdt.core;

import org.eclipse.core.resources.IMarker;
import org.eclipse.core.resources.IResource;
import org.eclipse.core.runtime.IProgressMonitor;

/**
 * Common protocol for Java elements that support working copies.
 * <p>
 * A working copy of a Java element acts just like a regular element (handle),
 * except it is not attached to an underlying resource. A working copy is not
 * visible to the rest of the Java model. Changes in a working copy's
 * buffer are not realized in a resource. To bring the Java model up-to-date with a working
 * copy's contents, an explicit commit must be performed on the working copy.
 * Other operations performed on a working copy update the
 * contents of the working copy's buffer but do not commit the contents
 * of the working copy.
 * </p>
 * <p>
 * Note: The contents of a working copy is determined when a working
 * copy is created, based on the current content of the element the working
 * copy is created from. If a working copy is an <code>IOpenable</code> and is explicitly
 * closed, the working copy's buffer will be thrown away. However, clients should not
 * explicitly open and close working copies.
 * </p>
 * <p>
 * The client that creates a working copy is responsible for
 * destroying the working copy. The Java model will never automatically
 * destroy or close a working copy. (Note that destroying a working copy
 * does not commit it to the model, it only frees up the memory occupied by
 * the element). After a working copy is destroyed, the working copy cannot
 * be accessed again. Non-handle methods will throw a
 * <code>JavaModelException</code> indicating the Java element does not exist.
 * </p>
 * <p>
 * A working copy cannot be created from another working copy.
 * Calling <code>getWorkingCopy</code> on a working copy returns the receiver.
 * </p>
 *
 * @deprecated Use {@link ICompilationUnit} instead
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IWorkingCopy {

    /**
     * Commits the contents of this working copy to its original element
     * and underlying resource, bringing the Java model up-to-date with
     * the current contents of the working copy.
     *
     * <p>It is possible that the contents of the original resource have changed
     * since this working copy was created, in which case there is an update conflict.
     * The value of the <code>force</code> parameter effects the resolution of
     * such a conflict:<ul>
     * <li> <code>true</code> - in this case the contents of this working copy are applied to
     *  the underlying resource even though this working copy was created before
     *  a subsequent change in the resource</li>
     * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
     * </ul>
     * <p>
     * Since 2.1, a working copy can be created on a not-yet existing compilation
     * unit. In particular, such a working copy can then be committed in order to create
     * the corresponding compilation unit.
     * </p>
     * @param force a flag to handle the cases when the contents of the original resource have changed
     * since this working copy was created
     * @param monitor the given progress monitor
     * @exception JavaModelException if this working copy could not commit. Reasons include:
     * <ul>
     * <li> A <code>CoreException</code> occurred while updating an underlying resource
     * <li> This element is not a working copy (INVALID_ELEMENT_TYPES)
     * <li> A update conflict (described above) (UPDATE_CONFLICT)
     * </ul>
     * @deprecated Use {@link ICompilationUnit#commitWorkingCopy(boolean, IProgressMonitor)} instead.
     */
    void commit(boolean force, IProgressMonitor monitor) throws JavaModelException;

    /**
     * Destroys this working copy, closing its buffer and discarding
     * its structure. Subsequent attempts to access non-handle information
     * for this working copy will result in <code>IJavaModelException</code>s. Has
     * no effect if this element is not a working copy.
     * <p>
     * If this working copy is shared, it is destroyed only when the number of calls to
     * <code>destroy()</code> is the same as the number of calls to <code>
     * getSharedWorkingCopy(IProgressMonitor, IBufferFactory)</code>.
     * </p><p>
     * When it is destroyed, a REMOVED IJavaElementDelta is reported on this
     * working copy.
     * </p>
     * @deprecated Use {@link ICompilationUnit#discardWorkingCopy()} instead.
     */
    void destroy();

    /**
     * Finds the shared working copy for this element, given a <code>IBuffer</code> factory.
     * If no working copy has been created for this element associated with this
     * buffer factory, returns <code>null</code>.
     * <p>
     * Users of this method must not destroy the resulting working copy.
     *
     * @param bufferFactory the given <code>IBuffer</code> factory
     * @return the found shared working copy for this element, <code>null</code> if none
     * @see IBufferFactory
     * @since 2.0
     *
     * @deprecated Use {@link ICompilationUnit#findWorkingCopy(WorkingCopyOwner)} instead.
     */
    IJavaElement findSharedWorkingCopy(IBufferFactory bufferFactory);

    /**
     * Returns the original element the specified working copy element was created from,
     * or <code>null</code> if this is not a working copy element.  This is a handle
     * only method, the returned element may or may not exist.
     *
     * @param workingCopyElement the specified working copy element
     * @return the original element the specified working copy element was created from,
     * or <code>null</code> if this is not a working copy element
     *
     * @deprecated Use {@link IJavaElement#getPrimaryElement()} instead.
     */
    IJavaElement getOriginal(IJavaElement workingCopyElement);

    /**
     * Returns the original element this working copy was created from,
     * or <code>null</code> if this is not a working copy.
     *
     * @return the original element this working copy was created from,
     * or <code>null</code> if this is not a working copy
     *
     * @deprecated Use {@link ICompilationUnit#getPrimaryElement()} instead.
     */
    IJavaElement getOriginalElement();

    /**
     * Finds the elements in this compilation unit that correspond to
     * the given element.
     * An element A corresponds to an element B if:
     * <ul>
     * <li>A has the same element name as B.
     * <li>If A is a method, A must have the same number of arguments as
     *     B and the simple names of the argument types must be equals.
     * <li>The parent of A corresponds to the parent of B recursively up to
     *     their respective compilation units.
     * <li>A exists.
     * </ul>
     * Returns <code>null</code> if no such java elements can be found
     * or if the given element is not included in a compilation unit.
     *
     * @param element the given element
     * @return the found elements in this compilation unit that correspond to the given element
     * @since 2.0
     *
     * @deprecated Use {@link ICompilationUnit#findElements(IJavaElement)} instead.
     */
    IJavaElement[] findElements(IJavaElement element);

    /**
     * Finds the primary type of this compilation unit (that is, the type with the same name as the
     * compilation unit), or <code>null</code> if no such a type exists.
     *
     * @return the found primary type of this compilation unit, or <code>null</code> if no such a type exists
     * @since 2.0
     *
     * @deprecated Use {@link ITypeRoot#findPrimaryType()} instead.
     */
    IType findPrimaryType();

    /**
     * Returns a shared working copy on this element using the given factory to create
     * the buffer, or this element if this element is already a working copy.
     * This API can only answer an already existing working copy if it is based on the same
     * original compilation unit AND was using the same buffer factory (that is, as defined by <code>Object.equals</code>).
     * <p>
     * The life time of a shared working copy is as follows:
     * <ul>
     * <li>The first call to <code>getSharedWorkingCopy(...)</code> creates a new working copy for this
     *     element</li>
     * <li>Subsequent calls increment an internal counter.</li>
     * <li>A call to <code>destroy()</code> decrements the internal counter.</li>
     * <li>When this counter is 0, the working copy is destroyed.
     * </ul>
     * So users of this method must destroy exactly once the working copy.
     * <p>
     * Note that the buffer factory will be used for the life time of this working copy, that is if the
     * working copy is closed then reopened, this factory will be used.
     * The buffer will be automatically initialized with the original's compilation unit content
     * upon creation.
     * <p>
     * When the shared working copy instance is created, an ADDED IJavaElementDelta is reported on this
     * working copy.
     *
     * @param monitor a progress monitor used to report progress while opening this compilation unit
     *                 or <code>null</code> if no progress should be reported
     * @param factory the factory that creates a buffer that is used to get the content of the working copy
     *                 or <code>null</code> if the internal factory should be used
     * @param problemRequestor a requestor which will get notified of problems detected during
     *  reconciling as they are discovered. The requestor can be set to <code>null</code> indicating
     *  that the client is not interested in problems.
     * @exception JavaModelException if the contents of this element can
     *   not be determined.
     * @return a shared working copy on this element using the given factory to create
     * the buffer, or this element if this element is already a working copy
     * @see IBufferFactory
     * @see IProblemRequestor
     * @since 2.0
     *
     * @deprecated Use {@link ICompilationUnit#getWorkingCopy(WorkingCopyOwner, IProblemRequestor, IProgressMonitor)} instead.
     */
    IJavaElement getSharedWorkingCopy(
        IProgressMonitor monitor,
        IBufferFactory factory,
        IProblemRequestor problemRequestor)
        throws JavaModelException;

    /**
     * Returns a new working copy of this element if this element is not
     * a working copy, or this element if this element is already a working copy.
     * <p>
     * Note: if intending to share a working copy amongst several clients, then
     * <code>#getSharedWorkingCopy</code> should be used instead.
     * </p><p>
     * When the working copy instance is created, an ADDED IJavaElementDelta is
     * reported on this working copy.
     * </p><p>
     * Since 2.1, a working copy can be created on a not-yet existing compilation
     * unit. In particular, such a working copy can then be committed in order to create
     * the corresponding compilation unit.
     * </p>
     * @exception JavaModelException if the contents of this element can
     *   not be determined.
     * @return a new working copy of this element if this element is not
     * a working copy, or this element if this element is already a working copy
     *
     * @deprecated Use {@link ICompilationUnit#getWorkingCopy(IProgressMonitor)} instead.
     */
    IJavaElement getWorkingCopy() throws JavaModelException;

    /**
     * Returns a new working copy of this element using the given factory to create
     * the buffer, or this element if this element is already a working copy.
     * Note that this factory will be used for the life time of this working copy, that is if the
     * working copy is closed then reopened, this factory will be reused.
     * The buffer will be automatically initialized with the original's compilation unit content
     * upon creation.
     * <p>
     * Note: if intending to share a working copy amongst several clients, then
     * <code>#getSharedWorkingCopy</code> should be used instead.
     * </p><p>
     * When the working copy instance is created, an ADDED IJavaElementDelta is
     * reported on this working copy.
     * </p><p>
     * Since 2.1, a working copy can be created on a not-yet existing compilation
     * unit. In particular, such a working copy can then be committed in order to create
     * the corresponding compilation unit.
     * </p>
     * @param monitor a progress monitor used to report progress while opening this compilation unit
     *                 or <code>null</code> if no progress should be reported
     * @param factory the factory that creates a buffer that is used to get the content of the working copy
     *                 or <code>null</code> if the internal factory should be used
     * @param problemRequestor a requestor which will get notified of problems detected during
     *  reconciling as they are discovered. The requestor can be set to <code>null</code> indicating
     *  that the client is not interested in problems.
     * @exception JavaModelException if the contents of this element can
     *   not be determined.
     * @return a new working copy of this element using the given factory to create
     * the buffer, or this element if this element is already a working copy
     * @since 2.0
     *
     * @deprecated Use {@link ICompilationUnit#getWorkingCopy(WorkingCopyOwner, IProblemRequestor, IProgressMonitor)} instead.
     */
    IJavaElement getWorkingCopy(
        IProgressMonitor monitor,
        IBufferFactory factory,
        IProblemRequestor problemRequestor)
        throws JavaModelException;

    /**
     * Returns whether this working copy's original element's content
     * has not changed since the inception of this working copy.
     *
     * @param resource this working copy's resource
     * @return true if this working copy's original element's content
     * has not changed since the inception of this working copy, false otherwise
     *
     * @deprecated Use {@link ICompilationUnit#hasResourceChanged()} instead.
     */
    boolean isBasedOn(IResource resource);

    /**
     * Returns whether this element is a working copy.
     *
     * @return true if this element is a working copy, false otherwise
     *
     * @deprecated Use {@link ICompilationUnit#isWorkingCopy()} instead.
     */
    boolean isWorkingCopy();

    /**
     * Reconciles the contents of this working copy.
     * It performs the reconciliation by locally caching the contents of
     * the working copy, updating the contents, then creating a delta
     * over the cached contents and the new contents, and finally firing
     * this delta.
     * <p>
     * If the working copy hasn't changed, then no problem will be detected,
     * this is equivalent to <code>IWorkingCopy#reconcile(false, null)</code>.</p>
     * <p>
     * Compilation problems found in the new contents are notified through the
     * <code>IProblemRequestor</code> interface which was passed at
     * creation, and no longer as transient markers. Therefore this API will
     * return <code>null</code>.</p>
     * <p>
     * Note: Since 3.0 added/removed/changed inner types generate change deltas.</p>
     *
     * @exception JavaModelException if the contents of the original element
     *      cannot be accessed. Reasons include:
     * <ul>
     * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
     * </ul>
     * @return <code>null</code>
     *
     * @deprecated Use {@link ICompilationUnit#reconcile(int, boolean, WorkingCopyOwner, IProgressMonitor)} instead.
     */
    IMarker[] reconcile() throws JavaModelException;

    /**
     * Reconciles the contents of this working copy.
     * It performs the reconciliation by locally caching the contents of
     * the working copy, updating the contents, then creating a delta
     * over the cached contents and the new contents, and finally firing
     * this delta.
     * <p>
     * The boolean argument allows to force problem detection even if the
     * working copy is already consistent.</p>
     * <p>
     * Compilation problems found in the new contents are notified through the
     * <code>IProblemRequestor</code> interface which was passed at
     * creation, and no longer as transient markers. Therefore this API answers
     * nothing.</p>
     * <p>
     * Note: Since 3.0 added/removed/changed inner types generate change deltas.</p>
     *
     * @param forceProblemDetection boolean indicating whether problem should be recomputed
     *   even if the source hasn't changed.
     * @param monitor a progress monitor
     * @exception JavaModelException if the contents of the original element
     *      cannot be accessed. Reasons include:
     * <ul>
     * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
     * </ul>
     * @since 2.0
     *
     * @deprecated Use {@link ICompilationUnit#reconcile(int, boolean, WorkingCopyOwner, IProgressMonitor)} instead.
     */
    void reconcile(boolean forceProblemDetection, IProgressMonitor monitor) throws JavaModelException;

    /**
     * Restores the contents of this working copy to the current contents of
     * this working copy's original element. Has no effect if this element
     * is not a working copy.
     *
     * <p>Note: This is the inverse of committing the content of the
     * working copy to the original element with <code>commit(boolean, IProgressMonitor)</code>.
     *
     * @exception JavaModelException if the contents of the original element
     *      cannot be accessed.  Reasons include:
     * <ul>
     * <li> The original Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
     * </ul>
     * @deprecated Use {@link ICompilationUnit#restore()} instead.
     */
    void restore() throws JavaModelException;
}