/*******************************************************************************
* 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 java.util.EventListener;
import org.eclipse.core.runtime.CoreException;
/**
* A participant in the saving of the workspace.
* <p>
* Plug-ins implement this interface and register to participate
* in workspace save operations.
* </p>
* <p>
* Clients may implement this interface.
* </p>
* @see IWorkspace#save(boolean, org.eclipse.core.runtime.IProgressMonitor)
*/
public interface ISaveParticipant extends EventListener {
/**
* Tells this participant that the workspace save operation is now
* complete and it is free to go about its normal business.
* Exceptions are not expected to be thrown at this point, so they
* should be handled internally.
* <p>
* Note: This method is called by the platform; it is not intended
* to be called directly by clients.
* </p>
*
* @param context the save context object
*/
public void doneSaving(ISaveContext context);
/**
* Tells this participant that the workspace is about to be
* saved. In preparation, the participant is expected to suspend
* its normal operation until further notice. <code>saving</code>
* will be next, followed by either <code>doneSaving</code>
* or <code>rollback</code> depending on whether the workspace
* save was successful.
* <p>
* Note: This method is called by the platform; it is not intended
* to be called directly by clients.
* </p>
*
* @param context the save context object
* @exception CoreException if this method fails to snapshot
* the state of this workspace
*/
public void prepareToSave(ISaveContext context) throws CoreException;
/**
* Tells this participant to rollback its important state.
* The context's previous state number indicates what it was prior
* to the failed save.
* Exceptions are not expected to be thrown at this point, so they
* should be handled internally.
* <p>
* Note: This method is called by the platform; it is not intended
* to be called directly by clients.
* </p>
*
* @param context the save context object
* @see ISaveContext#getPreviousSaveNumber()
*/
public void rollback(ISaveContext context);
/**
* Tells this participant to save its important state because
* the workspace is being saved, as described in the supplied
* save context.
* <p>
* Note: This method is called by the platform; it is not intended
* to be called directly by clients.
* </p>
* <p>
* The basic contract for this method is the same for full saves,
* snapshots and project saves: the participant must absolutely guarantee that any
* important user data it has gathered will not be irrecoverably lost
* in the event of a crash. The only difference is in the space-time
* tradeoffs that the participant should make.
* <ul>
* <li>Full saves: the participant is
* encouraged to save additional non-essential information that will aid
* it in retaining user state and configuration information and quickly getting
* back in sync with the state of the platform at a later point.
* </li>
* <li>Snapshots: the participant is discouraged from saving non-essential
* information that could be recomputed in the unlikely event of a crash.
* This lifecycle event will happen often and participant actions should take
* an absolute minimum of time.
* </li>
* <li>Project saves: the participant should only save project related data.
* It is discouraged from saving non-essential information that could be recomputed
* in the unlikely event of a crash.
* </li>
* </ul>
* For instance, the Java IDE gathers various user preferences and would want to
* make sure that the current settings are safe and sound after a
* <code>save</code> (if not saved immediately).
* The Java IDE would likely save computed image builder state on full saves,
* because this would allow the Java IDE to be restarted later and not
* have to recompile the world at that time. On the other hand, the Java
* IDE would not save the image builder state on a snapshot because
* that information is non-essential; in the unlikely event of a crash,
* the image should be rebuilt either from scratch or from the last saved
* state.
* </p>
* <p>
* The following snippet shows how a plug-in participant would write
* its important state to a file whose name is based on the save
* number for this save operation.
* <pre>
* Plugin plugin = ...; // known
* int saveNumber = context.getSaveNumber();
* String saveFileName = "save-" + Integer.toString(saveNumber);
* File f = plugin.getStateLocation().append(saveFileName).toFile();
* plugin.writeImportantState(f);
* context.map(new Path("save"), new Path(saveFileName));
* context.needSaveNumber();
* context.needDelta(); // optional
* </pre>
* When the plug-in is reactivated in a subsequent workspace session,
* it needs to re-register to participate in workspace saves. When it
* does so, it is handed back key information about what state it had last
* saved. If it's interested, it can also ask for a resource delta
* describing all resource changes that have happened since then, if this
* information is still available.
* The following snippet shows what a participant plug-in would
* need to do if and when it is reactivated:
* <pre>
* IWorkspace ws = ...; // known
* Plugin plugin = ...; // known
* ISaveParticipant saver = ...; // known
* ISavedState ss = ws.addSaveParticipant(plugin, saver);
* if (ss == null) {
* // activate for very first time
* plugin.buildState();
* } else {
* String saveFileName = ss.lookup(new Path("save"));
* File f = plugin.getStateLocation().append(saveFileName).toFile();
* plugin.readImportantState(f);
* IResourceChangeListener listener = new IResourceChangeListener() {
* public void resourceChanged(IResourceChangeEvent event) {
* IResourceDelta delta = event.getDelta();
* if (delta != null) {
* // fast reactivation using delta
* plugin.updateState(delta);
* } else {
* // slower reactivation without benefit of delta
* plugin.rebuildState();
* }
* };
* ss.processResourceChangeEvents(listener);
* }
* </pre>
* </p>
*
* @param context the save context object
* @exception CoreException if this method fails
* @see ISaveContext#getSaveNumber()
*/
public void saving(ISaveContext context) throws CoreException;
}