org.eclipse.core.resources.ISaveContext Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2000, 2009 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.core.resources;
import org.eclipse.core.runtime.IPath;
/**
* A context for workspace save operations.
*
* Note that IWorkspace.save uses a
* different save context for each registered participant,
* allowing each to declare whether they have actively
* participated and decide whether to receive a resource
* delta on reactivation.
*
*
* @see IWorkspace#save(boolean, org.eclipse.core.runtime.IProgressMonitor)
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface ISaveContext {
/*====================================================================
* Constants related to save kind
*====================================================================*/
/**
* Type constant which identifies a full save.
*
* @see ISaveContext#getKind()
*/
int FULL_SAVE = 1;
/**
* Type constant which identifies a snapshot.
*
* @see ISaveContext#getKind()
*/
int SNAPSHOT = 2;
/**
* Type constant which identifies a project save.
*
* @see ISaveContext#getKind()
*/
int PROJECT_SAVE = 3;
/**
* Returns current files mapped with the ISaveContext.map
* facility or an empty array if there are no mapped files.
*
* @return the files currently mapped by the participant
*
* @see #map(IPath, IPath)
*/
IPath[] getFiles();
/**
* Returns the type of this save. The types can be:
*
* -
ISaveContext.FULL_SAVE
* -
ISaveContext.SNAPSHOT
* -
ISaveContext.PROJECT_SAVE
*
*
* @return the type of the current save
*/
int getKind();
/**
* Returns the number for the previous save in
* which the plug-in actively participated, or 0
* if the plug-in has never actively participated in a save before.
*
* In the event of an unsuccessful save, this is the value to
* rollback to.
*
*
* @return the previous save number if positive, or 0
* if never saved before
* @see ISaveParticipant#rollback(ISaveContext)
*/
int getPreviousSaveNumber();
/**
* If the current save is a project save, this method returns the project
* being saved.
*
* @return the project being saved or null if this is not
* project save
*
* @see #getKind()
*/
IProject getProject();
/**
* Returns the number for this save. This number is
* guaranteed to be 1 more than the
* previous save number.
*
* This is the value to use when, for example, creating files
* in which a participant will save its data.
*
*
* @return the save number
* @see ISaveParticipant#saving(ISaveContext)
*/
int getSaveNumber();
/**
* Returns the current location for the given file or
* null if none.
*
* @return the location of a given file or null
* @see #map(IPath, IPath)
* @see ISavedState#lookup(IPath)
*/
IPath lookup(IPath file);
/**
* Maps the given plug-in file to its real location. This method is intended to be used
* with ISaveContext.getSaveNumber() to map plug-in configuration
* file names to real locations.
*
* For example, assume a plug-in has a configuration file named "config.properties".
* The map facility can be used to map that logical name onto a real
* name which is specific to a particular save (e.g., 10.config.properties,
* where 10 is the current save number). The paths specified here should
* always be relative to the plug-in state location for the plug-in saving the state.
*
*
* Each save participant must manage the deletion of its old state files. Old state files
* can be discovered using getPreviousSaveNumber or by using
* getFiles to discover the current files and comparing that to the
* list of files on disk.
*
* @param file the logical name of the participant's data file
* @param location the real (i.e., filesystem) name by which the file should be known
* for this save, or null to remove the entry
* @see #lookup(IPath)
* @see #getSaveNumber()
* @see #needSaveNumber()
* @see ISavedState#lookup(IPath)
*/
void map(IPath file, IPath location);
/**
* Indicates that the saved workspace tree should be remembered so that a delta
* will be available in a subsequent session when the plug-in re-registers
* to participate in saves. If this method is not called, no resource delta will
* be made available. This facility is not available for marker deltas.
* Plug-ins must assume that all markers may have changed when they are activated.
*
* Note that this is orthogonal to needSaveNumber. That is,
* one can ask for a delta regardless of whether or not one is an active participant.
*
*
* Note that deltas are not guaranteed to be saved even if saving is requested.
* Deltas cannot be supplied where the previous state is too old or has become invalid.
*
*
* This method is only valid for full saves. It is ignored during snapshots
* or project saves.
*
*
* @see IWorkspace#addSaveParticipant(org.eclipse.core.runtime.Plugin, ISaveParticipant)
* @see ISavedState#processResourceChangeEvents(IResourceChangeListener)
*/
void needDelta();
/**
* Indicates that this participant has actively participated in this save.
* If the save is successful, the current save number will be remembered;
* this save number will be the previous save number for subsequent saves
* until the participant again actively participates.
*
* If this method is not called, the plug-in is not deemed to be an active
* participant in this save.
*
*
* Note that this is orthogonal to needDelta. That is,
* one can be an active participant whether or not one asks for a delta.
*
*
* @see IWorkspace#addSaveParticipant(org.eclipse.core.runtime.Plugin, ISaveParticipant)
* @see ISavedState#getSaveNumber()
*/
void needSaveNumber();
}