/*******************************************************************************
 *  Copyright (c) 2000, 2009 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.core.resources;

import org.eclipse.core.runtime.IPath;

/**
 * A data structure returned by {@link IWorkspace#addSaveParticipant(org.eclipse.core.runtime.Plugin, ISaveParticipant)}
 * containing a save number and an optional resource delta.
 *
 * @see IWorkspace#addSaveParticipant(org.eclipse.core.runtime.Plugin, ISaveParticipant)
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface ISavedState {
	/**
	 * Returns the files mapped with the {@link ISaveContext#map(IPath, IPath)}
	 * facility. Returns an empty array if there are no mapped files.
	 *
	 * @return the files currently mapped by the participant
	 *
	 * @see #lookup(IPath)
	 * @see ISaveContext#map(IPath, IPath)
	 */
	public IPath[] getFiles();

	/**
	 * Returns the save number for the save participant.
	 * This is the save number of the last successful save in which the plug-in
	 * <b>actively</b> participated, or <code>0</code> if the plug-in has
	 * never actively participated in a successful save.
	 *
	 * @return the save number
	 */
	public int getSaveNumber();

	/**
	 * Returns the mapped location associated with the given path
	 * or <code>null</code> if none.
	 *
	 * @return the mapped location of a given path
	 * @see #getFiles()
	 * @see ISaveContext#map(IPath, IPath)
	 */
	public IPath lookup(IPath file);

	/**
	 * Used to receive notification of changes that might have happened
	 * while this plug-in was not active. The listener receives notifications of changes to
	 * the workspace resource tree since the time this state was saved.  After this
	 * method is run, the delta is forgotten. Subsequent calls to this method
	 * will have no effect.
	 * <p>
	 * No notification is received in the following cases:
	 * <ul>
	 * <li>if a saved state was never recorded ({@link ISaveContext#needDelta()}</code>
	 * 		was not called) </li>
	 * <li>a saved state has since been forgotten (using {@link IWorkspace#forgetSavedTree(String)}) </li>
	 * <li>a saved state has been deemed too old or has become invalid</li>
	 * </ul>
	 * <p>
	 * All clients should have a contingency plan in place in case
	 * a changes are not available (the case should be very similar
	 * to the first time a plug-in is activated, and only has the
	 * current state of the workspace to work from).
	 * </p>
	 * <p>
	 * The supplied event is of type {@link IResourceChangeEvent#POST_BUILD}
	 * and contains the delta detailing changes since this plug-in last participated
	 * in a save. This event object (and the resource delta within it) is valid only
	 * for the duration of the invocation of this method.
	 * </p>
	 *
	 * @param listener the listener
	 * @see ISaveContext#needDelta()
	 * @see IResourceChangeListener
	 */
	public void processResourceChangeEvents(IResourceChangeListener listener);
}