public interface ISaveParticipant extends EventListener
Plug-ins implement this interface and register to participate in workspace save operations.
Clients may implement this interface.
Modifier and Type | Method and Description |
---|---|
void |
doneSaving(ISaveContext context)
Tells this participant that the workspace save operation is now
complete and it is free to go about its normal business.
|
void |
prepareToSave(ISaveContext context)
Tells this participant that the workspace is about to be
saved.
|
void |
rollback(ISaveContext context)
Tells this participant to rollback its important state.
|
void |
saving(ISaveContext context)
Tells this participant to save its important state because
the workspace is being saved, as described in the supplied
save context.
|
void doneSaving(ISaveContext context)
Note: This method is called by the platform; it is not intended to be called directly by clients.
context
- the save context objectvoid prepareToSave(ISaveContext context) throws CoreException
saving
will be next, followed by either doneSaving
or rollback
depending on whether the workspace
save was successful.
Note: This method is called by the platform; it is not intended to be called directly by clients.
context
- the save context objectCoreException
- if this method fails to snapshot
the state of this workspacevoid rollback(ISaveContext context)
Note: This method is called by the platform; it is not intended to be called directly by clients.
context
- the save context objectISaveContext.getPreviousSaveNumber()
void saving(ISaveContext context) throws CoreException
Note: This method is called by the platform; it is not intended to be called directly by clients.
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.
save
(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.
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.
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(); // optionalWhen 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:
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); }
context
- the save context objectCoreException
- if this method failsISaveContext.getSaveNumber()
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.